@ar.io/sdk 2.6.0 → 2.7.0-alpha.2

package/lib/esm/cli/options.js

@@ -0,0 +1,333 @@
+/**
+ * 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 const optionMap = {
+    walletFile: {
+        alias: '-w, --wallet-file <walletFilePath>',
+        description: 'The file path to the wallet to use for the interaction',
+    },
+    // mnemonic: {
+    //   alias: '-m, --mnemonic <phrase>',
+    //   description: 'Mnemonic to use with the action',
+    // },
+    privateKey: {
+        alias: '--private-key <key>',
+        description: 'Private key to use with the action',
+    },
+    dev: {
+        alias: '--dev',
+        description: 'Run against the AR.IO devnet process',
+        type: 'boolean',
+    },
+    ioProcessId: {
+        alias: '--io-process-id',
+        description: 'Run against a custom AR.IO process id',
+    },
+    cuUrl: {
+        alias: '--cu-url <cuUrl>',
+        description: 'The URL for a custom compute unit',
+    },
+    processId: {
+        alias: '--process-id <processId>',
+        description: 'The process ID to interact with',
+    },
+    debug: {
+        alias: '--debug',
+        description: 'Enable debug log output',
+        type: 'boolean',
+    },
+    address: {
+        alias: '-a, --address <address>',
+        description: 'The address to interact with',
+    },
+    target: {
+        alias: '--target <target>',
+        description: 'The target address to interact with',
+    },
+    source: {
+        alias: '--source <source>',
+        description: 'The source address to interact with',
+    },
+    quantity: {
+        alias: '-q, --quantity <quantity>',
+        description: 'The quantity of IO to interact with',
+    },
+    autoStake: {
+        alias: '--auto-stake',
+        description: 'Enable auto-staking of operator rewards',
+        type: 'boolean',
+    },
+    allowDelegatedStaking: {
+        alias: '--allow-delegated-staking',
+        description: 'Allow delegating stake to the gateway',
+        type: 'boolean',
+    },
+    minDelegatedStake: {
+        alias: '--min-delegated-stake <minDelegatedStake>',
+        description: 'The minimum delegated stake allowed',
+    },
+    delegateRewardShareRatio: {
+        alias: '--delegate-reward-share-ratio <delegateRewardShareRatio>',
+        description: 'The percentage of rewards to share with delegates',
+    },
+    label: {
+        alias: '--label <label>',
+        description: 'The label for the gateway',
+    },
+    note: {
+        alias: '--note <note>',
+        description: 'The note for the gateway',
+    },
+    properties: {
+        alias: '--properties <properties>',
+        description: 'The properties for the gateway',
+    },
+    observerAddress: {
+        alias: '--observer-address <observerAddress>',
+        description: 'The observer wallet address for the gateway',
+    },
+    fqdn: {
+        alias: '--fqdn <fqdn>',
+        description: 'The fully qualified domain name for the gateway',
+    },
+    port: {
+        alias: '--port <port>',
+        description: 'The port for the gateway',
+    },
+    protocol: {
+        alias: '--protocol <protocol>',
+        description: 'The protocol for the gateway',
+    },
+    allowedDelegates: {
+        alias: '--allowed-delegates <allowedDelegates...>',
+        description: 'The allowed delegates for the gateway. By default this is empty, meaning all are allowed delegate stake unless delegating is explicitly disallowed by the gateway',
+        type: 'array',
+    },
+    skipConfirmation: {
+        alias: '--skip-confirmation',
+        description: 'Skip confirmation prompts',
+        type: 'boolean',
+    },
+    vaultId: {
+        alias: '--vault-id <vaultId>',
+        description: 'The vault ID to interact with',
+    },
+    operatorStake: {
+        alias: '--operator-stake <operatorStake>',
+        description: 'The operator stake to interact with',
+    },
+    name: {
+        alias: '--name <name>',
+        description: 'The ArNS name to interact with',
+    },
+    epochIndex: {
+        alias: '--epoch-index <epochIndex>',
+        description: 'The epoch index to interact with',
+    },
+    timestamp: {
+        alias: '--timestamp <timestamp>',
+        description: 'The timestamp to interact with',
+    },
+    initiator: {
+        alias: '--initiator <initiator>',
+        description: 'The initiator of the action',
+    },
+    intent: {
+        alias: '--intent <intent>',
+        description: 'The intent for the cost details action',
+    },
+    type: {
+        alias: '--type <type>',
+        description: 'The type for the cost details action. Either "lease" or "permabuy"',
+    },
+    years: {
+        alias: '--years <years>',
+        description: 'The number of years for the cost details action',
+    },
+    intervalMs: {
+        alias: '--interval-ms <intervalMs>',
+        description: 'The interval in milliseconds for the action',
+    },
+    cursor: {
+        alias: '--cursor <cursor>',
+        description: 'The cursor for pagination',
+    },
+    limit: {
+        alias: '--limit <limit>',
+        description: 'The limit for pagination',
+    },
+    sortBy: {
+        alias: '--sort-by <sortBy>',
+        description: 'The field to sort by',
+    },
+    sortOrder: {
+        alias: '--sort-order <sortOrder>',
+        description: 'The order to sort by, either "asc" or "desc"',
+    },
+    tags: {
+        description: 'An array of additional tags for the write action, in "--tags name1 value1 name2 value2" format',
+        alias: '--tags <tags...>',
+        type: 'array',
+    },
+    instant: {
+        alias: '--instant',
+        description: 'Use the instant transaction method',
+        type: 'boolean',
+    },
+    increaseCount: {
+        alias: '--increase-count <increaseCount>',
+        description: 'Amount to increase the undername count of the record by',
+    },
+    undername: {
+        alias: '--undername <undername>',
+        description: 'The undername to interact with',
+    },
+    controller: {
+        alias: '--controller <controller>',
+        description: 'The controller to interact with',
+    },
+    controllers: {
+        alias: '--controllers <controllers...>',
+        description: 'The controller to interact with',
+        type: 'array',
+    },
+    transactionId: {
+        alias: '--transaction-id <transactionId>',
+        description: 'The transaction ID to interact with',
+    },
+    ttlSeconds: {
+        alias: '--ttl-seconds <ttlSeconds>',
+        description: 'The TTL in seconds for the record',
+    },
+    ticker: {
+        alias: '--ticker <ticker>',
+        description: 'The ticker for the ANT',
+    },
+    description: {
+        alias: '--description <description>',
+        description: 'The description for the ANT',
+    },
+    keywords: {
+        alias: '--keywords <keywords...>',
+        description: 'The keywords for the ANT',
+        type: 'array',
+    },
+    names: {
+        alias: '--names <names...>',
+        description: 'The names to interact with',
+        type: 'array',
+    },
+    failedGateways: {
+        alias: '--failed-gateways <failedGateways...>',
+        description: 'Include failed gateways in the list',
+        type: 'array',
+    },
+};
+export const walletOptions = [
+    optionMap.walletFile,
+    // optionMap.mnemonic,
+    optionMap.privateKey,
+];
+export const globalOptions = [
+    ...walletOptions,
+    optionMap.dev,
+    optionMap.debug,
+    optionMap.ioProcessId,
+    optionMap.cuUrl,
+];
+export const writeActionOptions = [optionMap.skipConfirmation, optionMap.tags];
+export const addressOptions = [optionMap.address];
+export const nameOptions = [optionMap.name];
+export const initiatorOptions = [optionMap.initiator];
+export const epochOptions = [optionMap.epochIndex, optionMap.timestamp];
+export const addressAndVaultIdOptions = [...addressOptions, optionMap.vaultId];
+export const nameWriteOptions = [...writeActionOptions, optionMap.name];
+export const paginationOptions = [
+    optionMap.cursor,
+    optionMap.limit,
+    optionMap.sortBy,
+    optionMap.sortOrder,
+];
+export const paginationAddressOptions = [
+    optionMap.address,
+    ...paginationOptions,
+];
+export const getVaultOptions = addressAndVaultIdOptions;
+export const tokenCostOptions = [
+    optionMap.name,
+    optionMap.intent,
+    optionMap.type,
+    optionMap.years,
+    optionMap.quantity,
+];
+export const arNSAuctionPricesOptions = [
+    optionMap.name,
+    optionMap.type,
+    optionMap.years,
+    optionMap.timestamp,
+    optionMap.intervalMs,
+];
+export const transferOptions = [
+    ...writeActionOptions,
+    optionMap.quantity,
+    optionMap.target,
+];
+export const operatorStakeOptions = [
+    ...writeActionOptions,
+    optionMap.operatorStake,
+];
+export const redelegateStakeOptions = [...transferOptions, optionMap.source];
+export const delegateStakeOptions = transferOptions;
+export const decreaseDelegateStakeOptions = [
+    ...delegateStakeOptions,
+    optionMap.instant,
+];
+export const updateGatewaySettingsOptions = [
+    ...writeActionOptions,
+    optionMap.autoStake,
+    optionMap.allowDelegatedStaking,
+    optionMap.allowedDelegates,
+    optionMap.minDelegatedStake,
+    optionMap.delegateRewardShareRatio,
+    optionMap.label,
+    optionMap.note,
+    optionMap.properties,
+    optionMap.observerAddress,
+    optionMap.fqdn,
+    optionMap.port,
+    optionMap.protocol,
+];
+export const joinNetworkOptions = [
+    ...updateGatewaySettingsOptions,
+    optionMap.operatorStake,
+];
+export const buyRecordOptions = [
+    ...writeActionOptions,
+    optionMap.name,
+    optionMap.quantity,
+    optionMap.type,
+    optionMap.years,
+    optionMap.processId,
+];
+export const antStateOptions = [
+    ...writeActionOptions,
+    optionMap.target,
+    optionMap.keywords,
+    optionMap.ticker,
+    optionMap.name,
+    optionMap.description,
+    optionMap.controllers,
+    optionMap.ttlSeconds,
+];

package/lib/esm/cli/types.js

@@ -0,0 +1 @@
+export {};

package/lib/esm/cli/utils.js

@@ -0,0 +1,366 @@
+/**
+ * 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 { connect } from '@permaweb/aoconnect';
+import { program } from 'commander';
+import { readFileSync } from 'fs';
+import prompts from 'prompts';
+import { ANT, AOProcess, ArweaveSigner, IO, IOToken, IO_DEVNET_PROCESS_ID, IO_TESTNET_PROCESS_ID, Logger, createAoSigner, fromB64Url, initANTStateForAddress, mIOToken, sha256B64Url, } from '../node/index.js';
+import { globalOptions } from './options.js';
+export function stringifyJsonForCLIDisplay(json) {
+    return JSON.stringify(json, null, 2);
+}
+function logCommandOutput(output) {
+    console.log(stringifyJsonForCLIDisplay(output));
+}
+function exitWithErrorLog(error, debug = false) {
+    let errorLog;
+    if (error instanceof Error) {
+        errorLog = error.message;
+        if (debug && error.stack !== undefined) {
+            errorLog = error.stack;
+        }
+    }
+    else {
+        errorLog = stringifyJsonForCLIDisplay(error);
+    }
+    console.error(errorLog);
+    process.exit(1);
+}
+export async function runCommand(command, action) {
+    const options = command.optsWithGlobals();
+    try {
+        const output = await action(options);
+        logCommandOutput(output);
+        process.exit(0);
+    }
+    catch (error) {
+        exitWithErrorLog(error, options.debug);
+    }
+}
+function applyOptions(command, options) {
+    [...options].forEach((option) => {
+        command.option(option.alias, option.description, option.default);
+    });
+    return command;
+}
+export function makeCommand({ description, name, options = [], action, }) {
+    const command = program.command(name).description(description);
+    const appliedCommand = applyOptions(command, [...options, ...globalOptions]);
+    if (action !== undefined) {
+        appliedCommand.action(() => runCommand(appliedCommand, action));
+    }
+    return appliedCommand;
+}
+export function ioProcessIdFromOptions({ ioProcessId, dev, }) {
+    return ioProcessId !== undefined
+        ? ioProcessId
+        : dev
+            ? IO_DEVNET_PROCESS_ID
+            : IO_TESTNET_PROCESS_ID;
+}
+function jwkFromOptions({ privateKey, walletFile, }) {
+    if (privateKey !== undefined) {
+        return JSON.parse(privateKey);
+    }
+    if (walletFile !== undefined) {
+        return JSON.parse(readFileSync(walletFile, 'utf-8'));
+    }
+    return undefined;
+}
+export function requiredJwkFromOptions(options) {
+    const jwk = jwkFromOptions(options);
+    if (jwk === undefined) {
+        throw new Error('No JWK provided for signing!\nPlease provide a stringified JWK with `--private-key` or the file path of a jwk.json file with `--wallet-file`');
+    }
+    return jwk;
+}
+export function jwkToAddress(jwk) {
+    return sha256B64Url(fromB64Url(jwk.n));
+}
+function setLoggerIfDebug(options) {
+    if (options.debug) {
+        Logger.default.setLogLevel('debug');
+    }
+}
+export function getLoggerFromOptions(options) {
+    setLoggerIfDebug(options);
+    return Logger.default;
+}
+function aoProcessFromOptions(options) {
+    return new AOProcess({
+        processId: ioProcessIdFromOptions(options),
+        ao: connect({
+            CU_URL: options.cuUrl,
+        }),
+    });
+}
+export function readIOFromOptions(options) {
+    setLoggerIfDebug(options);
+    return IO.init({
+        process: aoProcessFromOptions(options),
+    });
+}
+export function requiredContractSignerFromOptions(options) {
+    // TODO: Support other wallet types
+    const jwk = requiredJwkFromOptions(options);
+    const signer = new ArweaveSigner(jwk);
+    return { signer, signerAddress: jwkToAddress(jwk) };
+}
+export function requiredAoSignerFromOptions(options) {
+    return createAoSigner(requiredContractSignerFromOptions(options).signer);
+}
+export function writeIOFromOptions(options) {
+    const { signer, signerAddress } = requiredContractSignerFromOptions(options);
+    setLoggerIfDebug(options);
+    return {
+        io: IO.init({
+            process: aoProcessFromOptions(options),
+            signer,
+        }),
+        signerAddress,
+    };
+}
+export function formatIOWithCommas(value) {
+    const [integerPart, decimalPart] = value.toString().split('.');
+    const integerWithCommas = integerPart.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+    if (decimalPart === undefined) {
+        return integerWithCommas;
+    }
+    return integerWithCommas + '.' + decimalPart;
+}
+/** helper to get address from --address option first, then check wallet options  */
+export function addressFromOptions(options) {
+    if (options.address !== undefined) {
+        return options.address;
+    }
+    // TODO: Support other wallet types
+    const jwk = jwkFromOptions(options);
+    if (jwk !== undefined) {
+        return jwkToAddress(jwk);
+    }
+    return undefined;
+}
+export function requiredAddressFromOptions(options) {
+    const address = addressFromOptions(options);
+    if (address !== undefined) {
+        return address;
+    }
+    throw new Error('No address provided. Use --address or --wallet-file');
+}
+const defaultCliPaginationLimit = 10; // more friendly UX than 100
+export function paginationParamsFromOptions(options) {
+    const { cursor, limit, sortBy, sortOrder } = options;
+    if (sortOrder !== undefined && !['asc', 'desc'].includes(sortOrder)) {
+        throw new Error(`Invalid sort order: ${sortOrder}, must be "asc" or "desc"`);
+    }
+    const numberLimit = limit !== undefined ? +limit : defaultCliPaginationLimit;
+    if (isNaN(numberLimit) || numberLimit <= 0) {
+        throw new Error(`Invalid limit: ${numberLimit}, must be a positive number`);
+    }
+    return {
+        cursor,
+        limit: numberLimit,
+        sortBy,
+        sortOrder,
+    };
+}
+export function epochInputFromOptions(options) {
+    if (options.epochIndex !== undefined) {
+        return { epochIndex: +options.epochIndex };
+    }
+    if (options.timestamp !== undefined) {
+        return { timestamp: +options.timestamp };
+    }
+    return undefined;
+}
+export function requiredInitiatorFromOptions(options) {
+    if (options.initiator !== undefined) {
+        return options.initiator;
+    }
+    return requiredAddressFromOptions(options);
+}
+export function writeActionTagsFromOptions(options) {
+    if (options.tags === undefined) {
+        return {};
+    }
+    if (!Array.isArray(options.tags)) {
+        throw new Error('Tags must be an array');
+    }
+    if (options.tags.length === 0) {
+        return {};
+    }
+    if (options.tags.length % 2 !== 0) {
+        throw new Error('Tags must be an array of key-value pairs');
+    }
+    const tags = [];
+    for (let i = 0; i < options.tags.length; i += 2) {
+        tags.push({
+            name: options.tags[i],
+            value: options.tags[i + 1],
+        });
+    }
+    return {
+        tags,
+    };
+}
+export function gatewaySettingsFromOptions({ allowDelegatedStaking, autoStake, delegateRewardShareRatio, fqdn, label, minDelegatedStake, note, observerAddress, port, properties, allowedDelegates, }) {
+    return {
+        observerAddress,
+        allowDelegatedStaking,
+        autoStake,
+        delegateRewardShareRatio: delegateRewardShareRatio !== undefined
+            ? +delegateRewardShareRatio
+            : undefined,
+        allowedDelegates,
+        fqdn,
+        label,
+        minDelegatedStake: minDelegatedStake !== undefined ? +minDelegatedStake : undefined,
+        note,
+        port: port !== undefined ? +port : undefined,
+        properties,
+    };
+}
+export function requiredTargetAndQuantityFromOptions(options) {
+    if (options.target === undefined) {
+        throw new Error('No target provided. Use --target');
+    }
+    if (options.quantity === undefined) {
+        throw new Error('No quantity provided. Use --quantity');
+    }
+    return {
+        target: options.target,
+        ioQuantity: new IOToken(+options.quantity),
+    };
+}
+export function redelegateParamsFromOptions(options) {
+    const { target, ioQuantity } = requiredTargetAndQuantityFromOptions(options);
+    const source = options.source;
+    if (source === undefined) {
+        throw new Error('No source provided. Use --source');
+    }
+    return {
+        target,
+        source,
+        vaultId: options.vaultId,
+        stakeQty: ioQuantity.toMIO(),
+    };
+}
+export function recordTypeFromOptions(options) {
+    options.type ??= 'lease';
+    if (options.type !== 'lease' && options.type !== 'permabuy') {
+        throw new Error(`Invalid type. Valid types are: lease, permabuy`);
+    }
+    return options.type;
+}
+export function requiredMIOFromOptions(options, key) {
+    if (options[key] === undefined) {
+        throw new Error(`No ${key} provided. Use --${key} denominated in IO`);
+    }
+    return new IOToken(+options[key]).toMIO();
+}
+export async function assertEnoughBalance(io, address, ioQuantity) {
+    const balance = await io.getBalance({ address });
+    if (balance < ioQuantity.toMIO().valueOf()) {
+        throw new Error(`Insufficient IO balance for action. Balance available: ${new mIOToken(balance).toIO()} IO`);
+    }
+}
+export async function confirmationPrompt(message) {
+    const { confirm } = await prompts({
+        type: 'confirm',
+        name: 'confirm',
+        message,
+    });
+    return confirm;
+}
+export async function assertConfirmationPrompt(message, options) {
+    if (options.skipConfirmation) {
+        return true;
+    }
+    return confirmationPrompt(message);
+}
+export function requiredProcessIdFromOptions(o) {
+    if (o.processId === undefined) {
+        throw new Error('--process-id is required');
+    }
+    return o.processId;
+}
+function ANTProcessFromOptions(options) {
+    return new AOProcess({
+        processId: requiredProcessIdFromOptions(options),
+        ao: connect({
+            CU_URL: options.cuUrl,
+        }),
+    });
+}
+export function readANTFromOptions(options) {
+    return ANT.init({
+        process: ANTProcessFromOptions(options),
+    });
+}
+export function writeANTFromOptions(options, signer) {
+    signer ??= requiredContractSignerFromOptions(options).signer;
+    return ANT.init({
+        process: ANTProcessFromOptions(options),
+        signer,
+    });
+}
+export function requiredStringFromOptions(options, key) {
+    const value = options[key];
+    if (value === undefined) {
+        throw new Error(`--${key} is required`);
+    }
+    return value;
+}
+export function requiredStringArrayFromOptions(options, key) {
+    const value = options[key];
+    if (value === undefined) {
+        throw new Error(`--${key} is required`);
+    }
+    if (!Array.isArray(value)) {
+        throw new Error(`--${key} must be an array`);
+    }
+    return value;
+}
+export function positiveIntegerFromOptions(options, key) {
+    const value = options[key];
+    if (value === undefined) {
+        return undefined;
+    }
+    const numberValue = +value;
+    if (isNaN(numberValue) || numberValue <= 0) {
+        throw new Error(`Invalid ${key}: ${value}, must be a positive number`);
+    }
+    return numberValue;
+}
+export function requiredPositiveIntegerFromOptions(options, key) {
+    const value = positiveIntegerFromOptions(options, key);
+    if (value === undefined) {
+        throw new Error(`--${key} is required`);
+    }
+    return value;
+}
+export function getANTStateFromOptions(options) {
+    return initANTStateForAddress({
+        owner: requiredAddressFromOptions(options),
+        targetId: options.target,
+        controllers: options.controllers,
+        description: options.description,
+        ticker: options.ticker,
+        name: options.name,
+        keywords: options.keywords,
+        ttlSeconds: options.ttlSeconds !== undefined ? +options.ttlSeconds : 0,
+    });
+}