Wayfinder Core

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 Core?

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',
    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),
  },
})

Core Methods

request()

Fetches data from Arweave with intelligent routing and optional verification.

// Basic usage
const response = await wayfinder.request('ar://transaction-id')
const data = await response.text()

// With custom options
const response = await wayfinder.request('ar://transaction-id', {
  headers: { Accept: 'application/json' },
  signal: AbortSignal.timeout(5000),
})
const json = await response.json()

// Override settings for specific request
const response = await wayfinder.request('ar://transaction-id', {
  wayfinderOptions: {
    verificationEnabled: false,
    preferredGateways: ['https://my-gateway.com'],
  },
})

resolveUrl()

Resolves an ar:// URL to a gateway URL without fetching data.

// Basic URL resolution
const gatewayUrl = await wayfinder.resolveUrl('ar://transaction-id')
console.log(gatewayUrl) // https://selected-gateway.com/transaction-id

// With custom routing
const gatewayUrl = await wayfinder.resolveUrl('ar://transaction-id', {
  routingStrategy: new FastestPingRoutingStrategy({ timeoutMs: 1000 }),
})

Event Monitoring

Monitor wayfinder operations using the built-in event system:

// Routing events
wayfinder.emitter.on('routing-succeeded', (event) => {
  console.log('Gateway selected:', event.selectedGateway)
})

wayfinder.emitter.on('routing-failed', (error) => {
  console.error('Routing failed:', error.message)
})

// Verification events
wayfinder.emitter.on('verification-succeeded', (event) => {
  console.log('Verification passed for:', event.txId)
})

wayfinder.emitter.on('verification-failed', (error) => {
  console.warn('Verification failed:', error.message)
})

What Can Wayfinder Core Do?

Gateway Providers

NetworkGatewaysProvider: Discovers gateways from the AR.IO Network
StaticGatewaysProvider: Uses predefined gateway lists
SimpleCacheGatewaysProvider: Caches gateway lists for performance

Routing Strategies

FastestPingRoutingStrategy: Selects lowest latency gateway
PreferredWithFallbackRoutingStrategy: Tries preferred gateway first
RoundRobinRoutingStrategy: Distributes requests evenly
RandomRoutingStrategy: Randomly selects gateways

Verification Strategies

HashVerificationStrategy: Verifies against trusted gateway hashes
SignatureVerificationStrategy: Validates Arweave signatures
DataRootVerificationStrategy: Verifies against data roots

Best Practices

Choose Appropriate Routing: Use FastestPingRoutingStrategy for performance-critical apps
Enable Verification: Use verification for important or sensitive data
Handle Errors: Implement proper error handling for different failure scenarios
Monitor Performance: Use events to track gateway performance and success rates
Configure Timeouts: Set appropriate timeouts based on your application needs
Use Telemetry: Enable telemetry in production for monitoring and debugging

Next Steps

Events System: Learn about event handling and monitoring
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