@ar.io/sdk 3.10.0 → 3.11.0-alpha.2

package/lib/cjs/common/wayfinder/routers/fixed.test.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_assert_1 = require("node:assert");
+const node_test_1 = require("node:test");
+const fixed_js_1 = require("./fixed.js");
+(0, node_test_1.describe)('FixedRouter', () => {
+    (0, node_test_1.it)('should return the provided gateway', async () => {
+        const router = new fixed_js_1.FixedGatewayRouter({
+            gateway: new URL('http://test-gateway.net'),
+        });
+        const result = await router.getTargetGateway();
+        node_assert_1.strict.deepStrictEqual(result, new URL('http://test-gateway.net'));
+    });
+});

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

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PriorityGatewayRouter = void 0;
+const random_js_1 = require("../../../utils/random.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
+class PriorityGatewayRouter {
+    name = 'priority';
+    gatewaysProvider;
+    limit;
+    sortBy;
+    sortOrder;
+    blocklist;
+    constructor({ gatewaysProvider, limit = 1, sortBy = 'operatorStake', sortOrder = 'desc', blocklist = [], }) {
+        this.gatewaysProvider = gatewaysProvider;
+        this.limit = limit;
+        this.sortBy = sortBy;
+        this.sortOrder = sortOrder;
+        this.blocklist = blocklist;
+    }
+    async getTargetGateway() {
+        const allGateways = await this.gatewaysProvider.getGateways();
+        const gateways = allGateways.filter((gateway) => gateway.status === 'joined' &&
+            !this.blocklist.includes(gateway.settings.fqdn));
+        const sortedGateways = gateways
+            .sort(this.sortOrder === 'asc'
+            ? (a, b) => a[this.sortBy] - b[this.sortBy]
+            : (a, b) => b[this.sortBy] - a[this.sortBy])
+            .slice(0, this.limit);
+        const targetGateway = sortedGateways[(0, random_js_1.randomInt)(0, sortedGateways.length)];
+        if (targetGateway === undefined) {
+            throw new Error('No target gateway found');
+        }
+        return new URL(`${targetGateway.settings.protocol}://${targetGateway.settings.fqdn}:${targetGateway.settings.port}`);
+    }
+}
+exports.PriorityGatewayRouter = PriorityGatewayRouter;

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

@@ -0,0 +1,155 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_assert_1 = require("node:assert");
+const node_test_1 = require("node:test");
+const priority_js_1 = require("./priority.js");
+(0, node_test_1.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,
+    };
+    (0, node_test_1.it)('should prioritize gateway with highest success rate when using successRate weight', async () => {
+        const router = new priority_js_1.PriorityGatewayRouter({
+            gatewaysProvider: mockGatewaysProvider,
+            sortBy: 'totalDelegatedStake',
+            sortOrder: 'desc',
+            limit: 1,
+        });
+        const result = await router.getTargetGateway();
+        node_assert_1.strict.deepStrictEqual(result, new URL('http://gateway1.net'));
+    });
+    (0, node_test_1.it)('should prioritize gateway with lowest latency when using latency weight', async () => {
+        const router = new priority_js_1.PriorityGatewayRouter({
+            gatewaysProvider: mockGatewaysProvider,
+            sortBy: 'operatorStake',
+            sortOrder: 'desc',
+            limit: 1,
+        });
+        const result = await router.getTargetGateway();
+        node_assert_1.strict.deepStrictEqual(result, new URL('http://gateway2.net'));
+    });
+});

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

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RandomGatewayRouter = void 0;
+const random_js_1 = require("../../../utils/random.js");
+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[(0, random_js_1.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}`);
+    }
+}
+exports.RandomGatewayRouter = RandomGatewayRouter;

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

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_assert_1 = require("node:assert");
+const node_test_1 = require("node:test");
+const random_js_1 = require("./random.js");
+(0, node_test_1.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,
+    };
+    (0, node_test_1.it)('should only return joined gateways', async () => {
+        const router = new random_js_1.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();
+            node_assert_1.strict.deepStrictEqual(result, new URL('https://gateway1.net'));
+        }
+    });
+});

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

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SimpleCacheRouter = void 0;
+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;
+    }
+}
+exports.SimpleCacheRouter = SimpleCacheRouter;
+// 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/cjs/common/wayfinder/routers/simple-cache.test.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_assert_1 = require("node:assert");
+const node_test_1 = require("node:test");
+const simple_cache_js_1 = require("./simple-cache.js");
+(0, node_test_1.describe)('SimpleCacheRouter', () => {
+    (0, node_test_1.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 simple_cache_js_1.SimpleCacheRouter({
+            router: mockRouter,
+            ttlSeconds: 300, // 5 minutes
+        });
+        // Get initial gateway which should be cached
+        const initial = await router.getTargetGateway();
+        node_assert_1.strict.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();
+            node_assert_1.strict.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();
+            node_assert_1.strict.deepStrictEqual(result, gateway2);
+        }
+        finally {
+            Date.now = originalNow;
+        }
+    });
+});

package/lib/cjs/common/wayfinder/wayfinder.js

@@ -0,0 +1,174 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Wayfinder = exports.createWayfinderClient = exports.resolveWayfinderUrl = exports.txIdRegex = exports.arnsRegex = void 0;
+const io_js_1 = require("../io.js");
+const gateways_js_1 = require("./gateways.js");
+const random_js_1 = require("./routers/random.js");
+// known regexes for wayfinder urls
+exports.arnsRegex = /^[a-z0-9_-]{1,51}$/;
+exports.txIdRegex = /^[a-z0-9]{43}$/;
+/**
+ * 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
+ */
+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 (exports.txIdRegex.test(path)) {
+            const [txId, ...rest] = path.split('/');
+            return new URL(`${txId}${rest.join('/')}`, targetGateway);
+        }
+        if (exports.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);
+};
+exports.resolveWayfinderUrl = resolveWayfinderUrl;
+/**
+ * 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
+ */
+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
+        },
+    });
+};
+exports.createWayfinderClient = createWayfinderClient;
+/**
+ * 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
+ */
+class Wayfinder {
+    /**
+     * The router to use for requests
+     *
+     * @example
+     * const wayfinder = new Wayfinder({
+     *   router: new RandomGatewayRouter({
+     *     gatewaysProvider: new ARIOGatewaysProvider({ ario: ARIO.mainnet() })
+     *   }),
+     * });
+     */
+    router;
+    /**
+     * The http client to use for requests
+     *
+     * @example
+     * const wayfinder = new Wayfinder({
+     *   router: new RandomGatewayRouter({
+     *     gatewaysProvider: new ARIOGatewaysProvider({ 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({
+     *     gatewaysProvider: new ARIOGatewaysProvider({ 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({
+     *     gatewaysProvider: new ARIOGatewaysProvider({ ario: ARIO.mainnet() })
+     *   }),
+     *   httpClient: axios,
+     * });;
+     *
+     * const response = await wayfind('ar://example', {
+     *   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 random_js_1.RandomGatewayRouter({
+        // optionally use a cache gateways provider to reduce the number of requests to the contract
+        gatewaysProvider: new gateways_js_1.ARIOGatewaysProvider({ ario: io_js_1.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 }) => (0, exports.resolveWayfinderUrl)({
+            originalUrl,
+            targetGateway: await this.router.getTargetGateway(),
+        });
+        this.request = (0, exports.createWayfinderClient)({
+            httpClient,
+            resolveUrl: this.resolveUrl,
+            // TODO: provide the verifyDataHash function from the verifier to the wayfinder client along with verificationSettings
+        });
+    }
+}
+exports.Wayfinder = Wayfinder;