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

package/lib/cjs/common/index.js

@@ -38,3 +38,5 @@ __exportStar(require("./faucet.js"), exports);
 // ao
 __exportStar(require("./io.js"), exports);
 __exportStar(require("./contracts/ao-process.js"), exports);
+// wayfinder
+__exportStar(require("./wayfinder/index.js"), exports);

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

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SimpleCacheGatewaysProvider = exports.StaticGatewaysProvider = exports.ARIOGatewaysProvider = void 0;
+class ARIOGatewaysProvider {
+    ario;
+    constructor({ ario }) {
+        this.ario = ario;
+    }
+    async getGateways() {
+        let cursor;
+        let attempts = 0;
+        const gateways = [];
+        do {
+            try {
+                const { items: newGateways, nextCursor } = await this.ario.getGateways({
+                    limit: 1000,
+                    cursor,
+                });
+                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
+        return gateways.filter((g) => g.status === 'joined');
+    }
+}
+exports.ARIOGatewaysProvider = ARIOGatewaysProvider;
+class StaticGatewaysProvider {
+    gateways;
+    constructor({ gateways }) {
+        this.gateways = gateways;
+    }
+    async getGateways() {
+        return this.gateways;
+    }
+}
+exports.StaticGatewaysProvider = StaticGatewaysProvider;
+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.filter((g) => g.status === 'joined');
+                this.lastUpdated = now;
+            }
+            catch (error) {
+                console.error('Error fetching gateways', error);
+            }
+        }
+        return this.gatewaysCache;
+    }
+}
+exports.SimpleCacheGatewaysProvider = SimpleCacheGatewaysProvider;

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

@@ -0,0 +1,36 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * 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.
+ */
+__exportStar(require("./wayfinder.js"), exports);
+// routers
+__exportStar(require("./routers/random.js"), exports);
+__exportStar(require("./routers/priority.js"), exports);
+__exportStar(require("./routers/fixed.js"), exports);

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

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FixedGatewayRouter = void 0;
+class FixedGatewayRouter {
+    name = 'fixed';
+    gateway;
+    constructor({ gateway }) {
+        this.gateway = gateway;
+    }
+    async getTargetGateway() {
+        return this.gateway;
+    }
+}
+exports.FixedGatewayRouter = FixedGatewayRouter;

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 wayfinder_js_1 = require("../wayfinder.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, wayfinder_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 wayfinder_js_1 = require("../wayfinder.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, wayfinder_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;
+        }
+    });
+});