@ar.io/sdk 3.11.0-alpha.8 → 3.11.0-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ar.io/sdk",
-  "version": "3.11.0-alpha.8",
+  "version": "3.11.0-beta.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ar-io/ar-io-sdk.git"

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

@@ -1,29 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.PriorityGatewayRouter = void 0;
-const random_js_1 = require("../../../utils/random.js");
-const gateways_js_1 = require("../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
-class PriorityGatewayRouter {
-    name = 'priority';
-    gatewaysProvider;
-    constructor({ ario, sortBy, sortOrder, limit, }) {
-        this.gatewaysProvider = new gateways_js_1.NetworkGatewaysProvider({
-            ario,
-            sortBy,
-            sortOrder,
-            limit,
-        });
-    }
-    async getTargetGateway() {
-        const gateways = await this.gatewaysProvider.getGateways();
-        const targetGateway = gateways[(0, random_js_1.randomInt)(0, gateways.length)];
-        if (targetGateway === undefined) {
-            throw new Error('No target gateway found');
-        }
-        return targetGateway;
-    }
-}
-exports.PriorityGatewayRouter = PriorityGatewayRouter;

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

@@ -1,155 +0,0 @@
-"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 mockArIOClient = {
-        getGateways: async () => ({ items: 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({
-            ario: mockArIOClient,
-            sortBy: 'operatorStake',
-            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({
-            ario: mockArIOClient,
-            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

@@ -1,23 +0,0 @@
-"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) => !this.blocklist.includes(g.hostname));
-        const targetGateway = gateways[(0, random_js_1.randomInt)(0, gateways.length)];
-        if (targetGateway === undefined) {
-            throw new Error('No target gateway found');
-        }
-        return targetGateway;
-    }
-}
-exports.RandomGatewayRouter = RandomGatewayRouter;

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

@@ -1,25 +0,0 @@
-"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 = [
-        new URL('https://gateway1.net'),
-        new URL('https://gateway2.net'),
-        new URL('https://gateway3.net'),
-    ];
-    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,
-        });
-        // random gateway should be one of the mock gateways
-        for (let i = 0; i < 10; i++) {
-            const result = await router.getTargetGateway();
-            node_assert_1.strict.ok(mockGateways.includes(result));
-        }
-    });
-});

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

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

@@ -1,41 +0,0 @@
-"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/routers/static.js

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

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

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

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'));
-    });
-});