@ar.io/sdk 3.24.0 → 4.0.0-solana.3

package/lib/cjs/cli/commands/gatewayWriteCommands.js

@@ -33,7 +33,7 @@ const prompts_1 = __importDefault(require("prompts"));
 const index_js_1 = require("../../node/index.js");
 const utils_js_1 = require("../utils.js");
 async function joinNetwork(options) {
-    const { ario, signerAddress } = (0, utils_js_1.writeARIOFromOptions)(options);
+    const { ario, signerAddress } = await (0, utils_js_1.writeARIOFromOptions)(options);
     const mARIOQuantity = (0, utils_js_1.requiredMARIOFromOptions)(options, 'operatorStake');
     const settings = {
         ...(0, utils_js_1.gatewaySettingsFromOptions)(options),
@@ -66,7 +66,7 @@ async function joinNetwork(options) {
     return output;
 }
 async function updateGatewaySettings(options) {
-    const { ario, signerAddress } = (0, utils_js_1.writeARIOFromOptions)(options);
+    const { ario, signerAddress } = await (0, utils_js_1.writeARIOFromOptions)(options);
     const gatewaySettings = (0, utils_js_1.gatewaySettingsFromOptions)(options);
     if (Object.keys(gatewaySettings).length === 0) {
         // TODO: The contract accepts empty Update-Gateway-Settings actions, but we'll throw in the CLI for now
@@ -82,7 +82,7 @@ async function updateGatewaySettings(options) {
     return output;
 }
 async function leaveNetwork(options) {
-    const { ario, signerAddress } = (0, utils_js_1.writeARIOFromOptions)(options);
+    const { ario, signerAddress } = await (0, utils_js_1.writeARIOFromOptions)(options);
     if (!options.skipConfirmation) {
         const gateway = await ario.getGateway({ address: signerAddress });
         await (0, utils_js_1.assertConfirmationPrompt)('Gateway Details:\n\n' +
@@ -90,13 +90,13 @@ async function leaveNetwork(options) {
             '\n\n' +
             'Are you sure you want to leave the AR.IO network?', options);
     }
-    return (0, utils_js_1.writeARIOFromOptions)(options).ario.leaveNetwork((0, utils_js_1.customTagsFromOptions)(options));
+    return (await (0, utils_js_1.writeARIOFromOptions)(options)).ario.leaveNetwork((0, utils_js_1.customTagsFromOptions)(options));
 }
 async function saveObservations(o) {
     const failedGateways = (0, utils_js_1.requiredStringArrayFromOptions)(o, 'failedGateways');
     const reportTxId = (0, utils_js_1.requiredStringFromOptions)(o, 'transactionId');
     await (0, utils_js_1.assertConfirmationPrompt)(`You are about to save the following failed gateways to the AR.IO network:\n\n${failedGateways.join('\n')}\n\nTransaction ID: ${reportTxId}\n\nAre you sure?`, o);
-    return (0, utils_js_1.writeARIOFromOptions)(o).ario.saveObservations({
+    return (await (0, utils_js_1.writeARIOFromOptions)(o)).ario.saveObservations({
         failedGateways: (0, utils_js_1.requiredStringArrayFromOptions)(o, 'failedGateways'),
         reportTxId: (0, utils_js_1.requiredStringFromOptions)(o, 'transactionId'),
     }, (0, utils_js_1.customTagsFromOptions)(o));
@@ -104,15 +104,30 @@ async function saveObservations(o) {
 async function increaseOperatorStake(o) {
     const increaseQty = (0, utils_js_1.requiredMARIOFromOptions)(o, 'operatorStake');
     await (0, utils_js_1.assertConfirmationPrompt)(`You are about to increase your operator stake by ${(0, utils_js_1.formatARIOWithCommas)(increaseQty.toARIO())} ARIO\nAre you sure?`, o);
-    return (0, utils_js_1.writeARIOFromOptions)(o).ario.increaseOperatorStake({
+    return (await (0, utils_js_1.writeARIOFromOptions)(o)).ario.increaseOperatorStake({
         increaseQty,
     }, (0, utils_js_1.customTagsFromOptions)(o));
 }
 async function decreaseOperatorStake(o) {
+    const { ario, signerAddress } = await (0, utils_js_1.writeARIOFromOptions)(o);
     const decreaseQty = (0, utils_js_1.requiredMARIOFromOptions)(o, 'operatorStake');
-    // TODO: Can assert stake is sufficient for action, and new target stake meets contract minimum
+    if (!o.skipConfirmation) {
+        const gateway = await ario.getGateway({ address: signerAddress });
+        if (gateway === undefined) {
+            throw new Error(`No gateway found for address ${signerAddress}. You must be a gateway operator to decrease stake.`);
+        }
+        const settings = await ario.getGatewayRegistrySettings();
+        const currentStake = gateway.operatorStake;
+        const remaining = currentStake - decreaseQty.valueOf();
+        if (remaining < 0) {
+            throw new Error(`Insufficient operator stake. Current: ${(0, utils_js_1.formatARIOWithCommas)(new index_js_1.mARIOToken(currentStake).toARIO())} ARIO, requested decrease: ${(0, utils_js_1.formatARIOWithCommas)(decreaseQty.toARIO())} ARIO`);
+        }
+        if (remaining > 0 && remaining < settings.operators.minStake) {
+            throw new Error(`Remaining stake (${(0, utils_js_1.formatARIOWithCommas)(new index_js_1.mARIOToken(remaining).toARIO())} ARIO) would be below minimum (${(0, utils_js_1.formatARIOWithCommas)(new index_js_1.mARIOToken(settings.operators.minStake).toARIO())} ARIO). Decrease to exactly 0 (after calling leave-network) or keep above the minimum.`);
+        }
+    }
     await (0, utils_js_1.assertConfirmationPrompt)(`You are about to decrease your operator stake by ${(0, utils_js_1.formatARIOWithCommas)(decreaseQty.toARIO())} ARIO\nAre you sure?`, o);
-    return (0, utils_js_1.writeARIOFromOptions)(o).ario.decreaseOperatorStake({
+    return ario.decreaseOperatorStake({
         decreaseQty,
     }, (0, utils_js_1.customTagsFromOptions)(o));
 }
@@ -120,7 +135,7 @@ async function instantWithdrawal(o) {
     const vaultId = (0, utils_js_1.requiredStringFromOptions)(o, 'vaultId');
     const gatewayAddress = (0, utils_js_1.requiredAddressFromOptions)(o);
     await (0, utils_js_1.assertConfirmationPrompt)(`You are about to instantly withdraw from vault ${vaultId} for with gateway address ${gatewayAddress}\nAre you sure?`, o);
-    return (0, utils_js_1.writeARIOFromOptions)(o).ario.instantWithdrawal({
+    return (await (0, utils_js_1.writeARIOFromOptions)(o)).ario.instantWithdrawal({
         vaultId,
         gatewayAddress,
     }, (0, utils_js_1.customTagsFromOptions)(o));
@@ -129,13 +144,13 @@ async function cancelWithdrawal(o) {
     const vaultId = (0, utils_js_1.requiredStringFromOptions)(o, 'vaultId');
     const gatewayAddress = (0, utils_js_1.requiredAddressFromOptions)(o);
     await (0, utils_js_1.assertConfirmationPrompt)(`You are about to cancel the pending withdrawal from vault ${vaultId} for with gateway address ${gatewayAddress}\nAre you sure?`, o);
-    return (0, utils_js_1.writeARIOFromOptions)(o).ario.cancelWithdrawal({
+    return (await (0, utils_js_1.writeARIOFromOptions)(o)).ario.cancelWithdrawal({
         vaultId,
         gatewayAddress,
     }, (0, utils_js_1.customTagsFromOptions)(o));
 }
 async function delegateStake(options) {
-    const { ario, signerAddress } = (0, utils_js_1.writeARIOFromOptions)(options);
+    const { ario, signerAddress } = await (0, utils_js_1.writeARIOFromOptions)(options);
     const { target, arioQuantity } = (0, utils_js_1.requiredTargetAndQuantityFromOptions)(options);
     const mARIOQuantity = arioQuantity.toMARIO();
     if (!options.skipConfirmation) {
@@ -150,8 +165,59 @@ async function delegateStake(options) {
         if (targetGateway.settings.allowDelegatedStaking === false) {
             throw new Error(`Gateway does not allow delegated staking: ${target}`);
         }
-        // TODO: could get allow list and assert doesn't exist or user is on it
-        // TODO: could read from contract to get current delegated stake if there is none, get contract minimum delegated stake. Then see if the new stake value will satisfy minimum delegated stake for both the target gateway settings min delegate stake and contract min delegated amounts
+        // Check allowlist if gateway restricts delegation. `allowDelegatedStaking`
+        // is `boolean | 'allowlist'`; the SDK maps `allowlist_enabled = true` on
+        // Solana to the `'allowlist'` variant (see deserialize.ts).
+        //
+        // `getGatewayDelegateAllowList` returns `PaginationResult<WalletAddress>`,
+        // so we walk pages by cursor — the previous shape (plain `string[]`) was
+        // never the actual return type and made the membership check dead code.
+        //
+        // Note: the on-chain delegate handler also lets you bypass the allowlist
+        // if you already have stake > 0 with this gateway (delegate.rs). We
+        // can't easily check that client-side, so this preflight surfaces the
+        // most common case (new-delegator-not-on-list) but falls through any
+        // unexpected error to let the on-chain check arbitrate.
+        if (targetGateway.settings.allowDelegatedStaking === 'allowlist') {
+            try {
+                let cursor;
+                let onAllowlist = false;
+                let allowlistHasEntries = false;
+                do {
+                    const page = await ario.getGatewayDelegateAllowList({
+                        address: target,
+                        limit: 1_000,
+                        cursor,
+                    });
+                    if (page.items.length > 0)
+                        allowlistHasEntries = true;
+                    if (page.items.includes(signerAddress)) {
+                        onAllowlist = true;
+                        break;
+                    }
+                    cursor = page.nextCursor;
+                } while (cursor);
+                if (allowlistHasEntries && !onAllowlist) {
+                    throw new Error(`You (${signerAddress}) are not on the delegation allowlist for gateway ${target}.`);
+                }
+            }
+            catch (e) {
+                // Re-throw our own "not on allowlist" error; swallow anything else
+                // so the on-chain check can produce the canonical failure.
+                if (e instanceof Error &&
+                    e.message.includes('not on the delegation allowlist')) {
+                    throw e;
+                }
+            }
+        }
+        // Validate minimum delegation amount
+        const settings = await ario.getGatewayRegistrySettings();
+        const contractMinDelegation = settings.delegates.minStake;
+        const gatewayMinDelegation = targetGateway.settings.minDelegatedStake ?? contractMinDelegation;
+        const effectiveMin = Math.max(contractMinDelegation, gatewayMinDelegation);
+        if (mARIOQuantity.valueOf() < effectiveMin) {
+            throw new Error(`Delegation amount (${(0, utils_js_1.formatARIOWithCommas)(arioQuantity)} ARIO) is below minimum (${(0, utils_js_1.formatARIOWithCommas)(new index_js_1.mARIOToken(effectiveMin).toARIO())} ARIO).`);
+        }
         const { confirm } = await (0, prompts_1.default)({
             type: 'confirm',
             name: 'confirm',
@@ -173,13 +239,40 @@ async function delegateStake(options) {
     return output;
 }
 async function decreaseDelegateStake(options) {
-    const ario = (0, utils_js_1.writeARIOFromOptions)(options).ario;
+    const ario = await (await (0, utils_js_1.writeARIOFromOptions)(options)).ario;
     const { target, arioQuantity } = (0, utils_js_1.requiredTargetAndQuantityFromOptions)(options);
     const instant = options.instant ?? false;
-    // TODO: Could assert sender is a delegate with enough stake to decrease
-    // TODO: Could assert new target stake meets contract and target gateway minimums
-    // TODO: Could present confirmation prompt with any fee for instant withdrawal (50% of the stake is put back into protocol??)
-    await (0, utils_js_1.assertConfirmationPrompt)(`Are you sure you'd like to decrease delegated stake of ${(0, utils_js_1.formatARIOWithCommas)(arioQuantity)} ARIO on gateway ${target}?`, options);
+    if (!options.skipConfirmation) {
+        // Verify the target gateway exists and look up delegation
+        const signerAddr = (await (0, utils_js_1.writeARIOFromOptions)(options)).signerAddress;
+        const targetGateway = await ario.getGateway({ address: target });
+        if (targetGateway === undefined) {
+            throw new Error(`Gateway not found: ${target}`);
+        }
+        // Find delegation to this gateway
+        const delegations = await ario.getDelegations({ address: signerAddr });
+        const delegation = delegations.items.find((d) => d.gatewayAddress === target && d.type === 'stake');
+        if (!delegation) {
+            throw new Error(`No active delegation found for you on gateway ${target}.`);
+        }
+        if (arioQuantity.toMARIO().valueOf() > delegation.balance) {
+            throw new Error(`Cannot decrease by ${(0, utils_js_1.formatARIOWithCommas)(arioQuantity)} ARIO — you only have ${(0, utils_js_1.formatARIOWithCommas)(new index_js_1.mARIOToken(delegation.balance).toARIO())} ARIO delegated.`);
+        }
+        const remaining = delegation.balance - arioQuantity.toMARIO().valueOf();
+        if (remaining > 0) {
+            const registrySettings = await ario.getGatewayRegistrySettings();
+            const contractMin = registrySettings.delegates.minStake;
+            if (remaining < contractMin) {
+                throw new Error(`Remaining delegation (${(0, utils_js_1.formatARIOWithCommas)(new index_js_1.mARIOToken(remaining).toARIO())} ARIO) would be below minimum (${(0, utils_js_1.formatARIOWithCommas)(new index_js_1.mARIOToken(contractMin).toARIO())} ARIO). Decrease to exactly 0 or keep above the minimum.`);
+            }
+        }
+    }
+    if (instant) {
+        await (0, utils_js_1.assertConfirmationPrompt)(`WARNING: Instant withdrawal incurs a penalty.\nAre you sure you'd like to instantly decrease delegated stake of ${(0, utils_js_1.formatARIOWithCommas)(arioQuantity)} ARIO on gateway ${target}?`, options);
+    }
+    else {
+        await (0, utils_js_1.assertConfirmationPrompt)(`Are you sure you'd like to decrease delegated stake of ${(0, utils_js_1.formatARIOWithCommas)(arioQuantity)} ARIO on gateway ${target}?`, options);
+    }
     const result = await ario.decreaseDelegateStake({
         target,
         decreaseQty: arioQuantity.toMARIO(),
@@ -193,11 +286,28 @@ async function decreaseDelegateStake(options) {
     return output;
 }
 async function redelegateStake(options) {
-    const ario = (0, utils_js_1.writeARIOFromOptions)(options).ario;
+    const ario = await (await (0, utils_js_1.writeARIOFromOptions)(options)).ario;
     const params = (0, utils_js_1.redelegateParamsFromOptions)(options);
-    // TODO: Could assert target gateway exists
-    // TODO: Could do assertion on source has enough stake to redelegate
-    // TODO: Could do assertions on source/target min delegate stakes are met
+    if (!options.skipConfirmation) {
+        const targetGateway = await ario.getGateway({ address: params.target });
+        if (targetGateway === undefined) {
+            throw new Error(`Target gateway not found: ${params.target}`);
+        }
+        if (targetGateway.settings.allowDelegatedStaking === false) {
+            throw new Error(`Target gateway ${params.target} does not allow delegated staking.`);
+        }
+        const sourceGateway = await ario.getGateway({ address: params.source });
+        if (sourceGateway === undefined) {
+            throw new Error(`Source gateway not found: ${params.source}`);
+        }
+        const signerAddr = (await (0, utils_js_1.writeARIOFromOptions)(options)).signerAddress;
+        const delegations = await ario.getDelegations({ address: signerAddr });
+        const delegation = delegations.items.find((d) => d.gatewayAddress === params.source && d.type === 'stake');
+        if (!delegation || delegation.balance < params.stakeQty.valueOf()) {
+            const available = delegation?.balance ?? 0;
+            throw new Error(`Insufficient delegated stake on source gateway ${params.source}. Available: ${(0, utils_js_1.formatARIOWithCommas)(new index_js_1.mARIOToken(available).toARIO())} ARIO, requested: ${(0, utils_js_1.formatARIOWithCommas)(params.stakeQty.toARIO())} ARIO`);
+        }
+    }
     await (0, utils_js_1.assertConfirmationPrompt)(`Are you sure you'd like to redelegate stake of ${(0, utils_js_1.formatARIOWithCommas)(params.stakeQty.toARIO())} ARIO from ${params.source} to ${params.target}?`, options);
     const result = await ario.redelegateStake(params);
     const output = {

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

@@ -208,8 +208,16 @@ async function resolveArNSName(o) {
 }
 async function listAntsForAddress(o) {
     const address = (0, utils_js_1.requiredAddressFromOptions)(o);
-    const result = await (0, utils_js_1.readANTRegistryFromOptions)(o).accessControlList({
+    // Both AO and Solana backends expose `accessControlList({ address })`.
+    // Solana is backed by the paginated per-user ACL (ADR-012): a head
+    // `AclConfig` PDA at ["acl_config", user] plus N `AclPage` PDAs at
+    // ["acl_page", user, page_idx_le]. The ario-ant program maintains them
+    // alongside `initialize`, `add_controller`, `remove_controller`,
+    // `transfer_record`, and the marketplace reconcile path.
+    const registry = await (0, utils_js_1.readANTRegistryFromOptions)(o);
+    const result = await registry.accessControlList({
         address,
     });
-    return result ?? { message: `No ANTs found for address ${address}` };
+    const hasAny = result && (result.Owned.length > 0 || result.Controlled.length > 0);
+    return hasAny ? result : { message: `No ANTs found for address ${address}` };
 }

package/lib/cjs/cli/commands/transfer.js

@@ -10,7 +10,7 @@ const token_js_1 = require("../../types/token.js");
 const utils_js_1 = require("../utils.js");
 async function transferCLICommand(options) {
     const { target, arioQuantity } = (0, utils_js_1.requiredTargetAndQuantityFromOptions)(options);
-    const { ario, signerAddress } = (0, utils_js_1.writeARIOFromOptions)(options);
+    const { ario, signerAddress } = await (0, utils_js_1.writeARIOFromOptions)(options);
     if (!options.skipConfirmation) {
         await (0, utils_js_1.assertEnoughMARIOBalance)({
             ario,
@@ -36,7 +36,7 @@ async function transferCLICommand(options) {
 async function vaultedTransferCLICommand(o) {
     const mARIOQuantity = (0, utils_js_1.requiredMARIOFromOptions)(o, 'quantity');
     const recipient = (0, utils_js_1.requiredStringFromOptions)(o, 'recipient');
-    const { ario, signerAddress } = (0, utils_js_1.writeARIOFromOptions)(o);
+    const { ario, signerAddress } = await (0, utils_js_1.writeARIOFromOptions)(o);
     const lockLengthMs = (0, utils_js_1.requiredPositiveIntegerFromOptions)(o, 'lockLengthMs');
     (0, utils_js_1.assertLockLengthInRange)(lockLengthMs);
     if (!o.skipConfirmation) {
@@ -64,7 +64,7 @@ async function vaultedTransferCLICommand(o) {
     return output;
 }
 async function revokeVaultCLICommand(o) {
-    const { ario, signerAddress } = (0, utils_js_1.writeARIOFromOptions)(o);
+    const { ario, signerAddress } = await (0, utils_js_1.writeARIOFromOptions)(o);
     const vaultId = (0, utils_js_1.requiredStringFromOptions)(o, 'vaultId');
     const recipient = (0, utils_js_1.requiredStringFromOptions)(o, 'recipient');
     if (!o.skipConfirmation) {
@@ -87,7 +87,7 @@ async function revokeVaultCLICommand(o) {
 }
 async function createVaultCLICommand(o) {
     const mARIOQuantity = (0, utils_js_1.requiredMARIOFromOptions)(o, 'quantity');
-    const { ario, signerAddress } = (0, utils_js_1.writeARIOFromOptions)(o);
+    const { ario, signerAddress } = await (0, utils_js_1.writeARIOFromOptions)(o);
     const lockLengthMs = (0, utils_js_1.requiredPositiveIntegerFromOptions)(o, 'lockLengthMs');
     (0, utils_js_1.assertLockLengthInRange)(lockLengthMs);
     if (!o.skipConfirmation) {
@@ -113,7 +113,7 @@ async function createVaultCLICommand(o) {
     return output;
 }
 async function extendVaultCLICommand(o) {
-    const { ario, signerAddress } = (0, utils_js_1.writeARIOFromOptions)(o);
+    const { ario, signerAddress } = await (0, utils_js_1.writeARIOFromOptions)(o);
     const vaultId = (0, utils_js_1.requiredStringFromOptions)(o, 'vaultId');
     const extendLengthMs = (0, utils_js_1.requiredPositiveIntegerFromOptions)(o, 'extendLengthMs');
     (0, utils_js_1.assertLockLengthInRange)(extendLengthMs, false);
@@ -137,7 +137,7 @@ async function extendVaultCLICommand(o) {
 }
 async function increaseVaultCLICommand(o) {
     const mARIOQuantity = (0, utils_js_1.requiredMARIOFromOptions)(o, 'quantity');
-    const { ario, signerAddress } = (0, utils_js_1.writeARIOFromOptions)(o);
+    const { ario, signerAddress } = await (0, utils_js_1.writeARIOFromOptions)(o);
     const vaultId = (0, utils_js_1.requiredStringFromOptions)(o, 'vaultId');
     if (!o.skipConfirmation) {
         const vault = await ario.getVault({ vaultId, address: signerAddress });

package/lib/cjs/cli/options.js

@@ -56,6 +56,69 @@ exports.optionMap = {
         alias: '--hyperbeam-url <hyperbeamUrl>',
         description: 'The URL for a custom hyperbeam node',
     },
+    ao: {
+        alias: '--ao',
+        description: 'Use the legacy AO backend instead of Solana',
+        type: 'boolean',
+    },
+    rpcUrl: {
+        alias: '--rpc-url <rpcUrl>',
+        description: 'Solana RPC URL (defaults to mainnet-beta)',
+    },
+    antProgramId: {
+        alias: '--ant-program-id <antProgramId>',
+        description: 'Override the ario-ant program id (Solana backend). Defaults to the SDK-bundled mainnet id; ' +
+            'set this when querying localnet/devnet (see migration/localnet/out/localnet.env -> ARIO_ANT_PROGRAM_ID).',
+    },
+    coreProgramId: {
+        alias: '--core-program-id <coreProgramId>',
+        description: 'Override the ario-core program id (Solana backend). See ARIO_CORE_PROGRAM_ID in localnet.env.',
+    },
+    garProgramId: {
+        alias: '--gar-program-id <garProgramId>',
+        description: 'Override the ario-gar program id (Solana backend). See ARIO_GAR_PROGRAM_ID in localnet.env.',
+    },
+    arnsProgramId: {
+        alias: '--arns-program-id <arnsProgramId>',
+        description: 'Override the ario-arns program id (Solana backend). See ARIO_ARNS_PROGRAM_ID in localnet.env.',
+    },
+    escrowProgramId: {
+        alias: '--escrow-program-id <escrowProgramId>',
+        description: 'Override the ario-ant-escrow program id. Defaults to the SDK-bundled placeholder; ' +
+            'set when running against a deployed devnet/mainnet instance.',
+    },
+    ant: {
+        alias: '--ant <antMint>',
+        description: 'The Metaplex Core ANT mint pubkey (base58)',
+    },
+    recipientArweave: {
+        alias: '--recipient-arweave <jwkFile>',
+        description: 'Path to an Arweave JWK file. The "n" field (RSA-4096 modulus) is used as the escrow recipient identity.',
+    },
+    recipientEthereum: {
+        alias: '--recipient-ethereum <0xAddress>',
+        description: 'A 0x-prefixed Ethereum address to use as the escrow recipient identity.',
+    },
+    newRecipientArweave: {
+        alias: '--new-recipient-arweave <jwkFile>',
+        description: 'New Arweave JWK file (for `escrow update-recipient`).',
+    },
+    newRecipientEthereum: {
+        alias: '--new-recipient-ethereum <0xAddress>',
+        description: 'New Ethereum address (for `escrow update-recipient`).',
+    },
+    signatureFile: {
+        alias: '--signature-file <path>',
+        description: 'Path to a binary signature file (512 bytes for Arweave PSS, 65 bytes for Ethereum r||s||v).',
+    },
+    saltLen: {
+        alias: '--salt-len <bytes>',
+        description: 'PSS salt length (Arweave only; defaults to 32, the wallet-default).',
+    },
+    claimant: {
+        alias: '--claimant <pubkey>',
+        description: 'Solana pubkey that will receive the ANT on claim.',
+    },
     cuUrl: {
         alias: '--cu-url <cuUrl>',
         description: 'The URL for a custom compute unit',
@@ -239,7 +302,11 @@ exports.optionMap = {
     },
     transactionId: {
         alias: '--transaction-id <transactionId>',
-        description: 'The transaction ID to interact with',
+        description: 'The content target (Arweave TX ID, IPFS CID, etc.)',
+    },
+    targetProtocol: {
+        alias: '--target-protocol <targetProtocol>',
+        description: 'Storage protocol for the target: "arweave" (default) or "ipfs"',
     },
     ttlSeconds: {
         alias: '--ttl-seconds <ttlSeconds>',
@@ -278,7 +345,31 @@ exports.optionMap = {
     },
     fundFrom: {
         alias: '--fund-from <fundFrom>',
-        description: 'Where to fund the action from. e.g. "balance", "stakes", or "any',
+        description: 'Funding source: balance | stakes | withdrawal | plan | any | turbo. ' +
+            "'stakes' requires --gateway-address (uses delegation; add --fund-as-operator " +
+            "for operator stake). 'withdrawal' requires --withdrawal-id. 'plan' / 'any' " +
+            'use the multi-source funding plan (see --funding-plan-json or auto-discover).',
+    },
+    gatewayAddress: {
+        alias: '--gateway-address <gatewayAddress>',
+        description: 'Gateway operator address for funding from stakes. Required when --fund-from is "stakes"',
+    },
+    fundAsOperator: {
+        alias: '--fund-as-operator',
+        description: 'Fund from operator stake instead of delegation (default: delegation)',
+        type: 'boolean',
+    },
+    withdrawalId: {
+        alias: '--withdrawal-id <withdrawalId>',
+        description: 'Withdrawal vault id (u64) — required when --fund-from is "withdrawal" (Solana). ' +
+            'Find with `ar.io listMyWithdrawals` or query Withdrawal PDAs directly.',
+    },
+    fundingPlanJson: {
+        alias: '--funding-plan-json <json>',
+        description: 'Explicit funding plan as JSON: [{"kind":"balance","amount":"100"},...]. ' +
+            "Used when --fund-from is 'plan' or 'any' to bypass auto-discovery. " +
+            "kind is 'balance' | 'delegation' | 'operatorStake' | 'withdrawal'; " +
+            'amount is a string-encoded mARIO bigint. Sum must equal the operation cost.',
     },
     revokable: {
         alias: '--revokable',
@@ -310,6 +401,10 @@ exports.optionMap = {
         alias: '--module <module>',
         description: 'The module ID to use for spawning the ANT process',
     },
+    metadataUri: {
+        alias: '--metadata-uri <metadataUri>',
+        description: 'Solana spawn-ant only: URI baked into the Metaplex Core asset (e.g. "ar://<txid>" or "https://<gateway>/raw/<txid>"). Build the JSON with `buildAntMetadata` from `@ar.io/sdk/solana` and upload via Turbo. See sdk/scripts/devnet-validation/populate-ant.ts.',
+    },
     token: {
         alias: '-t, --token <type>',
         description: 'Crypto token type for wallet or action',
@@ -345,12 +440,22 @@ exports.globalOptions = [
     exports.optionMap.arioProcessId,
     exports.optionMap.cuUrl,
     exports.optionMap.hyperbeamUrl,
+    exports.optionMap.ao,
+    exports.optionMap.rpcUrl,
+    exports.optionMap.antProgramId,
+    exports.optionMap.coreProgramId,
+    exports.optionMap.garProgramId,
+    exports.optionMap.arnsProgramId,
 ];
 exports.writeActionOptions = [exports.optionMap.skipConfirmation, exports.optionMap.tags];
 exports.arnsPurchaseOptions = [
     ...exports.writeActionOptions,
     exports.optionMap.name,
     exports.optionMap.fundFrom,
+    exports.optionMap.gatewayAddress,
+    exports.optionMap.fundAsOperator,
+    exports.optionMap.withdrawalId,
+    exports.optionMap.fundingPlanJson,
     exports.optionMap.paidBy,
     exports.optionMap.paymentUrl,
     exports.optionMap.referrer,
@@ -440,10 +545,15 @@ exports.antStateOptions = [
     exports.optionMap.ttlSeconds,
     exports.optionMap.logo,
     exports.optionMap.module,
+    // Required for Solana spawn-ant; ignored by AO. Without this entry,
+    // Commander rejects --metadata-uri as an unknown option even though
+    // spawnSolanaANTFromOptions in utils.ts reads it as `(options as any).metadataUri`.
+    exports.optionMap.metadataUri,
 ];
 exports.setAntBaseNameOptions = [
     exports.optionMap.processId,
     exports.optionMap.transactionId,
+    exports.optionMap.targetProtocol,
     exports.optionMap.ttlSeconds,
     exports.optionMap.owner,
     exports.optionMap.displayName,