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

package/README.md

@@ -11,14 +11,6 @@ This is the home of the ar.io SDK. This SDK provides functionality for interacti
 - [Table of Contents](#table-of-contents)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
-- [Usage](#usage)
-- [ARIO Contract](#ario-contract)
-- [ANT Contracts](#ant-contracts)
-- [Token Conversion](#token-conversion)
-- [Logging](#logging)
-- [Pagination](#pagination)
-- [Resources](#resources)
-- [Developers](#developers)
 
 <!-- tocstop -->
 
@@ -48,6 +40,22 @@ const ario = ARIO.mainnet(); // defaults to mainnet
 const gateways = await ario.getGateways();
 ```
 
+> **Solana backend (preview)** — `npm install @ar.io/sdk@solana`
+> ships the Solana port. Same `ARIO`/`ANT` API surface, kit-native:
+>
+> ```ts
+> import { ARIO } from '@ar.io/sdk/solana';
+> import { createSolanaRpc } from '@solana/kit';
+>
+> const ario = ARIO.init({
+>   backend: 'solana',
+>   rpc: createSolanaRpc('https://api.mainnet-beta.solana.com'),
+> });
+> ```
+>
+> See the **[Solana backend](#solana-backend)** section below for the
+> full kit-native usage (read + write paths, ANT spawn, escrow, etc.).
+
 <details>
   <summary>Output</summary>
 
@@ -98,7 +106,7 @@ const gateways = await ario.getGateways();
 
 ## Usage
 
-The SDK is provided in both CommonJS and ESM formats and is compatible with bundlers such as Webpack, Rollup, and ESbuild. Utilize the appropriately named exports provided by this SDK's [package.json] based on your project's configuration. Refer to the [examples] directory to see how to use the SDK in various environments.
+The SDK is published as an ES module (`"type": "module"`) and is compatible with modern bundlers such as Webpack, Rollup, ESbuild, and Vite. CommonJS consumers should migrate to ESM (Node 18+ supports ESM natively, and modern bundlers handle ESM packages out of the box). Utilize the appropriately named exports provided by this SDK's [package.json] based on your project's configuration. Refer to the [examples] directory to see how to use the SDK in various environments.
 
 ### Web
 
@@ -132,8 +140,6 @@ const gateways = await ario.getGateways();
 
 ### Node
 
-#### ESM (NodeNext)
-
 ```javascript
 import { ARIO } from "@ar.io/sdk/node";
 
@@ -143,17 +149,6 @@ const ario = ARIO.mainnet();
 const gateways = await ario.getGateways();
 ```
 
-#### CJS
-
-```javascript
-import { ARIO } from "@ar.io/sdk";
-
-// set up client
-const ario = ARIO.mainnet();
-// fetch gateways
-const gateways = await ario.getGateways();
-```
-
 ### Typescript
 
 The SDK provides TypeScript types. When you import the SDK in a TypeScript project types are exported from `./lib/types/[node/web]/index.d.ts` and should be automatically recognized by package managers, offering benefits such as type-checking and autocompletion.
@@ -3170,6 +3165,132 @@ In the example above, the query will return ArNS records where:
 - The type is "lease" AND
 - The processId is EITHER "ZkgLfyHALs5koxzojpcsEFAKA8fbpzP7l-tbM7wmQNM" OR "r61rbOjyXx3u644nGl9bkwLWlWmArMEzQgxBo2R-Vu0"
 
+## Solana backend
+
+The Solana backend ports the ARIO/ANT API surface to Solana. Same
+`ARIO.init`/`ANT.init` factory calls — pass `backend: 'solana'` plus a
+`@solana/kit` RPC client and you get the kit-native implementation.
+
+### Quick start
+
+```ts
+import { ARIO, ANT } from '@ar.io/sdk/solana';
+import {
+  createSolanaRpc,
+  createSolanaRpcSubscriptions,
+  createKeyPairSignerFromBytes,
+} from '@solana/kit';
+import { readFileSync } from 'node:fs';
+
+// Read-only client (RPC only)
+const rpc = createSolanaRpc('https://api.mainnet-beta.solana.com');
+const ario = ARIO.init({ backend: 'solana', rpc });
+
+const record = await ario.getArNSRecord({ name: 'ardrive' });
+//   record.processId === '<the ANT mint pubkey>'
+
+// Write client — pair an RPC + a signer
+const signerBytes = new Uint8Array(
+  JSON.parse(readFileSync('/path/to/keypair.json', 'utf8')),
+);
+const signer = await createKeyPairSignerFromBytes(signerBytes);
+const rpcSubs = createSolanaRpcSubscriptions(
+  'wss://api.mainnet-beta.solana.com',
+);
+
+const arioWrite = ARIO.init({
+  backend: 'solana',
+  rpc,
+  rpcSubscriptions: rpcSubs,
+  signer,
+});
+
+await arioWrite.buyRecord({
+  name: 'foo',
+  type: 'lease',
+  years: 1,
+  processId: '<ANT mint pubkey>',
+});
+```
+
+### What's available
+
+The Solana backend implements the full `AoARIOWrite` and `AoANTWrite`
+interfaces — every method on the AO-backed clients has a Solana
+equivalent. Read paths (`getArNSRecord`, `getGateway`,
+`getEpochSettings`, etc.) and write paths (`buyRecord`, `extendLease`,
+`upgradeRecord`, `joinNetwork`, `delegateStake`, `decreaseDelegateStake`,
+`createVault`, `transferAnt`, `setRecord`, etc.) all work against the
+on-chain AR.IO programs deployed on Solana.
+
+Multi-source funding works the same way as Lua's `getFundingPlan`:
+pass `fundFrom: 'any'` and the SDK composes a plan across balance,
+matured withdrawal vaults, excess delegated stake, and minimum stake
+across multiple gateways. See the planner at
+`src/solana/funding-plan.ts` for the Lua-faithful drawdown order.
+
+### ANT lifecycle
+
+ANTs on Solana are Metaplex Core NFTs with an Attributes plugin
+carrying ArNS traits (`ArNS Name`, `Type`, `Undername Limit`,
+`ANT Program`). Spawn a fresh one:
+
+```ts
+import { ANT, spawnSolanaANT } from '@ar.io/sdk/solana';
+
+const { processId } = await spawnSolanaANT({
+  rpc, rpcSubscriptions: rpcSubs, signer,
+  state: {
+    name: 'My ANT',
+    ticker: 'MYANT',
+    description: 'whatever',
+    uri: 'ar://placeholder-metadata',
+  },
+});
+
+const ant = await ANT.init({
+  backend: 'solana',
+  processId,           // the Metaplex Core asset pubkey
+  rpc, rpcSubscriptions: rpcSubs, signer,
+});
+await ant.setBaseNameRecord({ transactionId: '...', ttlSeconds: 3600 });
+await ant.addController({ controller: '<some-pubkey>' });
+```
+
+The asset's Attributes plugin tracks which ANT program (the canonical
+`ARIO_ANT_PROGRAM_ID` or a third-party-conformant program — see
+ADR-016) holds the records. The SDK reads the plugin to derive the
+correct `AntRecord` PDA on every record lookup.
+
+### Conditional imports
+
+The `@ar.io/sdk/solana` subpath bundles Solana-only deps (`@solana/kit`,
+`@solana-program/compute-budget`, etc.). The default `@ar.io/sdk` /
+`@ar.io/sdk/node` / `@ar.io/sdk/web` entries stay AO-only — bundle size
+is unchanged for AO-only consumers.
+
+You can also import the codama-emitted typed clients directly for
+custom transaction building:
+
+```ts
+import {
+  getBuyNameInstructionAsync,
+  ARIO_ARNS_PROGRAM_ADDRESS,
+} from '@ar.io/sdk/solana/generated';
+```
+
+### Networks
+
+| Network | RPC | Programs |
+|---|---|---|
+| Mainnet | not yet deployed | TBD |
+| Devnet | `https://api.devnet.solana.com` | See `src/solana/constants.ts` for current devnet program IDs |
+| Localnet | Surfpool — `https://github.com/solana-foundation/surfpool` | Localnet harness in `solana-ar-io` monorepo |
+
+The migration tooling (snapshot exporter, batch importer, claim app)
+lives in the [`solana-ar-io`](https://github.com/ar-io/solana-ar-io)
+monorepo until cutover.
+
 ## Resources
 
 ### Bundling
@@ -3213,7 +3334,6 @@ For more information on how to use AO and AO Connect within this library, please
 - `yarn test:e2e` - runs e2e tests
 - `yarn test:unit` - runs unit tests
 - `yarn example:web` - opens up the example web page
-- `yarn example:cjs` - runs example CJS node script
 - `yarn example:esm` - runs example ESM node script
 - `yarn example:vite` - runs example Vite web page
 

package/lib/esm/cli/cli.js

@@ -20,8 +20,10 @@ import { AOProcess, spawnANT } from '../node/index.js';
 import { mARIOToken } from '../types/token.js';
 import { version } from '../version.js';
 import { setAntBaseNameCLICommand, setAntRecordCLICommand, setAntUndernameCLICommand, transferRecordOwnershipCLICommand, upgradeAntCLICommand, } from './commands/antCommands.js';
-import { buyRecordCLICommand, extendLeaseCLICommand, increaseUndernameLimitCLICommand, requestPrimaryNameCLICommand, setPrimaryNameCLICommand, upgradeRecordCLICommand, } from './commands/arnsPurchaseCommands.js';
+import { buyRecordCLICommand, extendLeaseCLICommand, increaseUndernameLimitCLICommand, requestPrimaryNameCLICommand, setPrimaryNameCLICommand, syncAttributesCLICommand, upgradeRecordCLICommand, } from './commands/arnsPurchaseCommands.js';
+import { escrowCancelCLICommand, escrowClaimArweaveCLICommand, escrowClaimEthereumCLICommand, escrowDepositCLICommand, escrowStatusCLICommand, escrowUpdateRecipientCLICommand, } from './commands/escrowCommands.js';
 import { cancelWithdrawal, decreaseDelegateStake, decreaseOperatorStake, delegateStake, increaseOperatorStake, instantWithdrawal, joinNetwork, leaveNetwork, redelegateStake, saveObservations, updateGatewaySettings, } from './commands/gatewayWriteCommands.js';
+import { closeDrainedWithdrawalCLICommand, closeEmptyDelegationCLICommand, closeExpiredRequestCLICommand, closeObservationCLICommand, finalizeGoneCLICommand, pruneExpiredNamesCLICommand, pruneExpiredReservationCLICommand, pruneGatewayCLICommand, pruneNameToReturnedCLICommand, pruneReturnedNamesCLICommand, releaseVaultCLICommand, } from './commands/pruneCommands.js';
 import { getAllGatewayVaults, getAllowedDelegates, getArNSRecord, getArNSReservedName, getArNSReturnedName, getCostDetails, getDelegations, getEpoch, getGateway, getGatewayDelegates, getGatewayVaults, getPrescribedNames, getPrescribedObservers, getPrimaryName, getTokenCost, getVault, listAllDelegatesCLICommand, listAntsForAddress, listArNSRecords, listArNSRecordsForAddress, 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, transferRecordOwnershipOptions, updateGatewaySettingsOptions, upgradeAntOptions, vaultedTransferOptions, writeActionOptions, } from './options.js';
@@ -411,7 +413,12 @@ makeCommand({
     options: buyRecordOptions,
     action: buyRecordCLICommand,
 });
-// TODO alias buy-record with buy-name
+makeCommand({
+    name: 'buy-name',
+    description: 'Buy a name (alias for buy-record)',
+    options: buyRecordOptions,
+    action: buyRecordCLICommand,
+});
 makeCommand({
     name: 'upgrade-record',
     description: 'Upgrade the lease of a record to a permabuy',
@@ -430,6 +437,14 @@ makeCommand({
     options: [...arnsPurchaseOptions, optionMap.increaseCount],
     action: increaseUndernameLimitCLICommand,
 });
+makeCommand({
+    name: 'sync-attributes',
+    description: 'Sync the on-chain ANT Attributes plugin (ArNS Name / Type / Undername Limit) ' +
+        'with the current ArnsRecord. Solana-only; permissionless reconciliation. ' +
+        'Use after a buy/reassign where the buyer was not the ANT NFT holder.',
+    options: arnsPurchaseOptions,
+    action: syncAttributesCLICommand,
+});
 makeCommand({
     name: 'request-primary-name',
     description: 'Request a primary name',
@@ -442,6 +457,77 @@ makeCommand({
     options: arnsPurchaseOptions,
     action: setPrimaryNameCLICommand,
 });
+// # Prune / cleanup (Solana-only — permissionless crank surface)
+makeCommand({
+    name: 'prune-expired-names',
+    description: 'Batch-prune expired ArnsRecord PDAs (Solana-only). Discovers eligible records ' +
+        'via getExpiredArnsRecords if --arns-records is omitted.',
+    options: [...writeActionOptions, optionMap.max, optionMap.arnsRecords],
+    action: pruneExpiredNamesCLICommand,
+});
+makeCommand({
+    name: 'prune-name-to-returned',
+    description: 'Convert a single expired-but-not-yet-returned lease into a ReturnedName ' +
+        '(starts the Dutch auction). Solana-only.',
+    options: [...writeActionOptions, optionMap.name],
+    action: pruneNameToReturnedCLICommand,
+});
+makeCommand({
+    name: 'prune-returned-names',
+    description: 'Batch-prune expired ReturnedName PDAs (Solana-only). Discovers via ' +
+        'getExpiredReturnedNames if --returned-names is omitted.',
+    options: [...writeActionOptions, optionMap.max, optionMap.returnedNames],
+    action: pruneReturnedNamesCLICommand,
+});
+makeCommand({
+    name: 'prune-expired-reservation',
+    description: 'Close an expired ReservedName PDA (Solana-only).',
+    options: [...writeActionOptions, optionMap.name],
+    action: pruneExpiredReservationCLICommand,
+});
+makeCommand({
+    name: 'prune-gateway',
+    description: 'Slash + remove a deficient gateway (≥30 consecutive failures). Solana-only.',
+    options: [...writeActionOptions, optionMap.gateway],
+    action: pruneGatewayCLICommand,
+});
+makeCommand({
+    name: 'finalize-gone',
+    description: 'GC a Leaving/Gone gateway whose leave window has fully elapsed. Solana-only.',
+    options: [...writeActionOptions, optionMap.gateway],
+    action: finalizeGoneCLICommand,
+});
+makeCommand({
+    name: 'close-observation',
+    description: 'Reclaim rent from an Observation PDA whose epoch has been distributed. Solana-only.',
+    options: [...writeActionOptions, optionMap.epochIndex, optionMap.observer],
+    action: closeObservationCLICommand,
+});
+makeCommand({
+    name: 'close-empty-delegation',
+    description: 'Close an empty Delegation PDA (amount == 0). Rent refunds to the original delegator. Solana-only.',
+    options: [...writeActionOptions, optionMap.gateway, optionMap.delegator],
+    action: closeEmptyDelegationCLICommand,
+});
+makeCommand({
+    name: 'close-drained-withdrawal',
+    description: 'Close a drained Withdrawal PDA (amount == 0). Rent refunds to the original owner. Solana-only.',
+    options: [...writeActionOptions, optionMap.owner, optionMap.withdrawalId],
+    action: closeDrainedWithdrawalCLICommand,
+});
+makeCommand({
+    name: 'release-vault',
+    description: 'Release tokens from an expired vault back to the owner (Solana-only). ' +
+        'NOT permissionless — must be called from the vault owner wallet.',
+    options: [...writeActionOptions, optionMap.vaultId, optionMap.owner],
+    action: releaseVaultCLICommand,
+});
+makeCommand({
+    name: 'close-expired-request',
+    description: 'Close an expired PrimaryNameRequest PDA. Solana-only.',
+    options: [...writeActionOptions, optionMap.initiator],
+    action: closeExpiredRequestCLICommand,
+});
 // # ANT Registry
 makeCommand({
     name: 'get-ants-for-address',
@@ -456,7 +542,7 @@ makeCommand({
     description: 'Get the state of an ANT process',
     options: [optionMap.processId],
     action: async (options) => {
-        return readANTFromOptions(options).getState();
+        return (await readANTFromOptions(options)).getState();
     },
 });
 makeCommand({
@@ -464,7 +550,7 @@ makeCommand({
     description: 'Get the info of an ANT process',
     options: [optionMap.processId],
     action: async (options) => {
-        return readANTFromOptions(options).getInfo();
+        return (await readANTFromOptions(options)).getInfo();
     },
 });
 makeCommand({
@@ -472,7 +558,7 @@ makeCommand({
     description: 'Get a record of an ANT process',
     options: [optionMap.processId, optionMap.undername],
     action: async (options) => {
-        return ((await readANTFromOptions(options).getRecord({
+        return ((await (await readANTFromOptions(options)).getRecord({
             undername: requiredStringFromOptions(options, 'undername'),
         })) ?? { message: 'No record found' });
     },
@@ -482,7 +568,7 @@ makeCommand({
     description: 'Get the owner of an ANT process',
     options: [optionMap.processId],
     action: async (options) => {
-        return readANTFromOptions(options).getOwner();
+        return (await readANTFromOptions(options)).getOwner();
     },
 });
 makeCommand({
@@ -490,7 +576,7 @@ makeCommand({
     description: 'Get the name of an ANT process',
     options: [optionMap.processId],
     action: async (options) => {
-        return readANTFromOptions(options).getName();
+        return (await readANTFromOptions(options)).getName();
     },
 });
 makeCommand({
@@ -498,7 +584,7 @@ makeCommand({
     description: 'Get the ticker of an ANT process',
     options: [optionMap.processId],
     action: async (options) => {
-        return readANTFromOptions(options).getTicker();
+        return (await readANTFromOptions(options)).getTicker();
     },
 });
 makeCommand({
@@ -506,7 +592,7 @@ makeCommand({
     description: 'Get the logo of an ANT process',
     options: [optionMap.processId],
     action: async (options) => {
-        return readANTFromOptions(options).getLogo();
+        return (await readANTFromOptions(options)).getLogo();
     },
 });
 makeCommand({
@@ -514,7 +600,7 @@ makeCommand({
     description: 'Get the balance of an ANT process',
     options: [optionMap.processId, optionMap.address],
     action: async (options) => {
-        return readANTFromOptions(options).getBalance({
+        return (await readANTFromOptions(options)).getBalance({
             address: requiredAddressFromOptions(options),
         });
     },
@@ -525,17 +611,32 @@ makeCommand({
     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),
-            ...(options.module !== undefined ? { module: options.module } : {}),
-        });
+        if (options.ao) {
+            const state = getANTStateFromOptions(options);
+            const antProcessId = await spawnANT({
+                state,
+                signer: requiredAoSignerFromOptions(options),
+                logger: getLoggerFromOptions(options),
+                ...(options.module !== undefined ? { module: options.module } : {}),
+            });
+            return {
+                processId: antProcessId,
+                signature: null,
+                state,
+                message: `Spawned ANT process with process ID ${antProcessId}`,
+            };
+        }
+        // Solana branch: the signer's pubkey IS the owner — no separate
+        // `--address` is needed (or possible, since the address would be the
+        // signer's pubkey anyway). We pass the raw CLI options through and let
+        // `spawnSolanaANTFromOptions` build the InitializeAntParams payload.
+        const { spawnSolanaANTFromOptions } = await import('./utils.js');
+        const result = await spawnSolanaANTFromOptions(options);
         return {
-            processId: antProcessId,
-            state,
-            message: `Spawned ANT process with process ID ${antProcessId}`,
+            processId: result.processId,
+            signature: result.signature,
+            state: null,
+            message: `Spawned Solana ANT (mint=${result.processId})`,
         };
     },
 });
@@ -545,7 +646,7 @@ makeCommand({
     description: 'Get the records of an ANT process',
     options: [optionMap.processId],
     action: async (options) => {
-        return readANTFromOptions(options).getRecords();
+        return (await readANTFromOptions(options)).getRecords();
     },
 });
 makeCommand({
@@ -553,7 +654,7 @@ makeCommand({
     description: 'List the controllers of an ANT process',
     options: [optionMap.processId],
     action: async (options) => {
-        return readANTFromOptions(options).getControllers();
+        return (await readANTFromOptions(options)).getControllers();
     },
 });
 makeCommand({
@@ -561,7 +662,7 @@ makeCommand({
     description: 'Get the balances of an ANT process',
     options: [optionMap.processId],
     action: async (options) => {
-        return readANTFromOptions(options).getBalances();
+        return (await readANTFromOptions(options)).getBalances();
     },
 });
 // # Actions
@@ -580,7 +681,7 @@ makeCommand({
             ? options.removeControllers
             : true;
         await assertConfirmationPrompt(`Are you sure you want to transfer ANT ownership to ${target}${removeControllers ? ' (controllers will be removed)' : ' (controllers will be retained)'}?`, options);
-        return writeANTFromOptions(options).transfer({
+        return (await writeANTFromOptions(options)).transfer({
             target,
             removeControllers,
         }, customTagsFromOptions(options));
@@ -593,7 +694,7 @@ makeCommand({
     action: async (options) => {
         const controller = requiredStringFromOptions(options, 'controller');
         await assertConfirmationPrompt(`Are you sure you want to add ${controller} as a controller?`, options);
-        return writeANTFromOptions(options).addController({
+        return (await writeANTFromOptions(options)).addController({
             controller: requiredStringFromOptions(options, 'controller'),
         }, customTagsFromOptions(options));
     },
@@ -603,7 +704,7 @@ makeCommand({
     description: 'Remove a controller from an ANT process',
     options: [optionMap.processId, optionMap.controller, ...writeActionOptions],
     action: async (options) => {
-        return writeANTFromOptions(options).removeController({
+        return (await writeANTFromOptions(options)).removeController({
             controller: requiredStringFromOptions(options, 'controller'),
         }, customTagsFromOptions(options));
     },
@@ -615,7 +716,7 @@ makeCommand({
     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({
+        return (await writeANTFromOptions(options)).removeRecord({
             undername,
         }, customTagsFromOptions(options));
     },
@@ -657,7 +758,7 @@ makeCommand({
     action: async (options) => {
         const ticker = requiredStringFromOptions(options, 'ticker');
         await assertConfirmationPrompt(`Are you sure you want to set the ticker to ${ticker}?`, options);
-        return writeANTFromOptions(options).setTicker({
+        return (await writeANTFromOptions(options)).setTicker({
             ticker,
         }, customTagsFromOptions(options));
     },
@@ -669,7 +770,7 @@ makeCommand({
     action: async (options) => {
         const name = requiredStringFromOptions(options, 'name');
         await assertConfirmationPrompt(`Are you sure you want to set the name to ${requiredStringFromOptions(options, 'name')}?`, options);
-        return writeANTFromOptions(options).setName({
+        return (await writeANTFromOptions(options)).setName({
             name,
         }, customTagsFromOptions(options));
     },
@@ -681,7 +782,7 @@ makeCommand({
     action: async (options) => {
         const description = requiredStringFromOptions(options, 'description');
         await assertConfirmationPrompt(`Are you sure you want to set the ANT description to ${description}?`, options);
-        return writeANTFromOptions(options).setDescription({
+        return (await writeANTFromOptions(options)).setDescription({
             description,
         }, customTagsFromOptions(options));
     },
@@ -693,7 +794,7 @@ makeCommand({
     action: async (options) => {
         const keywords = requiredStringArrayFromOptions(options, 'keywords');
         await assertConfirmationPrompt(`Are you sure you want to set the ANT keywords to ${keywords}?`, options);
-        return writeANTFromOptions(options).setKeywords({
+        return (await writeANTFromOptions(options)).setKeywords({
             keywords,
         }, customTagsFromOptions(options));
     },
@@ -709,7 +810,7 @@ makeCommand({
     action: async (options) => {
         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({
+        return (await writeANTFromOptions(options)).setLogo({
             txId,
         }, customTagsFromOptions(options));
     },
@@ -722,7 +823,7 @@ makeCommand({
     action: async (options) => {
         const name = requiredStringFromOptions(options, 'name');
         await assertConfirmationPrompt(`Are you sure you want to release the name ${name} back to the protocol?`, options);
-        return writeANTFromOptions(options).releaseName({
+        return (await writeANTFromOptions(options)).releaseName({
             name,
             arioProcessId: arioProcessIdFromOptions(options),
         }, customTagsFromOptions(options));
@@ -741,7 +842,7 @@ makeCommand({
         const targetProcess = requiredStringFromOptions(options, 'target');
         const name = requiredStringFromOptions(options, 'name');
         await assertConfirmationPrompt(`Are you sure you want to reassign the name ${name} to ANT process ${targetProcess}?`, options);
-        return writeANTFromOptions(options).reassignName({
+        return (await writeANTFromOptions(options)).reassignName({
             name,
             arioProcessId: arioProcessIdFromOptions(options),
             antProcessId: targetProcess,
@@ -761,7 +862,7 @@ makeCommand({
         const address = requiredAddressFromOptions(options);
         const name = requiredStringFromOptions(options, 'name');
         await assertConfirmationPrompt(`Are you sure you want to approve the primary name request ${name} to ${address}?`, options);
-        return writeANTFromOptions(options).approvePrimaryNameRequest({
+        return (await writeANTFromOptions(options)).approvePrimaryNameRequest({
             name,
             address,
             arioProcessId: arioProcessIdFromOptions(options),
@@ -775,7 +876,7 @@ makeCommand({
     action: async (options) => {
         const names = requiredStringArrayFromOptions(options, 'names');
         await assertConfirmationPrompt(`Are you sure you want to remove the primary names ${names}?`, options);
-        return writeANTFromOptions(options).removePrimaryNames({
+        return (await writeANTFromOptions(options)).removePrimaryNames({
             names,
             arioProcessId: arioProcessIdFromOptions(options),
         }, customTagsFromOptions(options));
@@ -811,10 +912,69 @@ makeCommand({
         });
     },
 });
-// Normalize separators so includes() works on Windows (argv uses backslashes).
-const argvScript = process.argv[1].replace(/\\/g, '/');
-if (argvScript.includes('bin/ar.io') || // Running from global .bin
-    argvScript.includes('cli/cli') // Running from source
+// =========================================
+// ANT Escrow commands (`ario-ant-escrow` program — Solana-only)
+// =========================================
+// `optionMap.rpcUrl`, `walletFile`, and `privateKey` are already in
+// `globalOptions` and are merged in by `makeCommand` for every command — re-listing
+// them here would re-register the flags and crash Commander with
+// "due to conflicting flag '--rpc-url'" at CLI startup.
+const escrowCommonOptions = [optionMap.escrowProgramId, optionMap.ant];
+makeCommand({
+    name: 'escrow-status',
+    description: 'Read the on-chain EscrowAnt PDA for an ANT mint (no signer needed).',
+    options: [optionMap.escrowProgramId, optionMap.ant],
+    action: escrowStatusCLICommand,
+});
+makeCommand({
+    name: 'escrow-deposit',
+    description: 'Lock an ANT into the trustless escrow program. Use --recipient-arweave <jwk> or --recipient-ethereum <0x...>.',
+    options: [
+        ...escrowCommonOptions,
+        optionMap.recipientArweave,
+        optionMap.recipientEthereum,
+    ],
+    action: escrowDepositCLICommand,
+});
+makeCommand({
+    name: 'escrow-cancel',
+    description: 'Pull an escrowed ANT back to the depositor. Closes the escrow PDA and refunds rent.',
+    options: escrowCommonOptions,
+    action: escrowCancelCLICommand,
+});
+makeCommand({
+    name: 'escrow-update-recipient',
+    description: 'Re-target an active escrow at a different Arweave/Ethereum identity. Rotates the on-chain nonce.',
+    options: [
+        ...escrowCommonOptions,
+        optionMap.newRecipientArweave,
+        optionMap.newRecipientEthereum,
+    ],
+    action: escrowUpdateRecipientCLICommand,
+});
+makeCommand({
+    name: 'escrow-claim-arweave',
+    description: 'Submit an Arweave RSA-PSS-4096 signature to release the ANT. Anyone can submit; only the named claimant receives.',
+    options: [
+        ...escrowCommonOptions,
+        optionMap.signatureFile,
+        optionMap.saltLen,
+        optionMap.claimant,
+    ],
+    action: escrowClaimArweaveCLICommand,
+});
+makeCommand({
+    name: 'escrow-claim-ethereum',
+    description: 'Submit an Ethereum ECDSA personal_sign signature (65 bytes r||s||v) to release the ANT.',
+    options: [
+        ...escrowCommonOptions,
+        optionMap.signatureFile,
+        optionMap.claimant,
+    ],
+    action: escrowClaimEthereumCLICommand,
+});
+if (process.argv[1].includes('bin/ar.io') || // Running from global .bin
+    process.argv[1].includes('cli/cli') // Running from source
 ) {
     program.parse(process.argv);
 }