ar.ioar.io Documentation

Data Retrieval Strategies

Wayfinder supports multiple data retrieval strategies to fetch transaction data from AR.IO gateways. These strategies determine how data is requested and assembled from the underlying storage layer.

StrategyUse CaseRequirements
ContiguousDataRetrievalStrategyStandard data fetching via direct GETGateway has the data cached or able to fetch from trusted peers
ChunkDataRetrievalStrategyChunk-based data assemblyGateway supports /chunk/\<offset\>/data endpoint (r58) and has requested transactions indexed

ContiguousDataRetrievalStrategy

The default strategy that fetches data using a direct GET request to the gateway. This is the most straightforward approach and works for most use cases.

import { Wayfinder, ContiguousDataRetrievalStrategy } from '@ar.io/wayfinder-core';

const wayfinder = new Wayfinder({
  dataRetrievalStrategy: new ContiguousDataRetrievalStrategy(),
});

ChunkDataRetrievalStrategy

An advanced strategy that provides the easiest way to load chunks stored on Arweave nodes via the robust chunk API provided by AR.IO gateways. This approach is particularly useful for:

  • Direct chunk access: Efficiently retrieves data directly from the underlying chunk storage layer
  • Bundled data items: Seamlessly fetches data items from within ANS-104 bundles using calculated offsets
  • x402 payment compatibility: Both strategies support custom fetch clients for payment-enabled requests
  • Large file handling: More reliable for large transactions that may time out with direct requests

Requirements:

  • Gateway must support the /chunk/\<offset\>/data endpoint (added in r58)
  • Gateway must have the requested transaction indexed (offsets are needed to fetch directly from chunks)
import { Wayfinder, ChunkDataRetrievalStrategy } from '@ar.io/wayfinder-core';

const wayfinder = new Wayfinder({
  dataRetrievalStrategy: new ChunkDataRetrievalStrategy(),
});

How it works:

  1. Makes a HEAD request for the requested URL and reads the X-AR-IO-Root-Transaction-Id, X-AR-IO-Root-Data-Offset and Content-Length headers
  2. Queries /tx/{root-tx-id}/offset, which returns the root transaction's end offset and size in the weave, and computes its start offset as offset - size + 1
  3. Adds the root data offset to that start offset to get the absolute offset of the requested data
  4. Fetches /chunk/{offset}/data in a loop, keeping the bytes from X-Arweave-Chunk-Read-Offset onward and moving to X-Arweave-Chunk-Start-Offset plus the chunk length, until Content-Length bytes have been streamed
  5. Rejects any chunk whose X-Arweave-Chunk-Tx-Id does not match the root transaction ID, and fails if the gateway returns no chunk headers at all

Example with createWayfinderClient:

import { createWayfinderClient, ChunkDataRetrievalStrategy } from '@ar.io/wayfinder-core';

const wayfinder = createWayfinderClient({
  dataRetrievalStrategy: new ChunkDataRetrievalStrategy(),
});

// Fetch a data item from within an ANS-104 bundle
const response = await wayfinder.request('ar://data-item-id');

x402 Support

Both data retrieval strategies support custom fetch implementations, allowing you to use x402-enabled fetch clients for paid gateway requests.

import { createWayfinderClient, ChunkDataRetrievalStrategy } from '@ar.io/wayfinder-core';
import { createX402Fetch } from '@ar.io/wayfinder-x402-fetch';

const x402Fetch = createX402Fetch({ /* payment config */ });

const wayfinder = createWayfinderClient({
  fetch: x402Fetch,
  dataRetrievalStrategy: new ChunkDataRetrievalStrategy({
    fetch: x402Fetch,
  }),
});

How is this guide?