@ar.io/sdk 3.11.0-alpha.6 → 3.11.0-alpha.8

package/lib/types/common/wayfinder/routers/priority.d.ts

@@ -14,20 +14,16 @@
  * limitations under the License.
  */
 import { WayfinderRouter } from '../../../types/wayfinder.js';
-import { GatewaysProvider } from '../gateways.js';
+import { AoARIORead } from '../../../web/index.js';
+import { NetworkGatewaysProvider } from '../gateways.js';
 export declare class PriorityGatewayRouter implements WayfinderRouter {
     readonly name = "priority";
-    private gatewaysProvider;
-    private limit;
-    private sortBy;
-    private sortOrder;
-    private blocklist;
-    constructor({ gatewaysProvider, limit, sortBy, sortOrder, blocklist, }: {
-        gatewaysProvider: GatewaysProvider;
-        limit?: number;
-        sortBy?: 'totalDelegatedStake' | 'operatorStake' | 'startTimestamp';
-        sortOrder?: 'asc' | 'desc';
-        blocklist?: string[];
+    readonly gatewaysProvider: NetworkGatewaysProvider;
+    constructor({ ario, sortBy, sortOrder, limit, }: {
+        ario: AoARIORead;
+        sortBy: 'operatorStake' | 'totalDelegatedStake' | 'startTimestamp';
+        sortOrder: 'asc' | 'desc';
+        limit: number;
     });
     getTargetGateway(): Promise<URL>;
 }

package/lib/types/common/wayfinder/routers/{fixed.d.ts → static.d.ts}

@@ -14,11 +14,11 @@
  * limitations under the License.
  */
 import { WayfinderRouter } from '../../../types/wayfinder.js';
-export declare class FixedGatewayRouter implements WayfinderRouter {
-    readonly name = "fixed";
+export declare class StaticGatewayRouter implements WayfinderRouter {
+    readonly name = "static";
     private gateway;
     constructor({ gateway }: {
-        gateway: URL;
+        gateway: string;
     });
     getTargetGateway(): Promise<URL>;
 }

package/lib/types/common/wayfinder/verification/data-root-verifier.d.ts

@@ -0,0 +1,31 @@
+import { Readable } from 'node:stream';
+import { DataRootProvider, DataVerifier } from '../../../types/wayfinder.js';
+export declare function convertBufferToDataRoot({ buffer, }: {
+    buffer: Buffer;
+}): Promise<string>;
+export declare const convertReadableToDataRoot: <T extends AsyncIterable<Uint8Array>>({ iterable, }: {
+    iterable: T;
+}) => Promise<string>;
+export declare class DataRootVerifier implements DataVerifier {
+    private readonly trustedDataRootProvider;
+    constructor({ trustedDataRootProvider, }: {
+        trustedDataRootProvider: DataRootProvider;
+    });
+    verifyData({ data, txId, }: {
+        data: Buffer | Readable | ReadableStream;
+        txId: string;
+    }): Promise<void>;
+}
+/**
+ * - when you get a signature of a data item, you can only verify the owner
+ * - you still need to verify it's going back to the bundle, unpack it, and verify the data item exists at the offset
+ * - you need to the location of the chunks for the data item, and prove it's in the chunk and then prove the data root of the bundle, then you have fully verified the data verifier
+ * - how to prove the data item is on arweave - verify the merkle hash that the chunks for the data item, fit within the expected tree of the parent bundle
+ *
+ * Composite verifier - you'll want to be very efficient with streams
+ * - hash verifier
+ * - parent chunks verifier --> for any range of data within a single transaction, tell me that it's correct
+ * - signature verifier
+ * - offset verifier
+ * - data item verifier
+ */

package/lib/types/common/wayfinder/verification/hash-verifier.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Copyright (C) 2022-2024 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 { Readable } from 'node:stream';
+import { DataHashProvider, DataVerifier } from '../../../types/wayfinder.js';
+export declare class HashVerifier implements DataVerifier {
+    private readonly trustedHashProvider;
+    constructor({ trustedHashProvider, }: {
+        trustedHashProvider: DataHashProvider;
+    });
+    verifyData({ data, txId, }: {
+        data: Buffer | Readable | ReadableStream;
+        txId: string;
+    }): Promise<void>;
+}

package/lib/types/common/wayfinder/wayfinder.d.ts

@@ -13,9 +13,11 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { WayfinderRouter } from '../../types/wayfinder.js';
+import EventEmitter from 'node:events';
+import { PassThrough, Readable } from 'node:stream';
+import { DataHashProvider, DataVerifier, WayfinderRouter } from '../../types/wayfinder.js';
 import { Logger } from '../logger.js';
-type HttpClientArgs = [string | URL, ...unknown[]];
+type HttpClientArgs = unknown[];
 type HttpClientFunction = (...args: HttpClientArgs) => unknown;
 type WayfinderHttpClient<T extends HttpClientFunction> = T;
 export declare const arnsRegex: RegExp;
@@ -31,6 +33,69 @@ export declare const resolveWayfinderUrl: ({ originalUrl, targetGateway, logger,
     targetGateway: () => Promise<string | URL>;
     logger?: Logger;
 }) => Promise<URL>;
+/**
+ * Wayfinder event emitter with verification events
+ */
+export type WayfinderEvent = {
+    type: 'verification-passed';
+    txId: string;
+} | {
+    type: 'verification-failed';
+    txId: string;
+    error: Error;
+} | {
+    type: 'verification-skipped';
+    originalUrl: string;
+} | {
+    type: 'verification-progress';
+    txId: string;
+    processedBytes: number;
+    totalBytes: number;
+} | {
+    type: 'routing-started';
+    originalUrl: string;
+} | {
+    type: 'routing-succeeded';
+    originalUrl: string;
+    targetGateway: string;
+} | {
+    type: 'routing-failed';
+    originalUrl: string;
+    error: Error;
+} | {
+    type: 'identified-transaction-id';
+    originalUrl: string;
+    targetGateway: string;
+    txId: string;
+};
+export interface WayfinderEventArgs {
+    onVerificationPassed?: (payload: Omit<Extract<WayfinderEvent, {
+        type: 'verification-passed';
+    }>, 'type'>) => void;
+    onVerificationFailed?: (payload: Omit<Extract<WayfinderEvent, {
+        type: 'verification-failed';
+    }>, 'type'>) => void;
+    onVerificationProgress?: (payload: Omit<Extract<WayfinderEvent, {
+        type: 'verification-progress';
+    }>, 'type'>) => void;
+}
+export declare class WayfinderEmitter extends EventEmitter {
+    constructor({ onVerificationPassed, onVerificationFailed, onVerificationProgress, }?: WayfinderEventArgs);
+    emit<E extends WayfinderEvent['type']>(event: E, payload: Omit<Extract<WayfinderEvent, {
+        type: E;
+    }>, 'type'>): boolean;
+    on<E extends WayfinderEvent['type']>(event: E, listener: (payload: Omit<Extract<WayfinderEvent, {
+        type: E;
+    }>, 'type'>) => void): this;
+}
+export declare function tapAndVerifyStream<T extends Readable | ReadableStream>({ originalStream, contentLength, verifyData, txId, emitter, }: {
+    originalStream: T;
+    contentLength: number;
+    verifyData: DataVerifier['verifyData'];
+    txId: string;
+    emitter?: WayfinderEmitter;
+}): T extends Readable ? PassThrough : T;
+export declare function wrapVerifiedResponse(original: Response, newBody: ReadableStream<Uint8Array>, txId: string): Response;
 /**
  * Creates a wrapped http client that supports ar:// protocol
  *
@@ -44,13 +109,18 @@ export declare const resolveWayfinderUrl: ({ originalUrl, targetGateway, logger,
  * @param resolveUrl - the function to construct the redirect url for ar:// requests
  * @returns a wrapped http client that supports ar:// protocol
  */
-export declare const createWayfinderClient: <T extends HttpClientFunction>({ httpClient, resolveUrl, logger, }: {
+export declare const createWayfinderClient: <T extends HttpClientFunction>({ httpClient, resolveUrl, verifyData, emitter, logger, }: {
     httpClient: T;
     resolveUrl: (params: {
         originalUrl: string | URL;
         logger?: Logger;
     }) => Promise<URL>;
+    verifyData?: <T_1 extends Readable | ReadableStream | Buffer>({ data, txId, }: {
+        data: T_1;
+        txId: string;
+    }) => Promise<void>;
     logger?: Logger;
+    emitter?: WayfinderEmitter;
 }) => WayfinderHttpClient<T>;
 /**
  * The main class for the wayfinder
@@ -65,21 +135,31 @@ export declare class Wayfinder<T extends HttpClientFunction> {
      * @example
      * const wayfinder = new Wayfinder({
      *   router: new RandomGatewayRouter({
-     *     gatewaysProvider: new ARIOGatewaysProvider({ ario: ARIO.mainnet() })
+     *     gatewaysProvider: new SimpleCacheGatewaysProvider({
+     *       gatewaysProvider: new NetworkGatewaysProvider({ ario: ARIO.mainnet() }),
+     *       ttlSeconds: 60 * 60 * 24, // 1 day
+     *     }),
      *   }),
      * });
+     *
+     * // Returns a target gateway based on the routing strategy
+     * const targetGateway = await wayfinder.router.getTargetGateway();
      */
     readonly router: WayfinderRouter;
     /**
-     * The http client to use for requests
+     * The native http client used by wayfinder
      *
      * @example
      * const wayfinder = new Wayfinder({
      *   router: new RandomGatewayRouter({
-     *     gatewaysProvider: new ARIOGatewaysProvider({ ario: ARIO.mainnet() })
+     *     gatewaysProvider: new SimpleCacheGatewaysProvider({
+     *       gatewaysProvider: new NetworkGatewaysProvider({ ario: ARIO.mainnet() }),
+     *       ttlSeconds: 60 * 60 * 24, // 1 day
+     *     }),
      *   }),
      *   httpClient: axios,
      * });
+     *
      */
     readonly httpClient: T;
     /**
@@ -88,11 +168,15 @@ export declare class Wayfinder<T extends HttpClientFunction> {
      * @example
      * const wayfinder = new Wayfinder({
      *   router: new RandomGatewayRouter({
-     *     gatewaysProvider: new ARIOGatewaysProvider({ ario: ARIO.mainnet() })
+     *     gatewaysProvider: new SimpleCacheGatewaysProvider({
+     *       gatewaysProvider: new NetworkGatewaysProvider({ ario: ARIO.mainnet() }),
+     *       ttlSeconds: 60 * 60 * 24, // 1 day
+     *     }),
      *   }),
      *   httpClient: axios,
      * });
      *
+     * // returns the redirected URL based on the routing strategy and the original url
      * const redirectUrl = await wayfinder.resolveUrl({ originalUrl: 'ar://example' });
      */
     readonly resolveUrl: (params: {
@@ -105,7 +189,10 @@ export declare class Wayfinder<T extends HttpClientFunction> {
      * @example
      * const { request: wayfind } = new Wayfinder({
      *   router: new RandomGatewayRouter({
-     *     gatewaysProvider: new ARIOGatewaysProvider({ ario: ARIO.mainnet() })
+     *     gatewaysProvider: new SimpleCacheGatewaysProvider({
+     *       gatewaysProvider: new NetworkGatewaysProvider({ ario: ARIO.mainnet() }),
+     *       ttlSeconds: 60 * 60 * 24, // 1 day
+     *     }),
      *   }),
      *   httpClient: axios,
      * });;
@@ -118,10 +205,61 @@ export declare class Wayfinder<T extends HttpClientFunction> {
      * })
      */
     readonly request: WayfinderHttpClient<T>;
-    constructor({ router, httpClient, logger, }: {
-        router: WayfinderRouter;
+    readonly verifyData: DataVerifier['verifyData'];
+    /**
+     * The event emitter for wayfinder that emits verification events.
+     *
+     * const wayfinder = new Wayfinder()
+     *
+     * wayfinder.emitter.on('verification-passed', (event) => {
+     *   console.log('Verification passed!', event);
+     * })
+     *
+     * wayfinder.emitter.on('verification-failed', (event) => {
+     *   console.log('Verification failed!', event);
+     * })
+     *
+     * or implement the events interface and pass it in, using callback functions
+     *
+     * const wayfinder = new Wayfinder({
+     *   events: {
+     *     onVerificationPassed: (event) => {
+     *       console.log('Verification passed!', event);
+     *     },
+     *     onVerificationFailed: (event) => {
+     *       console.log('Verification failed!', event);
+     *     },
+     *     onVerificationProgress: (event) => {
+     *       console.log('Verification progress!', event);
+     *     },
+     *   }
+     * })
+     *
+     * const response = await wayfind('ar://example');
+     */
+    readonly emitter: WayfinderEmitter;
+    constructor({ httpClient, router, logger, verifier, events, }: {
         httpClient: T;
+        router?: WayfinderRouter;
         logger?: Logger;
+        verifier?: DataVerifier;
+        hashProvider?: DataHashProvider;
+        events?: WayfinderEventArgs;
     });
 }
 export {};
+/**
+ *
+ *  type    | complexity | performance | security
+ * ---------|------------|-------------|---------
+ *  hash    | low        | high        | low
+ * ---------|------------|-------------|---------
+ *  data root    | medium       | medium      | low | only L1
+ * ---------|------------|-------------|---------
+ * signature    | medium       | medium      | medium
+ * ---------|------------|-------------|---------
+ *  composite | high       | low         | high
+ * ---------|------------|-------------|---------
+ *
+ *
+ */

package/lib/types/types/wayfinder.d.ts

@@ -13,7 +13,50 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import { Readable } from 'stream';
 export interface WayfinderRouter {
     readonly name: string;
     getTargetGateway: () => Promise<URL>;
 }
+export interface DataVerifier {
+    /**
+     * Verifies the provided data for a given txId
+     *
+     * Depending on the implementation, the hash can be the computed data root of a transaction, the digest of the data, or some other hash of the data.
+     *
+     * The interface is intended to be vague in order to support various degrees of verification.
+     *
+     * @param data - The data to verify
+     * @param txId - The txId of the data
+     * @returns the hash of the data
+     */
+    verifyData: ({ data, txId, }: {
+        data: Buffer | Readable | ReadableStream;
+        txId: string;
+    }) => Promise<void>;
+}
+export interface DataHashProvider {
+    /**
+     * Returns a hash for the provided txId using the specified algorithm.
+     *
+     * @param txId - The txId of the data
+     * @returns the hash of the data
+     */
+    getHash: ({ txId, }: {
+        txId: string;
+    }) => Promise<{
+        hash: string;
+        algorithm: 'sha256';
+    }>;
+}
+export interface DataRootProvider {
+    /**
+     * Returns the data root for the provided txId
+     *
+     * @param txId - The txId of the data
+     * @returns the data root of the data
+     */
+    getDataRoot: ({ txId }: {
+        txId: string;
+    }) => Promise<string>;
+}

package/lib/types/utils/hash.d.ts

@@ -0,0 +1,4 @@
+import { Readable } from 'stream';
+export declare const hashReadableToB64Url: (stream: Readable, algorithm?: string) => Promise<string>;
+export declare const hashReadableStreamToB64Url: (stream: ReadableStream, algorithm?: string) => Promise<string>;
+export declare const hashBufferToB64Url: (buffer: Buffer, algorithm?: string) => string;

package/lib/types/version.d.ts

@@ -13,4 +13,4 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-export declare const version = "3.11.0-alpha.5";
+export declare const version = "3.11.0-alpha.7";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ar.io/sdk",
-  "version": "3.11.0-alpha.6",
+  "version": "3.11.0-alpha.8",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ar-io/ar-io-sdk.git"