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

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

@@ -1,74 +1,101 @@
 import { antRecordMetadataFromOptions, arioProcessIdFromOptions, assertConfirmationPrompt, booleanFromOptions, customTagsFromOptions, defaultTtlSecondsCLI, readARIOFromOptions, requiredStringFromOptions, stringArrayFromOptions, writeANTFromOptions, } from '../utils.js';
+function targetProtocolFromOptions(o) {
+    const raw = o.targetProtocol;
+    if (!raw || raw === 'arweave')
+        return 0;
+    if (raw === 'ipfs')
+        return 1;
+    throw new Error(`Invalid --target-protocol "${raw}". Must be "arweave" or "ipfs".`);
+}
 /** @deprecated -- use set-ant-base-name and set-ant-undername */
 export async function setAntRecordCLICommand(o) {
     const ttlSeconds = +(o.ttlSeconds ?? defaultTtlSecondsCLI);
     const undername = requiredStringFromOptions(o, 'undername');
     const transactionId = requiredStringFromOptions(o, 'transactionId');
-    const writeAnt = writeANTFromOptions(o);
+    const targetProtocol = targetProtocolFromOptions(o);
+    const writeAnt = await writeANTFromOptions(o);
     const recordParams = {
         undername,
         transactionId,
         ttlSeconds,
+        targetProtocol,
         ...antRecordMetadataFromOptions(o),
     };
     if (!o.skipConfirmation) {
         await assertConfirmationPrompt(`Are you sure you want to set this record on the ANT process ${writeAnt.processId}?\n${JSON.stringify(recordParams, null, 2)}`, o);
     }
-    return writeANTFromOptions(o).setRecord(recordParams, customTagsFromOptions(o));
+    return (await writeANTFromOptions(o)).setRecord(recordParams, customTagsFromOptions(o));
 }
 export async function setAntBaseNameCLICommand(o) {
     const ttlSeconds = +(o.ttlSeconds ?? defaultTtlSecondsCLI);
     const transactionId = requiredStringFromOptions(o, 'transactionId');
+    const targetProtocol = targetProtocolFromOptions(o);
     const params = {
         transactionId,
         ttlSeconds,
+        targetProtocol,
         ...antRecordMetadataFromOptions(o),
     };
-    const writeAnt = writeANTFromOptions(o);
+    const writeAnt = await writeANTFromOptions(o);
     if (!o.skipConfirmation) {
         await assertConfirmationPrompt(`Are you sure you want to set this base name on the ANT process ${writeAnt.processId}?\n${JSON.stringify(params, null, 2)}`, o);
     }
-    return writeANTFromOptions(o).setBaseNameRecord(params, customTagsFromOptions(o));
+    return (await writeANTFromOptions(o)).setBaseNameRecord(params, customTagsFromOptions(o));
 }
 export async function setAntUndernameCLICommand(o) {
     const ttlSeconds = +(o.ttlSeconds ?? defaultTtlSecondsCLI);
     const undername = requiredStringFromOptions(o, 'undername');
     const transactionId = requiredStringFromOptions(o, 'transactionId');
+    const targetProtocol = targetProtocolFromOptions(o);
     const params = {
         undername,
         transactionId,
         ttlSeconds,
+        targetProtocol,
         ...antRecordMetadataFromOptions(o),
     };
-    const writeAnt = writeANTFromOptions(o);
+    const writeAnt = await writeANTFromOptions(o);
     if (!o.skipConfirmation) {
         await assertConfirmationPrompt(`Are you sure you want to set this undername on the ANT process ${writeAnt.processId}?\n${JSON.stringify(params, null, 2)}`, o);
     }
-    return writeANTFromOptions(o).setUndernameRecord(params, customTagsFromOptions(o));
+    return (await writeANTFromOptions(o)).setUndernameRecord(params, customTagsFromOptions(o));
 }
 export async function transferRecordOwnershipCLICommand(o) {
     const undername = requiredStringFromOptions(o, 'undername');
     const recipient = requiredStringFromOptions(o, 'recipient');
-    const writeAnt = writeANTFromOptions(o);
+    const writeAnt = await writeANTFromOptions(o);
     if (!o.skipConfirmation) {
         await assertConfirmationPrompt(`Are you sure you want to transfer ownership of "${undername}" to "${recipient}" on ANT process ${writeAnt.processId}?\n${JSON.stringify({ undername, recipient }, null, 2)}`, o);
     }
-    return writeANTFromOptions(o).transferRecord({ undername, recipient }, customTagsFromOptions(o));
+    return (await writeANTFromOptions(o)).transferRecord({ undername, recipient }, customTagsFromOptions(o));
 }
 export async function upgradeAntCLICommand(o) {
-    const writeAnt = writeANTFromOptions(o);
+    // Solana: simple per-ANT schema migration (no forking, no name reassignment)
+    if (!o.ao) {
+        const writeAnt = await writeANTFromOptions(o);
+        if (!o.skipConfirmation) {
+            await assertConfirmationPrompt(`Migrate ANT to latest schema version?\n` +
+                `ANT: ${writeAnt.processId}`, o);
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const result = await writeAnt.upgrade();
+        if (!result.needsMigration) {
+            return { message: 'ANT is already at the latest version' };
+        }
+        return { message: 'ANT migrated successfully', txId: String(result.id) };
+    }
+    // AO: fork process and reassign names
+    const writeAnt = await writeANTFromOptions(o);
     const arioProcessId = arioProcessIdFromOptions(o);
     const ario = readARIOFromOptions(o);
     const reassignAffiliatedNames = booleanFromOptions(o, 'reassignAffiliatedNames');
     const names = stringArrayFromOptions(o, 'names') || [];
     if (reassignAffiliatedNames) {
-        // Fetch all ArNS records that point to this ANT process
         const allRecords = await ario.getArNSRecords({
             filters: {
                 processId: writeAnt.processId,
             },
         });
-        // Filter records that belong to this ANT
         const affiliatedNames = allRecords.items.map((record) => record.name);
         names.push(...affiliatedNames);
     }
@@ -82,15 +109,14 @@ export async function upgradeAntCLICommand(o) {
             `Names that will be reassigned (${names.length}): ${names.join(', ')}`, o);
     }
     const result = reassignAffiliatedNames
-        ? await writeANTFromOptions(o).upgrade({
+        ? await (await writeANTFromOptions(o)).upgrade({
             reassignAffiliatedNames,
             arioProcessId,
         })
-        : await writeANTFromOptions(o).upgrade({
+        : await (await writeANTFromOptions(o)).upgrade({
             names,
             arioProcessId,
         });
-    // Serialize error objects for JSON compatibility
     const serializedFailedReassignedNames = {};
     for (const [name, failure] of Object.entries(result.failedReassignedNames)) {
         serializedFailedReassignedNames[name] = {

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

@@ -14,9 +14,19 @@
  * limitations under the License.
  */
 import { ANT } from '../../common/ant.js';
-import { assertConfirmationPrompt, assertEnoughBalanceForArNSPurchase, customTagsFromOptions, fundFromFromOptions, positiveIntegerFromOptions, recordTypeFromOptions, referrerFromOptions, requiredPositiveIntegerFromOptions, requiredStringFromOptions, stringArrayFromOptions, writeARIOFromOptions, } from '../utils.js';
+import { assertConfirmationPrompt, assertEnoughBalanceForArNSPurchase, customTagsFromOptions, fundFromFromOptions, fundingPlanFromOptions, positiveIntegerFromOptions, recordTypeFromOptions, referrerFromOptions, requiredPositiveIntegerFromOptions, requiredStringFromOptions, stringArrayFromOptions, withdrawalIdFromOptions, writeARIOFromOptions, } from '../utils.js';
+/** Coerce the JSON-parsed funding plan to the typed `FundingSourceSpec[]`. */
+function coerceFundingPlanSources(parsed) {
+    if (!parsed)
+        return undefined;
+    return parsed.map((s) => ({
+        kind: s.kind,
+        amount: s.amount,
+        ...(s.gateway ? { gateway: s.gateway } : {}),
+    }));
+}
 export async function buyRecordCLICommand(o) {
-    const { ario, signerAddress } = writeARIOFromOptions(o);
+    const { ario, signerAddress } = await writeARIOFromOptions(o);
     const name = requiredStringFromOptions(o, 'name');
     const type = recordTypeFromOptions(o);
     const years = positiveIntegerFromOptions(o, 'years');
@@ -56,13 +66,17 @@ export async function buyRecordCLICommand(o) {
         type,
         years,
         fundFrom: fundFromFromOptions(o),
+        gatewayAddress: o.gatewayAddress,
+        fundAsOperator: o.fundAsOperator,
+        withdrawalId: withdrawalIdFromOptions(o),
+        sources: coerceFundingPlanSources(fundingPlanFromOptions(o)),
         paidBy: stringArrayFromOptions(o, 'paidBy'),
         referrer,
     }, customTagsFromOptions(o));
 }
 export async function upgradeRecordCLICommand(o) {
     const name = requiredStringFromOptions(o, 'name');
-    const { ario, signerAddress } = writeARIOFromOptions(o);
+    const { ario, signerAddress } = await writeARIOFromOptions(o);
     const fundFrom = fundFromFromOptions(o);
     const referrer = referrerFromOptions(o);
     if (!o.skipConfirmation) {
@@ -90,6 +104,8 @@ export async function upgradeRecordCLICommand(o) {
     return ario.upgradeRecord({
         name,
         fundFrom,
+        gatewayAddress: o.gatewayAddress,
+        fundAsOperator: o.fundAsOperator,
         paidBy: stringArrayFromOptions(o, 'paidBy'),
         referrer,
     });
@@ -99,7 +115,7 @@ export async function extendLeaseCLICommand(o) {
     const years = requiredPositiveIntegerFromOptions(o, 'years');
     const fundFrom = fundFromFromOptions(o);
     const referrer = referrerFromOptions(o);
-    const { ario, signerAddress } = writeARIOFromOptions(o);
+    const { ario, signerAddress } = await writeARIOFromOptions(o);
     if (!o.skipConfirmation) {
         const existingRecord = await ario.getArNSRecord({
             name,
@@ -126,6 +142,9 @@ export async function extendLeaseCLICommand(o) {
     return ario.extendLease({
         name,
         years,
+        fundFrom,
+        gatewayAddress: o.gatewayAddress,
+        fundAsOperator: o.fundAsOperator,
         paidBy: stringArrayFromOptions(o, 'paidBy'),
         referrer,
     }, customTagsFromOptions(o));
@@ -135,7 +154,7 @@ export async function increaseUndernameLimitCLICommand(o) {
     const increaseCount = requiredPositiveIntegerFromOptions(o, 'increaseCount');
     const fundFrom = fundFromFromOptions(o);
     const referrer = referrerFromOptions(o);
-    const { ario, signerAddress } = writeARIOFromOptions(o);
+    const { ario, signerAddress } = await writeARIOFromOptions(o);
     if (!o.skipConfirmation) {
         const existingRecord = await ario.getArNSRecord({
             name,
@@ -159,12 +178,15 @@ export async function increaseUndernameLimitCLICommand(o) {
     return ario.increaseUndernameLimit({
         name,
         increaseCount,
+        fundFrom,
+        gatewayAddress: o.gatewayAddress,
+        fundAsOperator: o.fundAsOperator,
         paidBy: stringArrayFromOptions(o, 'paidBy'),
         referrer,
     }, customTagsFromOptions(o));
 }
 export async function requestPrimaryNameCLICommand(o) {
-    const { ario, signerAddress } = writeARIOFromOptions(o);
+    const { ario, signerAddress } = await writeARIOFromOptions(o);
     const fundFrom = fundFromFromOptions(o);
     const referrer = referrerFromOptions(o);
     const name = requiredStringFromOptions(o, 'name');
@@ -193,7 +215,7 @@ export async function requestPrimaryNameCLICommand(o) {
     return result.request;
 }
 export async function setPrimaryNameCLICommand(o) {
-    const { ario, signerAddress } = writeARIOFromOptions(o);
+    const { ario, signerAddress } = await writeARIOFromOptions(o);
     const name = requiredStringFromOptions(o, 'name');
     const fundFrom = fundFromFromOptions(o);
     const referrer = referrerFromOptions(o);
@@ -202,3 +224,20 @@ export async function setPrimaryNameCLICommand(o) {
     }
     return ario.setPrimaryName({ name, fundFrom, referrer });
 }
+/**
+ * Reconcile the on-chain ANT Attributes plugin (`ArNS Name`, `Type`,
+ * `Undername Limit`) with the current `ArnsRecord` state. Permissionless,
+ * Solana-only; AO backend will throw with a clear error.
+ *
+ * Use after a `buy-record` / `reassign-name` where the buyer/recipient was
+ * not the ANT NFT holder (the ANT-side trait CPI gets skipped at runtime
+ * in that case so the plugin stays empty until the actual holder reconciles).
+ */
+export async function syncAttributesCLICommand(o) {
+    const name = requiredStringFromOptions(o, 'name');
+    const { ario } = await writeARIOFromOptions(o);
+    if (!o.skipConfirmation) {
+        await assertConfirmationPrompt(`Sync on-chain ANT traits for "${name}" to match the current ArnsRecord?`, o);
+    }
+    return ario.syncAttributes({ name });
+}

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

@@ -0,0 +1,208 @@
+/**
+ * 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
+ */
+/**
+ * CLI commands for `ario-ant-escrow` — trustless multi-protocol ANT custody.
+ *
+ * Each command instantiates an {@link ANTEscrow} with options-driven RPC +
+ * signer wiring (mirrors the rest of the Solana CLI surface — see
+ * `arnsPurchaseCommands.ts`). All read commands work without a signer; all
+ * write commands require `--wallet-file` or `--private-key`.
+ *
+ * Recipient pubkey loading:
+ * - Arweave: `--recipient-arweave <jwk-file>` reads the JWK JSON, decodes
+ *   the base64url `n` field to 512 raw bytes (RSA-4096 modulus).
+ * - Ethereum: `--recipient-ethereum 0x...` parses the 20-byte hex address.
+ */
+import { readFileSync } from 'node:fs';
+import { address, createKeyPairSignerFromBytes, createSolanaRpc, createSolanaRpcSubscriptions, } from '@solana/kit';
+import bs58 from 'bs58';
+import { ARIO_ANT_ESCROW_PROGRAM_ID } from '../../solana/constants.js';
+import { ANTEscrow } from '../../solana/escrow.js';
+// =========================================
+// Wiring helpers
+// =========================================
+function wsUrlFromRpcUrl(rpcUrl) {
+    return rpcUrl.replace(/^http/, 'ws');
+}
+function escrowProgramIdFrom(options) {
+    return options.escrowProgramId
+        ? address(options.escrowProgramId)
+        : ARIO_ANT_ESCROW_PROGRAM_ID;
+}
+async function readEscrowReader(options) {
+    const rpcUrl = options.rpcUrl ?? 'https://api.mainnet-beta.solana.com';
+    return ANTEscrow.init({
+        rpc: createSolanaRpc(rpcUrl),
+        programId: escrowProgramIdFrom(options),
+    });
+}
+async function writeEscrowFromOptions(options) {
+    let secretKey;
+    if (options.privateKey) {
+        secretKey = bs58.decode(options.privateKey);
+    }
+    else if (options.walletFile) {
+        const raw = readFileSync(options.walletFile, 'utf-8');
+        secretKey = new Uint8Array(JSON.parse(raw));
+    }
+    else {
+        throw new Error('escrow write operations require a signer. Provide --wallet-file <path> or --private-key <base58>');
+    }
+    const signer = await createKeyPairSignerFromBytes(secretKey);
+    const rpcUrl = options.rpcUrl ?? 'https://api.mainnet-beta.solana.com';
+    return ANTEscrow.init({
+        rpc: createSolanaRpc(rpcUrl),
+        rpcSubscriptions: createSolanaRpcSubscriptions(wsUrlFromRpcUrl(rpcUrl)),
+        signer,
+        programId: escrowProgramIdFrom(options),
+    });
+}
+// =========================================
+// Recipient pubkey parsing
+// =========================================
+function base64UrlDecode(s) {
+    // Convert base64url → base64, then decode.
+    let b64 = s.replace(/-/g, '+').replace(/_/g, '/');
+    while (b64.length % 4 !== 0)
+        b64 += '=';
+    return new Uint8Array(Buffer.from(b64, 'base64'));
+}
+/** Load an Arweave RSA-4096 modulus from a JWK file (`.json` with `n` field). */
+function loadArweaveModulusFromJwk(filePath) {
+    const raw = readFileSync(filePath, 'utf-8');
+    const jwk = JSON.parse(raw);
+    if (jwk.kty !== 'RSA' || !jwk.n) {
+        throw new Error(`Not a valid Arweave RSA JWK (missing kty=RSA or n field)`);
+    }
+    const modulus = base64UrlDecode(jwk.n);
+    if (modulus.length !== 512) {
+        throw new Error(`Arweave modulus must be 512 bytes (4096-bit RSA); got ${modulus.length}`);
+    }
+    return modulus;
+}
+/** Parse an Ethereum address (`0xabc...`) into 20 raw bytes. */
+function parseEthereumAddress(hex) {
+    const cleaned = hex.startsWith('0x') ? hex.slice(2) : hex;
+    if (cleaned.length !== 40 || !/^[0-9a-fA-F]+$/.test(cleaned)) {
+        throw new Error(`Ethereum address must be 0x-prefixed 40-char hex; got "${hex}"`);
+    }
+    return Uint8Array.from(Buffer.from(cleaned, 'hex'));
+}
+function recipientFromDepositOptions(o) {
+    if (o.recipientArweave && o.recipientEthereum) {
+        throw new Error('--recipient-arweave and --recipient-ethereum are mutually exclusive');
+    }
+    if (o.recipientArweave) {
+        return {
+            protocol: 'arweave',
+            publicKey: loadArweaveModulusFromJwk(o.recipientArweave),
+        };
+    }
+    if (o.recipientEthereum) {
+        return {
+            protocol: 'ethereum',
+            publicKey: parseEthereumAddress(o.recipientEthereum),
+        };
+    }
+    throw new Error('one of --recipient-arweave or --recipient-ethereum is required');
+}
+function recipientFromUpdateOptions(o) {
+    return recipientFromDepositOptions({
+        recipientArweave: o.newRecipientArweave,
+        recipientEthereum: o.newRecipientEthereum,
+    });
+}
+function antFromOptions(o) {
+    if (!o.ant)
+        throw new Error('--ant <mint> is required');
+    return address(o.ant);
+}
+// =========================================
+// CLI handlers
+// =========================================
+/** `ar.io escrow status --ant <mint>` */
+export async function escrowStatusCLICommand(o) {
+    const escrow = await readEscrowReader(o);
+    const ant = antFromOptions(o);
+    const state = await escrow.get(ant);
+    if (!state) {
+        return { active: false, antMint: ant };
+    }
+    return {
+        active: true,
+        antMint: state.antMint,
+        depositor: state.depositor,
+        recipientProtocol: state.recipientProtocol,
+        recipientPubkeyHex: Buffer.from(state.recipientPubkey).toString('hex'),
+        nonceHex: Buffer.from(state.nonce).toString('hex'),
+        depositSlot: state.depositSlot.toString(),
+        version: state.version,
+    };
+}
+/** `ar.io escrow deposit --ant <mint> --recipient-{arweave|ethereum} ...` */
+export async function escrowDepositCLICommand(o) {
+    const recipient = recipientFromDepositOptions(o);
+    const escrow = await writeEscrowFromOptions(o);
+    const sig = await escrow.deposit({ antMint: antFromOptions(o), recipient });
+    return { signature: sig };
+}
+/** `ar.io escrow cancel --ant <mint>` */
+export async function escrowCancelCLICommand(o) {
+    const escrow = await writeEscrowFromOptions(o);
+    const sig = await escrow.cancel({ antMint: antFromOptions(o) });
+    return { signature: sig };
+}
+/** `ar.io escrow update-recipient --ant <mint> --new-recipient-{arweave|ethereum} ...` */
+export async function escrowUpdateRecipientCLICommand(o) {
+    const newRecipient = recipientFromUpdateOptions(o);
+    const escrow = await writeEscrowFromOptions(o);
+    const sig = await escrow.updateRecipient({
+        antMint: antFromOptions(o),
+        newRecipient,
+    });
+    return { signature: sig };
+}
+/** `ar.io escrow claim-arweave --ant <mint> --signature-file <bin> --claimant <pubkey> [--salt-len 32]` */
+export async function escrowClaimArweaveCLICommand(o) {
+    if (!o.signatureFile)
+        throw new Error('--signature-file <path> is required');
+    if (!o.claimant)
+        throw new Error('--claimant <pubkey> is required');
+    const sigBytes = new Uint8Array(readFileSync(o.signatureFile));
+    if (sigBytes.length !== 512) {
+        throw new Error(`signature file must be 512 bytes; got ${sigBytes.length}`);
+    }
+    const escrow = await writeEscrowFromOptions(o);
+    const sig = await escrow.claimArweave({
+        antMint: antFromOptions(o),
+        claimant: address(o.claimant),
+        signature: sigBytes,
+        saltLen: o.saltLen ? Number(o.saltLen) : 32,
+    });
+    return { signature: sig };
+}
+/** `ar.io escrow claim-ethereum --ant <mint> --signature-file <bin> --claimant <pubkey>` */
+export async function escrowClaimEthereumCLICommand(o) {
+    if (!o.signatureFile)
+        throw new Error('--signature-file <path> is required');
+    if (!o.claimant)
+        throw new Error('--claimant <pubkey> is required');
+    const sigBytes = new Uint8Array(readFileSync(o.signatureFile));
+    if (sigBytes.length !== 65) {
+        throw new Error(`signature file must be 65 bytes (r||s||v); got ${sigBytes.length}`);
+    }
+    const escrow = await writeEscrowFromOptions(o);
+    const sig = await escrow.claimEthereum({
+        antMint: antFromOptions(o),
+        claimant: address(o.claimant),
+        signature: sigBytes,
+    });
+    return { signature: sig };
+}