@ar.io/sdk 3.24.0 → 4.0.0-alpha.2

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

@@ -1,106 +1,71 @@
-import { antRecordMetadataFromOptions, arioProcessIdFromOptions, assertConfirmationPrompt, booleanFromOptions, customTagsFromOptions, defaultTtlSecondsCLI, readARIOFromOptions, requiredStringFromOptions, stringArrayFromOptions, writeANTFromOptions, } from '../utils.js';
+import { antRecordMetadataFromOptions, assertConfirmationPrompt, customTagsFromOptions, defaultTtlSecondsCLI, requiredStringFromOptions, 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 writeAnt.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 writeAnt.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 writeAnt.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));
-}
-export async function upgradeAntCLICommand(o) {
-    const writeAnt = 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);
-    }
-    if (names.length === 0) {
-        throw new Error('No names to reassign');
-    }
-    if (!o.skipConfirmation) {
-        await assertConfirmationPrompt(`Upgrade all names affiliated with this ANT on ARIO process?\n` +
-            `ARIO Process ID: ${arioProcessId}\n` +
-            `ANT Process ID: ${writeAnt.processId}\n` +
-            `Names that will be reassigned (${names.length}): ${names.join(', ')}`, o);
-    }
-    const result = reassignAffiliatedNames
-        ? await writeANTFromOptions(o).upgrade({
-            reassignAffiliatedNames,
-            arioProcessId,
-        })
-        : 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] = {
-            id: failure.id,
-            error: failure.error.message,
-        };
-    }
-    return {
-        forkedProcessId: result.forkedProcessId,
-        reassignedNames: result.reassignedNames,
-        failedReassignedNames: serializedFailedReassignedNames,
-    };
+    return writeAnt.transferRecord({ undername, recipient }, customTagsFromOptions(o));
 }

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

@@ -1,22 +1,16 @@
-/**
- * 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 { 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');
@@ -42,13 +36,9 @@ export async function buyRecordCLICommand(o) {
                 fromAddress: signerAddress,
             },
         });
-        // assert spawn new ant with module id
-        let antSpawnConfirmation = '';
-        if (processId === undefined) {
-            const { moduleId, version } = await ANT.versions.getLatestANTVersion();
-            antSpawnConfirmation = `Note: A new ANT process will be spawned with module ${moduleId} (v${version}) and assigned to this name.`;
-        }
-        await assertConfirmationPrompt(`Are you sure you want to ${type} the record ${name}? ${antSpawnConfirmation}`, o);
+        await assertConfirmationPrompt(`Are you sure you want to ${type} the record ${name}?${processId === undefined
+            ? ' Note: A new ANT (MPL Core asset) will be spawned and assigned to this name.'
+            : ''}`, o);
     }
     return ario.buyRecord({
         name: requiredStringFromOptions(o, 'name'),
@@ -56,13 +46,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 +84,8 @@ export async function upgradeRecordCLICommand(o) {
     return ario.upgradeRecord({
         name,
         fundFrom,
+        gatewayAddress: o.gatewayAddress,
+        fundAsOperator: o.fundAsOperator,
         paidBy: stringArrayFromOptions(o, 'paidBy'),
         referrer,
     });
@@ -99,7 +95,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 +122,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 +134,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 +158,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 +195,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 +204,19 @@ 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.
+ *
+ * Use after a `buy-record` where the buyer 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,227 @@
+/**
+ * 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.
+ */
+/**
+ * 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, createSolanaRpcSubscriptions, } from '@solana/kit';
+import bs58 from 'bs58';
+import { ARIO_ANT_ESCROW_PROGRAM_ID } from '../../solana/constants.js';
+import { ANTEscrow } from '../../solana/escrow.js';
+import { createCircuitBreakerRpc, defaultFallbackUrl, } from '../../solana/rpc-circuit-breaker.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: createCircuitBreakerRpc({
+            primaryUrl: rpcUrl,
+            fallbackUrl: defaultFallbackUrl(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: createCircuitBreakerRpc({
+            primaryUrl: rpcUrl,
+            fallbackUrl: defaultFallbackUrl(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}`);
+    }
+    // RSA-PSS salt length: 0 is a valid value, so only reject NaN / negative /
+    // non-integer. An unset flag defaults to 32 (a full SHA-256 digest).
+    const saltLen = o.saltLen ? Number.parseInt(o.saltLen, 10) : 32;
+    if (!Number.isInteger(saltLen) || saltLen < 0) {
+        throw new Error(`--salt-len must be a non-negative integer (got '${o.saltLen}')`);
+    }
+    const escrow = await writeEscrowFromOptions(o);
+    const sig = await escrow.claimArweave({
+        antMint: antFromOptions(o),
+        claimant: address(o.claimant),
+        signature: sigBytes,
+        saltLen,
+    });
+    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 };
+}