@ar.io/sdk 3.11.0-alpha.7 → 3.11.0-alpha.9

package/lib/esm/cli/cli.js

@@ -22,7 +22,7 @@ import { version } from '../version.js';
 import { setAntBaseNameCLICommand, setAntRecordCLICommand, } from './commands/antCommands.js';
 import { buyRecordCLICommand, extendLeaseCLICommand, increaseUndernameLimitCLICommand, requestPrimaryNameCLICommand, upgradeRecordCLICommand, } from './commands/arnsPurchaseCommands.js';
 import { cancelWithdrawal, decreaseDelegateStake, decreaseOperatorStake, delegateStake, increaseOperatorStake, instantWithdrawal, joinNetwork, leaveNetwork, redelegateStake, saveObservations, updateGatewaySettings, } from './commands/gatewayWriteCommands.js';
-import { getAllGatewayVaults, getAllowedDelegates, getArNSRecord, getArNSReservedName, getArNSReturnedName, getCostDetails, getDelegations, getEpoch, getGateway, getGatewayDelegates, getGatewayVaults, getPrescribedNames, getPrescribedObservers, getPrimaryName, getTokenCost, getVault, listAllDelegatesCLICommand, listArNSRecords, listArNSReservedNames, listArNSReturnedNames, listGateways, } from './commands/readCommands.js';
+import { getAllGatewayVaults, getAllowedDelegates, getArNSRecord, getArNSReservedName, getArNSReturnedName, getCostDetails, getDelegations, getEpoch, getGateway, getGatewayDelegates, getGatewayVaults, getPrescribedNames, getPrescribedObservers, getPrimaryName, getTokenCost, getVault, listAllDelegatesCLICommand, listArNSRecords, listArNSReservedNames, listArNSReturnedNames, listGateways, resolveArNSName, } from './commands/readCommands.js';
 import { createVaultCLICommand, extendVaultCLICommand, increaseVaultCLICommand, revokeVaultCLICommand, transferCLICommand, vaultedTransferCLICommand, } from './commands/transfer.js';
 import { addressAndVaultIdOptions, antStateOptions, arnsPurchaseOptions, buyRecordOptions, decreaseDelegateStakeOptions, delegateStakeOptions, epochOptions, getVaultOptions, globalOptions, joinNetworkOptions, operatorStakeOptions, optionMap, paginationAddressOptions, paginationOptions, redelegateStakeOptions, setAntBaseNameOptions, setAntUndernameOptions, tokenCostOptions, transferOptions, updateGatewaySettingsOptions, vaultedTransferOptions, writeActionOptions, } from './options.js';
 import { applyOptions, arioProcessIdFromOptions, assertConfirmationPrompt, customTagsFromOptions, epochInputFromOptions, formatARIOWithCommas, getANTStateFromOptions, getLoggerFromOptions, makeCommand, paginationParamsFromOptions, readANTFromOptions, readARIOFromOptions, requiredAddressFromOptions, requiredAoSignerFromOptions, requiredProcessIdFromOptions, requiredStringArrayFromOptions, requiredStringFromOptions, writeANTFromOptions, } from './utils.js';
@@ -31,6 +31,7 @@ applyOptions(program
     .version(version)
     .description('AR.IO Network CLI')
     .helpCommand(true), globalOptions);
+// # Getters
 makeCommand({
     name: 'info',
     description: 'Get network info',
@@ -41,6 +42,18 @@ makeCommand({
     description: 'Get the total token supply',
     action: (options) => readARIOFromOptions(options).getTokenSupply(),
 });
+makeCommand({
+    name: 'balance',
+    description: 'Get the balance of an address',
+    options: [optionMap.address],
+    action: (options) => readARIOFromOptions(options)
+        .getBalance({ address: requiredAddressFromOptions(options) })
+        .then((result) => ({
+        address: requiredAddressFromOptions(options),
+        mARIOBalance: result,
+        message: `Provided address current has a balance of ${formatARIOWithCommas(new mARIOToken(result).toARIO())} ARIO`,
+    })),
+});
 makeCommand({
     name: 'get-registration-fees',
     description: 'Get registration fees',
@@ -67,24 +80,18 @@ makeCommand({
     options: [optionMap.address],
     action: getGateway,
 });
-makeCommand({
-    name: 'list-gateways',
-    description: 'List the gateways of the network',
-    options: paginationOptions,
-    action: listGateways,
-});
-makeCommand({
-    name: 'list-all-delegates',
-    description: 'List all paginated delegates from all gateways',
-    options: paginationOptions,
-    action: listAllDelegatesCLICommand,
-});
 makeCommand({
     name: 'get-gateway-delegates',
     description: 'Get the delegates of a gateway',
     options: paginationAddressOptions,
     action: getGatewayDelegates,
 });
+makeCommand({
+    name: 'get-gateway-vaults',
+    description: 'Get the vaults of a gateway',
+    options: paginationAddressOptions,
+    action: getGatewayVaults,
+});
 makeCommand({
     name: 'get-delegations',
     description: 'Get all stake delegated to gateways from this address',
@@ -103,36 +110,18 @@ makeCommand({
     options: [optionMap.name],
     action: getArNSRecord,
 });
-makeCommand({
-    name: 'list-arns-records',
-    description: 'List all ArNS records',
-    options: paginationOptions,
-    action: listArNSRecords,
-});
 makeCommand({
     name: 'get-arns-reserved-name',
     description: 'Get a reserved ArNS name',
     options: [optionMap.name],
     action: getArNSReservedName,
 });
-makeCommand({
-    name: 'list-arns-reserved-names',
-    description: 'Get all reserved ArNS names',
-    options: paginationOptions,
-    action: listArNSReservedNames,
-});
 makeCommand({
     name: 'get-arns-returned-name',
     description: 'Get an ArNS returned name by name',
     options: [optionMap.name],
     action: getArNSReturnedName,
 });
-makeCommand({
-    name: 'list-arns-returned-names',
-    description: 'Get all ArNS recently returned names',
-    options: paginationOptions,
-    action: listArNSReturnedNames,
-});
 makeCommand({
     name: 'get-epoch',
     description: 'Get epoch data',
@@ -193,14 +182,11 @@ makeCommand({
     action: getCostDetails,
 });
 makeCommand({
-    name: 'list-vaults',
-    description: 'Get all wallet vaults',
-    options: paginationOptions,
-    action: (o) => readARIOFromOptions(o)
-        .getVaults(paginationParamsFromOptions(o))
-        .then((result) => result.items.length ? result : { message: 'No vaults found' }),
+    name: 'get-primary-name',
+    description: 'Get primary name',
+    options: [optionMap.address, optionMap.name],
+    action: getPrimaryName,
 });
-// TODO: Could assert valid arweave (or ETH) addresses at CLI level when coming from options (no need from wallet)
 makeCommand({
     name: 'get-primary-name-request',
     description: 'Get primary name request',
@@ -213,6 +199,66 @@ makeCommand({
         message: `No primary name request found`,
     }),
 });
+makeCommand({
+    name: 'get-redelegation-fee',
+    description: 'Get redelegation fee',
+    options: [optionMap.address],
+    action: (options) => readARIOFromOptions(options).getRedelegationFee({
+        address: requiredAddressFromOptions(options),
+    }),
+});
+makeCommand({
+    name: 'get-vault',
+    description: 'Get the vault of provided address and vault ID',
+    options: getVaultOptions,
+    action: getVault,
+});
+// # ArNS Resolution
+makeCommand({
+    name: 'resolve-arns-name',
+    description: 'Resolve an ArNS name',
+    options: [optionMap.name],
+    action: resolveArNSName,
+});
+// # Paginated handlers
+makeCommand({
+    name: 'list-gateways',
+    description: 'List the gateways of the network',
+    options: paginationOptions,
+    action: listGateways,
+});
+makeCommand({
+    name: 'list-all-delegates',
+    description: 'List all paginated delegates from all gateways',
+    options: paginationOptions,
+    action: listAllDelegatesCLICommand,
+});
+makeCommand({
+    name: 'list-arns-records',
+    description: 'List all ArNS records',
+    options: paginationOptions,
+    action: listArNSRecords,
+});
+makeCommand({
+    name: 'list-arns-reserved-names',
+    description: 'Get all reserved ArNS names',
+    options: paginationOptions,
+    action: listArNSReservedNames,
+});
+makeCommand({
+    name: 'list-arns-returned-names',
+    description: 'Get all ArNS recently returned names',
+    options: paginationOptions,
+    action: listArNSReturnedNames,
+});
+makeCommand({
+    name: 'list-vaults',
+    description: 'Get all wallet vaults',
+    options: paginationOptions,
+    action: (o) => readARIOFromOptions(o)
+        .getVaults(paginationParamsFromOptions(o))
+        .then((result) => result.items.length ? result : { message: 'No vaults found' }),
+});
 makeCommand({
     name: 'list-primary-name-requests',
     description: 'Get primary name requests',
@@ -221,12 +267,6 @@ makeCommand({
         .getPrimaryNameRequests(paginationParamsFromOptions(o))
         .then((result) => result.items.length ? result : { message: 'No requests found' }),
 });
-makeCommand({
-    name: 'get-primary-name',
-    description: 'Get primary name',
-    options: [optionMap.address, optionMap.name],
-    action: getPrimaryName,
-});
 makeCommand({
     name: 'list-primary-names',
     description: 'Get primary names',
@@ -235,18 +275,6 @@ makeCommand({
         .getPrimaryNames(paginationParamsFromOptions(o))
         .then((result) => result.items.length ? result : { message: 'No names found' }),
 });
-makeCommand({
-    name: 'balance',
-    description: 'Get the balance of an address',
-    options: [optionMap.address],
-    action: (options) => readARIOFromOptions(options)
-        .getBalance({ address: requiredAddressFromOptions(options) })
-        .then((result) => ({
-        address: requiredAddressFromOptions(options),
-        mARIOBalance: result,
-        message: `Provided address current has a balance of ${formatARIOWithCommas(new mARIOToken(result).toARIO())} ARIO`,
-    })),
-});
 makeCommand({
     name: 'list-balances',
     description: 'List all balances',
@@ -255,32 +283,13 @@ makeCommand({
         .getBalances(paginationParamsFromOptions(o))
         .then((result) => result.items.length ? result : { message: 'No balances found' }),
 });
-makeCommand({
-    name: 'get-redelegation-fee',
-    description: 'Get redelegation fee',
-    options: [optionMap.address],
-    action: (options) => readARIOFromOptions(options).getRedelegationFee({
-        address: requiredAddressFromOptions(options),
-    }),
-});
-makeCommand({
-    name: 'get-vault',
-    description: 'Get the vault of provided address and vault ID',
-    options: getVaultOptions,
-    action: getVault,
-});
-makeCommand({
-    name: 'get-gateway-vaults',
-    description: 'Get the vaults of a gateway',
-    options: paginationAddressOptions,
-    action: getGatewayVaults,
-});
 makeCommand({
     name: 'list-all-gateway-vaults',
     description: 'List vaults from all gateways',
     options: paginationAddressOptions,
     action: getAllGatewayVaults,
 });
+// # Actions
 makeCommand({
     name: 'transfer',
     description: 'Transfer ARIO to another address',
@@ -416,24 +425,8 @@ makeCommand({
     options: arnsPurchaseOptions,
     action: requestPrimaryNameCLICommand,
 });
-makeCommand({
-    name: 'spawn-ant',
-    description: 'Spawn an ANT process',
-    options: antStateOptions,
-    action: async (options) => {
-        const state = getANTStateFromOptions(options);
-        const antProcessId = await spawnANT({
-            state,
-            signer: requiredAoSignerFromOptions(options),
-            logger: getLoggerFromOptions(options),
-        });
-        return {
-            processId: antProcessId,
-            state,
-            message: `Spawned ANT process with process ID ${antProcessId}`,
-        };
-    },
-});
+// # ANTS
+// # Getters
 makeCommand({
     name: 'get-ant-state',
     description: 'Get the state of an ANT process',
@@ -460,14 +453,6 @@ makeCommand({
         })) ?? { message: 'No record found' });
     },
 });
-makeCommand({
-    name: 'list-ant-records',
-    description: 'Get the records of an ANT process',
-    options: [optionMap.processId],
-    action: async (options) => {
-        return readANTFromOptions(options).getRecords();
-    },
-});
 makeCommand({
     name: 'get-ant-owner',
     description: 'Get the owner of an ANT process',
@@ -476,14 +461,6 @@ makeCommand({
         return readANTFromOptions(options).getOwner();
     },
 });
-makeCommand({
-    name: 'list-ant-controllers',
-    description: 'List the controllers of an ANT process',
-    options: [optionMap.processId],
-    action: async (options) => {
-        return readANTFromOptions(options).getControllers();
-    },
-});
 makeCommand({
     name: 'get-ant-name',
     description: 'Get the name of an ANT process',
@@ -510,6 +487,42 @@ makeCommand({
         });
     },
 });
+// # Spawn
+makeCommand({
+    name: 'spawn-ant',
+    description: 'Spawn an ANT process',
+    options: antStateOptions,
+    action: async (options) => {
+        const state = getANTStateFromOptions(options);
+        const antProcessId = await spawnANT({
+            state,
+            signer: requiredAoSignerFromOptions(options),
+            logger: getLoggerFromOptions(options),
+        });
+        return {
+            processId: antProcessId,
+            state,
+            message: `Spawned ANT process with process ID ${antProcessId}`,
+        };
+    },
+});
+// # ANT Paginated Handlers
+makeCommand({
+    name: 'list-ant-records',
+    description: 'Get the records of an ANT process',
+    options: [optionMap.processId],
+    action: async (options) => {
+        return readANTFromOptions(options).getRecords();
+    },
+});
+makeCommand({
+    name: 'list-ant-controllers',
+    description: 'List the controllers of an ANT process',
+    options: [optionMap.processId],
+    action: async (options) => {
+        return readANTFromOptions(options).getControllers();
+    },
+});
 makeCommand({
     name: 'list-ant-balances',
     description: 'Get the balances of an ANT process',
@@ -518,6 +531,7 @@ makeCommand({
         return readANTFromOptions(options).getBalances();
     },
 });
+// # Actions
 makeCommand({
     name: 'transfer-ant-ownership',
     description: 'Transfer ownership of an ANT process',
@@ -552,6 +566,18 @@ makeCommand({
         }, customTagsFromOptions(options));
     },
 });
+makeCommand({
+    name: 'remove-ant-record',
+    description: 'Remove a record from an ANT process',
+    options: [optionMap.processId, optionMap.undername, ...writeActionOptions],
+    action: async (options) => {
+        const undername = requiredStringFromOptions(options, 'undername');
+        await assertConfirmationPrompt(`Are you sure you want to remove the record with undername ${undername}?`, options);
+        return writeANTFromOptions(options).removeRecord({
+            undername,
+        }, customTagsFromOptions(options));
+    },
+});
 makeCommand({
     name: 'set-ant-record',
     description: 'Set a record of an ANT process. Deprecated: use set-ant-base-name and set-ant-undername',
@@ -570,18 +596,6 @@ makeCommand({
     options: setAntUndernameOptions,
     action: setAntRecordCLICommand,
 });
-makeCommand({
-    name: 'remove-ant-record',
-    description: 'Remove a record from an ANT process',
-    options: [optionMap.processId, optionMap.undername, ...writeActionOptions],
-    action: async (options) => {
-        const undername = requiredStringFromOptions(options, 'undername');
-        await assertConfirmationPrompt(`Are you sure you want to remove the record with undername ${undername}?`, options);
-        return writeANTFromOptions(options).removeRecord({
-            undername,
-        }, customTagsFromOptions(options));
-    },
-});
 makeCommand({
     name: 'set-ant-ticker',
     description: 'Set the ticker of an ANT process',
@@ -642,11 +656,11 @@ makeCommand({
         const txId = requiredStringFromOptions(options, 'transactionId');
         await assertConfirmationPrompt(`Are you sure you want to set the ANT logo to target Arweave TxID ${txId}?`, options);
         return writeANTFromOptions(options).setLogo({
-            // TODO: Could take a logo file, upload it to Arweave, get transaction ID
             txId,
         }, customTagsFromOptions(options));
     },
 });
+// # ARIO Actions
 makeCommand({
     name: 'release-name',
     description: 'Release the name of an ANT process',
@@ -713,6 +727,7 @@ makeCommand({
         }, customTagsFromOptions(options));
     },
 });
+// # Utilities
 makeCommand({
     name: 'write-action',
     description: 'Send a write action to an AO Process',

package/lib/esm/cli/commands/readCommands.js

@@ -165,3 +165,8 @@ export async function getVault(o) {
         message: `No vault found for provided address and vault ID`,
     });
 }
+export async function resolveArNSName(o) {
+    const name = requiredStringFromOptions(o, 'name');
+    const result = await readARIOFromOptions(o).resolveArNSName({ name });
+    return result ?? { message: `No record found for name ${name}` };
+}

package/lib/esm/common/ant.js

@@ -89,12 +89,12 @@ export class AoANTReadable {
      * ```
      */
     async getRecord({ undername }, { strict } = { strict: this.strict }) {
-        const tags = [
-            { name: 'Sub-Domain', value: undername },
-            { name: 'Action', value: 'Record' },
-        ];
+        // TODO: use sortedANTRecords to get priority on all records, even if ANT does not have a priority set
         const record = await this.process.read({
-            tags,
+            tags: [
+                { name: 'Action', value: 'Record' },
+                { name: 'Sub-Domain', value: undername },
+            ],
         });
         if (strict)
             parseSchemaResult(AntRecordSchema.passthrough(), record);

package/lib/esm/common/io.js

@@ -18,6 +18,7 @@ import { ARIO_MAINNET_PROCESS_ID, ARIO_TESTNET_PROCESS_ID, } from '../constants.
 import { isProcessConfiguration, isProcessIdConfiguration, } from '../types/index.js';
 import { createAoSigner } from '../utils/ao.js';
 import { getEpochDataFromGqlWithCUFallback, paginationParamsToTags, pruneTags, removeEligibleRewardsFromEpochData, sortAndPaginateEpochDataIntoEligibleDistributions, } from '../utils/arweave.js';
+import { ANT } from './ant.js';
 import { defaultArweave } from './arweave.js';
 import { AOProcess } from './contracts/ao-process.js';
 import { InvalidContractConfigurationError } from './error.js';
@@ -620,6 +621,42 @@ export class ARIOReadable {
             ],
         });
     }
+    async resolveArNSName({ name, }) {
+        const baseName = name.split('_').pop();
+        if (baseName === undefined) {
+            throw new Error('Invalid name');
+        }
+        const undername = name === baseName ? '@' : name.replace(`_${baseName}`, '');
+        const nameData = await this.getArNSRecord({ name: baseName });
+        const ant = ANT.init({
+            process: new AOProcess({
+                ao: this.process.ao,
+                processId: nameData.processId,
+            }),
+        });
+        const [owner, antRecord] = await Promise.all([
+            ant.getOwner(),
+            ant.getRecord({ undername }),
+        ]);
+        if (antRecord === undefined) {
+            throw new Error(`Record for ${undername} not found on ANT.`);
+        }
+        if (antRecord.ttlSeconds === undefined ||
+            antRecord.transactionId === undefined) {
+            throw new Error(`Invalid record on ANT. Must have ttlSeconds and transactionId. Record: ${JSON.stringify(antRecord)}`);
+        }
+        return {
+            name: name,
+            owner: owner,
+            txId: antRecord.transactionId,
+            ttlSeconds: antRecord.ttlSeconds,
+            priority: antRecord.priority,
+            // NOTE: we may want return the actual index of the record based on sorting in case ANT tries to set duplicate priority values to get around undername limits
+            processId: nameData.processId,
+            undernameLimit: nameData.undernameLimit,
+            type: nameData.type,
+        };
+    }
 }
 export class ARIOWriteable extends ARIOReadable {
     signer;

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

@@ -0,0 +1,102 @@
+const arioGatewayHeaders = {
+    digest: 'x-ar-io-digest',
+    verified: 'x-ar-io-verified',
+    txId: 'x-arns-resolved-tx-id',
+    processId: 'x-arns-resolved-process-id',
+};
+export class TrustedGatewaysHashProvider {
+    gatewaysProvider;
+    constructor({ gatewaysProvider,
+    // TODO: add threshold for allowed hash difference (i.e. by count or ratio of total gateways checked)
+     }) {
+        this.gatewaysProvider = gatewaysProvider;
+    }
+    /**
+     * Gets the digest for a given txId from all trusted gateways and ensures they all match.
+     * @param txId - The txId to get the digest for.
+     * @returns The digest for the given txId.
+     */
+    async getHash({ txId, }) {
+        // get the hash from every gateway, and ensure they all match
+        const hashSet = new Set();
+        const hashResults = [];
+        const gateways = await this.gatewaysProvider.getGateways();
+        const hashes = await Promise.all(gateways.map(async (gateway) => {
+            const response = await fetch(`${gateway.toString()}${txId}`, {
+                method: 'HEAD',
+                redirect: 'follow',
+            });
+            if (!response.ok) {
+                // skip this gateway
+                return undefined;
+            }
+            const txIdHash = response.headers.get(arioGatewayHeaders.digest);
+            if (txIdHash === null || txIdHash === undefined) {
+                // skip this gateway
+                return undefined;
+            }
+            hashResults.push({
+                gateway: gateway.hostname,
+                txIdHash,
+            });
+            return txIdHash;
+        }));
+        for (const hash of hashes) {
+            if (hash !== undefined) {
+                hashSet.add(hash);
+            }
+        }
+        if (hashSet.size === 0) {
+            throw new Error(`No trusted gateways found for txId ${txId}`);
+        }
+        if (hashSet.size > 1) {
+            throw new Error(`Failed to get consistent hash from all trusted gateways. ${JSON.stringify(hashResults)}`);
+        }
+        return { hash: hashResults[0].txIdHash, algorithm: 'sha256' };
+    }
+    /**
+     * Get the data root for a given txId from all trusted gateways and ensure they all match.
+     * @param txId - The txId to get the data root for.
+     * @returns The data root for the given txId.
+     */
+    async getDataRoot({ txId }) {
+        const dataRootSet = new Set();
+        const dataRootResults = [];
+        const gateways = await this.gatewaysProvider.getGateways();
+        const dataRoots = await Promise.all(gateways.map(async (gateway) => {
+            const response = await fetch(`${gateway.toString()}tx/${txId}/data_root`);
+            if (!response.ok) {
+                // skip this gateway
+                return undefined;
+            }
+            const dataRoot = await response.text();
+            dataRootResults.push({
+                gateway: gateway.hostname,
+                dataRoot,
+            });
+            return dataRoot;
+        }));
+        for (const dataRoot of dataRoots) {
+            if (dataRoot !== undefined) {
+                dataRootSet.add(dataRoot);
+            }
+        }
+        if (dataRootSet.size > 1) {
+            throw new Error(`Failed to get consistent data root from all trusted gateways. ${JSON.stringify(dataRootResults)}`);
+        }
+        return dataRootSet.values().next().value;
+    }
+}
+// client could check hashes of data items, match expected hash
+// if the gateway has the hash and they've verified it, you can trust the data item and offset
+// you would be only trusting the gateway that it is a valid bundle
+// you can request the offset from the gateway to verify the id
+/**
+ * Note from @djwhitt
+ *
+ * Calculating data roots this way is fine, but it may not reproduce the original data root.
+ * We could also implement a data root verifier that pulls all the chunks, checks that they
+ * reproduce the expected data root, and then compares the concatenated chunk data to the
+ * original data retrieved. That would take a while, but it should be able to verify any L1
+ * data where we can find the chunks.
+ */

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

@@ -20,3 +20,9 @@ export * from './routers/priority.js';
 export * from './routers/static.js';
 // gateways providers
 export * from './gateways.js';
+// trusted gateways
+export * from './gateways/trusted-gateways.js';
+// hash providers
+export * from './verification/data-root-verifier.js';
+export * from './verification/hash-verifier.js';
+// TODO: signature verification