@ar.io/sdk 3.11.0-alpha.9 → 3.11.0

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

@@ -1,80 +0,0 @@
-export class NetworkGatewaysProvider {
-    ario;
-    sortBy;
-    sortOrder;
-    limit;
-    filter;
-    constructor({ ario, 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}`));
-    }
-}
-export class StaticGatewaysProvider {
-    gateways;
-    constructor({ gateways }) {
-        this.gateways = gateways.map((g) => new URL(g));
-    }
-    async getGateways() {
-        return this.gateways;
-    }
-}
-export class SimpleCacheGatewaysProvider {
-    gatewaysProvider;
-    ttlSeconds;
-    lastUpdated;
-    gatewaysCache;
-    constructor({ gatewaysProvider, ttlSeconds = 5 * 60, // 5 minutes
-     }) {
-        this.gatewaysCache = [];
-        this.gatewaysProvider = gatewaysProvider;
-        this.ttlSeconds = ttlSeconds;
-    }
-    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) {
-                console.error('Error fetching gateways', error);
-            }
-        }
-        return this.gatewaysCache;
-    }
-}

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

@@ -1,28 +0,0 @@
-/**
- * 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';
-// routers
-export * from './routers/random.js';
-export * from './routers/priority.js';
-export * from './routers/static.js';
-// gateways providers
-export * from './gateways.js';
-// trusted gateways
-export * from './gateways/trusted-gateways.js';
-// hash providers
-export * from './verification/data-root-verifier.js';
-export * from './verification/hash-verifier.js';
-// TODO: signature verification

package/lib/esm/common/wayfinder/routers/priority.js

@@ -1,25 +0,0 @@
-import { randomInt } from '../../../utils/random.js';
-import { NetworkGatewaysProvider } from '../gateways.js';
-// TODO: one of N where N are in the last time window have met certain performance thresholds
-// TODO: look at bitorrent routing protocols for inspiration
-// TODO: router that looks at local stats/metrics and adjusts based on those
-export class PriorityGatewayRouter {
-    name = 'priority';
-    gatewaysProvider;
-    constructor({ ario, sortBy, sortOrder, limit, }) {
-        this.gatewaysProvider = new NetworkGatewaysProvider({
-            ario,
-            sortBy,
-            sortOrder,
-            limit,
-        });
-    }
-    async getTargetGateway() {
-        const gateways = await this.gatewaysProvider.getGateways();
-        const targetGateway = gateways[randomInt(0, gateways.length)];
-        if (targetGateway === undefined) {
-            throw new Error('No target gateway found');
-        }
-        return targetGateway;
-    }
-}

package/lib/esm/common/wayfinder/routers/priority.test.js

@@ -1,153 +0,0 @@
-import { strict as assert } from 'node:assert';
-import { describe, it } from 'node:test';
-import { PriorityGatewayRouter } from './priority.js';
-describe('PriorityRouter', () => {
-    const mockGateways = [
-        {
-            settings: {
-                fqdn: 'gateway1.net',
-                port: 443,
-                protocol: 'https',
-                allowDelegatedStaking: false,
-                delegateRewardShareRatio: 0.5,
-                allowedDelegates: [],
-                minDelegatedStake: 0,
-                autoStake: false,
-                properties: '',
-                label: '',
-                note: '',
-            },
-            gatewayAddress: 'addr1',
-            observerAddress: 'addr1',
-            totalDelegatedStake: 1000,
-            startTimestamp: 0,
-            endTimestamp: 0,
-            operatorStake: 100,
-            status: 'joined',
-            weights: {
-                normalizedCompositeWeight: 0.5,
-                stakeWeight: 0.5,
-                tenureWeight: 0.5,
-                gatewayPerformanceRatio: 0.5,
-                observerPerformanceRatio: 0.5,
-                compositeWeight: 0.5,
-                gatewayRewardRatioWeight: 0.5,
-                observerRewardRatioWeight: 0.5,
-            },
-            stats: {
-                passedConsecutiveEpochs: 10,
-                failedConsecutiveEpochs: 5,
-                totalEpochCount: 15,
-                passedEpochCount: 10,
-                failedEpochCount: 5,
-                observedEpochCount: 15,
-                prescribedEpochCount: 20,
-            },
-        },
-        {
-            settings: {
-                fqdn: 'gateway1.net',
-                port: 443,
-                protocol: 'https',
-                allowDelegatedStaking: false,
-                delegateRewardShareRatio: 0.5,
-                allowedDelegates: [],
-                minDelegatedStake: 0,
-                autoStake: false,
-                properties: '',
-                label: '',
-                note: '',
-            },
-            gatewayAddress: 'addr1',
-            observerAddress: 'addr1',
-            totalDelegatedStake: 2000,
-            startTimestamp: 0,
-            endTimestamp: 0,
-            operatorStake: 2000,
-            status: 'joined',
-            weights: {
-                normalizedCompositeWeight: 0.5,
-                stakeWeight: 0.5,
-                tenureWeight: 0.5,
-                gatewayPerformanceRatio: 0.5,
-                observerPerformanceRatio: 0.5,
-                compositeWeight: 0.5,
-                gatewayRewardRatioWeight: 0.5,
-                observerRewardRatioWeight: 0.5,
-            },
-            stats: {
-                passedConsecutiveEpochs: 10,
-                failedConsecutiveEpochs: 5,
-                totalEpochCount: 15,
-                passedEpochCount: 10,
-                failedEpochCount: 5,
-                observedEpochCount: 15,
-                prescribedEpochCount: 20,
-            },
-        },
-        {
-            settings: {
-                fqdn: 'gateway2.net',
-                port: 443,
-                protocol: 'https',
-                allowDelegatedStaking: false,
-                delegateRewardShareRatio: 0.5,
-                allowedDelegates: [],
-                minDelegatedStake: 0,
-                autoStake: false,
-                properties: '',
-                label: '',
-                note: '',
-            },
-            gatewayAddress: 'addr2',
-            observerAddress: 'addr2',
-            totalDelegatedStake: 0,
-            startTimestamp: 0,
-            endTimestamp: 0,
-            operatorStake: 0,
-            status: 'leaving',
-            weights: {
-                normalizedCompositeWeight: 0.5,
-                stakeWeight: 0.5,
-                tenureWeight: 0.5,
-                gatewayPerformanceRatio: 0.5,
-                observerPerformanceRatio: 0.5,
-                compositeWeight: 0.5,
-                gatewayRewardRatioWeight: 0.5,
-                observerRewardRatioWeight: 0.5,
-            },
-            stats: {
-                passedConsecutiveEpochs: 10,
-                failedConsecutiveEpochs: 5,
-                totalEpochCount: 15,
-                passedEpochCount: 10,
-                failedEpochCount: 5,
-                observedEpochCount: 15,
-                prescribedEpochCount: 20,
-            },
-        },
-    ];
-    const mockArIOClient = {
-        getGateways: async () => ({ items: mockGateways }),
-    };
-    it('should prioritize gateway with highest success rate when using successRate weight', async () => {
-        const router = new PriorityGatewayRouter({
-            ario: mockArIOClient,
-            sortBy: 'operatorStake',
-            sortOrder: 'desc',
-            limit: 1,
-        });
-        const result = await router.getTargetGateway();
-        assert.deepStrictEqual(result, new URL('http://gateway1.net'));
-    });
-    it('should prioritize gateway with lowest latency when using latency weight', async () => {
-        const router = new PriorityGatewayRouter({
-            ario: mockArIOClient,
-            sortBy: 'operatorStake',
-            sortOrder: 'desc',
-            limit: 1,
-        });
-        const result = await router.getTargetGateway();
-        assert.deepStrictEqual(result, new URL('http://gateway2.net'));
-    });
-});

package/lib/esm/common/wayfinder/routers/random.js

@@ -1,19 +0,0 @@
-import { randomInt } from '../../../utils/random.js';
-export class RandomGatewayRouter {
-    name = 'random';
-    gatewaysProvider;
-    blocklist;
-    constructor({ gatewaysProvider, blocklist = [], }) {
-        this.gatewaysProvider = gatewaysProvider;
-        this.blocklist = blocklist;
-    }
-    async getTargetGateway() {
-        const allGateways = await this.gatewaysProvider.getGateways();
-        const gateways = allGateways.filter((g) => !this.blocklist.includes(g.hostname));
-        const targetGateway = gateways[randomInt(0, gateways.length)];
-        if (targetGateway === undefined) {
-            throw new Error('No target gateway found');
-        }
-        return targetGateway;
-    }
-}

package/lib/esm/common/wayfinder/routers/random.test.js

@@ -1,23 +0,0 @@
-import { strict as assert } from 'node:assert';
-import { describe, it } from 'node:test';
-import { RandomGatewayRouter } from './random.js';
-describe('RandomRouter', () => {
-    const mockGateways = [
-        new URL('https://gateway1.net'),
-        new URL('https://gateway2.net'),
-        new URL('https://gateway3.net'),
-    ];
-    const mockGatewaysProvider = {
-        getGateways: async () => mockGateways,
-    };
-    it('should only return joined gateways', async () => {
-        const router = new RandomGatewayRouter({
-            gatewaysProvider: mockGatewaysProvider,
-        });
-        // random gateway should be one of the mock gateways
-        for (let i = 0; i < 10; i++) {
-            const result = await router.getTargetGateway();
-            assert.ok(mockGateways.includes(result));
-        }
-    });
-});

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

@@ -1,21 +0,0 @@
-export class SimpleCacheRouter {
-    name;
-    lastUpdatedTimestamp;
-    ttlSeconds;
-    targetGateway;
-    router;
-    constructor({ router, ttlSeconds = 5 * 60, // 5 minutes
-     }) {
-        this.router = router;
-        this.ttlSeconds = ttlSeconds;
-    }
-    async getTargetGateway() {
-        if (this.targetGateway === undefined ||
-            this.lastUpdatedTimestamp + this.ttlSeconds * 1000 < Date.now()) {
-            this.targetGateway = await this.router.getTargetGateway();
-            this.lastUpdatedTimestamp = Date.now();
-        }
-        return this.targetGateway;
-    }
-}
-// TODO: a router that accepts ario and a router, and adds read through promise cache to ario.getGateways to avoid calling the ARIO contract on every request

package/lib/esm/common/wayfinder/routers/simple-cache.test.js

@@ -1,39 +0,0 @@
-import { strict as assert } from 'node:assert';
-import { describe, it } from 'node:test';
-import { SimpleCacheRouter } from './simple-cache.js';
-describe('SimpleCacheRouter', () => {
-    it('should cache gateway for TTL period even if underlying gateway changes', async () => {
-        const gateway1 = new URL('https://gateway1.net');
-        const gateway2 = new URL('https://gateway2.net');
-        let currentGateway = gateway1;
-        const mockRouter = {
-            name: 'mock',
-            getTargetGateway: async () => currentGateway,
-        };
-        const router = new SimpleCacheRouter({
-            router: mockRouter,
-            ttlSeconds: 300, // 5 minutes
-        });
-        // Get initial gateway which should be cached
-        const initial = await router.getTargetGateway();
-        assert.deepStrictEqual(initial, gateway1);
-        // Change the underlying gateway
-        currentGateway = gateway2;
-        // Should still return cached gateway1 for multiple calls
-        for (let i = 0; i < 5; i++) {
-            const result = await router.getTargetGateway();
-            assert.deepStrictEqual(result, gateway1);
-        }
-        // Advance time past TTL
-        const originalNow = Date.now;
-        try {
-            Date.now = () => originalNow() + 300 * 1000 + 1;
-            // Should now return the new gateway2
-            const result = await router.getTargetGateway();
-            assert.deepStrictEqual(result, gateway2);
-        }
-        finally {
-            Date.now = originalNow;
-        }
-    });
-});

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

@@ -1,10 +0,0 @@
-export class StaticGatewayRouter {
-    name = 'static';
-    gateway;
-    constructor({ gateway }) {
-        this.gateway = new URL(gateway);
-    }
-    async getTargetGateway() {
-        return this.gateway;
-    }
-}

package/lib/esm/common/wayfinder/routers/static.test.js

@@ -1,12 +0,0 @@
-import { strict as assert } from 'node:assert';
-import { describe, it } from 'node:test';
-import { StaticGatewayRouter } from './static.js';
-describe('StaticGatewayRouter', () => {
-    it('should return the provided gateway', async () => {
-        const router = new StaticGatewayRouter({
-            gateway: 'http://test-gateway.net',
-        });
-        const result = await router.getTargetGateway();
-        assert.deepStrictEqual(result, new URL('http://test-gateway.net'));
-    });
-});

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

@@ -1,130 +0,0 @@
-/**
- * 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 { Readable } from 'node:stream';
-import { toB64Url } from '../../../utils/base64.js';
-export async function convertBufferToDataRoot({ buffer, }) {
-    const chunks = [];
-    let cursor = 0;
-    let offset = 0;
-    while (offset < buffer.byteLength) {
-        let chunkSize = Math.min(MAX_CHUNK_SIZE, buffer.byteLength - offset);
-        const remainder = buffer.byteLength - offset - chunkSize;
-        if (remainder > 0 && remainder < MIN_CHUNK_SIZE) {
-            chunkSize = Math.ceil((buffer.byteLength - offset) / 2);
-        }
-        // subarray does not exist on web Buffer type
-        const slice = buffer.subarray(offset, offset + chunkSize);
-        const hash = await crypto.subtle.digest('SHA-256', slice);
-        const hashArray = new Uint8Array(hash);
-        chunks.push({
-            dataHash: hashArray,
-            minByteRange: cursor,
-            maxByteRange: cursor + chunkSize,
-        });
-        cursor += chunkSize;
-        offset += chunkSize;
-    }
-    const leaves = await generateLeaves(chunks);
-    const result = await buildLayers(leaves);
-    return Buffer.from(result.id).toString('base64url');
-}
-export const convertReadableToDataRoot = async ({ iterable, }) => {
-    const chunks = [];
-    let leftover = new Uint8Array(0);
-    let cursor = 0;
-    for await (const data of iterable) {
-        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) {
-        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 DataRootVerifier {
-    trustedDataRootProvider;
-    constructor({ trustedDataRootProvider, }) {
-        this.trustedDataRootProvider = trustedDataRootProvider;
-    }
-    async verifyData({ data, txId, }) {
-        const trustedDataRootPromise = this.trustedDataRootProvider.getDataRoot({
-            txId,
-        });
-        let computedDataRoot;
-        if (Buffer.isBuffer(data)) {
-            computedDataRoot = await convertBufferToDataRoot({ buffer: data });
-        }
-        else if (data instanceof Readable || data instanceof ReadableStream) {
-            computedDataRoot = await convertReadableToDataRoot({ iterable: data });
-        }
-        if (computedDataRoot === undefined) {
-            throw new Error('Data root could not be computed');
-        }
-        const trustedDataRoot = await trustedDataRootPromise;
-        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/hash-verifier.js

@@ -1,46 +0,0 @@
-/**
- * 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 { hashBufferToB64Url, hashReadableStreamToB64Url, hashReadableToB64Url, } from '../../../utils/hash.js';
-export class HashVerifier {
-    trustedHashProvider;
-    constructor({ trustedHashProvider, }) {
-        this.trustedHashProvider = trustedHashProvider;
-    }
-    async verifyData({ data, txId, }) {
-        const hashPromise = this.trustedHashProvider.getHash({ txId });
-        let computedHash;
-        if (Buffer.isBuffer(data)) {
-            computedHash = hashBufferToB64Url(data);
-        }
-        else if (data instanceof Readable) {
-            computedHash = await hashReadableToB64Url(data);
-        }
-        else if (data instanceof ReadableStream) {
-            computedHash = await hashReadableStreamToB64Url(data);
-        }
-        // await on the hash promise and compare to get a little concurrency when computing hashes over larger data
-        const { hash } = await hashPromise;
-        if (computedHash === undefined) {
-            throw new Error('Hash could not be computed');
-        }
-        if (computedHash !== hash) {
-            throw new Error('Hash does not match', {
-                cause: { computedHash, trustedHash: hash },
-            });
-        }
-    }
-}