@ar.io/wayfinder-core 1.0.0 → 1.0.1-alpha.0

package/README.md

@@ -19,98 +19,76 @@ yarn add @ar.io/wayfinder-core
 ```javascript
 import { Wayfinder } from '@ar.io/wayfinder-core';
 
-// create a new Wayfinder instance with default settings
-const wayfinder = new Wayfinder();
+// 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,
+  }),
+});
 
 // use Wayfinder to fetch and verify data using ar:// protocol
 const response = await wayfinder.request('ar://example-name');
 ```
 
-### Custom Configuration
+## ar:// Protocol
 
-You can customize the wayfinder instance with different gateways, verification strategies, and routing strategies based on your use case.
+Wayfinder supports several ar:// URL formats:
 
-Example:
+```bash
+ar://TRANSACTION_ID              // Direct transaction ID
+ar://NAME                        // ArNS name (paths supported)
+ar:///info                       // Gateway endpoint (/info)
+```
 
-> _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._
+## Dynamic Wayfinder URLs
+
+Wayfinder supports a `resolveUrl` method which generates dynamic redirect URLs to a target gateway based on the provided routing strategy. This function can be used to directly replace any hard-coded gateway URLs, and instead use Wayfinder's routing logic to select a gateway for the request.
+
+### Dynamic routing for ArNS names
+
+Given an ArNS name, the redirect URL will be the same as the original URL, but with the gateway selected by Wayfinder's routing strategy.
 
 ```javascript
-import { Wayfinder, NetworkGatewaysProvider, SimpleCacheGatewaysProvider, FastestPingRoutingStrategy, HashVerificationStrategy } from '@ar.io/wayfinder-core';
-import { ARIO } from '@ar.io/sdk';
+const redirectUrl = await wayfinder.resolveUrl({
+  arnsName: 'ardrive',
+});
+// results in https://ardrive.<selected-gateway>
+```
 
-const wayfinder = new Wayfinder({
-  // cache the top 10 gateways by operator stake from the ARIO Network for 1 hour
-  gatewaysProvider: new SimpleCacheGatewaysProvider({
-    ttlSeconds: 60 * 60, // cache the gateways for 1 hour
-    gatewaysProvider: new NetworkGatewaysProvider({
-      ario: ARIO.mainnet(),
-      sortBy: 'operatorStake',
-      sortOrder: 'desc',
-      limit: 10,
-    }),
-  }),
-  // routing settings
-  routingSettings: {
-    // use the fastest pinging strategy to select the fastest gateway for requests
-    strategy: new FastestPingRoutingStrategy({
-      timeoutMs: 1000,
-    }),
-    // events
-    events: {
-      onRoutingStarted: (event) => {
-        console.log('Routing started!', event);
-      },
-      onRoutingSkipped: (event) => {
-        console.log('Routing skipped!', event);
-      },
-      onRoutingSucceeded: (event) => {
-        console.log('Routing succeeded!', event);
-      },
-    },
-  },
-  // verification settings
-  verificationSettings: {
-    // enable verification - if false, verification will be skipped for all requests
-    enabled: true,
-    // verify the data using the hash of the data against a list of trusted gateways
-    strategy: new HashVerificationStrategy({
-      trustedGateways: ['https://permagate.io'],
-    }),
-    // strict verification - if true, verification failures will cause requests to fail
-    strict: true,
-    // events
-    events: {
-      onVerificationProgress: (event) => {
-        console.log('Verification progress!', event);
-      },
-      onVerificationSucceeded: (event) => {
-        console.log('Verification succeeded!', event);
-      },
-      onVerificationFailed: (event) => {
-        console.log('Verification failed!', event);
-      },
-    },
-  },
-  // telemetry configuration
-  telemetrySettings: {
-    enabled: true, // disabled by default (must be explicitly enabled)
-    sampleRate: 0.1, // 10% sample rate by default
-  },
+### Dynamic routing for txIds
+
+Given a txId, the redirect URL will be the same as the original URL, but with the gateway selected by Wayfinder's routing strategy.
+
+```javascript
+const redirectUrl = await wayfinder.resolveUrl({
+  txId: 'example-tx-id',
 });
+// results in https://<selected-gateway>/example-tx-id
 ```
 
-### Telemetry
+### Dynamic routing for legacy arweave.net or arweave.dev URLs
 
-Wayfinder can optionally emit OpenTelemetry spans for every request. **By default, telemetry is disabled**. You can control this behavior with the `telemetrySettings` option.
+Given a legacy arweave.net or arweave.dev URL, the redirect URL will be the same as the original URL, but with the gateway selected by Wayfinder's routing strategy.
 
-## ar:// Protocol
+```javascript
+const redirectUrl = await wayfinder.resolveUrl({
+  originalUrl: 'https://arweave.net/example-tx-id',
+});
+// results in https://<selected-gateway>/example-tx-id
+```
 
-Wayfinder supports several ar:// URL formats:
+### Dynamic routing for ar:// URLs
 
-```bash
-ar://TRANSACTION_ID              // Direct transaction ID
-ar://NAME                        // ArNS name (paths supported)
-ar:///info                       // Gateway endpoint (/info)
+Given an ar:// URL, the redirect URL will be the same as the original URL, but with the gateway selected by Wayfinder's routing strategy.
+
+```javascript
+const redirectUrl = await wayfinder.resolveUrl({
+  originalUrl: 'ar://example-name/subpath?query=value',
+});
+// results in https://<selected-gateway>/example-name/subpath?query=value
 ```
 
 ## Gateway Providers
@@ -151,6 +129,7 @@ Wayfinder supports multiple routing strategies to select target gateways for you
 | `StaticRoutingStrategy`      | Always uses a single gateway                   | When you need to use a specific gateway |
 | `RoundRobinRoutingStrategy`  | Selects gateways in round-robin order          | Good for load balancing and resilience  |
 | `FastestPingRoutingStrategy` | Selects the fastest gateway based on ping time | Good for performance and latency        |
+| `PreferredWithFallbackRoutingStrategy` | Uses a preferred gateway, with a fallback strategy if the preferred gateway is not available | Good for performance and resilience. Ideal for builders who run their own gateways. |
 
 ### RandomRoutingStrategy
 
@@ -217,6 +196,21 @@ const gateway = await routingStrategy.selectGateway({
 });
 ```
 
+### PreferredWithFallbackRoutingStrategy
+
+Uses a preferred gateway, with a fallback strategy if the preferred gateway is not available. This is useful for builders who run their own gateways and want to use their own gateway as the preferred gateway, but also want to have a fallback strategy in case their gateway is not available.
+
+```javascript
+import { Wayfinder, PreferredWithFallbackRoutingStrategy } from '@ar.io/wayfinder-core';
+
+const routingStrategy = new PreferredWithFallbackRoutingStrategy({
+  preferredGateway: 'https://permagate.io',
+  fallbackStrategy: new FastestPingRoutingStrategy({
+    timeoutMs: 500,
+  }),
+});
+```
+
 ## Verification Strategies
 
 Wayfinder includes verification mechanisms to ensure the integrity of retrieved data. Verification strategies offer different trade-offs between complexity, performance, and security.
@@ -382,16 +376,93 @@ const response = await wayfinder.request('ar://example-name', {
 
 ## Advanced Usage
 
-### Custom URL Resolution
+### Custom Configuration
+
+You can customize the wayfinder instance with different gateways, verification strategies, and routing strategies based on your use case.
 
-Returns the resolved URL for a given ar:// URL. This is useful for debugging and for users who want to know the target gateway for a given ar:// URL.
+Example:
+
+> _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._
 
 ```javascript
-// Get the resolved URL without making a request
-const redirectUrl = await wayfinder.resolveUrl({
-  originalUrl: 'ar://example-name',
+import { Wayfinder, NetworkGatewaysProvider, SimpleCacheGatewaysProvider, FastestPingRoutingStrategy, HashVerificationStrategy } from '@ar.io/wayfinder-core';
+import { ARIO } from '@ar.io/sdk';
+
+const wayfinder = new Wayfinder({
+  // cache the top 10 gateways by operator stake from the ARIO Network for 1 hour
+  gatewaysProvider: new SimpleCacheGatewaysProvider({
+    ttlSeconds: 60 * 60, // cache the gateways for 1 hour
+    gatewaysProvider: new NetworkGatewaysProvider({
+      ario: ARIO.mainnet(),
+      sortBy: 'operatorStake',
+      sortOrder: 'desc',
+      limit: 10,
+    }),
+  }),
+  // routing settings
+  routingSettings: {
+    // use the fastest pinging strategy to select the fastest gateway for requests
+    strategy: new FastestPingRoutingStrategy({
+      timeoutMs: 1000,
+    }),
+    // events
+    events: {
+      onRoutingStarted: (event) => {
+        console.log('Routing started!', event);
+      },
+      onRoutingSkipped: (event) => {
+        console.log('Routing skipped!', event);
+      },
+      onRoutingSucceeded: (event) => {
+        console.log('Routing succeeded!', event);
+      },
+    },
+  },
+  // verification settings
+  verificationSettings: {
+    // enable verification - if false, verification will be skipped for all requests
+    enabled: true,
+    // verify the data using the hash of the data against a list of trusted gateways
+    strategy: new HashVerificationStrategy({
+      trustedGateways: ['https://permagate.io'],
+    }),
+    // strict verification - if true, verification failures will cause requests to fail
+    strict: true,
+    // events
+    events: {
+      onVerificationProgress: (event) => {
+        console.log('Verification progress!', event);
+      },
+      onVerificationSucceeded: (event) => {
+        console.log('Verification succeeded!', event);
+      },
+      onVerificationFailed: (event) => {
+        console.log('Verification failed!', event);
+      },
+    },
+  },
+});
+```
+
+### Telemetry
+
+Wayfinder can optionally emit OpenTelemetry spans for every request. **By default, telemetry is disabled**. You can control this behavior with the `telemetrySettings` option.
+
+```javascript
+
+const wayfinder = new Wayfinder({
+  gatewaysProvider: new NetworkGatewaysProvider({
+    ario: ARIO.mainnet(),
+    sortBy: 'operatorStake',
+    sortOrder: 'desc',
+    limit: 10,
+  }),
+  telemetrySettings: {
+    enabled: true, // disabled by default (must be explicitly enabled)
+    sampleRate: 0.1, // 10% sample rate by default
+    exporterUrl: 'https://your-custom-otel-exporter', // optional, defaults to https://api.honeycomb.io/v1/traces
+  },
 });
-console.log(`This request would be routed to: ${redirectUrl}`);
 ```
 
 ## Request Flow

package/dist/telemetry.d.ts

@@ -14,11 +14,11 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { Span, type Tracer } from '@opentelemetry/api';
+import { Span, type Tracer, TracerProvider } from '@opentelemetry/api';
 import 'zone.js';
 import { WayfinderEmitter } from './emitter.js';
 import type { GatewaysProvider, TelemetrySettings, WayfinderOptions } from './types.js';
-export declare const initTelemetry: ({ enabled, sampleRate, exporterUrl, apiKey, }: TelemetrySettings) => Tracer | undefined;
+export declare const initTelemetry: ({ enabled, sampleRate, exporterUrl, apiKey, }: TelemetrySettings) => TracerProvider | undefined;
 export declare const startRequestSpans: ({ originalUrl, emitter, tracer, verificationSettings, routingSettings, gatewaysProvider, }?: {
     originalUrl?: string;
     emitter?: WayfinderEmitter;

package/dist/telemetry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAGL,IAAI,EACJ,KAAK,MAAM,EAIZ,MAAM,oBAAoB,CAAC;AAc5B,OAAO,SAAS,CAAC;AACjB,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAGpB,eAAO,MAAM,aAAa,GAAI,+CAK3B,iBAAiB,KAAG,MAAM,GAAG,SA2C/B,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,6FAO/B;IACD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oBAAoB,CAAC,EAAE,gBAAgB,CAAC,sBAAsB,CAAC,CAAC;IAChE,eAAe,CAAC,EAAE,gBAAgB,CAAC,iBAAiB,CAAC,CAAC;IACtD,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CAChC;;;;CA+EL,CAAC"}
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAGL,IAAI,EACJ,KAAK,MAAM,EACX,cAAc,EAIf,MAAM,oBAAoB,CAAC;AAc5B,OAAO,SAAS,CAAC;AACjB,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAOpB,eAAO,MAAM,aAAa,GAAI,+CAK3B,iBAAiB,KAAG,cAAc,GAAG,SA4CvC,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,6FAO/B;IACD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oBAAoB,CAAC,EAAE,gBAAgB,CAAC,sBAAsB,CAAC,CAAC;IAChE,eAAe,CAAC,EAAE,gBAAgB,CAAC,iBAAiB,CAAC,CAAC;IACtD,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CAChC;;;;CA+EL,CAAC"}

package/dist/telemetry.js

@@ -23,12 +23,19 @@ import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
 import { WebTracerProvider } from '@opentelemetry/sdk-trace-web';
 import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION, } from '@opentelemetry/semantic-conventions';
 import 'zone.js';
+import { isBrowser, isChromeExtension } from './utils/browser.js';
 import { WAYFINDER_CORE_VERSION } from './version.js';
+// avoid re-initializing the tracer provider and tracer
+let tracerProvider;
 export const initTelemetry = ({ enabled = false, sampleRate = 0.1, // 10% sample rate by default
 exporterUrl = 'https://api.honeycomb.io/v1/traces', apiKey = 'c8gU8dHlu6V7e5k2Gn9LaG', // intentionally left here - if it gets abused we'll disable it
  }) => {
     if (enabled === false)
         return undefined;
+    // if the tracer provider and tracer are already initialized, return the tracer
+    if (tracerProvider) {
+        return tracerProvider;
+    }
     diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ERROR);
     const exporter = new OTLPTraceExporter({
         url: exporterUrl,
@@ -37,14 +44,14 @@ exporterUrl = 'https://api.honeycomb.io/v1/traces', apiKey = 'c8gU8dHlu6V7e5k2Gn
             'x-honeycomb-dataset': 'wayfinder-core',
         },
     });
-    const isBrowser = typeof window !== 'undefined';
-    const spanProcessor = new BatchSpanProcessor(exporter);
     const sampler = new TraceIdRatioBasedSampler(sampleRate);
+    const spanProcessor = new BatchSpanProcessor(exporter);
     const resource = resourceFromAttributes({
         [ATTR_SERVICE_NAME]: 'wayfinder-core',
         [ATTR_SERVICE_VERSION]: WAYFINDER_CORE_VERSION,
     });
-    const provider = isBrowser
+    const useWebTracer = isBrowser() || isChromeExtension();
+    const provider = useWebTracer
         ? new WebTracerProvider({
             sampler,
             resource,
@@ -55,17 +62,11 @@ exporterUrl = 'https://api.honeycomb.io/v1/traces', apiKey = 'c8gU8dHlu6V7e5k2Gn
             resource,
             spanProcessors: [spanProcessor],
         });
-    if (isBrowser) {
-        // import zone.js for browser
-        provider.register({
-            contextManager: new ZoneContextManager(),
-        });
-    }
-    else {
-        // node environments don't need zone.js
-        provider.register();
-    }
-    return trace.getTracer('wayfinder-core');
+    provider.register({
+        // zone.js is only used in the browser (node/extensions/service workers don't need it)
+        contextManager: isBrowser() ? new ZoneContextManager() : undefined,
+    });
+    return tracerProvider;
 };
 export const startRequestSpans = ({ originalUrl, emitter, tracer, verificationSettings, routingSettings, gatewaysProvider, } = {}) => {
     const parentSpan = tracer?.startSpan('wayfinder.request', {

package/dist/utils/browser.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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.
+ */
+/**
+ * Returns true if running in a browser environment (window is defined).
+ */
+export declare function isBrowser(): boolean;
+/**
+ * Returns true if running as a Chrome extension (chrome.runtime and chrome.runtime.id are defined).
+ */
+export declare function isChromeExtension(): boolean;
+//# sourceMappingURL=browser.d.ts.map

package/dist/utils/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../src/utils/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;GAEG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAInC;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAM3C"}

package/dist/utils/browser.js

@@ -0,0 +1,30 @@
+/**
+ * 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.
+ */
+/**
+ * Returns true if running in a browser environment (window is defined).
+ */
+export function isBrowser() {
+    return (typeof window !== 'undefined' && typeof window.document !== 'undefined');
+}
+/**
+ * Returns true if running as a Chrome extension (chrome.runtime and chrome.runtime.id are defined).
+ */
+export function isChromeExtension() {
+    return (typeof chrome !== 'undefined' &&
+        typeof chrome.runtime !== 'undefined' &&
+        typeof chrome.runtime.id === 'string');
+}

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.0.0";
+export declare const WAYFINDER_CORE_VERSION = "v1.0.1-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.0.0';
+export const WAYFINDER_CORE_VERSION = 'v1.0.1-alpha.0';

package/dist/wayfinder.d.ts

@@ -14,7 +14,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { type Tracer } from '@opentelemetry/api';
+import { type Tracer, TracerProvider } from '@opentelemetry/api';
 import { WayfinderEmitter } from './emitter.js';
 import type { GatewaysProvider, Logger, TelemetrySettings, VerificationStrategy, WayfinderFetch, WayfinderOptions, WayfinderURL, WayfinderURLParams } from './types.js';
 export declare const wayfinderRequestHeaders: ({ traceId, }: {
@@ -114,9 +114,9 @@ export declare class Wayfinder {
      */
     readonly telemetrySettings: TelemetrySettings;
     /**
-     * OpenTelemetry tracer instance
+     * OpenTelemetry tracer provider instance
      */
-    protected tracer?: Tracer;
+    protected tracerProvider?: TracerProvider;
     /**
      * A helper function that resolves a provided url to a target gateway.
      *

package/dist/wayfinder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wayfinder.d.ts","sourceRoot":"","sources":["../src/wayfinder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"wayfinder.d.ts","sourceRoot":"","sources":["../src/wayfinder.ts"],"names":[],"mappings":"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"}

package/dist/wayfinder.js

@@ -15,7 +15,7 @@
  * limitations under the License.
  */
 import { defaultLogger } from './logger.js';
-import { context, trace } from '@opentelemetry/api';
+import { context, trace, } from '@opentelemetry/api';
 import { WayfinderEmitter } from './emitter.js';
 import { FastestPingRoutingStrategy } from './routing/ping.js';
 import { initTelemetry, startRequestSpans } from './telemetry.js';
@@ -250,6 +250,7 @@ export const wayfinderFetch = ({ logger = defaultLogger, gatewaysProvider, verif
         });
         const maxRetries = 3;
         const retryDelay = 1000;
+        let requestSpan;
         for (let i = 0; i < maxRetries; i++) {
             try {
                 // extract routing information from the ar:// URL
@@ -282,7 +283,7 @@ export const wayfinderFetch = ({ logger = defaultLogger, gatewaysProvider, verif
                     originalUrl: url,
                     redirectUrl: redirectUrl.toString(),
                 });
-                const requestSpan = parentSpan
+                requestSpan = parentSpan
                     ? tracer?.startSpan('wayfinder.fetch', undefined, trace.setSpan(context.active(), parentSpan))
                     : undefined;
                 // make the request to the target gateway using the redirect url
@@ -382,6 +383,7 @@ export const wayfinderFetch = ({ logger = defaultLogger, gatewaysProvider, verif
                 }
             }
             catch (error) {
+                requestSpan?.end();
                 logger?.debug('Failed to route request', {
                     error: error.message,
                     stack: error.stack,
@@ -393,6 +395,9 @@ export const wayfinderFetch = ({ logger = defaultLogger, gatewaysProvider, verif
                     await new Promise((resolve) => setTimeout(resolve, retryDelay));
                 }
             }
+            finally {
+                requestSpan?.end();
+            }
         }
         throw new Error('Failed to route request after max retries', {
             cause: {
@@ -433,9 +438,9 @@ export class Wayfinder {
      */
     telemetrySettings;
     /**
-     * OpenTelemetry tracer instance
+     * OpenTelemetry tracer provider instance
      */
-    tracer;
+    tracerProvider;
     /**
      * A helper function that resolves a provided url to a target gateway.
      *
@@ -602,14 +607,14 @@ export class Wayfinder {
             apiKey: telemetrySettings?.apiKey,
             exporterUrl: telemetrySettings?.exporterUrl,
         };
-        this.tracer = initTelemetry(this.telemetrySettings);
+        this.tracerProvider = initTelemetry(this.telemetrySettings);
         this.request = wayfinderFetch({
             logger: this.logger,
             emitter: this.emitter,
             gatewaysProvider: this.gatewaysProvider,
             routingSettings: this.routingSettings,
             verificationSettings: this.verificationSettings,
-            tracer: this.tracer,
+            tracer: this.tracerProvider?.getTracer('wayfinder-core'),
         });
         this.resolveUrl = async (params) => {
             const wayfinderUrl = createWayfinderUrl(params);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ar.io/wayfinder-core",
-  "version": "1.0.0",
+  "version": "1.0.1-alpha.0",
   "description": "WayFinder core library for intelligently routing to optimal AR.IO gateways",
   "main": "dist/index.js",
   "module": "dist/index.js",