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

package/lib/esm/common/index.js

@@ -22,3 +22,5 @@ export * from './faucet.js';
 // ao
 export * from './io.js';
 export * from './contracts/ao-process.js';
+// wayfinder
+export * from './wayfinder/index.js';

package/lib/esm/common/io.js

@@ -22,6 +22,7 @@ import { defaultArweave } from './arweave.js';
 import { AOProcess } from './contracts/ao-process.js';
 import { InvalidContractConfigurationError } from './error.js';
 import { createFaucet } from './faucet.js';
+import { TurboArNSPaymentFactory, TurboArNSPaymentProviderAuthenticated, isTurboArNSSigner, } from './turbo.js';
 export class ARIO {
     // Implementation
     static init(config) {
@@ -85,6 +86,7 @@ export class ARIOReadable {
     process;
     epochSettings;
     arweave;
+    paymentProvider; // TODO: this could be an array/map of payment providers
     constructor(config) {
         this.arweave = config?.arweave ?? defaultArweave;
         if (config === undefined || Object.keys(config).length === 0) {
@@ -103,6 +105,9 @@ export class ARIOReadable {
         else {
             throw new InvalidContractConfigurationError();
         }
+        this.paymentProvider = TurboArNSPaymentFactory.init({
+            paymentUrl: config?.paymentUrl,
+        });
     }
     async getInfo() {
         return this.process.read({
@@ -434,6 +439,20 @@ export class ARIOReadable {
     // TODO: Can overload this function to refine different types of cost details params
     async getCostDetails({ intent, type, years, name, quantity, fromAddress, fundFrom, }) {
         const replacedBuyRecordWithBuyName = intent === 'Buy-Record' ? 'Buy-Name' : intent;
+        if (fundFrom === 'turbo') {
+            const { mARIO, winc } = await this.paymentProvider.getArNSPriceDetails({
+                intent: replacedBuyRecordWithBuyName,
+                name,
+                quantity,
+                type,
+                years,
+            });
+            return {
+                tokenCost: +mARIO,
+                wincQty: winc,
+                discounts: [],
+            };
+        }
         const allTags = [
             { name: 'Action', value: 'Cost-Details' },
             {
@@ -600,7 +619,8 @@ export class ARIOReadable {
 }
 export class ARIOWriteable extends ARIOReadable {
     signer;
-    constructor({ signer, ...config }) {
+    paymentProvider;
+    constructor({ signer, paymentUrl, ...config }) {
         if (config === undefined) {
             super({
                 process: new AOProcess({
@@ -612,6 +632,10 @@ export class ARIOWriteable extends ARIOReadable {
             super(config);
         }
         this.signer = createAoSigner(signer);
+        this.paymentProvider = TurboArNSPaymentFactory.init({
+            signer: isTurboArNSSigner(signer) ? signer : undefined,
+            paymentUrl,
+        });
     }
     async transfer({ target, qty, }, options) {
         const { tags = [] } = options || {};
@@ -886,6 +910,15 @@ export class ARIOWriteable extends ARIOReadable {
         });
     }
     async buyRecord(params, options) {
+        if (params.fundFrom === 'turbo') {
+            if (!(this.paymentProvider instanceof TurboArNSPaymentProviderAuthenticated)) {
+                throw new Error('Turbo funding is not supported for this payment provider');
+            }
+            return this.paymentProvider.initiateArNSPurchase({
+                intent: 'Buy-Name',
+                ...params,
+            });
+        }
         const { tags = [] } = options || {};
         const allTags = [
             ...tags,
@@ -910,6 +943,15 @@ export class ARIOWriteable extends ARIOReadable {
      * @returns {Promise<AoMessageResult>} The result of the upgrade
      */
     async upgradeRecord(params, options) {
+        if (params.fundFrom === 'turbo') {
+            if (!(this.paymentProvider instanceof TurboArNSPaymentProviderAuthenticated)) {
+                throw new Error('Turbo funding is not supported for this payment provider');
+            }
+            return this.paymentProvider.initiateArNSPurchase({
+                intent: 'Upgrade-Name',
+                name: params.name,
+            });
+        }
         const { tags = [] } = options || {};
         const allTags = [
             ...tags,
@@ -932,6 +974,15 @@ export class ARIOWriteable extends ARIOReadable {
      * @returns {Promise<AoMessageResult>} The result of the extension
      */
     async extendLease(params, options) {
+        if (params.fundFrom === 'turbo') {
+            if (!(this.paymentProvider instanceof TurboArNSPaymentProviderAuthenticated)) {
+                throw new Error('Turbo funding is not supported for this payment provider');
+            }
+            return this.paymentProvider.initiateArNSPurchase({
+                intent: 'Extend-Lease',
+                ...params,
+            });
+        }
         const { tags = [] } = options || {};
         const allTags = [
             ...tags,
@@ -946,6 +997,15 @@ export class ARIOWriteable extends ARIOReadable {
         });
     }
     async increaseUndernameLimit(params, options) {
+        if (params.fundFrom === 'turbo') {
+            if (!(this.paymentProvider instanceof TurboArNSPaymentProviderAuthenticated)) {
+                throw new Error('Turbo funding is not supported for this payment provider');
+            }
+            return this.paymentProvider.initiateArNSPurchase({
+                intent: 'Increase-Undername-Limit',
+                ...params,
+            });
+        }
         const { tags = [] } = options || {};
         const allTags = [
             ...tags,
@@ -982,6 +1042,9 @@ export class ARIOWriteable extends ARIOReadable {
         });
     }
     async requestPrimaryName(params, options) {
+        if (params.fundFrom === 'turbo') {
+            throw new Error('Turbo funding is not yet supported for primary name requests');
+        }
         const { tags = [] } = options || {};
         const allTags = [
             ...tags,

package/lib/esm/common/turbo.js

@@ -0,0 +1,200 @@
+/**
+ * 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 { ArconnectSigner, ArweaveSigner, EthereumSigner, InjectedEthereumSigner, SignatureConfig, } from '@dha-team/arbundles';
+import { v4 as uuidv4 } from 'uuid';
+import { mARIOToken } from '../types/token.js';
+import { toB64Url } from '../utils/base64.js';
+import { createAxiosInstance } from '../utils/http-client.js';
+import { urlWithSearchParams } from '../utils/url.js';
+import { Logger } from './logger.js';
+export async function signedRequestHeadersFromSigner({ signer, nonce = uuidv4(), }) {
+    let signature = undefined;
+    let publicKey = undefined;
+    const signatureType = isWanderArweaveBrowserSigner(signer)
+        ? SignatureConfig.ARWEAVE
+        : signer.signatureType;
+    // equivalent to window.arweaveWallet
+    if (isWanderArweaveBrowserSigner(signer)) {
+        signature = toB64Url(Buffer.from(await signer.signMessage(Uint8Array.from(Buffer.from(nonce)))));
+    }
+    else if (signer instanceof ArconnectSigner) {
+        signature = toB64Url(Buffer.from(await signer['signer'].signMessage(Uint8Array.from(Buffer.from(nonce)))));
+    }
+    else if (signer instanceof ArweaveSigner ||
+        signer instanceof EthereumSigner ||
+        signer instanceof InjectedEthereumSigner) {
+        if ('setPublicKey' in signer && signer['publicKey'] === undefined) {
+            await signer.setPublicKey();
+        }
+        signature = toB64Url(Buffer.from(await signer.sign(Uint8Array.from(Buffer.from(nonce)))));
+    }
+    switch (signatureType) {
+        case SignatureConfig.ARWEAVE:
+            if (isWanderArweaveBrowserSigner(signer)) {
+                publicKey = await signer.getActivePublicKey();
+            }
+            else if ('setPublicKey' in signer) {
+                await signer.setPublicKey();
+                publicKey = toB64Url(signer.publicKey);
+            }
+            break;
+        case SignatureConfig.ETHEREUM:
+            if ('publicKey' in signer) {
+                publicKey = '0x' + signer.publicKey.toString('hex');
+            }
+            else {
+                throw new Error('Public key not found');
+            }
+            break;
+        // TODO: solana sig support
+        // case SignatureConfig.SOLANA:
+        // case SignatureConfig.ED25519:
+        default:
+            throw new Error(`Unsupported signer type for signing requests: ${signatureType}`);
+    }
+    if (publicKey === undefined || signature === undefined) {
+        throw new Error('Public key or signature not found');
+    }
+    return {
+        'x-public-key': publicKey,
+        'x-nonce': nonce,
+        'x-signature': signature,
+        'x-signature-type': signatureType,
+    };
+}
+export class TurboArNSPaymentFactory {
+    static init(config) {
+        const { signer, paymentUrl, axios, logger } = config ?? {};
+        if (signer !== undefined) {
+            return new TurboArNSPaymentProviderAuthenticated({
+                signer,
+                paymentUrl,
+                axios,
+                logger,
+            });
+        }
+        return new TurboArNSPaymentProviderUnauthenticated({
+            paymentUrl,
+            axios,
+            logger,
+        });
+    }
+}
+// Base class for unauthenticated operations
+export class TurboArNSPaymentProviderUnauthenticated {
+    paymentUrl;
+    axios;
+    logger;
+    constructor({ paymentUrl = 'https://payment.ardrive.io', axios = createAxiosInstance(), logger = Logger.default, }) {
+        this.paymentUrl = paymentUrl;
+        this.axios = axios;
+        this.logger = logger;
+    }
+    async getArNSPriceDetails({ intent, name, quantity, type, years, }) {
+        const url = urlWithSearchParams({
+            baseUrl: `${this.paymentUrl}/v1/arns/price/${intent}/${name}`,
+            params: {
+                increaseQty: quantity,
+                type,
+                years,
+            },
+        });
+        const { data, status } = await this.axios.get(url);
+        this.logger.debug('getArNSPriceDetails', {
+            intent,
+            name,
+            quantity,
+            type,
+            years,
+            data,
+            status,
+        });
+        if (status !== 200) {
+            throw new Error('Failed to get ArNS purchase price ' + JSON.stringify(data));
+        }
+        if (!data.winc || !data.mARIO) {
+            throw new Error('Invalid response from Turbo ' + JSON.stringify(data));
+        }
+        return {
+            winc: data.winc,
+            mARIO: new mARIOToken(+data.mARIO),
+        };
+    }
+    async getPrice(params) {
+        const { winc } = await this.getArNSPriceDetails(params);
+        return +winc;
+    }
+}
+// Class for authenticated operations, extending the base class
+export class TurboArNSPaymentProviderAuthenticated extends TurboArNSPaymentProviderUnauthenticated {
+    signer;
+    constructor({ signer, ...restConfig }) {
+        super(restConfig); // Pass unauthenticated config to base class+
+        if (!isTurboArNSSigner(signer)) {
+            throw new Error('Signer must be a TurboArNSSigner');
+        }
+        this.signer = signer;
+    }
+    async initiateArNSPurchase({ intent, name, quantity, type, processId, years, }) {
+        // Signer check is implicitly handled by requiring it in the constructor
+        const url = urlWithSearchParams({
+            baseUrl: `${this.paymentUrl}/v1/arns/purchase/${intent}/${name}`,
+            params: {
+                increaseQty: quantity,
+                processId,
+                type,
+                years,
+            },
+        });
+        const headers = await signedRequestHeadersFromSigner({
+            signer: this.signer,
+        });
+        const { data, status } = await this.axios.post(url, null, {
+            headers,
+        });
+        this.logger.debug('Initiated ArNS purchase', {
+            intent,
+            name,
+            quantity,
+            processId,
+            type,
+            years,
+            data,
+            status,
+        });
+        if (status !== 200) {
+            throw new Error('Failed to initiate ArNS purchase ' + JSON.stringify(data));
+        }
+        return {
+            id: data.arioWriteResult.id,
+            result: data.purchaseReceipt,
+        };
+    }
+}
+function isWanderArweaveBrowserSigner(signer) {
+    return (typeof signer === 'object' &&
+        signer !== null &&
+        'signMessage' in signer &&
+        'getActivePublicKey' in signer);
+}
+export function isTurboArNSSigner(signer) {
+    const isWanderWallet = isWanderArweaveBrowserSigner(signer);
+    const isSigner = signer instanceof EthereumSigner ||
+        signer instanceof InjectedEthereumSigner ||
+        signer instanceof ArweaveSigner ||
+        signer instanceof ArconnectSigner;
+    return isWanderWallet || isSigner;
+}

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

@@ -0,0 +1,69 @@
+export 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');
+    }
+}
+export class StaticGatewaysProvider {
+    gateways;
+    constructor({ gateways }) {
+        this.gateways = gateways;
+    }
+    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.filter((g) => g.status === 'joined');
+                this.lastUpdated = now;
+            }
+            catch (error) {
+                console.error('Error fetching gateways', error);
+            }
+        }
+        return this.gatewaysCache;
+    }
+}

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

@@ -0,0 +1,20 @@
+/**
+ * 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/fixed.js';

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

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

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

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

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

@@ -0,0 +1,34 @@
+import { randomInt } from '../../../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
+export 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[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}`);
+    }
+}

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 '../../../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) => 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}`);
+    }
+}