@ar.io/sdk 3.10.0-alpha.5 → 3.10.0-alpha.6

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

@@ -0,0 +1,153 @@
+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 mockGatewaysProvider = {
+        getGateways: async () => mockGateways,
+    };
+    it('should prioritize gateway with highest success rate when using successRate weight', async () => {
+        const router = new PriorityGatewayRouter({
+            gatewaysProvider: mockGatewaysProvider,
+            sortBy: 'totalDelegatedStake',
+            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({
+            gatewaysProvider: mockGatewaysProvider,
+            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

@@ -0,0 +1,19 @@
+import { randomInt } from '../wayfinder.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) => g.status === 'joined' && !this.blocklist.includes(g.settings.fqdn));
+        const targetGateway = gateways[randomInt(0, gateways.length)];
+        if (targetGateway === undefined) {
+            throw new Error('No target gateway found');
+        }
+        return new URL(`${targetGateway.settings.protocol}://${targetGateway.settings.fqdn}:${targetGateway.settings.port}`);
+    }
+}

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

@@ -0,0 +1,102 @@
+import { strict as assert } from 'node:assert';
+import { describe, it } from 'node:test';
+import { RandomGatewayRouter } from './random.js';
+describe('RandomRouter', () => {
+    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: '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 mockGatewaysProvider = {
+        getGateways: async () => mockGateways,
+    };
+    it('should only return joined gateways', async () => {
+        const router = new RandomGatewayRouter({
+            gatewaysProvider: mockGatewaysProvider,
+        });
+        // Run multiple times to ensure we only get joined gateways
+        for (let i = 0; i < 10; i++) {
+            const result = await router.getTargetGateway();
+            assert.deepStrictEqual(result, new URL('https://gateway1.net'));
+        }
+    });
+});

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

@@ -0,0 +1,21 @@
+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

@@ -0,0 +1,39 @@
+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/wayfinder.js

@@ -0,0 +1,187 @@
+/**
+ * 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 { webcrypto } from 'crypto';
+import { ARIO } from '../io.js';
+import { ARIOGatewaysProvider } from './gateways.js';
+import { RandomGatewayRouter } from './routers/random.js';
+// known regexes for wayfinder urls
+export const arnsRegex = /^[a-z0-9_-]{1,51}$/;
+export const txIdRegex = /^[a-z0-9]{43}$/;
+/**
+ * Cryptographically secure helper for randomness, does not support seeding
+ * @param min - the minimum value
+ * @param max - the maximum value
+ * @returns a random integer between min and max
+ */
+export const randomInt = (min, max) => {
+    const [rand] = webcrypto.getRandomValues(new Uint32Array(1));
+    return min + (rand % (max - min));
+};
+/**
+ * Core function to resolve a wayfinder url against a target gateway
+ * @param originalUrl - the wayfinder url to resolve
+ * @param targetGateway - the target gateway to resolve the url against
+ * @returns the resolved url that can be used to make a request
+ */
+export const resolveWayfinderUrl = ({ originalUrl, targetGateway, }) => {
+    if (originalUrl.toString().startsWith('ar://')) {
+        const [, path] = originalUrl.toString().split('ar://');
+        // e.g. ar:///info should route to the info endpoint of the target gateway
+        if (path.startsWith('/')) {
+            return new URL(path.slice(1), targetGateway);
+        }
+        // TODO: this breaks 43 character named arns names - we should check a a local name cache list before resolving raw transaction ids
+        if (txIdRegex.test(path)) {
+            const [txId, ...rest] = path.split('/');
+            return new URL(`${txId}${rest.join('/')}`, targetGateway);
+        }
+        if (arnsRegex.test(path)) {
+            // TODO: tests to ensure arns names support query params and paths
+            const [name, ...rest] = path.split('/');
+            const targetGatewayUrl = new URL(targetGateway);
+            const arnsUrl = `${targetGatewayUrl.protocol}//${name}.${targetGatewayUrl.hostname}${targetGatewayUrl.port ? `:${targetGatewayUrl.port}` : ''}`;
+            return new URL(rest.join('/'), arnsUrl);
+        }
+        // TODO: support .eth addresses
+        // TODO: "gasless" routing via DNS TXT records (e.g. ar://gatewaypie.com -> TXT record lookup for TX ID and redirect to that gateway)
+    }
+    // return the original url if it's not a wayfinder url (allows you to use the wayfinder client with non-wayfinder urls)
+    return new URL(originalUrl);
+};
+/**
+ * Creates a wrapped http client that supports ar:// protocol
+ *
+ * This function leverages a Proxy to intercept calls to the http client
+ * and redirects them to the target gateway using the resolveUrl function url.
+ * It also supports the http client methods like get(), post(), put(), delete(), etc.
+ *
+ * Any URLs provided that are not wayfinder urls will be returned as is.
+ *
+ * @param httpClient - the http client to wrap (e.g. axios, fetch, got, etc.)
+ * @param resolveUrl - the function to construct the redirect url for ar:// requests
+ * @returns a wrapped http client that supports ar:// protocol
+ */
+export const createWayfinderClient = ({ httpClient, resolveUrl, }) => {
+    const wayfinderRedirect = async (fn, rawArgs) => {
+        // TODO: handle if first arg is not a string (i.e. just return the result of the function call)
+        const [originalUrl, ...rest] = rawArgs;
+        // route the request to the target gateway
+        const redirectUrl = await resolveUrl({
+            originalUrl,
+        });
+        // make the request to the target gateway using the redirect url and http client
+        const response = await fn(redirectUrl.toString(), ...rest);
+        // TODO: if verifyDataHash is provided, verify the data hash before returning
+        return response;
+    };
+    return new Proxy(httpClient, {
+        // support direct calls: fetch('ar://…', options)
+        // axios() or got()
+        apply: (_target, _thisArg, argArray) => wayfinderRedirect(httpClient, argArray),
+        // support http clients that use methods like `got.get`, `got.post`, `axios.get`, etc. while still using the wayfinder redirect function
+        get: (target, prop, receiver) => {
+            const value = Reflect.get(target, prop, receiver);
+            if (typeof value === 'function') {
+                return (...inner) => wayfinderRedirect(value.bind(target), inner);
+            }
+            return value; // numbers, objects, symbols pass through untouched
+        },
+    });
+};
+/**
+ * The main class for the wayfinder
+ * @param router - the router to use for requests
+ * @param httpClient - the http client to use for requests
+ * @param blocklist - the blocklist of gateways to avoid
+ */
+export class Wayfinder {
+    /**
+     * The router to use for requests
+     *
+     * @example
+     * const wayfinder = new Wayfinder({
+     *   router: new RandomGatewayRouter({ ario: ARIO.mainnet() }),
+     * });
+     */
+    router;
+    /**
+     * The http client to use for requests
+     *
+     * @example
+     * const wayfinder = new Wayfinder({
+     *   router: new RandomGatewayRouter({ ario: ARIO.mainnet() }),
+     *   httpClient: axios,
+     * });
+     */
+    httpClient;
+    /**
+     * The function that resolves the redirect url for ar:// requests to a target gateway
+     *
+     * @example
+     * const wayfinder = new Wayfinder({
+     *   router: new RandomGatewayRouter({ ario: ARIO.mainnet() }),
+     *   httpClient: axios,
+     * });
+     *
+     * const redirectUrl = await wayfinder.resolveUrl({ originalUrl: 'ar://example' });
+     */
+    resolveUrl;
+    /**
+     * A wrapped http client that supports ar:// protocol
+     *
+     * @example
+     * const { request: wayfind } = new Wayfinder({
+     *   router: new RandomGatewayRouter({ ario: ARIO.mainnet() }),
+     *   httpClient: axios,
+     * });;
+     *
+     * TODO: consider a top level function that supports wayfinder routing under the hood
+     * const response = await wayfind('ar://', {
+     *   method: 'POST',
+     *   data: {
+     *     name: 'John Doe',
+     *   },
+     * })
+     */
+    request;
+    // TODO: stats provider
+    // TODO: metricsProvider for otel/prom support
+    // TODO: private verificationSettings: {
+    //   trustedGateways: URL[];
+    //   method: 'local' | 'remote';
+    // };
+    constructor({ 
+    // TODO: consider changing router to routingStrategy or strategy
+    router = new RandomGatewayRouter({
+        // optionally use a cache gateways provider to reduce the number of requests to the contract
+        gatewaysProvider: new ARIOGatewaysProvider({ ario: ARIO.mainnet() }),
+    }), httpClient,
+    // TODO: add verifier interface that provides a verifyDataHash function
+    // TODO: stats provider
+     }) {
+        this.router = router;
+        this.httpClient = httpClient;
+        this.resolveUrl = async ({ originalUrl }) => resolveWayfinderUrl({
+            originalUrl,
+            targetGateway: await this.router.getTargetGateway(),
+        });
+        this.request = createWayfinderClient({
+            httpClient,
+            resolveUrl: this.resolveUrl,
+            // TODO: provide the verifyDataHash function from the verifier to the wayfinder client along with verificationSettings
+        });
+    }
+}