Getting Started with Wayfinder

Wayfinder provides decentralized and verified access to data stored on Arweave. This guide will help you get started with the core concepts and basic usage.

Verification strategies may be dependent on the gateway being used having the data indexed locally. A gateway cannot verify data it doesn't have access to or hasn't indexed yet.

Installation

Choose the package that fits your project:

Core Library (JavaScript/TypeScript)

npm install @ar.io/wayfinder-core
# or
yarn add @ar.io/wayfinder-core

React Components

npm install @ar.io/wayfinder-react
# or
yarn add @ar.io/wayfinder-react

Quick Start

Basic Usage with Default Settings

The simplest way to get started is with the default configuration:

import { Wayfinder } from '@ar.io/wayfinder-core'
import { ARIO } from '@ar.io/sdk'

// Create wayfinder with default settings
const wayfinder = new Wayfinder({
  gatewaysProvider: new NetworkGatewaysProvider({
    ario: ARIO.mainnet(),
  }),
})

// Fetch data using ar:// protocol
try {
  const response = await wayfinder.request('ar://transaction-id')
  const data = await response.text()
  console.log('Data:', data)
} catch (error) {
  console.error('Failed to fetch data:', error)
}

React Integration

For React applications, use the wayfinder-react package:

import { WayfinderProvider, useWayfinder } from '@ar.io/wayfinder-react'

// Wrap your app with the provider
function App() {
  return (
    <WayfinderProvider
      gatewaysProvider={new NetworkGatewaysProvider({ ario: ARIO.mainnet() })}
      routingSettings={{
        strategy: new FastestPingRoutingStrategy({ timeoutMs: 500 }),
      }}
    >
      <MyComponent />
    </WayfinderProvider>
  )
}

// Use the hook in your components
function MyComponent() {
  const { wayfinder, isReady } = useWayfinder()
  const [data, setData] = useState(null)

  useEffect(() => {
    if (isReady) {
      wayfinder
        .request('ar://transaction-id')
        .then((response) => response.text())
        .then(setData)
    }
  }, [wayfinder, isReady])

  return <div>{data}</div>
}

Available Strategies

Routing Strategies

← Swipe to see more →

Strategy	Description	Use Case
FastestPingRoutingStrategy	Selects gateway with lowest latency	Performance-critical applications
PreferredWithFallbackRoutingStrategy	Tries preferred gateway first, falls back to others	When you have a trusted primary gateway
RoundRobinRoutingStrategy	Distributes requests evenly across gateways	Load balancing and fair distribution
RandomRoutingStrategy	Randomly selects from available gateways	Simple load distribution

← Swipe to see more →

Verification Strategies

← Swipe to see more →

Strategy	Description	Use Case
HashVerificationStrategy	Verifies data against trusted gateway hashes	Fast verification with trusted sources
SignatureVerificationStrategy	Validates Arweave transaction signatures	Cryptographic proof of authenticity
DataRootVerificationStrategy	Verifies against transaction data roots	Block-level verification

← Swipe to see more →

Handling Unknown Data Types

When you're not sure what type of data you're fetching, check the content type and handle accordingly:

import { Wayfinder } from '@ar.io/wayfinder-core'
import { ARIO } from '@ar.io/sdk'

const wayfinder = new Wayfinder({
  gatewaysProvider: new NetworkGatewaysProvider({
    ario: ARIO.mainnet(),
  }),
})

async function fetchUnknownData(txId) {
  try {
    const response = await wayfinder.request(`ar://${txId}`)
    const contentType = response.headers.get('content-type') || ''

    if (contentType.includes('application/json')) {
      // Handle JSON data
      const jsonData = await response.json()
      console.log('JSON data:', jsonData)
      return jsonData
    } else if (contentType.startsWith('text/')) {
      // Handle text data
      const textData = await response.text()
      console.log('Text data:', textData)
      return textData
    } else if (contentType.startsWith('image/')) {
      // Handle image data
      const blob = await response.blob()
      const imageUrl = URL.createObjectURL(blob)
      console.log('Image URL:', imageUrl)
      return imageUrl
    } else {
      // Handle binary/unknown data as ArrayBuffer
      const buffer = await response.arrayBuffer()
      console.log('Binary data size:', buffer.byteLength, 'bytes')
      return buffer
    }
  } catch (error) {
    console.error('Failed to fetch data:', error)
    throw error
  }
}

// Usage
fetchUnknownData('your-transaction-id')

Event Monitoring

Monitor wayfinder operations using events:

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

wayfinder.emitter.on('verification-succeeded', (event) => {
  console.log('Data verified for transaction:', event.txId)
})

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

Advanced Configuration

For production applications, you'll want to configure gateway providers, routing strategies, and verification:

import {
  Wayfinder,
  NetworkGatewaysProvider,
  FastestPingRoutingStrategy,
  HashVerificationStrategy,
} from '@ar.io/wayfinder-core'
import { ARIO } from '@ar.io/sdk'

const wayfinder = new Wayfinder({
  // Discover gateways from the AR.IO Network
  gatewaysProvider: new NetworkGatewaysProvider({
    ario: ARIO.mainnet(),
    limit: 10,
    sortBy: 'operatorStake',
    sortOrder: 'desc',
  }),

  // Use fastest ping routing strategy
  routingSettings: {
    strategy: new FastestPingRoutingStrategy({
      timeoutMs: 500,
    }),
    events: {
      onRoutingSucceeded: (event) => {
        console.log('Selected gateway:', event.selectedGateway)
      },
    },
  },

  // Enable data verification
  verificationSettings: {
    enabled: true,
    strategy: new HashVerificationStrategy({
      trustedGateways: ['https://arweave.net'],
    }),
    events: {
      onVerificationSucceeded: (event) => {
        console.log('Verification passed for:', event.txId)
      },
    },
  },

  // Enable telemetry
  telemetrySettings: {
    enabled: true,
    serviceName: 'my-app',
    sampleRate: 0.1, // 10% sampling
  },

  // Configure event handlers
  events: {
    onGatewaysRefreshed: (event) => {
      console.log(`Refreshed ${event.gateways.length} gateways`)
    },
    onRequestStarted: (event) => {
      console.log(`Starting request for ${event.url}`)
    },
    onRequestCompleted: (event) => {
      console.log(`Request completed in ${event.duration}ms`)
    },
    onRequestFailed: (event) => {
      console.error(`Request failed: ${event.error.message}`)
    },
  },
})

Core Concepts

Gateway Providers

Gateway providers discover and manage the list of available AR.IO gateways:

NetworkGatewaysProvider: Fetches gateways from the AR.IO Network
StaticGatewaysProvider: Uses a predefined list of gateways
SimpleCacheGatewaysProvider: Caches gateway lists for performance

Routing Strategies

Routing strategies determine which gateway to use for each request:

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

Verification Strategies

Verification strategies ensure data integrity:

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