@ar.io/sdk 3.13.0-alpha.1 → 3.13.0-beta.1

package/lib/esm/common/wayfinder/gateways/network.js

@@ -0,0 +1,44 @@
+import { ARIO } from '../../io.js';
+export class NetworkGatewaysProvider {
+    ario;
+    sortBy;
+    sortOrder;
+    limit;
+    filter;
+    constructor({ ario = ARIO.mainnet(), sortBy = 'operatorStake', sortOrder = 'desc', limit = 1000, filter = (g) => g.status === 'joined', }) {
+        this.ario = ario;
+        this.sortBy = sortBy;
+        this.sortOrder = sortOrder;
+        this.limit = limit;
+        this.filter = filter;
+    }
+    async getGateways() {
+        let cursor;
+        let attempts = 0;
+        const gateways = [];
+        do {
+            try {
+                const { items: newGateways = [], nextCursor } = await this.ario.getGateways({
+                    limit: 1000,
+                    cursor,
+                    sortBy: this.sortBy,
+                    sortOrder: this.sortOrder,
+                });
+                gateways.push(...newGateways);
+                cursor = nextCursor;
+                attempts = 0; // reset attempts if we get a new cursor
+            }
+            catch (error) {
+                console.error('Error fetching gateways', {
+                    cursor,
+                    attempts,
+                    error,
+                });
+                attempts++;
+            }
+        } while (cursor !== undefined && attempts < 3);
+        // filter out any gateways that are not joined
+        const filteredGateways = gateways.filter(this.filter).slice(0, this.limit);
+        return filteredGateways.map((g) => new URL(`${g.settings.protocol}://${g.settings.fqdn}:${g.settings.port}`));
+    }
+}

package/lib/esm/common/wayfinder/gateways/simple-cache.js

@@ -0,0 +1,31 @@
+import { Logger } from '../../../web/index.js';
+export class SimpleCacheGatewaysProvider {
+    gatewaysProvider;
+    ttlSeconds;
+    lastUpdated;
+    gatewaysCache;
+    logger;
+    constructor({ gatewaysProvider, ttlSeconds = 60 * 60, // 1 hour
+    logger = Logger.default, }) {
+        this.gatewaysCache = [];
+        this.gatewaysProvider = gatewaysProvider;
+        this.ttlSeconds = ttlSeconds;
+        this.logger = logger;
+    }
+    async getGateways() {
+        const now = Date.now();
+        if (this.gatewaysCache.length === 0 ||
+            now - this.lastUpdated > this.ttlSeconds * 1000) {
+            try {
+                // preserve the cache if the fetch fails
+                const allGateways = await this.gatewaysProvider.getGateways();
+                this.gatewaysCache = allGateways;
+                this.lastUpdated = now;
+            }
+            catch (error) {
+                this.logger.error('Error fetching gateways', error);
+            }
+        }
+        return this.gatewaysCache;
+    }
+}

package/lib/esm/common/wayfinder/gateways/static.js

@@ -0,0 +1,9 @@
+export class StaticGatewaysProvider {
+    gateways;
+    constructor({ gateways }) {
+        this.gateways = gateways.map((g) => new URL(g));
+    }
+    async getGateways() {
+        return this.gateways;
+    }
+}

package/lib/esm/common/wayfinder/index.js

@@ -0,0 +1,32 @@
+/**
+ * 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.
+ */
+export * from './wayfinder.js';
+// routing strategies
+export * from './routing/strategies/random.js';
+export * from './routing/strategies/static.js';
+export * from './routing/strategies/ping.js';
+export * from './routing/strategies/round-robin.js';
+export * from './routing/strategies/preferred-with-fallback.js';
+// gateways providers
+export * from './gateways/network.js';
+export * from './gateways/simple-cache.js';
+export * from './gateways/static.js';
+// trusted gateways
+export * from './verification/trusted.js';
+// hash providers
+export * from './verification/strategies/data-root-verifier.js';
+export * from './verification/strategies/hash-verifier.js';
+// TODO: signature verification

package/lib/esm/common/wayfinder/routing/strategies/ping.js

@@ -0,0 +1,68 @@
+export class FastestPingRoutingStrategy {
+    timeoutMs;
+    probePath;
+    constructor({ timeoutMs = 500, probePath = '/ar-io/info', // TODO: limit to allowed /ar-io and arweave node endpoints
+     } = {}) {
+        this.timeoutMs = timeoutMs;
+        this.probePath = probePath;
+    }
+    async selectGateway({ gateways }) {
+        if (gateways.length === 0) {
+            throw new Error('No gateways provided');
+        }
+        try {
+            const results = await Promise.allSettled(gateways.map(async (gateway) => {
+                try {
+                    const startTime = Date.now();
+                    const response = await fetch(`${gateway.toString().replace(/\/$/, '')}${this.probePath}`, {
+                        method: 'HEAD',
+                        signal: AbortSignal.timeout(this.timeoutMs),
+                    });
+                    const endTime = Date.now();
+                    const durationMs = endTime - startTime;
+                    return {
+                        gateway,
+                        status: response.status,
+                        durationMs,
+                        error: null,
+                    };
+                }
+                catch (error) {
+                    // Handle network errors
+                    return {
+                        gateway,
+                        status: 'rejected',
+                        durationMs: Infinity,
+                        error,
+                    };
+                }
+            }));
+            // Process results
+            const processedResults = results.map((result, index) => {
+                if (result.status === 'fulfilled') {
+                    return result.value;
+                }
+                else {
+                    return {
+                        gateway: gateways[index],
+                        status: 'rejected',
+                        durationMs: Infinity,
+                        error: result.reason,
+                    };
+                }
+            });
+            // Filter healthy gateways and sort by latency
+            const healthyGateways = processedResults
+                .filter((result) => result.status === 200)
+                .sort((a, b) => a.durationMs - b.durationMs);
+            if (healthyGateways.length > 0) {
+                return healthyGateways[0].gateway;
+            }
+            throw new Error('No healthy gateways found');
+        }
+        catch (error) {
+            throw new Error('Failed to ping gateways: ' +
+                (error instanceof Error ? error.message : String(error)));
+        }
+    }
+}

package/lib/esm/common/wayfinder/routing/strategies/preferred-with-fallback.js

@@ -0,0 +1,46 @@
+import { Logger } from '../../../logger.js';
+import { FastestPingRoutingStrategy } from './ping.js';
+export class PreferredWithFallbackRoutingStrategy {
+    name = 'preferred-with-fallback';
+    preferredGateway;
+    fallbackStrategy;
+    logger;
+    constructor({ preferredGateway, fallbackStrategy = new FastestPingRoutingStrategy(), logger = Logger.default, }) {
+        try {
+            this.preferredGateway = new URL(preferredGateway);
+        }
+        catch (error) {
+            throw new Error(`Invalid URL provided for preferred gateway: ${preferredGateway}`);
+        }
+        this.fallbackStrategy = fallbackStrategy;
+        this.logger = logger;
+    }
+    async selectGateway({ gateways = [] }) {
+        this.logger.debug('Attempting to connect to preferred gateway', {
+            preferredGateway: this.preferredGateway.toString(),
+        });
+        try {
+            // Check if the preferred gateway is responsive
+            const response = await fetch(this.preferredGateway.toString(), {
+                method: 'HEAD',
+                signal: AbortSignal.timeout(1000),
+            });
+            if (response.ok) {
+                this.logger.debug('Successfully connected to preferred gateway', {
+                    preferredGateway: this.preferredGateway.toString(),
+                });
+                return this.preferredGateway;
+            }
+            throw new Error(`Preferred gateway responded with status: ${response.status}`);
+        }
+        catch (error) {
+            this.logger.warn('Failed to connect to preferred gateway, falling back to alternative strategy', {
+                preferredGateway: this.preferredGateway.toString(),
+                error: error instanceof Error ? error.message : String(error),
+                fallbackStrategy: this.fallbackStrategy.constructor.name,
+            });
+            // Fall back to the provided routing strategy
+            return this.fallbackStrategy.selectGateway({ gateways });
+        }
+    }
+}

package/lib/esm/common/wayfinder/routing/strategies/random.js

@@ -0,0 +1,9 @@
+import { randomInt } from '../../../../utils/random.js';
+export class RandomRoutingStrategy {
+    async selectGateway({ gateways }) {
+        if (gateways.length === 0) {
+            throw new Error('No gateways available');
+        }
+        return gateways[randomInt(0, gateways.length)];
+    }
+}

package/lib/esm/common/wayfinder/routing/strategies/round-robin.js

@@ -0,0 +1,38 @@
+/**
+ * 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 { Logger } from '../../../../common/logger.js';
+export class RoundRobinRoutingStrategy {
+    gateways;
+    currentIndex;
+    logger;
+    constructor({ gateways, logger = Logger.default, }) {
+        this.gateways = gateways;
+        this.currentIndex = 0;
+        this.logger = logger;
+    }
+    // provided gateways are ignored
+    async selectGateway({ gateways = [], } = {}) {
+        if (gateways.length > 0) {
+            this.logger.warn('RoundRobinRoutingStrategy does not accept provided gateways. Ignoring provided gateways...', {
+                providedGateways: gateways.length,
+                internalGateways: this.gateways,
+            });
+        }
+        const gateway = this.gateways[this.currentIndex];
+        this.currentIndex = (this.currentIndex + 1) % this.gateways.length;
+        return gateway;
+    }
+}

package/lib/esm/common/wayfinder/routing/strategies/static.js

@@ -0,0 +1,25 @@
+import { Logger } from '../../../logger.js';
+export class StaticRoutingStrategy {
+    name = 'static';
+    gateway;
+    logger;
+    constructor({ gateway, logger = Logger.default, }) {
+        try {
+            this.gateway = new URL(gateway);
+        }
+        catch (error) {
+            throw new Error(`Invalid URL provided for static gateway: ${gateway}`);
+        }
+        this.logger = logger;
+    }
+    // provided gateways are ignored
+    async selectGateway({ gateways = [], } = {}) {
+        if (gateways.length > 0) {
+            this.logger.warn('StaticRoutingStrategy does not accept provided gateways. Ignoring provided gateways...', {
+                providedGateways: gateways.length,
+                internalGateway: this.gateway,
+            });
+        }
+        return this.gateway;
+    }
+}

package/lib/esm/common/wayfinder/verification/strategies/data-root-verifier.js

@@ -0,0 +1,102 @@
+/**
+ * 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 Arweave from 'arweave';
+import { MAX_CHUNK_SIZE, MIN_CHUNK_SIZE, buildLayers, generateLeaves, } from 'arweave/node/lib/merkle.js';
+import { toB64Url } from '../../../../utils/base64.js';
+import { isAsyncIterable, readableStreamToAsyncIterable, } from '../../../../utils/hash.js';
+export const convertDataStreamToDataRoot = async ({ dataStream, }) => {
+    const chunks = [];
+    let leftover = new Uint8Array(0);
+    let cursor = 0;
+    const asyncIterable = isAsyncIterable(dataStream)
+        ? dataStream
+        : readableStreamToAsyncIterable(dataStream);
+    for await (const data of asyncIterable) {
+        const inputChunk = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+        const combined = new Uint8Array(leftover.length + inputChunk.length);
+        combined.set(leftover, 0);
+        combined.set(inputChunk, leftover.length);
+        let startIndex = 0;
+        while (combined.length - startIndex >= MAX_CHUNK_SIZE) {
+            let chunkSize = MAX_CHUNK_SIZE;
+            const remainderAfterThis = combined.length - startIndex - MAX_CHUNK_SIZE;
+            if (remainderAfterThis > 0 && remainderAfterThis < MIN_CHUNK_SIZE) {
+                chunkSize = Math.ceil((combined.length - startIndex) / 2);
+            }
+            const chunkData = combined.slice(startIndex, startIndex + chunkSize);
+            const dataHash = await Arweave.crypto.hash(chunkData);
+            chunks.push({
+                dataHash,
+                minByteRange: cursor,
+                maxByteRange: cursor + chunkSize,
+            });
+            cursor += chunkSize;
+            startIndex += chunkSize;
+        }
+        leftover = combined.slice(startIndex);
+    }
+    if (leftover.length > 0) {
+        // TODO: ensure a web friendly crypto hash function is used in web
+        const dataHash = await Arweave.crypto.hash(leftover);
+        chunks.push({
+            dataHash,
+            minByteRange: cursor,
+            maxByteRange: cursor + leftover.length,
+        });
+    }
+    const leaves = await generateLeaves(chunks);
+    const root = await buildLayers(leaves);
+    return toB64Url(Buffer.from(root.id));
+};
+export class DataRootVerificationStrategy {
+    trustedDataRootProvider;
+    constructor({ trustedDataRootProvider, }) {
+        this.trustedDataRootProvider = trustedDataRootProvider;
+    }
+    async verifyData({ data, txId, }) {
+        const [computedDataRoot, trustedDataRoot] = await Promise.all([
+            convertDataStreamToDataRoot({
+                dataStream: data,
+            }),
+            this.trustedDataRootProvider.getDataRoot({
+                txId,
+            }),
+        ]);
+        if (computedDataRoot !== trustedDataRoot) {
+            throw new Error('Data root does not match', {
+                cause: { computedDataRoot, trustedDataRoot },
+            });
+        }
+    }
+}
+// some data item options
+// compute and verify data root, use offsets from server and verify the signature that the data item at the offset matches the signature
+// does not give you assurance of valid bundle, but gives verification that the data item itself is valid
+// reading from offsets is the only way for the client to compute and verify the signature
+/**
+ * - 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
+ */
+// introduce a composite verifier that determines where/how to lookup the hash

package/lib/esm/common/wayfinder/verification/strategies/hash-verifier.js

@@ -0,0 +1,23 @@
+import { hashDataStreamToB64Url } from '../../../../utils/hash.js';
+export class HashVerificationStrategy {
+    trustedHashProvider;
+    constructor({ trustedHashProvider, }) {
+        this.trustedHashProvider = trustedHashProvider;
+    }
+    async verifyData({ data, txId, }) {
+        // kick off the hash computation, but don't wait for it until we compute our own hash
+        const [computedHash, fetchedHash] = await Promise.all([
+            hashDataStreamToB64Url(data),
+            this.trustedHashProvider.getHash({ txId }),
+        ]);
+        // await on the hash promise and compare to get a little concurrency when computing hashes over larger data
+        if (computedHash === undefined) {
+            throw new Error('Hash could not be computed');
+        }
+        if (computedHash !== fetchedHash.hash) {
+            throw new Error('Hash does not match', {
+                cause: { computedHash, trustedHash: fetchedHash },
+            });
+        }
+    }
+}

package/lib/esm/common/wayfinder/verification/trusted.js

@@ -0,0 +1,121 @@
+import { sandboxFromId } from '../wayfinder.js';
+const arioGatewayHeaders = {
+    digest: 'x-ar-io-digest',
+    verified: 'x-ar-io-verified',
+    txId: 'x-arns-resolved-tx-id',
+    processId: 'x-arns-resolved-process-id',
+};
+export class TrustedGatewaysHashProvider {
+    gatewaysProvider;
+    constructor({ gatewaysProvider,
+    // TODO: add threshold for allowed hash difference (i.e. by count or ratio of total gateways checked)
+     }) {
+        this.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.
+     */
+    async getHash({ txId, }) {
+        // get the hash from every gateway, and ensure they all match
+        const hashSet = new Set();
+        const hashResults = [];
+        const gateways = await this.gatewaysProvider.getGateways();
+        const hashes = await Promise.all(gateways.map(async (gateway) => {
+            const sandbox = sandboxFromId(txId);
+            const urlWithSandbox = `${gateway.protocol}//${sandbox}.${gateway.hostname}/${txId}`;
+            let txIdHash;
+            /**
+             * This is a problem because we're not able to verify the hash of the data item if the gateway doesn't have the data in its cache.
+             * We should add the ability to send a HEAD request to trigger a GET request to hydrate the cache on the trusted gateway via a header.
+             * For now, we'll just do a GET request to hydrate the cache if the HEAD request doesn't contain the digest.
+             */
+            for (const method of ['GET', 'GET']) {
+                const response = await fetch(urlWithSandbox, {
+                    method,
+                    redirect: 'follow',
+                    mode: 'cors',
+                    headers: {
+                        'Cache-Control': 'no-cache',
+                    },
+                });
+                if (!response.ok) {
+                    // skip if the request failed or the digest is not present
+                    return;
+                }
+                const fetchedTxIdHash = response.headers.get(arioGatewayHeaders.digest);
+                if (fetchedTxIdHash !== null && fetchedTxIdHash !== undefined) {
+                    txIdHash = fetchedTxIdHash;
+                    break;
+                }
+            }
+            if (txIdHash === undefined) {
+                // skip this gateway if we didn't get a hash
+                return undefined;
+            }
+            hashResults.push({
+                gateway: gateway.hostname,
+                txIdHash,
+            });
+            return txIdHash;
+        }));
+        for (const hash of hashes) {
+            if (hash !== undefined) {
+                hashSet.add(hash);
+            }
+        }
+        if (hashSet.size === 0) {
+            throw new Error(`No trusted gateways returned a hash for txId ${txId}`);
+        }
+        if (hashSet.size > 1) {
+            throw new Error(`Failed to get consistent hash from all trusted gateways. ${JSON.stringify(hashResults)}`);
+        }
+        return { hash: hashResults[0].txIdHash, 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.
+     */
+    async getDataRoot({ txId }) {
+        const dataRootSet = new Set();
+        const dataRootResults = [];
+        const gateways = await this.gatewaysProvider.getGateways();
+        const dataRoots = await Promise.all(gateways.map(async (gateway) => {
+            const response = await fetch(`${gateway.toString()}tx/${txId}/data_root`);
+            if (!response.ok) {
+                // skip this gateway
+                return undefined;
+            }
+            const dataRoot = await response.text();
+            dataRootResults.push({
+                gateway: gateway.hostname,
+                dataRoot,
+            });
+            return dataRoot;
+        }));
+        for (const dataRoot of dataRoots) {
+            if (dataRoot !== undefined) {
+                dataRootSet.add(dataRoot);
+            }
+        }
+        if (dataRootSet.size > 1) {
+            throw new Error(`Failed to get consistent data root from all trusted gateways. ${JSON.stringify(dataRootResults)}`);
+        }
+        return dataRootSet.values().next().value;
+    }
+}
+// client could check hashes of data items, match expected hash
+// if the gateway has the hash and they've verified it, you can trust the data item and offset
+// you would be only trusting the gateway that it is a valid bundle
+// you can request the offset from the gateway to verify the id
+/**
+ * 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.
+ */