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.

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

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 { LocalStorageGatewaysProvider, NetworkGatewaysProvider } from '@ar.io/wayfinder-core'
import { WayfinderProvider, useWayfinder } from '@ar.io/wayfinder-react'

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

function YourComponent() {
  const txId = 'your-transaction-id'; // Replace with actual txId

  // Use custom hooks for URL resolution and data fetching
  const request = useWayfinderRequest();

  // store the fetched data
  const [data, setData] = useState<any>(null);
  const [dataLoading, setDataLoading] = useState(false);
  const [dataError, setDataError] = useState<Error | null>(null);

  useEffect(() => {
    (async () => {
      try {
        setDataLoading(true);
        setDataError(null);
        // fetch the data for the txId using wayfinder
        const response = await request(`ar://${txId}`, {
          verificationSettings: {
            enabled: true, // enable verification on the request
            strict: true, // don't use the data if it's not verified
          },
        });
        const data = await response.arrayBuffer(); // or response.json() if you want to parse the data as JSON
        setData(data);
      } catch (error) {
        setDataError(error as Error);
      } finally {
        setDataLoading(false);
      }
    })();
  }, [request, txId]);

  return (
    <div>
      {dataLoading && <p>Loading data...</p>}
      {dataError && <p>Error loading data: {dataError.message}</p>}
      <pre>{data}</pre>
    </div>
  );
}

Available Strategies

Routing Strategies

← Swipe to see more →
StrategyDescriptionUse Case
FastestPingRoutingStrategySelects gateway with lowest latencyPerformance-critical applications
PreferredWithFallbackRoutingStrategy

Tries preferred gateway first, falls back to others

When you have a trusted primary gateway
RoundRobinRoutingStrategyDistributes requests evenly across gatewaysLoad balancing and fair distribution
RandomRoutingStrategyRandomly selects from available gatewaysSimple load distribution
← Swipe to see more →

Verification Strategies

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.

← Swipe to see more →
StrategyDescriptionUse Case
HashVerificationStrategyVerifies data against trusted gateway hashesFast verification with trusted sources
SignatureVerificationStrategyValidates Arweave transaction signaturesCryptographic proof of authenticity
DataRootVerificationStrategyVerifies against transaction data rootsBlock-level verification
← Swipe to see more →

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 SimpleCacheGatewaysProvider({
    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)
      },
      onVerificationFailed: (event) => {
        console.log('Verification failed for:', event.txId)
      },
    },
  },

  // Enable telemetry
  telemetrySettings: {
    enabled: true,
    clientName: 'my-app',
    clientVersion: '1.0.0',
    sampleRate: 0.1, // 10% sampling
  },
})

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 in-memory
  • LocalStorageGatewaysProvider Caches gateway lists for performance in window.localStorage

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

Was this page helpful?