@ar.io/wayfinder-core 1.3.1 → 1.4.0-alpha.0

package/README.md

@@ -17,21 +17,96 @@ yarn add @ar.io/wayfinder-core
 ### Basic Usage
 
 ```javascript
+import { createWayfinderClient } from '@ar.io/wayfinder-core';
+
+// Uses static gateways by default
+const wayfinder = createWayfinderClient();
+
+// Use Wayfinder to fetch and verify data using ar:// protocol
+const response = await wayfinder.request('ar://example-name');
+```
+
+### Using with AR.IO Network
+
+```javascript
+import { createWayfinderClient } from '@ar.io/wayfinder-core';
 import { ARIO } from '@ar.io/sdk';
-import { Wayfinder } from '@ar.io/wayfinder-core';
 
-// create a new Wayfinder instance that uses the top 10 gateways by operator stake from the ARIO Network
-const wayfinder = new Wayfinder({
-  gatewaysProvider: new NetworkGatewaysProvider({
-    ario: ARIO.mainnet(),
-    sortBy: 'operatorStake',
-    sortOrder: 'desc',
-    limit: 10,
-  }),
+// Provide ARIO instance to use AR.IO network gateways
+const wayfinder = createWayfinderClient({
+  ario: ARIO.mainnet(),
+  gatewaySelection: 'highest-performing', // Selection criteria for AR.IO network
 });
+```
 
-// use Wayfinder to fetch and verify data using ar:// protocol
-const response = await wayfinder.request('ar://example-name');
+### Static Gateways with Custom Options
+
+```javascript
+import { createWayfinderClient } from '@ar.io/wayfinder-core';
+
+// Use custom static gateways
+const wayfinder = createWayfinderClient({
+  trustedGateways: ['https://permagate.io', 'https://arweave.net'],
+  routing: 'fastest',
+  verification: 'hash',
+});
+```
+
+### Configuration Options
+
+`createWayfinderClient` accepts the following options:
+
+```javascript
+const wayfinder = createWayfinderClient({
+  // Routing strategy
+  routing: 'fastest', // 'random' | 'fastest' | 'round-robin' | 'preferred'
+  
+  // Verification strategy  
+  verification: 'hash', // 'hash' | 'data-root' | 'remote' | 'disabled' (default: 'disabled')
+  
+  // Gateway selection (only applies when ario instance is provided)
+  gatewaySelection: 'highest-performing', // 'highest-performing' | 'longest-tenure' | etc.
+  
+  // Enable caching for routing and gateway providers
+  cache: true, // Uses default 5-minute TTL
+  // OR specify custom TTL:
+  // cache: { ttlSeconds: 3600 }, // 1 hour
+  
+  // List of trusted gateways for verification
+  trustedGateways: ['https://arweave.net', 'https://permagate.io'],
+});
+
+// Sync version with static gateways (when no ario instance provided)
+const wayfinderSync = createWayfinderClientSync({
+  // Same options as above, but uses static gateways by default
+  routing: 'random',
+  verification: 'disabled',
+  trustedGateways: ['https://permagate.io', 'https://arweave.net'],
+});
+```
+
+### Gateway Selection Options (with AR.IO Network)
+
+When using the AR.IO Network provider, you can specify how gateways are selected:
+
+```javascript
+import { createWayfinderClient } from '@ar.io/wayfinder-core';
+import { ARIO } from '@ar.io/sdk';
+
+const wayfinder = createWayfinderClient({
+  ario: ARIO.mainnet(),
+  
+  // Gateway selection (only works with ARIO instance)
+  gatewaySelection: 'highest-performing', // Options:
+  // 'highest-performing' - Gateways with best performance metrics
+  // 'longest-tenure' - Gateways with longest service history  
+  // 'highest-staked' - Gateways with most stake
+  // 'highest-weight' - Gateways with highest composite weight
+  // 'longest-streak' - Gateways with longest uptime streak
+  
+  routing: 'random', // How to select from the filtered gateways
+  cache: { ttlSeconds: 600 }, // Cache for 10 minutes
+});
 ```
 
 ## ar:// Protocol
@@ -259,21 +334,34 @@ const strategy = new SimpleCacheRoutingStrategy({
 
 #### Preferred gateway with fallback to ping-random
 
-Attempt to use a favorite gateway, but fall back to a ping-checked random choice
-if it fails.
+Attempt to use a favorite gateway, but fallback to a fastest pinging strategy using the ARIO Network if it fails.
 
 ```ts
 import {
   PreferredWithFallbackRoutingStrategy,
   RandomRoutingStrategy,
   PingRoutingStrategy,
+  NetworkGatewaysProvider,
 } from "@ar.io/wayfinder-core";
+import { ARIO } from '@ar.io/sdk';
+
+// these will be our fallback gateways
+const gatewayProvider = new NetworkGatewaysProvider({
+  ario: ARIO.mainnet(),
+  sortBy: 'operatorStake',
+  limit: 5,
+});
+
+// this is our fallback strategy if our preferred gateway fails
+const fastestPingStrategy = new FastestPingRoutingStrategy({
+  timeoutMs: 500,
+  gatewaysProvider: gatewayProvider,
+});
 
+// compose the strategies together, the preferred gateway will be used first, and if it fails, the fallback strategy will be used.
 const strategy = new PreferredWithFallbackRoutingStrategy({
   preferredGateway: "https://my-gateway.example",
-  fallbackStrategy: new PingRoutingStrategy({
-    routingStrategy: new RandomRoutingStrategy(),
-  }),
+  fallbackStrategy: fastestPingStrategy,
 });
 ```
 
@@ -285,13 +373,27 @@ Cycle through gateways sequentially, checking each one’s health before use.
 import {
   RoundRobinRoutingStrategy,
   PingRoutingStrategy,
+  NetworkGatewaysProvider,
 } from "@ar.io/wayfinder-core";
+import { ARIO } from '@ar.io/sdk';
 
+// use static gateways
 const strategy = new PingRoutingStrategy({
   routingStrategy: new RoundRobinRoutingStrategy({
     gateways: [new URL("https://gw1"), new URL("https://gw2")],
   }),
 });
+
+// use a dynamic list of gateways from the ARIO Network
+const strategy2 = new PingRoutingStrategy({
+  routingStrategy: new RoundRobinRoutingStrategy({
+    gatewaysProvider: new NetworkGatewaysProvider({
+      ario: ARIO.mainnet(),
+      sortBy: 'operatorStake',
+      limit: 5,
+    }),
+  }),
+});
 ```
 
 #### Cache around any composed strategy
@@ -300,10 +402,21 @@ Because `SimpleCacheRoutingStrategy` accepts any `RoutingStrategy`, you can
 cache more complex compositions too.
 
 ```ts
+// use a dynamic list of gateways from the ARIO Network
+const randomStrategy = new RandomRoutingStrategy({
+  gatewaysProvider: new NetworkGatewaysProvider({
+    ario: ARIO.mainnet(),
+    sortBy: 'operatorStake',
+    limit: 20,
+  }),
+});
+
+// wrap the random strategy with a ping strategy
 const pingRandom = new PingRoutingStrategy({
-  routingStrategy: new RandomRoutingStrategy(),
+  routingStrategy: randomStrategy,
 });
 
+// wrap the ping random strategy with a cache strategy, caching the selected gateway for 10 minutes
 const cachedStrategy = new SimpleCacheRoutingStrategy({
   routingStrategy: pingRandom,
   ttlSeconds: 600,
@@ -510,13 +623,77 @@ const response = await wayfinder.request('ar://example-name', {
 });
 ```
 
+## Installation Notes
+
+### Optional Dependencies
+
+The `@ar.io/sdk` package is an optional peer dependency. To use AR.IO network gateways, you must explicitly provide an `ario` instance:
+
+**With AR.IO SDK (Recommended):**
+```bash
+npm install @ar.io/wayfinder-core @ar.io/sdk
+# or
+yarn add @ar.io/wayfinder-core @ar.io/sdk
+```
+- `createWayfinderClient({ ario: ARIO.mainnet() })` uses AR.IO network gateways
+- Supports intelligent gateway selection criteria
+- Dynamic gateway discovery and updates
+
+**Without AR.IO SDK:**
+```bash
+npm install @ar.io/wayfinder-core
+```
+- `createWayfinderClient()` falls back to curated static gateways
+- `createWayfinderClientSync()` uses only static gateways
+- Full routing and verification functionality available
+- No network gateway selection options
+
+### Caching
+
+Wayfinder supports intelligent caching:
+
+- **In browsers**: Uses localStorage for persistent caching across page reloads
+- **In Node.js**: Uses in-memory caching
+- **What's cached**: Gateway lists, routing decisions, and more
+- **Cache configuration**:
+  - `cache: true` - Enable with default 5-minute TTL
+  - `cache: { ttlSeconds: 3600 }` - Enable with custom TTL (in seconds)
+  - `cache: false` - Disable caching (default)
+
 ## Advanced Usage
 
-### Custom Configuration
+### Using createWayfinderClient with Custom Providers
+
+For advanced use cases, you can provide custom providers and strategies to `createWayfinderClient`:
+
+```javascript
+import { createWayfinderClient, NetworkGatewaysProvider } from '@ar.io/wayfinder-core';
+import { ARIO } from '@ar.io/sdk';
+
+const wayfinder = createWayfinderClient({
+  // Use custom gateways provider
+  gatewaysProvider: new NetworkGatewaysProvider({
+    ario: ARIO.mainnet(),
+    sortBy: 'operatorStake',
+    sortOrder: 'desc',
+    limit: 10,
+  }),
+  
+  // Override with custom verification strategy
+  verification: 'hash',
+  trustedGateways: ['https://permagate.io'],
+  
+  // Gateway selection
+  gatewaySelection: 'highest-staked',
+  
+  // Enable caching with custom TTL
+  cache: { ttlSeconds: 3600 }, // 1 hour
+});
+```
 
-You can customize the wayfinder instance with different gateways, verification strategies, and routing strategies based on your use case.
+### Direct Constructor Usage
 
-Example:
+For complete control, you can use the Wayfinder constructor directly. This is useful when you need fine-grained control over the configuration:
 
 > _Wayfinder client that caches the top 10 gateways by operator stake from the ARIO Network for 1 hour and uses the fastest pinging routing strategy to select the fastest gateway for requests._
 

package/dist/client.d.ts

@@ -0,0 +1,89 @@
+/**
+ * WayFinder
+ * Copyright (C) 2022-2025 Permanent Data Solutions, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { AoARIORead } from '@ar.io/sdk';
+import type { GatewaysProvider, Logger, RoutingStrategy, VerificationStrategy } from './types.js';
+import { Wayfinder } from './wayfinder.js';
+export type RoutingOption = 'random' | 'fastest' | 'round-robin' | 'preferred';
+export type VerificationOption = 'hash' | 'data-root' | 'remote' | 'disabled';
+export type GatewaySelection = 'highest-performing' | 'longest-tenure' | 'highest-staked' | 'highest-weight' | 'longest-streak';
+/**
+ * Creates a Wayfinder client synchronously using static gateways
+ * Use this when you want to avoid the AR.IO SDK dependency
+ */
+export declare function createWayfinderClientSync(options?: CreateWayfinderClientOptions): Wayfinder;
+export interface CreateWayfinderClientOptions {
+    /**
+     * The ARIO instance to use for network gateways provider
+     * If not provided, will fall back to static gateways
+     */
+    ario?: AoARIORead;
+    /**
+     * The routing strategy to use
+     * @default 'random'
+     */
+    routing?: RoutingOption;
+    /**
+     * The verification strategy to use
+     * @default 'disabled'
+     */
+    verification?: VerificationOption;
+    /**
+     * The gateway selection when using NetworkGatewaysProvider (requires ario instance)
+     * Only applies when using AR.IO network - ignored for static gateways
+     * @default 'highest-performing'
+     */
+    gatewaySelection?: GatewaySelection;
+    /**
+     * The trusted gateways to use
+     * @default ['https://arweave.net']
+     */
+    trustedGateways?: string[];
+    /**
+     * Cache configuration. Can be:
+     * - false/undefined: No caching
+     * - true: Enable caching with default TTL (300 seconds)
+     * - { ttlSeconds: number }: Enable caching with custom TTL
+     * @default false
+     */
+    cache?: boolean | {
+        ttlSeconds: number;
+    };
+    /**
+     * Custom logger implementation
+     */
+    logger?: Logger;
+    /**
+     * Custom gateways provider (overrides gatewaySelection)
+     */
+    gatewaysProvider?: GatewaysProvider;
+    /**
+     * Custom routing strategy (overrides routing option)
+     */
+    routingStrategy?: RoutingStrategy;
+    /**
+     * Custom verification strategy (overrides verification option)
+     */
+    verificationStrategy?: VerificationStrategy;
+}
+/**
+ * Creates a Wayfinder client with the specified configuration
+ * Uses static gateways by default. Provide an `ario` instance to use NetworkGatewaysProvider
+ */
+export declare function createWayfinderClient(options?: CreateWayfinderClientOptions): Wayfinder;
+export declare const createWayfinder: typeof createWayfinderClient;
+export declare const createWayfinderSync: typeof createWayfinderClientSync;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAS7C,OAAO,KAAK,EACV,gBAAgB,EAChB,MAAM,EACN,eAAe,EACf,oBAAoB,EAErB,MAAM,YAAY,CAAC;AAKpB,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,SAAS,GAAG,aAAa,GAAG,WAAW,CAAC;AAE/E,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,WAAW,GAAG,QAAQ,GAAG,UAAU,CAAC;AAE9E,MAAM,MAAM,gBAAgB,GACxB,oBAAoB,GACpB,gBAAgB,GAChB,gBAAgB,GAChB,gBAAgB,GAChB,gBAAgB,CAAC;AAErB;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,GAAE,4BAAiC,GACzC,SAAS,CAoLX;AAED,MAAM,WAAW,4BAA4B;IAC3C;;;OAGG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB;;;OAGG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;IAExB;;;OAGG;IACH,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAElC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAEpC;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAE3B;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,OAAO,GAAG;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAEzC;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAEpC;;OAEG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;IAElC;;OAEG;IACH,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;CAC7C;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,GAAE,4BAAiC,GACzC,SAAS,CAmLX;AAGD,eAAO,MAAM,eAAe,8BAAwB,CAAC;AACrD,eAAO,MAAM,mBAAmB,kCAA4B,CAAC"}

package/dist/client.js

@@ -0,0 +1,353 @@
+/**
+ * WayFinder
+ * Copyright (C) 2022-2025 Permanent Data Solutions, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { LocalStorageGatewaysProvider } from './gateways/local-storage-cache.js';
+import { NetworkGatewaysProvider } from './gateways/network.js';
+import { SimpleCacheGatewaysProvider } from './gateways/simple-cache.js';
+import { StaticGatewaysProvider } from './gateways/static.js';
+import { FastestPingRoutingStrategy } from './routing/ping.js';
+import { PreferredWithFallbackRoutingStrategy } from './routing/preferred-with-fallback.js';
+import { RandomRoutingStrategy } from './routing/random.js';
+import { SimpleCacheRoutingStrategy } from './routing/simple-cache.js';
+import { isBrowser } from './utils/browser.js';
+import { DataRootVerificationStrategy } from './verification/data-root-verification.js';
+import { HashVerificationStrategy } from './verification/hash-verification.js';
+import { RemoteVerificationStrategy } from './verification/remote-verification.js';
+import { Wayfinder } from './wayfinder.js';
+/**
+ * Creates a Wayfinder client synchronously using static gateways
+ * Use this when you want to avoid the AR.IO SDK dependency
+ */
+export function createWayfinderClientSync(options = {}) {
+    const { routing = 'random', verification = 'disabled', trustedGateways = [], cache = false, gatewaySelection, logger, ario, gatewaysProvider: customGatewaysProvider, routingStrategy: customRoutingStrategy, verificationStrategy: customVerificationStrategy, } = options;
+    // Parse cache configuration
+    const cacheEnabled = !!cache;
+    const cacheTTLSeconds = typeof cache === 'object' ? cache.ttlSeconds : 300; // 5 minutes default
+    // Set up gateways provider
+    let gatewaysProvider;
+    if (customGatewaysProvider) {
+        gatewaysProvider = customGatewaysProvider;
+    }
+    else if (ario) {
+        // Use NetworkGatewaysProvider if ARIO instance is provided
+        let sortBy = 'totalDelegatedStake';
+        let sortOrder = 'desc';
+        const selection = gatewaySelection || 'highest-performing';
+        switch (selection) {
+            case 'highest-performing':
+                sortBy = 'weights.gatewayPerformanceRatio';
+                sortOrder = 'desc';
+                break;
+            case 'longest-tenure':
+                sortBy = 'weights.tenureWeight';
+                sortOrder = 'desc';
+                break;
+            case 'highest-staked':
+                sortBy = 'weights.stakeWeight';
+                sortOrder = 'desc';
+                break;
+            case 'highest-weight':
+                sortBy = 'weights.normalizedCompositeWeight';
+                sortOrder = 'desc';
+                break;
+            case 'longest-streak':
+                sortBy = 'stats.passedConsecutiveEpochs';
+                sortOrder = 'desc';
+                break;
+            default:
+                sortBy = 'weights.normalizedCompositeWeight';
+                sortOrder = 'desc';
+                break;
+        }
+        gatewaysProvider = new NetworkGatewaysProvider({
+            ario,
+            sortBy,
+            sortOrder,
+            limit: 10,
+        });
+    }
+    else {
+        // Fall back to static gateways when no ARIO instance is provided
+        gatewaysProvider = new StaticGatewaysProvider({
+            gateways: trustedGateways.length
+                ? trustedGateways
+                : [
+                    'https://permagate.io',
+                    'https://arweave.net',
+                    'https://ardrive.net',
+                ],
+        });
+    }
+    // Wrap with cache if enabled
+    if (cacheEnabled) {
+        if (isBrowser()) {
+            gatewaysProvider = new LocalStorageGatewaysProvider({
+                gatewaysProvider: gatewaysProvider,
+                ttlSeconds: cacheTTLSeconds,
+            });
+        }
+        else {
+            gatewaysProvider = new SimpleCacheGatewaysProvider({
+                gatewaysProvider: gatewaysProvider,
+                ttlSeconds: cacheTTLSeconds,
+            });
+        }
+    }
+    // Set up routing strategy
+    let routingStrategy;
+    if (customRoutingStrategy) {
+        routingStrategy = customRoutingStrategy;
+    }
+    else {
+        switch (routing) {
+            case 'random':
+                routingStrategy = new RandomRoutingStrategy();
+                break;
+            case 'fastest':
+                routingStrategy = new FastestPingRoutingStrategy();
+                break;
+            case 'preferred':
+                routingStrategy = new PreferredWithFallbackRoutingStrategy({
+                    preferredGateway: trustedGateways[0],
+                    fallbackStrategy: new RandomRoutingStrategy(),
+                });
+                break;
+            default:
+                throw new Error(`Unknown routing strategy: ${routing}`);
+        }
+        // Wrap with cache if enabled
+        if (cacheEnabled) {
+            // TODO: add browser cache support for routing strategy
+            routingStrategy = new SimpleCacheRoutingStrategy({
+                routingStrategy,
+                ttlSeconds: cacheTTLSeconds,
+            });
+        }
+    }
+    // Set up verification strategy
+    let verificationStrategy;
+    let verificationEnabled = true;
+    if (customVerificationStrategy) {
+        verificationStrategy = customVerificationStrategy;
+    }
+    else {
+        switch (verification) {
+            case 'hash':
+                verificationStrategy = new HashVerificationStrategy({
+                    trustedGateways: trustedGateways.map((url) => new URL(url)),
+                });
+                break;
+            case 'data-root':
+                verificationStrategy = new DataRootVerificationStrategy({
+                    trustedGateways: trustedGateways.map((url) => new URL(url)),
+                });
+                break;
+            case 'remote':
+                verificationStrategy = new RemoteVerificationStrategy();
+                break;
+            case 'disabled':
+                verificationEnabled = false;
+                verificationStrategy = undefined;
+                break;
+            default:
+                throw new Error(`Unknown verification strategy: ${verification}`);
+        }
+    }
+    // Create Wayfinder options
+    const wayfinderOptions = {
+        logger,
+        gatewaysProvider,
+        routingSettings: {
+            strategy: routingStrategy,
+        },
+    };
+    // Only add verification settings if not disabled
+    if (verificationEnabled && verificationStrategy) {
+        wayfinderOptions.verificationSettings = {
+            enabled: true,
+            strategy: verificationStrategy,
+        };
+    }
+    else {
+        wayfinderOptions.verificationSettings = {
+            enabled: false,
+        };
+    }
+    return new Wayfinder(wayfinderOptions);
+}
+/**
+ * Creates a Wayfinder client with the specified configuration
+ * Uses static gateways by default. Provide an `ario` instance to use NetworkGatewaysProvider
+ */
+export function createWayfinderClient(options = {}) {
+    const { routing = 'random', verification = 'disabled', trustedGateways = [], cache = false, gatewaySelection, logger, ario, gatewaysProvider: customGatewaysProvider, routingStrategy: customRoutingStrategy, verificationStrategy: customVerificationStrategy, } = options;
+    // Parse cache configuration
+    const cacheEnabled = !!cache;
+    const cacheTTLSeconds = typeof cache === 'object' ? cache.ttlSeconds : 300; // 5 minutes default
+    // Set up gateways provider
+    let gatewaysProvider;
+    if (customGatewaysProvider) {
+        gatewaysProvider = customGatewaysProvider;
+    }
+    else if (ario) {
+        // Use NetworkGatewaysProvider with dynamically imported ARIO
+        let sortBy = 'totalDelegatedStake';
+        let sortOrder = 'desc';
+        switch (gatewaySelection) {
+            case 'highest-performing':
+                sortBy = 'weights.gatewayPerformanceRatio';
+                sortOrder = 'desc';
+                break;
+            case 'longest-tenure':
+                sortBy = 'weights.tenureWeight';
+                sortOrder = 'desc';
+                break;
+            case 'highest-staked':
+                sortBy = 'weights.stakeWeight';
+                sortOrder = 'desc';
+                break;
+            case 'highest-weight':
+                sortBy = 'weights.normalizedCompositeWeight';
+                sortOrder = 'desc';
+                break;
+            case 'longest-streak':
+                sortBy = 'stats.passedConsecutiveEpochs';
+                sortOrder = 'desc';
+                break;
+            default:
+                sortBy = 'weights.normalizedCompositeWeight';
+                sortOrder = 'desc';
+                break;
+        }
+        gatewaysProvider = new NetworkGatewaysProvider({
+            ario,
+            sortBy,
+            sortOrder,
+            limit: 10,
+        });
+    }
+    else {
+        // Fall back to static gateways when no ARIO instance is provided
+        gatewaysProvider = new StaticGatewaysProvider({
+            gateways: trustedGateways.length
+                ? trustedGateways
+                : [
+                    'https://permagate.io',
+                    'https://arweave.net',
+                    'https://ardrive.net',
+                ],
+        });
+    }
+    // Wrap with cache if enabled
+    if (cacheEnabled) {
+        if (isBrowser()) {
+            gatewaysProvider = new LocalStorageGatewaysProvider({
+                gatewaysProvider: gatewaysProvider,
+                ttlSeconds: cacheTTLSeconds,
+            });
+        }
+        else {
+            gatewaysProvider = new SimpleCacheGatewaysProvider({
+                gatewaysProvider: gatewaysProvider,
+                ttlSeconds: cacheTTLSeconds,
+            });
+        }
+    }
+    // Set up routing strategy
+    let routingStrategy;
+    if (customRoutingStrategy) {
+        routingStrategy = customRoutingStrategy;
+    }
+    else {
+        switch (routing) {
+            case 'random':
+                routingStrategy = new RandomRoutingStrategy();
+                break;
+            case 'fastest':
+                routingStrategy = new FastestPingRoutingStrategy();
+                break;
+            case 'preferred':
+                routingStrategy = new PreferredWithFallbackRoutingStrategy({
+                    preferredGateway: trustedGateways[0],
+                    fallbackStrategy: new RandomRoutingStrategy(),
+                });
+                break;
+            default:
+                throw new Error(`Unknown routing strategy: ${routing}`);
+        }
+        // Wrap with cache if enabled
+        if (cacheEnabled) {
+            // TODO: add browser cache support for routing strategy
+            routingStrategy = new SimpleCacheRoutingStrategy({
+                routingStrategy,
+                ttlSeconds: cacheTTLSeconds,
+            });
+        }
+    }
+    // Set up verification strategy
+    let verificationStrategy;
+    let verificationEnabled = true;
+    if (customVerificationStrategy) {
+        verificationStrategy = customVerificationStrategy;
+    }
+    else {
+        switch (verification) {
+            case 'hash':
+                verificationStrategy = new HashVerificationStrategy({
+                    trustedGateways: trustedGateways.map((url) => new URL(url)),
+                });
+                break;
+            case 'data-root':
+                verificationStrategy = new DataRootVerificationStrategy({
+                    trustedGateways: trustedGateways.map((url) => new URL(url)),
+                });
+                break;
+            case 'remote':
+                verificationStrategy = new RemoteVerificationStrategy();
+                break;
+            case 'disabled':
+                verificationEnabled = false;
+                verificationStrategy = undefined;
+                break;
+            default:
+                throw new Error(`Unknown verification strategy: ${verification}`);
+        }
+    }
+    // Create Wayfinder options
+    const wayfinderOptions = {
+        logger,
+        gatewaysProvider,
+        routingSettings: {
+            strategy: routingStrategy,
+        },
+    };
+    // Only add verification settings if not disabled
+    if (verificationEnabled && verificationStrategy) {
+        wayfinderOptions.verificationSettings = {
+            enabled: true,
+            strategy: verificationStrategy,
+        };
+    }
+    else {
+        wayfinderOptions.verificationSettings = {
+            enabled: false,
+        };
+    }
+    return new Wayfinder(wayfinderOptions);
+}
+// Re-export as aliases
+export const createWayfinder = createWayfinderClient;
+export const createWayfinderSync = createWayfinderClientSync;

package/dist/gateways/network.d.ts

@@ -25,7 +25,7 @@ export declare class NetworkGatewaysProvider implements GatewaysProvider {
     private logger;
     constructor({ ario, sortBy, sortOrder, limit, filter, logger, }: {
         ario: AoARIORead;
-        sortBy?: 'totalDelegatedStake' | 'operatorStake' | 'startTimestamp';
+        sortBy?: 'totalDelegatedStake' | 'operatorStake' | 'startTimestamp' | 'weights.gatewayPerformanceRatio' | 'weights.tenureWeight' | 'weights.stakeWeight' | 'weights.compositeWeight' | 'stats.passedConsecutiveEpochs' | 'weights.normalizedCompositeWeight';
         sortOrder?: 'asc' | 'desc';
         limit?: number;
         blocklist?: string[];

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,aAAa,CAAC;AAE5D,qBAAa,uBAAwB,YAAW,gBAAgB;IAC9D,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,MAAM,CAA6D;IAC3E,OAAO,CAAC,SAAS,CAAiB;IAClC,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,qBAAqB,GAAG,eAAe,GAAG,gBAAgB,CAAC;QACpE,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;QAC3B,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;CA0DpC"}
+{"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,aAAa,CAAC;AAE5D,qBAAa,uBAAwB,YAAW,gBAAgB;IAC9D,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,MAAM,CAS0B;IACxC,OAAO,CAAC,SAAS,CAAiB;IAClC,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,EACH,qBAAqB,GACrB,eAAe,GACf,gBAAgB,GAChB,iCAAiC,GACjC,sBAAsB,GACtB,qBAAqB,GACrB,yBAAyB,GACzB,+BAA+B,GAC/B,mCAAmC,CAAC;QACxC,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;QAC3B,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"}

package/dist/gateways/network.js

@@ -31,6 +31,7 @@ export class NetworkGatewaysProvider {
                     cursor,
                     sortBy: this.sortBy,
                     sortOrder: this.sortOrder,
+                    // TODO: support filters on gateways
                 });
                 gateways.push(...newGateways);
                 cursor = nextCursor;

package/dist/index.d.ts

@@ -31,4 +31,5 @@ export * from './verification/signature-verification.js';
 export * from './verification/remote-verification.js';
 export * from './emitter.js';
 export * from './wayfinder.js';
+export * from './client.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,cAAc,YAAY,CAAC;AAG3B,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,sCAAsC,CAAC;AACrD,cAAc,2BAA2B,CAAC;AAG1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,mCAAmC,CAAC;AAGlD,cAAc,0CAA0C,CAAC;AACzD,cAAc,qCAAqC,CAAC;AACpD,cAAc,0CAA0C,CAAC;AACzD,cAAc,uCAAuC,CAAC;AAGtD,cAAc,cAAc,CAAC;AAG7B,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,cAAc,YAAY,CAAC;AAG3B,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,sCAAsC,CAAC;AACrD,cAAc,2BAA2B,CAAC;AAG1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,mCAAmC,CAAC;AAGlD,cAAc,0CAA0C,CAAC;AACzD,cAAc,qCAAqC,CAAC;AACpD,cAAc,0CAA0C,CAAC;AACzD,cAAc,uCAAuC,CAAC;AAGtD,cAAc,cAAc,CAAC;AAG7B,cAAc,gBAAgB,CAAC;AAG/B,cAAc,aAAa,CAAC"}

package/dist/index.js

@@ -37,3 +37,5 @@ export * from './verification/remote-verification.js';
 export * from './emitter.js';
 // wayfinder
 export * from './wayfinder.js';
+// utility functions
+export * from './client.js';

package/dist/routing/ping.d.ts

@@ -1,15 +1,17 @@
-import type { Logger, RoutingStrategy } from '../types.js';
+import type { GatewaysProvider, Logger, RoutingStrategy } from '../types.js';
 export declare class FastestPingRoutingStrategy implements RoutingStrategy {
     private timeoutMs;
     private logger;
     private maxConcurrency;
-    constructor({ timeoutMs, maxConcurrency, logger, }?: {
+    private gatewaysProvider?;
+    constructor({ timeoutMs, maxConcurrency, logger, gatewaysProvider, }?: {
         timeoutMs?: number;
         maxConcurrency?: number;
         logger?: Logger;
+        gatewaysProvider?: GatewaysProvider;
     });
     selectGateway({ gateways, path, subdomain, }: {
-        gateways: URL[];
+        gateways?: URL[];
         path?: string;
         subdomain?: string;
     }): Promise<URL>;
@@ -25,11 +27,13 @@ export declare class PingRoutingStrategy implements RoutingStrategy {
     private logger;
     private retries;
     private timeoutMs;
-    constructor({ routingStrategy, logger, retries, timeoutMs, }: {
+    private gatewaysProvider?;
+    constructor({ routingStrategy, logger, retries, timeoutMs, gatewaysProvider, }: {
         routingStrategy: RoutingStrategy;
         logger?: Logger;
         retries?: number;
         timeoutMs?: number;
+        gatewaysProvider?: GatewaysProvider;
     });
     selectGateway(params: {
         gateways?: URL[];

package/dist/routing/ping.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ping.d.ts","sourceRoot":"","sources":["../../src/routing/ping.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE3D,qBAAa,0BAA2B,YAAW,eAAe;IAChE,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,cAAc,CAAS;gBAEnB,EACV,SAAe,EACf,cAAmB,EACnB,MAAsB,GACvB,GAAE;QACD,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,MAAM,CAAC,EAAE,MAAM,CAAC;KACZ;IAMA,aAAa,CAAC,EAClB,QAAQ,EACR,IAAS,EACT,SAAS,GACV,EAAE;QACD,QAAQ,EAAE,GAAG,EAAE,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC,GAAG,CAAC;CA8EjB;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,YAAW,eAAe;IACzD,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAAS;gBAEd,EACV,eAAe,EACf,MAAsB,EACtB,OAAW,EACX,SAAgB,GACjB,EAAE;QACD,eAAe,EAAE,eAAe,CAAC;QACjC,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB;IAOK,aAAa,CAAC,MAAM,EAAE;QAC1B,QAAQ,CAAC,EAAE,GAAG,EAAE,CAAC;QACjB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC,GAAG,CAAC;CA4EjB"}
+{"version":3,"file":"ping.d.ts","sourceRoot":"","sources":["../../src/routing/ping.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE7E,qBAAa,0BAA2B,YAAW,eAAe;IAChE,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,gBAAgB,CAAC,CAAmB;gBAEhC,EACV,SAAe,EACf,cAAmB,EACnB,MAAsB,EACtB,gBAAgB,GACjB,GAAE;QACD,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;KAChC;IAOA,aAAa,CAAC,EAClB,QAAQ,EACR,IAAS,EACT,SAAS,GACV,EAAE;QACD,QAAQ,CAAC,EAAE,GAAG,EAAE,CAAC;QACjB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC,GAAG,CAAC;CAoFjB;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,YAAW,eAAe;IACzD,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,gBAAgB,CAAC,CAAmB;gBAEhC,EACV,eAAe,EACf,MAAsB,EACtB,OAAW,EACX,SAAgB,EAChB,gBAAgB,GACjB,EAAE;QACD,eAAe,EAAE,eAAe,CAAC;QACjC,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;KACrC;IAQK,aAAa,CAAC,MAAM,EAAE;QAC1B,QAAQ,CAAC,EAAE,GAAG,EAAE,CAAC;QACjB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC,GAAG,CAAC;CAkFjB"}

package/dist/routing/ping.js

@@ -20,25 +20,29 @@ export class FastestPingRoutingStrategy {
     timeoutMs;
     logger;
     maxConcurrency;
-    constructor({ timeoutMs = 500, maxConcurrency = 50, logger = defaultLogger, } = {}) {
+    gatewaysProvider;
+    constructor({ timeoutMs = 500, maxConcurrency = 50, logger = defaultLogger, gatewaysProvider, } = {}) {
         this.timeoutMs = timeoutMs;
         this.logger = logger;
         this.maxConcurrency = maxConcurrency;
+        this.gatewaysProvider = gatewaysProvider;
     }
     async selectGateway({ gateways, path = '', subdomain, }) {
-        if (gateways.length === 0) {
+        const resolvedGateways = gateways ??
+            (this.gatewaysProvider ? await this.gatewaysProvider.getGateways() : []);
+        if (resolvedGateways.length === 0) {
             const error = new Error('No gateways provided');
             this.logger.error('Failed to select gateway', { error: error.message });
             throw error;
         }
         try {
-            this.logger.debug(`Pinging ${gateways.length} gateways with timeout ${this.timeoutMs}ms`, {
-                gateways: gateways.map((g) => g.toString()),
+            this.logger.debug(`Pinging ${resolvedGateways.length} gateways with timeout ${this.timeoutMs}ms`, {
+                gateways: resolvedGateways.map((g) => g.toString()),
                 timeoutMs: this.timeoutMs,
                 probePath: path,
             });
-            const throttle = pLimit(Math.min(this.maxConcurrency, gateways.length));
-            const pingPromises = gateways.map(async (gateway) => {
+            const throttle = pLimit(Math.min(this.maxConcurrency, resolvedGateways.length));
+            const pingPromises = resolvedGateways.map(async (gateway) => {
                 return throttle(async () => {
                     const url = new URL(gateway.toString());
                     if (subdomain) {
@@ -79,11 +83,11 @@ export class FastestPingRoutingStrategy {
             this.logger.error('All gateways failed to respond', {
                 subdomain,
                 path,
-                gateways: gateways.map((g) => g.toString()),
+                gateways: resolvedGateways.map((g) => g.toString()),
             });
             throw new Error('All gateways failed to respond', {
                 cause: {
-                    gateways: gateways.map((g) => g.toString()),
+                    gateways: resolvedGateways.map((g) => g.toString()),
                     path,
                     subdomain,
                 },
@@ -102,21 +106,27 @@ export class PingRoutingStrategy {
     logger;
     retries;
     timeoutMs;
-    constructor({ routingStrategy, logger = defaultLogger, retries = 5, timeoutMs = 1000, }) {
+    gatewaysProvider;
+    constructor({ routingStrategy, logger = defaultLogger, retries = 5, timeoutMs = 1000, gatewaysProvider, }) {
         this.routingStrategy = routingStrategy;
         this.logger = logger;
         this.retries = retries;
         this.timeoutMs = timeoutMs;
+        this.gatewaysProvider = gatewaysProvider;
     }
     async selectGateway(params) {
-        const { gateways = [], path, subdomain } = params;
-        if (gateways.length === 0) {
+        const { gateways, path, subdomain } = params;
+        const resolvedGateways = gateways ??
+            (this.gatewaysProvider ? await this.gatewaysProvider.getGateways() : []);
+        if (resolvedGateways.length === 0) {
             throw new Error('No gateways available');
         }
+        const paramsWithGateways = { ...params, gateways: resolvedGateways };
         for (let i = 0; i < this.retries; i++) {
             let selectedGateway = undefined;
             try {
-                selectedGateway = await this.routingStrategy.selectGateway(params);
+                selectedGateway =
+                    await this.routingStrategy.selectGateway(paramsWithGateways);
                 const pingUrl = new URL(selectedGateway.toString());
                 if (subdomain) {
                     pingUrl.hostname = `${subdomain}.${pingUrl.hostname}`;
@@ -166,7 +176,7 @@ export class PingRoutingStrategy {
         }
         throw new Error('Failed to find working gateway after HEAD checks', {
             cause: {
-                gateways: gateways.map((g) => g.toString()),
+                gateways: resolvedGateways.map((g) => g.toString()),
                 path,
                 subdomain,
                 retries: this.retries,

package/dist/routing/random.d.ts

@@ -1,23 +1,13 @@
-/**
- * WayFinder
- * Copyright (C) 2022-2025 Permanent Data Solutions, Inc.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-import type { RoutingStrategy } from '../types.js';
+import type { GatewaysProvider, Logger, RoutingStrategy } from '../types.js';
 export declare class RandomRoutingStrategy implements RoutingStrategy {
-    selectGateway({ gateways, }: {
-        gateways: URL[];
+    private gatewaysProvider?;
+    private logger;
+    constructor({ gatewaysProvider, logger, }?: {
+        gatewaysProvider?: GatewaysProvider;
+        logger?: Logger;
+    });
+    selectGateway({ gateways, }?: {
+        gateways?: URL[];
     }): Promise<URL>;
 }
 //# sourceMappingURL=random.d.ts.map

package/dist/routing/random.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"random.d.ts","sourceRoot":"","sources":["../../src/routing/random.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGnD,qBAAa,qBAAsB,YAAW,eAAe;IACrD,aAAa,CAAC,EAClB,QAAQ,GACT,EAAE;QACD,QAAQ,EAAE,GAAG,EAAE,CAAC;KACjB,GAAG,OAAO,CAAC,GAAG,CAAC;CAMjB"}
+{"version":3,"file":"random.d.ts","sourceRoot":"","sources":["../../src/routing/random.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG7E,qBAAa,qBAAsB,YAAW,eAAe;IAC3D,OAAO,CAAC,gBAAgB,CAAC,CAAmB;IAC5C,OAAO,CAAC,MAAM,CAAS;gBAEX,EACV,gBAAgB,EAChB,MAAsB,GACvB,GAAE;QACD,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;QACpC,MAAM,CAAC,EAAE,MAAM,CAAC;KACZ;IAKA,aAAa,CAAC,EAClB,QAAQ,GACT,GAAE;QACD,QAAQ,CAAC,EAAE,GAAG,EAAE,CAAC;KACb,GAAG,OAAO,CAAC,GAAG,CAAC;CAatB"}

package/dist/routing/random.js

@@ -1,9 +1,38 @@
+/**
+ * WayFinder
+ * Copyright (C) 2022-2025 Permanent Data Solutions, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { defaultLogger } from '../logger.js';
 import { randomInt } from '../utils/random.js';
 export class RandomRoutingStrategy {
-    async selectGateway({ gateways, }) {
-        if (gateways.length === 0) {
+    gatewaysProvider;
+    logger;
+    constructor({ gatewaysProvider, logger = defaultLogger, } = {}) {
+        this.gatewaysProvider = gatewaysProvider;
+        this.logger = logger;
+    }
+    async selectGateway({ gateways, } = {}) {
+        const resolvedGateways = gateways ??
+            (this.gatewaysProvider ? await this.gatewaysProvider.getGateways() : []);
+        if (resolvedGateways.length === 0) {
+            this.logger.error('No gateways available');
             throw new Error('No gateways available');
         }
-        return gateways[randomInt(0, gateways.length)];
+        this.logger.debug('Selecting random gateway', {
+            gateways: resolvedGateways.map((g) => g.toString()),
+        });
+        return resolvedGateways[randomInt(0, resolvedGateways.length)];
     }
 }

package/dist/routing/round-robin.d.ts

@@ -1,12 +1,14 @@
-import type { Logger, RoutingStrategy } from '../types.js';
+import type { GatewaysProvider, Logger, RoutingStrategy } from '../types.js';
 export declare class RoundRobinRoutingStrategy implements RoutingStrategy {
     readonly name = "round-robin";
     private gateways;
     private currentIndex;
     private logger;
-    constructor({ gateways, logger, }: {
-        gateways: URL[];
+    private gatewaysProvider?;
+    constructor({ gateways, logger, gatewaysProvider, }?: {
+        gateways?: URL[];
         logger?: Logger;
+        gatewaysProvider?: GatewaysProvider;
     });
     selectGateway(): Promise<URL>;
 }

package/dist/routing/round-robin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"round-robin.d.ts","sourceRoot":"","sources":["../../src/routing/round-robin.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE3D,qBAAa,yBAA0B,YAAW,eAAe;IAC/D,SAAgB,IAAI,iBAAiB;IACrC,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,MAAM,CAAS;gBAEX,EACV,QAAQ,EACR,MAAsB,GACvB,EAAE;QACD,QAAQ,EAAE,GAAG,EAAE,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB;IAMK,aAAa,IAAI,OAAO,CAAC,GAAG,CAAC;CAMpC"}
+{"version":3,"file":"round-robin.d.ts","sourceRoot":"","sources":["../../src/routing/round-robin.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE7E,qBAAa,yBAA0B,YAAW,eAAe;IAC/D,SAAgB,IAAI,iBAAiB;IACrC,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,gBAAgB,CAAC,CAAmB;gBAEhC,EACV,QAAQ,EACR,MAAsB,EACtB,gBAAgB,GACjB,GAAE;QACD,QAAQ,CAAC,EAAE,GAAG,EAAE,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;KAChC;IAcA,aAAa,IAAI,OAAO,CAAC,GAAG,CAAC;CAqBpC"}

package/dist/routing/round-robin.js

@@ -20,14 +20,35 @@ export class RoundRobinRoutingStrategy {
     gateways;
     currentIndex;
     logger;
-    constructor({ gateways, logger = defaultLogger, }) {
-        this.gateways = gateways;
+    gatewaysProvider;
+    constructor({ gateways, logger = defaultLogger, gatewaysProvider, } = {}) {
+        if (gateways && gatewaysProvider) {
+            throw new Error('Cannot provide both gateways and gatewaysProvider');
+        }
+        if (!gateways && !gatewaysProvider) {
+            throw new Error('Must provide either gateways or gatewaysProvider');
+        }
+        this.gateways = gateways || [];
         this.currentIndex = 0;
         this.logger = logger;
+        this.gatewaysProvider = gatewaysProvider;
     }
     async selectGateway() {
+        // Lazy load gateways from provider if not already loaded
+        if (this.gateways.length === 0 && this.gatewaysProvider) {
+            this.logger.debug('Loading gateways from provider');
+            this.gateways = await this.gatewaysProvider.getGateways();
+            this.currentIndex = 0;
+        }
+        if (this.gateways.length === 0) {
+            throw new Error('No gateways available');
+        }
         const gateway = this.gateways[this.currentIndex];
-        this.logger.info('Selecting gateway', { gateway });
+        this.logger.debug('Selecting gateway', {
+            gateway: gateway.toString(),
+            currentIndex: this.currentIndex,
+            totalGateways: this.gateways.length,
+        });
         this.currentIndex = (this.currentIndex + 1) % this.gateways.length;
         return gateway;
     }

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.3.1";
+export declare const WAYFINDER_CORE_VERSION = "v1.4.0-alpha.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,sBAAsB,WAAW,CAAC"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,sBAAsB,mBAAmB,CAAC"}

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.3.1';
+export const WAYFINDER_CORE_VERSION = 'v1.4.0-alpha.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ar.io/wayfinder-core",
-  "version": "1.3.1",
+  "version": "1.4.0-alpha.0",
   "description": "WayFinder core library for intelligently routing to optimal AR.IO gateways",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -57,6 +57,11 @@
   "peerDependencies": {
     "@ar.io/sdk": ">=3.12.0"
   },
+  "peerDependenciesMeta": {
+    "@ar.io/sdk": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@ar.io/sdk": "^3.13.0",
     "@types/node": "^24.0.0",