@ar.io/sdk 3.11.0-alpha.1 → 3.11.0-alpha.11

package/lib/types/common/wayfinder/gateways/trusted-gateways.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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 { DataHashProvider, DataRootProvider } from '../../../types/wayfinder.js';
+import { GatewaysProvider } from '../gateways.js';
+export declare class TrustedGatewaysHashProvider implements DataHashProvider, DataRootProvider {
+    private gatewaysProvider;
+    constructor({ gatewaysProvider, }: {
+        gatewaysProvider: GatewaysProvider;
+    });
+    /**
+     * Gets the digest for a given txId from all trusted gateways and ensures they all match.
+     * @param txId - The txId to get the digest for.
+     * @returns The digest for the given txId.
+     */
+    getHash({ txId, }: {
+        txId: string;
+    }): Promise<{
+        hash: string;
+        algorithm: 'sha256';
+    }>;
+    /**
+     * Get the data root for a given txId from all trusted gateways and ensure they all match.
+     * @param txId - The txId to get the data root for.
+     * @returns The data root for the given txId.
+     */
+    getDataRoot({ txId }: {
+        txId: string;
+    }): Promise<string>;
+}
+/**
+ * Note from @djwhitt
+ *
+ * Calculating data roots this way is fine, but it may not reproduce the original data root.
+ * We could also implement a data root verifier that pulls all the chunks, checks that they
+ * reproduce the expected data root, and then compares the concatenated chunk data to the
+ * original data retrieved. That would take a while, but it should be able to verify any L1
+ * data where we can find the chunks.
+ */

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

@@ -15,21 +15,30 @@
  */
 import { AoARIORead, AoGatewayWithAddress } from '../../types/io.js';
 export interface GatewaysProvider {
-    getGateways(): Promise<AoGatewayWithAddress[]>;
+    getGateways(): Promise<URL[]>;
 }
-export declare class ARIOGatewaysProvider implements GatewaysProvider {
+export declare class NetworkGatewaysProvider implements GatewaysProvider {
     private ario;
-    constructor({ ario }: {
+    private sortBy;
+    private sortOrder;
+    private limit;
+    private filter;
+    constructor({ ario, sortBy, sortOrder, limit, filter, }: {
         ario: AoARIORead;
+        sortBy?: 'totalDelegatedStake' | 'operatorStake' | 'startTimestamp';
+        sortOrder?: 'asc' | 'desc';
+        limit?: number;
+        blocklist?: string[];
+        filter?: (gateway: AoGatewayWithAddress) => boolean;
     });
-    getGateways(): Promise<AoGatewayWithAddress[]>;
+    getGateways(): Promise<URL[]>;
 }
 export declare class StaticGatewaysProvider implements GatewaysProvider {
     private gateways;
     constructor({ gateways }: {
-        gateways: AoGatewayWithAddress[];
+        gateways: string[];
     });
-    getGateways(): Promise<AoGatewayWithAddress[]>;
+    getGateways(): Promise<URL[]>;
 }
 export declare class SimpleCacheGatewaysProvider implements GatewaysProvider {
     private gatewaysProvider;
@@ -40,5 +49,5 @@ export declare class SimpleCacheGatewaysProvider implements GatewaysProvider {
         gatewaysProvider: GatewaysProvider;
         ttlSeconds?: number;
     });
-    getGateways(): Promise<AoGatewayWithAddress[]>;
+    getGateways(): Promise<URL[]>;
 }

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

@@ -16,4 +16,8 @@
 export * from './wayfinder.js';
 export * from './routers/random.js';
 export * from './routers/priority.js';
-export * from './routers/fixed.js';
+export * from './routers/static.js';
+export * from './gateways.js';
+export * from './gateways/trusted-gateways.js';
+export * from './verification/data-root-verifier.js';
+export * from './verification/hash-verifier.js';

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,13 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { WayfinderRouter } from '../../types/wayfinder.js';
-type AnyFunction = (...args: [string, ...unknown[]]) => unknown;
-type WayfinderHttpClient<T extends AnyFunction> = T;
+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 = unknown[];
+type HttpClientFunction = (...args: HttpClientArgs) => unknown;
+type WayfinderHttpClient<T extends HttpClientFunction> = T;
 export declare const arnsRegex: RegExp;
 export declare const txIdRegex: RegExp;
 /**
@@ -24,10 +28,74 @@ export declare const txIdRegex: RegExp;
  * @param targetGateway - the target gateway to resolve the url against
  * @returns the resolved url that can be used to make a request
  */
-export declare const resolveWayfinderUrl: ({ originalUrl, targetGateway, }: {
+export declare const resolveWayfinderUrl: ({ originalUrl, targetGateway, logger, }: {
     originalUrl: string | URL;
-    targetGateway: string | URL;
-}) => URL;
+    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
  *
@@ -41,11 +109,18 @@ export declare const resolveWayfinderUrl: ({ originalUrl, targetGateway, }: {
  * @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 AnyFunction>({ httpClient, resolveUrl, }: {
+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
@@ -53,24 +128,38 @@ export declare const createWayfinderClient: <T extends AnyFunction>({ httpClient
  * @param httpClient - the http client to use for requests
  * @param blocklist - the blocklist of gateways to avoid
  */
-export declare class Wayfinder<T extends AnyFunction> {
+export declare class Wayfinder<T extends HttpClientFunction> {
     /**
      * The router to use for requests
      *
      * @example
      * const wayfinder = new Wayfinder({
-     *   router: new RandomGatewayRouter({ ario: ARIO.mainnet() }),
+     *   router: new RandomGatewayRouter({
+     *     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({ ario: ARIO.mainnet() }),
+     *   router: new RandomGatewayRouter({
+     *     gatewaysProvider: new SimpleCacheGatewaysProvider({
+     *       gatewaysProvider: new NetworkGatewaysProvider({ ario: ARIO.mainnet() }),
+     *       ttlSeconds: 60 * 60 * 24, // 1 day
+     *     }),
+     *   }),
      *   httpClient: axios,
      * });
+     *
      */
     readonly httpClient: T;
     /**
@@ -78,26 +167,37 @@ export declare class Wayfinder<T extends AnyFunction> {
      *
      * @example
      * const wayfinder = new Wayfinder({
-     *   router: new RandomGatewayRouter({ ario: ARIO.mainnet() }),
+     *   router: new RandomGatewayRouter({
+     *     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: {
         originalUrl: string;
+        logger?: Logger;
     }) => Promise<URL>;
     /**
      * A wrapped http client that supports ar:// protocol
      *
      * @example
      * const { request: wayfind } = new Wayfinder({
-     *   router: new RandomGatewayRouter({ ario: ARIO.mainnet() }),
+     *   router: new RandomGatewayRouter({
+     *     gatewaysProvider: new SimpleCacheGatewaysProvider({
+     *       gatewaysProvider: new NetworkGatewaysProvider({ ario: ARIO.mainnet() }),
+     *       ttlSeconds: 60 * 60 * 24, // 1 day
+     *     }),
+     *   }),
      *   httpClient: axios,
      * });;
      *
-     * TODO: consider a top level function that supports wayfinder routing under the hood
-     * const response = await wayfind('ar://', {
+     * const response = await wayfind('ar://example', {
      *   method: 'POST',
      *   data: {
      *     name: 'John Doe',
@@ -105,9 +205,61 @@ export declare class Wayfinder<T extends AnyFunction> {
      * })
      */
     readonly request: WayfinderHttpClient<T>;
-    constructor({ router, httpClient, }: {
-        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/io.d.ts

@@ -420,7 +420,22 @@ export type DemandFactorSettings = {
     maxPeriodsAtMinDemandFactor: number;
     criteria: string;
 };
-export interface AoARIORead {
+export type ArNSNameResolutionData = {
+    name: string;
+    owner?: string;
+    txId: string;
+    type: 'lease' | 'permabuy';
+    processId: string;
+    ttlSeconds: number;
+    priority?: number;
+    undernameLimit: number;
+};
+export interface ArNSNameResolver {
+    resolveArNSName({ name }: {
+        name: string;
+    }): Promise<ArNSNameResolutionData>;
+}
+export interface AoARIORead extends ArNSNameResolver {
     process: AOProcess;
     getInfo(): Promise<{
         Ticker: string;

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.10.0";
+export declare const version = "3.11.0-alpha.10";

package/package.json

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