Wayfinder
The @ar.io/wayfinder-core
library provides intelligent gateway routing and data verification for accessing Arweave data through the AR.IO network. It's the foundational package that powers all other Wayfinder tools.
What is Wayfinder?
Wayfinder Core is a JavaScript/TypeScript library that:
- Intelligently Routes Requests: Automatically selects the best AR.IO gateway for each request
- Verifies Data Integrity: Cryptographically verifies that data hasn't been tampered with
- Handles Failures Gracefully: Automatically retries with different gateways when requests fail
- Provides Observability: Emits events and telemetry for monitoring and debugging
- Works Everywhere: Compatible with browsers, Node.js, and edge environments
Installation
npm install @ar.io/wayfinder-core @ar.io/sdk
# or
yarn add @ar.io/wayfinder-core @ar.io/sdk
Basic Configuration
import { Wayfinder, NetworkGatewaysProvider } from '@ar.io/wayfinder-core'
import { ARIO } from '@ar.io/sdk'
const wayfinder = new Wayfinder({
gatewaysProvider: new NetworkGatewaysProvider({
ario: ARIO.mainnet(),
}),
})
// Fetch data using ar:// protocol
const response = await wayfinder.request(
'ar://bNbA3TEQVL60xlgCcqdz4ZPHFZ711cZ3hmkpGttDt_U',
)
const data = await response.text()
Advanced Configuration
With Routing Strategy
import {
Wayfinder,
NetworkGatewaysProvider,
FastestPingRoutingStrategy,
} from '@ar.io/wayfinder-core'
import { ARIO } from '@ar.io/sdk'
const wayfinder = new Wayfinder({
gatewaysProvider: new NetworkGatewaysProvider({
ario: ARIO.mainnet(),
}),
routingSettings: {
strategy: new FastestPingRoutingStrategy({
timeoutMs: 500,
}),
},
})
With Data Verification
import {
Wayfinder,
NetworkGatewaysProvider,
HashVerificationStrategy,
} from '@ar.io/wayfinder-core'
import { ARIO } from '@ar.io/sdk'
const wayfinder = new Wayfinder({
gatewaysProvider: new NetworkGatewaysProvider({
ario: ARIO.mainnet(),
}),
verificationSettings: {
enabled: true,
strategy: new HashVerificationStrategy({
trustedGateways: ['https://arweave.net'],
}),
},
})
Full Configuration Example
import {
Wayfinder,
NetworkGatewaysProvider,
FastestPingRoutingStrategy,
HashVerificationStrategy,
} from '@ar.io/wayfinder-core'
import { ARIO } from '@ar.io/sdk'
const wayfinder = new Wayfinder({
// Gateway discovery
gatewaysProvider: new NetworkGatewaysProvider({
ario: ARIO.mainnet(),
limit: 10,
sortBy: 'operatorStake',
}),
// Routing configuration
routingSettings: {
strategy: new FastestPingRoutingStrategy({
timeoutMs: 500,
cacheResultsMs: 30000,
}),
events: {
onRoutingSucceeded: (event) => {
console.log('Selected gateway:', event.selectedGateway)
},
onRoutingFailed: (error) => {
console.error('Routing failed:', error.message)
},
},
},
// Data verification
verificationSettings: {
enabled: true,
strategy: new HashVerificationStrategy({
trustedGateways: ['https://arweave.net'],
}),
strict: false,
events: {
onVerificationSucceeded: (event) => {
console.log('Verification passed:', event.txId)
},
onVerificationFailed: (error) => {
console.warn('Verification failed:', error.message)
},
},
},
// Telemetry (optional)
telemetrySettings: {
enabled: true,
serviceName: 'my-application',
clientName: 'my-app',
clientVersion: '1.0.0',
sampleRate: 0.1,
},
// Custom logger (optional)
logger: {
debug: (message, ...args) =>
console.debug(`[WAYFINDER] ${message}`, ...args),
info: (message, ...args) => console.info(`[WAYFINDER] ${message}`, ...args),
warn: (message, ...args) => console.warn(`[WAYFINDER] ${message}`, ...args),
error: (message, ...args) =>
console.error(`[WAYFINDER] ${message}`, ...args),
},
})
Next Steps
- request(): How to fetch Arweave data using Wayfinder
- resolveUrl(): Use dynamic URLs for transaction IDs, ArNS names, etc.
- Gateway Providers: Understand gateway discovery options
- Routing Strategies: Explore different routing algorithms
- Verification Strategies: Learn about data integrity verification
- Telemetry: Set up monitoring and observability