@ar.io/wayfinder-core 1.9.2 → 2.0.1

package/README.md

@@ -38,11 +38,18 @@ import {
   NetworkGatewaysProvider,
 } from '@ar.io/wayfinder-core';
 import { ARIO } from '@ar.io/sdk';
+import { createSolanaRpc } from '@solana/kit';
+
+// AR.IO Solana mainnet — program-id overrides are not needed on mainnet
+// (the SDK ships defaults). For devnet, pass explicit program IDs.
+const ario = ARIO.init({
+  rpc: createSolanaRpc('https://api.mainnet-beta.solana.com'),
+});
 
 const wayfinder = createWayfinderClient({
   routingStrategy: new FastestPingRoutingStrategy({
     gatewaysProvider: new NetworkGatewaysProvider({
-      ario: ARIO.mainnet(),
+      ario,
       sortBy: 'operatorStake',
       sortOrder: 'desc',
       limit: 10,
@@ -176,14 +183,19 @@ Gateway providers supply the list of gateways for routing. **By default, `create
 
 #### NetworkGatewaysProvider
 
-Returns a list of gateways from the ARIO Network based on on-chain [Gateway Address Registry](https://docs.ar.io/learn/gateways/gateway-registry). You can specify on-chain metrics for gateways to prioritize the highest quality gateways. This requires installing the `@ar.io/sdk` package and importing the `ARIO` object.
+Returns a list of gateways from the ARIO Network based on on-chain [Gateway Address Registry](https://docs.ar.io/learn/gateways/gateway-registry). You can specify on-chain metrics for gateways to prioritize the highest quality gateways. Requires `@ar.io/sdk` and `@solana/kit`.
 
 ```javascript
 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: ARIO.mainnet(),
+  ario,
   sortBy: 'operatorStake',
   sortOrder: 'desc',
   limit: 10,
@@ -222,13 +234,18 @@ import {
   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: ARIO.mainnet(),
+      ario,
       sortBy: 'operatorStake',
       limit: 10,
     }),
@@ -325,6 +342,11 @@ 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'),
+});
 
 // Example 1: Performance-first with resilience fallback
 const performanceWayfinder = createWayfinderClient({
@@ -334,7 +356,7 @@ const performanceWayfinder = createWayfinderClient({
       new FastestPingRoutingStrategy({
         timeoutMs: 500,
         gatewaysProvider: new NetworkGatewaysProvider({
-          ario: ARIO.mainnet(),
+          ario,
           sortBy: 'operatorStake',
           limit: 10,
         }),
@@ -342,7 +364,7 @@ const performanceWayfinder = createWayfinderClient({
       // Fallback to random selection (guaranteed to work if gateways exist)
       new RandomRoutingStrategy({
         gatewaysProvider: new NetworkGatewaysProvider({
-          ario: ARIO.mainnet(),
+          ario,
           sortBy: 'operatorStake', 
           limit: 20, // Use more gateways for fallback
         }),
@@ -363,7 +385,7 @@ const preferredWayfinder = createWayfinderClient({
       new FastestPingRoutingStrategy({
         timeoutMs: 1000,
         gatewaysProvider: new NetworkGatewaysProvider({
-          ario: ARIO.mainnet(),
+          ario,
           sortBy: 'operatorStake',
           limit: 5, // Only top 5 gateways
         }),
@@ -371,7 +393,7 @@ const preferredWayfinder = createWayfinderClient({
       // Final fallback: any random gateway from a larger pool
       new RandomRoutingStrategy({
         gatewaysProvider: new NetworkGatewaysProvider({
-          ario: ARIO.mainnet(),
+          ario,
           limit: 50, // Larger pool for maximum availability
         }),
       }),
@@ -693,6 +715,14 @@ const wayfinder = createWayfinderClient({
 });
 ```
 
+## Resiliency
+
+Wayfinder includes built-in resiliency features:
+
+- **Gateway retry**: If a gateway returns a 5xx error or a network failure occurs, Wayfinder automatically re-selects a different gateway and retries (up to 3 attempts). Client errors (4xx) are returned immediately without retry.
+- **Fetch timeouts**: All outbound requests include configurable timeouts — 10s for metadata (HEAD, peer list), 30s for data retrieval — to prevent indefinite hangs on slow or dead gateways.
+- **Smart pagination**: `NetworkGatewaysProvider` stops fetching from the on-chain registry once enough gateways pass the filter, avoiding unnecessary RPC calls.
+
 ## Request Flow
 
 ```mermaid

package/dist/constants.d.ts

@@ -39,6 +39,9 @@ export declare const arioHeaderNames: {
     chunkTxId: string;
     chunkTxStartOffset: string;
     rootTransactionId: string;
+    rootPath: string;
+    rootItemOffset: string;
+    rootItemSize: string;
     dataItemDataOffset: string;
     dataItemRootParentOffset: string;
     dataItemOffset: string;
@@ -51,9 +54,17 @@ export declare const arioHeaderNames: {
     arnsRecord: string;
     arnsResolvedId: string;
     dataId: string;
-    arnsProcessId: string;
+    arnsAntProgramId: string;
+    arnsAntId: string;
     arnsResolvedAt: string;
     arnsLimit: string;
     arnsIndex: string;
+    signatureInput: string;
+    signature: string;
+    arweaveOwner: string;
+    arweaveOwnerAddress: string;
+    arweaveSignature: string;
+    arweaveSignatureType: string;
+    arweaveTagCount: string;
 };
 //# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,eAAO,MAAM,SAAS,QAA2C,CAAC;AAClE,eAAO,MAAM,SAAS,QAAwB,CAAC;AAG/C,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuC3B,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,eAAO,MAAM,SAAS,QAA2C,CAAC;AAClE,eAAO,MAAM,SAAS,QAAwB,CAAC;AAG/C,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoD3B,CAAC"}

package/dist/constants.js

@@ -41,6 +41,9 @@ export const arioHeaderNames = {
     chunkTxId: 'X-Arweave-Chunk-Tx-Id',
     chunkTxStartOffset: 'X-Arweave-Chunk-Tx-Start-Offset',
     rootTransactionId: 'X-AR-IO-Root-Transaction-Id',
+    rootPath: 'X-AR-IO-Root-Path',
+    rootItemOffset: 'X-AR-IO-Root-Item-Offset',
+    rootItemSize: 'X-AR-IO-Root-Item-Size',
     dataItemDataOffset: 'X-AR-IO-Data-Item-Data-Offset',
     dataItemRootParentOffset: 'X-AR-IO-Data-Item-Root-Parent-Offset',
     dataItemOffset: 'X-AR-IO-Data-Item-Offset',
@@ -53,8 +56,18 @@ export const arioHeaderNames = {
     arnsRecord: 'X-ArNS-Record',
     arnsResolvedId: 'X-ArNS-Resolved-Id',
     dataId: 'X-AR-IO-Data-Id',
-    arnsProcessId: 'X-ArNS-Process-Id',
+    arnsAntProgramId: 'X-ArNS-Ant-Program-Id',
+    arnsAntId: 'X-ArNS-Ant-Id',
     arnsResolvedAt: 'X-ArNS-Resolved-At',
     arnsLimit: 'X-ArNS-Undername-Limit',
     arnsIndex: 'X-ArNS-Record-Index',
+    // HTTPSIG headers (RFC 9421)
+    signatureInput: 'Signature-Input',
+    signature: 'Signature',
+    // Arweave transaction metadata
+    arweaveOwner: 'X-Arweave-Owner',
+    arweaveOwnerAddress: 'X-Arweave-Owner-Address',
+    arweaveSignature: 'X-Arweave-Signature',
+    arweaveSignatureType: 'X-Arweave-Signature-Type',
+    arweaveTagCount: 'X-Arweave-Tag-Count',
 };

package/dist/fetch/wayfinder-fetch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wayfinder-fetch.d.ts","sourceRoot":"","sources":["../../src/fetch/wayfinder-fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH,OAAO,KAAK,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAS/E;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,oBAAoB,GAAI,mHAYlC,qBAAqB,KAAG,CAAC,CAC1B,KAAK,EAAE,GAAG,GAAG,WAAW,EACxB,IAAI,CAAC,EAAE,oBAAoB,KACxB,OAAO,CAAC,QAAQ,CAAC,CA4MrB,CAAC"}
+{"version":3,"file":"wayfinder-fetch.d.ts","sourceRoot":"","sources":["../../src/fetch/wayfinder-fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAOH,OAAO,KAAK,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAS/E;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,oBAAoB,GAAI,mHAYlC,qBAAqB,KAAG,CAAC,CAC1B,KAAK,EAAE,GAAG,GAAG,WAAW,EACxB,IAAI,CAAC,EAAE,oBAAoB,KACxB,OAAO,CAAC,QAAQ,CAAC,CA0PrB,CAAC"}

package/dist/fetch/wayfinder-fetch.js

@@ -94,43 +94,78 @@ export const createWayfinderFetch = ({ logger = defaultLogger, strict = false, f
                 subdomain,
                 path,
             });
-            // Select gateway using routing strategy
-            const selectedGateway = await routingStrategy.selectGateway({
-                path,
-                subdomain,
-            });
-            // it's just a non data specific request, construct the gateway URL and fetch directly
-            const redirectUrl = constructGatewayUrl({
-                selectedGateway,
-                subdomain,
-                path,
-            });
-            // Emit routing succeeded event
-            requestEmitter.emit('routing-succeeded', {
-                originalUrl: requestUri,
-                selectedGateway: selectedGateway.toString(),
-                redirectUrl: redirectUrl.toString(),
-            });
-            // if its a txId or arnsName use the dataRetrievalStrategy to fetch the data; otherwise just call internal fetch
-            if (!txId && !arnsName) {
-                logger.debug('No transaction ID or ARNS name found, performing direct fetch', {
-                    uri: requestUri,
-                });
-                return fetch(redirectUrl.toString(), init);
+            // Attempt data retrieval with gateway retry. If the selected gateway
+            // fails (network error, 5xx, timeout), re-select and try again up to
+            // maxAttempts times. 4xx responses are NOT retried (client error).
+            const maxAttempts = 3;
+            let dataResponse;
+            let selectedGateway;
+            let redirectUrl;
+            let lastError;
+            for (let attempt = 0; attempt < maxAttempts; attempt++) {
+                try {
+                    selectedGateway = await routingStrategy.selectGateway({
+                        path,
+                        subdomain,
+                    });
+                    redirectUrl = constructGatewayUrl({
+                        selectedGateway,
+                        subdomain,
+                        path,
+                    });
+                    // Emit routing succeeded event
+                    requestEmitter.emit('routing-succeeded', {
+                        originalUrl: requestUri,
+                        selectedGateway: selectedGateway.toString(),
+                        redirectUrl: redirectUrl.toString(),
+                    });
+                    // Non-data requests (e.g. /ar-io/info) don't need retry
+                    if (!txId && !arnsName) {
+                        logger.debug('No transaction ID or ARNS name found, performing direct fetch', { uri: requestUri });
+                        return fetch(redirectUrl.toString(), init);
+                    }
+                    const requestHeaders = {
+                        ...Object.fromEntries(new Headers(init?.headers || {})),
+                        ...createWayfinderRequestHeaders({
+                            traceId: requestSpan?.spanContext().traceId,
+                        }),
+                    };
+                    dataResponse = await dataRetrievalStrategy.getData({
+                        gateway: selectedGateway,
+                        requestUrl: redirectUrl,
+                        headers: requestHeaders,
+                    });
+                    // 4xx = client error, don't retry; 2xx/3xx = success
+                    if (dataResponse.ok ||
+                        (dataResponse.status >= 400 && dataResponse.status < 500)) {
+                        break;
+                    }
+                    // 5xx = server error, retry with different gateway
+                    logger.warn('Gateway returned server error, retrying with different gateway', {
+                        uri: requestUri,
+                        gateway: selectedGateway.toString(),
+                        status: dataResponse.status,
+                        attempt: attempt + 1,
+                        maxAttempts,
+                    });
+                }
+                catch (error) {
+                    lastError = error;
+                    if (attempt < maxAttempts - 1) {
+                        logger.warn('Gateway request failed, retrying with different gateway', {
+                            uri: requestUri,
+                            gateway: selectedGateway?.toString(),
+                            error: error.message,
+                            attempt: attempt + 1,
+                            maxAttempts,
+                        });
+                    }
+                }
+            }
+            // All attempts exhausted
+            if (!dataResponse) {
+                throw lastError ?? new Error('All gateway attempts failed');
             }
-            const requestHeaders = {
-                ...Object.fromEntries(new Headers(init?.headers || {})),
-                ...createWayfinderRequestHeaders({
-                    traceId: requestSpan?.spanContext().traceId,
-                }),
-            };
-            // Use data retrieval strategy to fetch the actual data
-            const dataResponse = await dataRetrievalStrategy.getData({
-                gateway: selectedGateway,
-                requestUrl: redirectUrl,
-                headers: requestHeaders,
-            });
-            // If the response is not successful (e.g., 404, 500), return it directly
             if (!dataResponse.ok) {
                 logger.debug('Gateway returned error response', {
                     uri: requestUri,

package/dist/gateways/network.d.ts

@@ -14,7 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import type { AoARIORead } from '@ar.io/sdk';
+import type { ARIORead } from '@ar.io/sdk';
 import type { GatewaysProvider, Logger, SortBy, SortOrder } from '../types.js';
 export declare class NetworkGatewaysProvider implements GatewaysProvider {
     private ario;
@@ -24,7 +24,7 @@ export declare class NetworkGatewaysProvider implements GatewaysProvider {
     private filter;
     private logger;
     constructor({ ario, sortBy, sortOrder, limit, filter, logger, }: {
-        ario: AoARIORead;
+        ario: ARIORead;
         sortBy?: SortBy;
         sortOrder?: SortOrder;
         limit?: number;

package/dist/gateways/network.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../src/gateways/network.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE/E,qBAAa,uBAAwB,YAAW,gBAAgB;IAC9D,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,MAAM,CAAS;gBAEX,EACV,IAAI,EACJ,MAAwB,EACxB,SAAkB,EAClB,KAAY,EACZ,MAAqC,EACrC,MAAsB,GACvB,EAAE;QACD,IAAI,EAAE,UAAU,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,SAAS,CAAC;QACtB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QACrB,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,OAAO,CAAC;QACnC,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB;IASK,WAAW,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;CA2DpC"}
+{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../src/gateways/network.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE/E,qBAAa,uBAAwB,YAAW,gBAAgB;IAC9D,OAAO,CAAC,IAAI,CAAW;IACvB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,MAAM,CAAS;gBAEX,EACV,IAAI,EACJ,MAAwB,EACxB,SAAkB,EAClB,KAAY,EACZ,MAAqC,EACrC,MAAsB,GACvB,EAAE;QACD,IAAI,EAAE,QAAQ,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,SAAS,CAAC;QACtB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QACrB,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,OAAO,CAAC;QACnC,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB;IASK,WAAW,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;CAwEpC"}

package/dist/gateways/network.js

@@ -23,24 +23,36 @@ export class NetworkGatewaysProvider {
             sortOrder: this.sortOrder,
             limit: this.limit,
         });
+        // Fetch enough gateways to satisfy the limit after filtering.
+        // Request up to limit per page (capped at 1000 by the SDK) and
+        // stop paginating once we have enough filtered results.
+        const pageSize = Math.min(this.limit, 1000);
         do {
             try {
                 this.logger.debug('Fetching gateways batch', { cursor, attempts });
                 const { items: newGateways = [], nextCursor } = await this.ario.getGateways({
-                    limit: 1000,
+                    limit: pageSize,
                     cursor,
                     sortBy: this.sortBy,
                     sortOrder: this.sortOrder,
-                    // TODO: support filters on gateways
                 });
                 gateways.push(...newGateways);
                 cursor = nextCursor;
-                attempts = 0; // reset attempts if we get a new cursor
+                attempts = 0;
                 this.logger.debug('Fetched gateways batch', {
                     batchSize: newGateways.length,
                     totalFetched: gateways.length,
                     nextCursor: cursor,
                 });
+                // Stop early if we already have enough gateways that pass the filter
+                const filteredSoFar = gateways.filter(this.filter);
+                if (filteredSoFar.length >= this.limit) {
+                    this.logger.debug('Reached gateway limit, stopping pagination', {
+                        filteredCount: filteredSoFar.length,
+                        limit: this.limit,
+                    });
+                    break;
+                }
             }
             catch (error) {
                 this.logger.error('Error fetching gateways', {
@@ -52,7 +64,6 @@ export class NetworkGatewaysProvider {
                 attempts++;
             }
         } while (cursor !== undefined && attempts < 3);
-        // filter out any gateways that are not joined
         const filteredGateways = gateways.filter(this.filter).slice(0, this.limit);
         this.logger.debug('Finished fetching gateways', {
             totalFetched: gateways.length,

package/dist/gateways/trusted-peers.d.ts

@@ -23,9 +23,11 @@ import type { GatewaysProvider, Logger } from '../types.js';
 export declare class TrustedPeersGatewaysProvider implements GatewaysProvider {
     private trustedGateway;
     private logger;
-    constructor({ trustedGateway, logger, }: {
+    private timeoutMs;
+    constructor({ trustedGateway, logger, timeoutMs, }: {
         trustedGateway: string | URL;
         logger?: Logger;
+        timeoutMs?: number;
     });
     getGateways(): Promise<URL[]>;
 }

package/dist/gateways/trusted-peers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trusted-peers.d.ts","sourceRoot":"","sources":["../../src/gateways/trusted-peers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH;;;;GAIG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE5D,qBAAa,4BAA6B,YAAW,gBAAgB;IACnE,OAAO,CAAC,cAAc,CAAM;IAC5B,OAAO,CAAC,MAAM,CAAS;gBAEX,EACV,cAAc,EACd,MAAsB,GACvB,EAAE;QAAE,cAAc,EAAE,MAAM,GAAG,GAAG,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;IAK9C,WAAW,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;CAoCpC"}
+{"version":3,"file":"trusted-peers.d.ts","sourceRoot":"","sources":["../../src/gateways/trusted-peers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH;;;;GAIG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE5D,qBAAa,4BAA6B,YAAW,gBAAgB;IACnE,OAAO,CAAC,cAAc,CAAM;IAC5B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAS;gBAEd,EACV,cAAc,EACd,MAAsB,EACtB,SAAkB,GACnB,EAAE;QAAE,cAAc,EAAE,MAAM,GAAG,GAAG,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE;IAMlE,WAAW,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;CAuCpC"}

package/dist/gateways/trusted-peers.js

@@ -23,14 +23,19 @@ import { defaultLogger } from '../logger.js';
 export class TrustedPeersGatewaysProvider {
     trustedGateway;
     logger;
-    constructor({ trustedGateway, logger = defaultLogger, }) {
+    timeoutMs;
+    constructor({ trustedGateway, logger = defaultLogger, timeoutMs = 10_000, }) {
         this.trustedGateway = new URL(trustedGateway.toString());
         this.logger = logger;
+        this.timeoutMs = timeoutMs;
     }
     async getGateways() {
         const endpoint = new URL('/ar-io/peers', this.trustedGateway).toString();
         this.logger.debug('Fetching trusted peer list from', { endpoint });
-        const response = await fetch(endpoint, { method: 'GET' });
+        const response = await fetch(endpoint, {
+            method: 'GET',
+            signal: AbortSignal.timeout(this.timeoutMs),
+        });
         if (!response.ok) {
             throw new Error(`Failed to fetch trusted peer list: ${response.status} ${response.statusText} ${await response.text()}`);
         }

package/dist/retrieval/chunk.d.ts

@@ -23,9 +23,13 @@ import type { DataRetrievalStrategy, Logger } from '../types.js';
 export declare class ChunkDataRetrievalStrategy implements DataRetrievalStrategy {
     private logger;
     private fetch;
-    constructor({ logger, fetch, }?: {
+    private metadataTimeoutMs;
+    private chunkTimeoutMs;
+    constructor({ logger, fetch, metadataTimeoutMs, chunkTimeoutMs, }?: {
         logger?: Logger;
         fetch?: typeof globalThis.fetch;
+        metadataTimeoutMs?: number;
+        chunkTimeoutMs?: number;
     });
     getData({ gateway, requestUrl, headers, }: {
         gateway: URL;

package/dist/retrieval/chunk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk.d.ts","sourceRoot":"","sources":["../../src/retrieval/chunk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAEjE;;;;GAIG;AACH,qBAAa,0BAA2B,YAAW,qBAAqB;IACtE,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,KAAK,CAA0B;gBAE3B,EACV,MAAsB,EACtB,KAAwB,GACzB,GAAE;QACD,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;KAC5B;IAKA,OAAO,CAAC,EACZ,OAAO,EACP,UAAU,EACV,OAAO,GACR,EAAE;QACD,OAAO,EAAE,GAAG,CAAC;QACb,UAAU,EAAE,GAAG,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAClC,GAAG,OAAO,CAAC,QAAQ,CAAC;CAwOtB"}
+{"version":3,"file":"chunk.d.ts","sourceRoot":"","sources":["../../src/retrieval/chunk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAEjE;;;;GAIG;AACH,qBAAa,0BAA2B,YAAW,qBAAqB;IACtE,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,cAAc,CAAS;gBAEnB,EACV,MAAsB,EACtB,KAAwB,EACxB,iBAA0B,EAC1B,cAAuB,GACxB,GAAE;QACD,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;QAChC,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;KACpB;IAOA,OAAO,CAAC,EACZ,OAAO,EACP,UAAU,EACV,OAAO,GACR,EAAE;QACD,OAAO,EAAE,GAAG,CAAC;QACb,UAAU,EAAE,GAAG,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAClC,GAAG,OAAO,CAAC,QAAQ,CAAC;CA4OtB"}

package/dist/retrieval/chunk.js

@@ -24,9 +24,13 @@ import { defaultLogger } from '../logger.js';
 export class ChunkDataRetrievalStrategy {
     logger;
     fetch;
-    constructor({ logger = defaultLogger, fetch = globalThis.fetch, } = {}) {
+    metadataTimeoutMs;
+    chunkTimeoutMs;
+    constructor({ logger = defaultLogger, fetch = globalThis.fetch, metadataTimeoutMs = 10_000, chunkTimeoutMs = 30_000, } = {}) {
         this.logger = logger;
         this.fetch = fetch;
+        this.metadataTimeoutMs = metadataTimeoutMs;
+        this.chunkTimeoutMs = chunkTimeoutMs;
     }
     async getData({ gateway, requestUrl, headers, }) {
         this.logger.debug('Fetching data via ChunkDataRetrievalStrategy from gateway', {
@@ -35,6 +39,7 @@ export class ChunkDataRetrievalStrategy {
         });
         const headResponse = await this.fetch(requestUrl.toString(), {
             method: 'HEAD',
+            signal: AbortSignal.timeout(this.metadataTimeoutMs),
             headers,
         });
         if (!headResponse.ok) {
@@ -56,6 +61,7 @@ export class ChunkDataRetrievalStrategy {
         const offsetResponse = await this.fetch(offsetForRootTransactionIdUrl.toString(), {
             method: 'GET',
             redirect: 'follow',
+            signal: AbortSignal.timeout(this.metadataTimeoutMs),
             headers,
         });
         if (!offsetResponse.ok) {
@@ -86,6 +92,7 @@ export class ChunkDataRetrievalStrategy {
         const logger = this.logger;
         const fetchFn = this.fetch;
         const chunkGateway = gateway;
+        const chunkTimeoutMs = this.chunkTimeoutMs;
         // Create a readable stream that fetches chunks on demand
         const stream = new ReadableStream({
             async start(controller) {
@@ -103,6 +110,7 @@ export class ChunkDataRetrievalStrategy {
                         const chunkResponse = await fetchFn(chunkUrl.toString(), {
                             method: 'GET',
                             redirect: 'follow',
+                            signal: AbortSignal.timeout(chunkTimeoutMs),
                             headers,
                         });
                         if (!chunkResponse.ok) {

package/dist/retrieval/contiguous.d.ts

@@ -22,9 +22,11 @@ import type { DataRetrievalStrategy, Logger } from '../types.js';
 export declare class ContiguousDataRetrievalStrategy implements DataRetrievalStrategy {
     private logger;
     private fetch;
-    constructor({ logger, fetch, }?: {
+    private timeoutMs;
+    constructor({ logger, fetch, timeoutMs, }?: {
         logger?: Logger;
         fetch?: typeof globalThis.fetch;
+        timeoutMs?: number;
     });
     getData({ requestUrl, headers, }: {
         gateway: URL;

package/dist/retrieval/contiguous.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contiguous.d.ts","sourceRoot":"","sources":["../../src/retrieval/contiguous.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAEjE;;;GAGG;AACH,qBAAa,+BAAgC,YAAW,qBAAqB;IAC3E,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,KAAK,CAA0B;gBAE3B,EACV,MAAsB,EACtB,KAAwB,GACzB,GAAE;QACD,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;KAC5B;IAKA,OAAO,CAAC,EACZ,UAAU,EACV,OAAO,GACR,EAAE;QACD,OAAO,EAAE,GAAG,CAAC;QACb,UAAU,EAAE,GAAG,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAClC,GAAG,OAAO,CAAC,QAAQ,CAAC;CAatB"}
+{"version":3,"file":"contiguous.d.ts","sourceRoot":"","sources":["../../src/retrieval/contiguous.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAEjE;;;GAGG;AACH,qBAAa,+BAAgC,YAAW,qBAAqB;IAC3E,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,SAAS,CAAS;gBAEd,EACV,MAAsB,EACtB,KAAwB,EACxB,SAAkB,GACnB,GAAE;QACD,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;QAChC,SAAS,CAAC,EAAE,MAAM,CAAC;KACf;IAMA,OAAO,CAAC,EACZ,UAAU,EACV,OAAO,GACR,EAAE;QACD,OAAO,EAAE,GAAG,CAAC;QACb,UAAU,EAAE,GAAG,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAClC,GAAG,OAAO,CAAC,QAAQ,CAAC;CActB"}

package/dist/retrieval/contiguous.js

@@ -22,9 +22,11 @@ import { defaultLogger } from '../logger.js';
 export class ContiguousDataRetrievalStrategy {
     logger;
     fetch;
-    constructor({ logger = defaultLogger, fetch = globalThis.fetch, } = {}) {
+    timeoutMs;
+    constructor({ logger = defaultLogger, fetch = globalThis.fetch, timeoutMs = 30_000, } = {}) {
         this.logger = logger;
         this.fetch = fetch;
+        this.timeoutMs = timeoutMs;
     }
     async getData({ requestUrl, headers, }) {
         this.logger.debug('Fetching contiguous transaction data', {
@@ -32,6 +34,7 @@ export class ContiguousDataRetrievalStrategy {
         });
         return this.fetch(requestUrl.toString(), {
             method: 'GET',
+            signal: AbortSignal.timeout(this.timeoutMs),
             headers: {
                 ...headers,
                 'x-wayfinder-data-retrieval-strategy': 'contiguous',

package/dist/version.d.ts

@@ -14,5 +14,5 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-export declare const WAYFINDER_CORE_VERSION = "v1.9.2";
+export declare const WAYFINDER_CORE_VERSION = "v2.0.1";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -14,4 +14,4 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-export const WAYFINDER_CORE_VERSION = 'v1.9.2';
+export const WAYFINDER_CORE_VERSION = 'v2.0.1';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ar.io/wayfinder-core",
-  "version": "1.9.2",
+  "version": "2.0.1",
   "description": "WayFinder core library for intelligently routing to optimal AR.IO gateways",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -44,7 +44,8 @@
     "clean": "rimraf dist",
     "update-version": "node scripts/update-version.mjs",
     "test": "npm run test:unit",
-    "test:unit": "c8 tsx --test 'src/**/*.test.ts'",
+    "test:unit": "c8 tsx --test 'src/client.test.ts' 'src/routing/*.test.ts' 'src/gateways/*.test.ts' 'src/retrieval/*.test.ts' 'src/verification/*.test.ts' 'src/utils/*.test.ts'",
+    "test:integration": "c8 tsx --test 'src/wayfinder.test.ts'",
     "lint:fix": "biome check --write --unsafe --config-path=../../biome.json",
     "lint:check": "biome check --unsafe --config-path=../../biome.json",
     "format:fix": "biome format --write --config-path=../../biome.json",
@@ -65,7 +66,7 @@
     "zone.js": "^0.15.1"
   },
   "peerDependencies": {
-    "@ar.io/sdk": ">=3.12.0"
+    "@ar.io/sdk": ">=4.0.0"
   },
   "peerDependenciesMeta": {
     "@ar.io/sdk": {
@@ -73,7 +74,7 @@
     }
   },
   "devDependencies": {
-    "@ar.io/sdk": "^3.13.0",
+    "@ar.io/sdk": "^4.0.2",
     "@types/node": "^24.0.0",
     "tsx": "^4.20.3"
   }