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,
  PingRoutingStrategy,
} from '@ar.io/wayfinder-core'
import { ARIO } from '@ar.io/sdk'

const wayfinder = new Wayfinder({
  gatewaysProvider: new NetworkGatewaysProvider({
    ario: ARIO.mainnet(),
  }),
  routingSettings: {
    strategy: new PingRoutingStrategy({
      routingStrategy: new FastestPingRoutingStrategy({
        timeoutMs: 500,
      }),
      timeoutMs: 1000,
    }),
  },
})

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

Was this page helpful?