Gateway Providers

Gateway providers supply the list of gateways for routing. By default, createWayfinderClient and new Wayfinder() use a cached CompositeGatewaysProvider that tries TrustedPeersGatewaysProvider first and falls back to the trusted gateway itself. Peer discovery is a single point of failure — a gateway can answer /ar-io/peers with 200 and an empty list — and the fallback keeps requests working (routed through the one gateway already trusted) instead of failing outright. Call createDefaultGatewaysProvider() to build the same thing yourself.

NetworkGatewaysProvider

Returns a list of gateways from the ARIO Network based on on-chain Gateway Address Registry. You can specify on-chain metrics for gateways to prioritize the highest quality gateways. Requires @ar.io/sdk and @solana/kit.

import { NetworkGatewaysProvider } from '@ar.io/wayfinder-core';
import { ARIO } from '@ar.io/sdk';
import { createSolanaRpc } from '@solana/kit';

const ario = ARIO.init({
  rpc: createSolanaRpc('https://api.mainnet-beta.solana.com'),
});

const gatewayProvider = new NetworkGatewaysProvider({
  ario,
  sortBy: 'operatorStake',
  sortOrder: 'desc',
  limit: 10,
  filter: (gateway) => gateway.status === 'joined',
});

Note on sorting. The Solana backend of @ar.io/sdk accepts sortBy and sortOrder but does not apply them — its pagination helper slices the account list in on-chain order. This provider therefore sorts client-side, which means it reads the whole registry before applying limit. That is what makes limit: 10 actually return the ten highest-staked gateways rather than ten arbitrary ones. sortBy also accepts dotted paths such as weights.stakeWeight; a gateway missing the field sorts as 0.

TrustedPeersGatewaysProvider

Fetches a dynamic list of trusted peer gateways from an AR.IO gateway's /ar-io/peers endpoint. This provider is useful for discovering available gateways from a trusted source.

import { TrustedPeersGatewaysProvider } from '@ar.io/wayfinder-core';

const gatewayProvider = new TrustedPeersGatewaysProvider({
  trustedGateway: 'https://turbo-gateway.com',
  retries: 3, // optional, defaults to 3
});

A gateway can answer /ar-io/peers with 200 and an empty gateways map — in practice this happens when an instance hasn't synced its view of the registry. The provider retries in that case and, if the list is still empty, throws an error naming the endpoint rather than returning [] (which would surface much later as an opaque "No gateways available" from whichever routing strategy consumed it). Both CompositeGatewaysProvider and SimpleCacheGatewaysProvider treat that throw as a signal to fall back, so wrapping this provider in either one gives you a clean degradation path.

CompositeGatewaysProvider

Chains multiple gateway providers together, trying each in sequence until one succeeds. This is useful for building resilient gateway discovery with fallbacks.

How it works:

1. Tries each provider in the order they're provided
2. If a provider returns a non-empty list of gateways, those gateways are used
3. If a provider throws an error or returns an empty list, moves to the next provider
4. If all providers fail, throws an error

import {
  CompositeGatewaysProvider,
  NetworkGatewaysProvider,
  StaticGatewaysProvider,
  TrustedPeersGatewaysProvider,
} from '@ar.io/wayfinder-core';
import { ARIO } from '@ar.io/sdk';
import { createSolanaRpc } from '@solana/kit';

const ario = ARIO.init({
  rpc: createSolanaRpc('https://api.mainnet-beta.solana.com'),
});

// Example: Network-first with static fallback
const gatewayProvider = new CompositeGatewaysProvider({
  providers: [
    // Try fetching from AR.IO network first
    new NetworkGatewaysProvider({
      ario,
      sortBy: 'operatorStake',
      limit: 10,
    }),
    // Fallback to trusted peers if network fetch fails
    new TrustedPeersGatewaysProvider({
      trustedGateway: 'https://turbo-gateway.com',
    }),
    // Final fallback to static list
    new StaticGatewaysProvider({
      gateways: ['https://turbo-gateway.com', 'https://g8way.io'],
    }),
  ],
});