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

package/lib/esm/solana/spawn-ant.js

@@ -0,0 +1,224 @@
+/**
+ * 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.
+ */
+/**
+ * Solana implementation of `ANT.spawn`.
+ *
+ * Mints a fresh Metaplex Core asset (the ANT NFT) AND initializes the
+ * `ario-ant` extended state PDAs (`AntConfig`, `AntControllers`, root `@`
+ * record) in a single atomic transaction.
+ *
+ * This is the Solana counterpart to the legacy AO `spawnANT` flow:
+ * - AO: `ao.spawn({ module, scheduler, ... })` → returns AO process id.
+ * - Solana: mint MPL Core asset + initialize ario-ant PDAs → returns the
+ *   asset's pubkey (which serves as the SDK's stable `processId`).
+ *
+ * For the bulk-import flow used by `migration/import` we use a separate
+ * code path that mints to the migration authority and uses the gated
+ * `import_account` instruction — that's intentional and not what this SDK
+ * helper is for.
+ */
+import { addSignersToTransactionMessage, appendTransactionMessageInstructions, createTransactionMessage, generateKeyPairSigner, getSignatureFromTransaction, pipe, sendAndConfirmTransactionFactory, setTransactionMessageFeePayerSigner, setTransactionMessageLifetimeUsingBlockhash, signTransactionMessageWithSigners, } from '@solana/kit';
+import { getInitializeInstructionAsync } from '@ar.io/solana-contracts/ant';
+import { DataState, getCreateV1Instruction, } from '@ar.io/solana-contracts/mpl-core';
+import { getSetComputeUnitLimitInstruction, getSetComputeUnitPriceInstruction, } from '@solana-program/compute-budget';
+import { SolanaANTRegistryWriteable } from './ant-registry-writeable.js';
+import { ARIO_ANT_PROGRAM_ID } from './constants.js';
+import { getAntRecordPDA } from './pda.js';
+/** AR.IO logo Arweave TX — matches the Rust default in `ario_ant::initialize`. */
+export const ARIO_LOGO_TX_ID = 'AnYvLJTWcG9lr2Ll5MwYWZR2o5uTE39WbpYB0zCxwKM';
+/**
+ * Default Arweave transaction id used when an ANT is spawned without an
+ * explicit `transactionId`. Empty string would fail the on-chain
+ * `is_valid_arweave_id` check, so we fall back to the AR.IO logo TX (which is
+ * a real Arweave id and won't trip validation).
+ */
+export const DEFAULT_ANT_TRANSACTION_ID = ARIO_LOGO_TX_ID;
+/**
+ * Public, low-level builder for the `CreateV1` MPL Core instruction with the
+ * AR.IO-standard ANT shape (Attributes plugin pre-installed, Owner authority).
+ *
+ * Delegates to the Codama-generated `getCreateV1Instruction`, but accepts
+ * plain `Address`es (rather than full `TransactionSigner`s) so test fixtures
+ * and devnet validation scripts can byte-pin the wire format without
+ * standing up real keypairs. The signer roles still flow through correctly
+ * because we re-cast under `unknown`.
+ *
+ * Most callers should use `ANT.spawn` / `spawnSolanaANT` instead — that path
+ * also wires up `ario_ant::initialize` so the ANT is fully usable end to end.
+ * Use this raw builder when you need fine-grained control over signing, or
+ * are bundling the mint into a larger compound transaction.
+ *
+ * **Why we always emit an Attributes plugin (even with an empty list):**
+ * `ario_arns::buy_record` and friends CPI into `UpdatePluginV1` to populate
+ * traits at purchase time. If the asset has no Attributes plugin, that CPI
+ * fails. Emitting an empty plugin here keeps every spawned ANT
+ * `purchase`-ready and matches what `migration/import` mints — see ADR-012
+ * and BD-096. Authority is `Owner` so the ANT NFT holder (= asset owner)
+ * can sign their own trait updates.
+ */
+export function buildCreateAntInstruction({ mint, authority, payer, name, uri, attributes = [], }) {
+    // Codama wants TransactionSigners for asset/authority/payer because the
+    // resulting account meta is marked SIGNER. The byte-pinning surface we're
+    // exposing only cares about pubkeys + wire bytes, so we adapt by feeding
+    // it minimal signer-shaped objects.
+    const asSigner = (a) => ({ address: a, signTransactions: () => Promise.resolve([]) });
+    return getCreateV1Instruction({
+        asset: asSigner(mint),
+        authority: asSigner(authority),
+        payer: asSigner(payer),
+        dataState: DataState.AccountState,
+        name,
+        uri,
+        plugins: [
+            {
+                plugin: {
+                    __kind: 'Attributes',
+                    fields: [{ attributeList: attributes }],
+                },
+                authority: { __kind: 'Owner' },
+            },
+        ],
+    });
+}
+/**
+ * Build the `ario_ant::initialize` instruction for a freshly minted asset.
+ */
+async function buildInitializeAntIx({ programId, mint, signer, state, }) {
+    // Codama auto-resolves antConfig + antControllers PDAs. rootRecord uses a
+    // hashed-undername seed Codama can't infer from args, so we derive it here.
+    const [rootRecordPda] = await getAntRecordPDA(mint, '@', programId);
+    return getInitializeInstructionAsync({
+        asset: mint,
+        rootRecord: rootRecordPda,
+        owner: signer,
+        name: state.name,
+        ticker: state.ticker ?? null,
+        target: state.transactionId ?? DEFAULT_ANT_TRANSACTION_ID,
+        targetProtocol: state.targetProtocol ?? null,
+        logo: state.logo ?? '',
+        description: state.description ?? '',
+        keywords: state.keywords ?? [],
+    }, { programAddress: programId });
+}
+/**
+ * Spawn a brand-new ANT on Solana. Returns the asset address, which is the
+ * SDK's stable `processId` for that ANT.
+ */
+export async function spawnSolanaANT(params) {
+    if (!params.state?.name || params.state.name.length === 0) {
+        throw new Error('spawnSolanaANT: state.name is required');
+    }
+    const { rpc, rpcSubscriptions, signer, state, antProgramId = ARIO_ANT_PROGRAM_ID, commitment = 'confirmed', computeUnitLimit = 400_000, } = params;
+    const mintSigner = params.mintSigner ?? (await generateKeyPairSigner());
+    const owner = signer.address;
+    const mint = mintSigner.address;
+    const uri = state.uri ??
+        `ar://${state.logo && state.logo.length > 0 ? state.logo : ARIO_LOGO_TX_ID}`;
+    // Emit the Attributes plugin (Owner authority) at mint time with the
+    // asset-side `ANT Program` entry pre-installed. Two reasons to always
+    // include it:
+    //
+    //   1. ADR-016 / BD-100 — the program managing this asset's per-mint
+    //      state PDAs is named on the asset itself. Writing it here means
+    //      every fresh ANT carries an explicit, queryable program id from
+    //      the moment it's minted; resolvers can read it without a lookup
+    //      against any external registry.
+    //   2. The Attributes plugin must already exist before
+    //      `ario_arns::buy_name` CPIs into `UpdatePluginV1` to populate
+    //      ARNS Name / Type / Undername Limit. Skipping this returns
+    //      MPL Core 0x4 ("Plugin not found") at ArNS purchase time.
+    //
+    // Default value is the canonical `ARIO_ANT_PROGRAM_ID`; passing
+    // `antProgramId` opts into the BYO-ANT (third-party) path.
+    const createIx = getCreateV1Instruction({
+        asset: mintSigner,
+        payer: signer,
+        authority: signer,
+        dataState: DataState.AccountState,
+        name: state.name,
+        uri,
+        plugins: [
+            {
+                plugin: {
+                    __kind: 'Attributes',
+                    fields: [
+                        {
+                            attributeList: [
+                                { key: 'ANT Program', value: antProgramId },
+                            ],
+                        },
+                    ],
+                },
+                authority: { __kind: 'Owner' },
+            },
+        ],
+    });
+    const initIx = await buildInitializeAntIx({
+        programId: antProgramId,
+        mint,
+        signer,
+        state,
+    });
+    // ADR-012 (ACL): bootstrap the new owner's paginated ACL. The
+    // contract's `initialize` handler seeds `ant_controllers = vec![owner]`
+    // (matches the Lua source), so the owner needs entries under both
+    // `Owner` (for "ANTs I own" lookups) and `Controller` (for "ANTs I
+    // can manage" lookups). Bundling here keeps the ACL atomic with the
+    // spawn — by the time the tx confirms, frontends can resolve the
+    // owner's ANT list via the head config + paged accounts.
+    const registry = new SolanaANTRegistryWriteable({
+        rpc,
+        signer,
+        commitment,
+        antProgramId,
+    });
+    const aclIxs = await registry.bootstrapOwnerOnSpawn({
+        owner,
+        asset: mint,
+    });
+    // The create instruction has two signers (mint + authority+payer). Kit picks
+    // them up from the account metadata roles: accounts marked as SIGNER roles
+    // must have a matching `TransactionSigner` attached. We do that by placing
+    // the mint signer on the message alongside the fee payer signer.
+    const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();
+    const message = pipe(createTransactionMessage({ version: 0 }), (tx) => setTransactionMessageFeePayerSigner(signer, tx), (tx) => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, tx), (tx) => appendTransactionMessageInstructions([
+        getSetComputeUnitLimitInstruction({ units: computeUnitLimit }),
+        // Pin the priority fee (at 0) so wallets like Phantom don't
+        // silently append their own compute-budget instructions and
+        // invalidate the paired mint keypair signer's signature. See
+        // `sendAndConfirm` in `./send.js` for the full rationale.
+        getSetComputeUnitPriceInstruction({ microLamports: 0n }),
+        createIx,
+        initIx,
+        ...aclIxs,
+    ], tx));
+    // Attach the mint signer so kit can satisfy the WRITABLE_SIGNER role on the
+    // mint account. `addSignersToTransactionMessage` walks the message's account
+    // metas and registers each matching signer by address, which is what
+    // `signTransactionMessageWithSigners` then looks up to produce signatures.
+    const withMintSigner = addSignersToTransactionMessage([mintSigner], message);
+    const signedTx = await signTransactionMessageWithSigners(withMintSigner);
+    const sendAndConfirmFactory = sendAndConfirmTransactionFactory({
+        rpc,
+        rpcSubscriptions,
+    });
+    await sendAndConfirmFactory(signedTx, { commitment });
+    return {
+        processId: mint,
+        mint,
+        signature: getSignatureFromTransaction(signedTx),
+    };
+}

package/lib/esm/solana/types.js

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

package/lib/esm/types/ant.js

@@ -34,8 +34,8 @@ export const ArweaveTxIdSchema = z
     .refine((val) => ARWEAVE_TX_REGEX.test(val), {
     message: 'Must be an Arweave Transaction ID',
 });
-export const AOAddressSchema = z.string({
-    description: 'AO Address',
+export const WalletAddressSchema = z.string({
+    description: 'Wallet address (Solana base58 pubkey)',
 });
 export const IntegerStringSchema = z
     .string({
@@ -45,13 +45,25 @@ export const IntegerStringSchema = z
     const num = parseInt(val);
     return Number.isInteger(num) && num >= 0;
 }, { message: 'Must be a non negative integer string' });
-export const AntDescriptionSchema = z.string(); // TODO: add specific limits for description ie max length
-export const AntKeywordsSchema = z.array(z.string()); // TODO: add specific limits for keywords ie max amount and max length
+export const AntDescriptionSchema = z.string().max(256, {
+    message: 'ANT description must be at most 256 characters',
+});
+export const AntKeywordsSchema = z
+    .array(z.string().max(32, {
+    message: 'Each keyword must be at most 32 characters',
+}))
+    .max(8, { message: 'ANT can have at most 8 keywords' });
 export const AntRecordSchema = z.object({
-    transactionId: ArweaveTxIdSchema.describe('The Target ID of the undername'),
+    transactionId: z
+        .string()
+        .describe('Content target (Arweave TX ID, IPFS CID, etc.)'),
     ttlSeconds: z.number(),
+    targetProtocol: z
+        .number()
+        .describe('Storage protocol: 0 = Arweave, 1 = IPFS')
+        .default(0),
     priority: z.number().optional(),
-    owner: AOAddressSchema.describe('The owner address of the record').optional(),
+    owner: WalletAddressSchema.describe('The owner address of the record').optional(),
     displayName: z
         .string()
         .max(61)
@@ -60,18 +72,18 @@ export const AntRecordSchema = z.object({
     logo: ArweaveTxIdSchema.describe('Logo transaction ID for the record').optional(),
     description: z
         .string()
-        .max(512)
-        .describe('Description of the record (max 512 chars)')
+        .max(256)
+        .describe('Description of the record (max 256 chars)')
         .optional(),
     keywords: z
         .array(z.string().max(32))
-        .max(16)
-        .describe('Keywords array (max 16, each max 32 chars)')
+        .max(8)
+        .describe('Keywords array (max 8, each max 32 chars)')
         .optional(),
 });
 export const AntRecordsSchema = z.record(z.string(), AntRecordSchema);
-export const AntControllersSchema = z.array(AOAddressSchema.describe('Controller address'));
-export const AntBalancesSchema = z.record(AOAddressSchema.describe('Holder address'), z.number());
+export const AntControllersSchema = z.array(WalletAddressSchema.describe('Controller address'));
+export const AntBalancesSchema = z.record(WalletAddressSchema.describe('Holder address'), z.number());
 export const AntStateSchema = z.object({
     Name: z.string().describe('The name of the ANT.'),
     Ticker: z.string().describe('The ticker symbol for the ANT.'),
@@ -81,7 +93,7 @@ export const AntStateSchema = z.object({
         .number()
         .describe('The number of decimal places to use for the ANT. Defaults to 0 if not set representing whole numbers.')
         .min(0, { message: 'Denomination must be a non-negative number' }),
-    Owner: AOAddressSchema.describe('The Owners address.'),
+    Owner: WalletAddressSchema.describe('The Owners address.'),
     Controllers: AntControllersSchema.describe('Controllers of the ANT who have administrative privileges.'),
     Records: AntRecordsSchema.describe('Records associated with the ANT.'),
     Balances: AntBalancesSchema.describe('Balance details for each address holding the ANT.'),
@@ -99,7 +111,7 @@ export const SpawnANTStateSchema = z.object({
     ticker: z.string().describe('The ticker symbol for the ANT.'),
     description: z.string().describe('The description for the ANT.'),
     keywords: AntKeywordsSchema.describe('The keywords for the ANT.'),
-    owner: AOAddressSchema.describe('The Owners address.'),
+    owner: WalletAddressSchema.describe('The Owners address.'),
     controllers: AntControllersSchema.describe('Controllers of the ANT who have administrative privileges.'),
     records: AntRecordsSchema.describe('Records associated with the ANT.'),
     balances: AntBalancesSchema.describe('Balance details for each address holding the ANT.'),
@@ -159,6 +171,6 @@ export const AntInfoSchema = z.object({
  * @param state {object}
  * @returns {boolean}
  */
-export function isAoANTState(state) {
+export function isANTState(state) {
     return AntStateSchema.safeParse(state).success;
 }

package/lib/esm/types/io.js

@@ -1,4 +1,3 @@
-import { validateArweaveId } from '../utils/arweave.js';
 export const isDistributedEpochData = (data) => {
     return data.distributedTimestamp !== undefined;
 };
@@ -22,20 +21,18 @@ export const intentsUsingYears = [
 export const isValidIntent = (intent) => {
     return validIntents.indexOf(intent) !== -1;
 };
-export const fundFromOptions = ['balance', 'stakes', 'any', 'turbo'];
+export const fundFromOptions = [
+    'balance',
+    'stakes',
+    'withdrawal',
+    'plan',
+    'any',
+    'turbo',
+];
 export const isValidFundFrom = (fundFrom) => {
     return fundFromOptions.indexOf(fundFrom) !== -1;
 };
 // Type-guard functions
-export function isProcessConfiguration(config) {
-    return config !== undefined && 'process' in config;
-}
-export function isProcessIdConfiguration(config) {
-    return (config !== undefined &&
-        'processId' in config &&
-        typeof config.processId === 'string' &&
-        validateArweaveId(config.processId) === true);
-}
 export function isLeasedArNSRecord(record) {
     return record.type === 'lease';
 }

package/lib/esm/utils/ant.js

@@ -37,66 +37,3 @@ export const sortANTRecords = (antRecords) => {
     // now that they are sorted, add the index to each record - this is their position in the sorted list and is used to enforce undername limits
     return Object.fromEntries(sortedEntries.map(([a, aRecord], index) => [a, { ...aRecord, index }]));
 };
-/**
- * @deprecated - this is no longer necessary because HyperBeam now uses the AoANTState type
- */
-export const isHyperBeamANTState = (state) => {
-    return ('name' in state &&
-        'ticker' in state &&
-        'description' in state &&
-        'keywords' in state &&
-        'denomination' in state &&
-        'owner' in state &&
-        'controllers' in state &&
-        'records' in state &&
-        'balances' in state &&
-        'logo' in state &&
-        'totalsupply' in state &&
-        'initialized' in state);
-};
-/**
- * Convert HyperBeam serialized ANT state to backwards compatible format.
- *
- * @deprecated - this is no longer necessary because HyperBeam now uses the AOANTState type
- * @param state - The HyperBeam serialized ANT state.
- */
-export const convertHyperBeamStateToAoANTState = (initialState) => {
-    function lowerCaseKeys(obj) {
-        return Object.fromEntries(Object.entries(obj).map(([key, value]) => {
-            if (key.toLowerCase().includes('balances')) {
-                return [key.toLowerCase(), value];
-            }
-            if (typeof value === 'object' &&
-                !Array.isArray(value) &&
-                value !== null) {
-                return [key.toLowerCase(), lowerCaseKeys(value)];
-            }
-            return [key.toLowerCase(), value];
-        }));
-    }
-    // we need to ensure keys are lower cased because hyperbeam json serializes keys to lowercase inconsistently
-    const state = lowerCaseKeys(initialState);
-    return {
-        Name: state.name,
-        Ticker: state.ticker,
-        Description: state.description,
-        Keywords: state.keywords,
-        Denomination: parseInt(state.denomination),
-        Owner: state.owner,
-        Controllers: state.controllers,
-        Records: Object.entries(state.records).reduce((acc, [key, record]) => {
-            acc[key] = {
-                transactionId: record.transactionid,
-                ttlSeconds: record.ttlseconds,
-                ...(record.priority !== undefined
-                    ? { priority: record.priority }
-                    : {}),
-            };
-            return acc;
-        }, {}),
-        Balances: state.balances,
-        Logo: state.logo,
-        TotalSupply: state.totalsupply || 1,
-        Initialized: state.initialized,
-    };
-};

package/lib/esm/utils/index.js

@@ -13,10 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-export * from './ao.js';
-export * from './arweave.js';
 export * from './base64.js';
 export * from './json.js';
-export * from './processes.js';
 export * from './schema.js';
 export * from './ant.js';

package/lib/esm/version.js

@@ -14,4 +14,4 @@
  * limitations under the License.
  */
 // AUTOMATICALLY GENERATED FILE - DO NOT TOUCH
-export const version = '3.24.0';
+export const version = '4.0.0-alpha.2';

package/lib/types/cli/commands/antCommands.d.ts

@@ -13,21 +13,13 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { AoANTSetBaseNameRecordParams, AoANTSetUndernameRecordParams } from '../../types/ant.js';
+import { ANTSetBaseNameRecordParams, ANTSetUndernameRecordParams } from '../../types/ant.js';
 import { CLIWriteOptionsFromAoAntParams } from '../types.js';
 /** @deprecated -- use set-ant-base-name and set-ant-undername */
-export declare function setAntRecordCLICommand(o: CLIWriteOptionsFromAoAntParams<AoANTSetUndernameRecordParams>): Promise<import("../../types/common.js").AoMessageResult<Record<string, string | number | boolean | null>>>;
-export declare function setAntBaseNameCLICommand(o: CLIWriteOptionsFromAoAntParams<AoANTSetBaseNameRecordParams>): Promise<import("../../types/common.js").AoMessageResult<Record<string, string | number | boolean | null>>>;
-export declare function setAntUndernameCLICommand(o: CLIWriteOptionsFromAoAntParams<AoANTSetUndernameRecordParams>): Promise<import("../../types/common.js").AoMessageResult<Record<string, string | number | boolean | null>>>;
+export declare function setAntRecordCLICommand(o: CLIWriteOptionsFromAoAntParams<ANTSetUndernameRecordParams>): Promise<import("../../types/common.js").MessageResult<Record<string, string | number | boolean | null>>>;
+export declare function setAntBaseNameCLICommand(o: CLIWriteOptionsFromAoAntParams<ANTSetBaseNameRecordParams>): Promise<import("../../types/common.js").MessageResult<Record<string, string | number | boolean | null>>>;
+export declare function setAntUndernameCLICommand(o: CLIWriteOptionsFromAoAntParams<ANTSetUndernameRecordParams>): Promise<import("../../types/common.js").MessageResult<Record<string, string | number | boolean | null>>>;
 export declare function transferRecordOwnershipCLICommand(o: CLIWriteOptionsFromAoAntParams<{
     undername: string;
     recipient: string;
-}>): Promise<import("../../types/common.js").AoMessageResult<Record<string, string | number | boolean | null>>>;
-export declare function upgradeAntCLICommand(o: CLIWriteOptionsFromAoAntParams<Record<string, unknown>>): Promise<{
-    forkedProcessId: string;
-    reassignedNames: Record<string, import("../../types/common.js").AoMessageResult>;
-    failedReassignedNames: Record<string, {
-        id?: string;
-        error: string;
-    }>;
-}>;
+}>): Promise<import("../../types/common.js").MessageResult<Record<string, string | number | boolean | null>>>;

package/lib/types/cli/commands/arnsPurchaseCommands.d.ts

@@ -1,10 +1,36 @@
-import { AoArNSPurchaseParams, AoBuyRecordParams, AoExtendLeaseParams, AoIncreaseUndernameLimitParams } from '../../types/io.js';
+/**
+ * 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 { ArNSPurchaseParams, BuyRecordParams, ExtendLeaseParams, IncreaseUndernameLimitParams } from '../../types/io.js';
 import { CLIWriteOptionsFromAoParams } from '../types.js';
-export declare function buyRecordCLICommand(o: CLIWriteOptionsFromAoParams<AoBuyRecordParams>): Promise<import("../../types/common.js").AoMessageResult>;
-export declare function upgradeRecordCLICommand(o: CLIWriteOptionsFromAoParams<AoArNSPurchaseParams>): Promise<import("../../types/common.js").AoMessageResult>;
-export declare function extendLeaseCLICommand(o: CLIWriteOptionsFromAoParams<AoExtendLeaseParams>): Promise<import("../../types/common.js").AoMessageResult>;
-export declare function increaseUndernameLimitCLICommand(o: CLIWriteOptionsFromAoParams<AoIncreaseUndernameLimitParams>): Promise<import("../../types/common.js").AoMessageResult>;
-export declare function requestPrimaryNameCLICommand(o: CLIWriteOptionsFromAoParams<AoArNSPurchaseParams>): Promise<Omit<import("../../types/common.js").AoPrimaryNameRequest, "initiator"> & {
+export declare function buyRecordCLICommand(o: CLIWriteOptionsFromAoParams<BuyRecordParams>): Promise<import("../../types/common.js").MessageResult>;
+export declare function upgradeRecordCLICommand(o: CLIWriteOptionsFromAoParams<ArNSPurchaseParams>): Promise<import("../../types/common.js").MessageResult>;
+export declare function extendLeaseCLICommand(o: CLIWriteOptionsFromAoParams<ExtendLeaseParams>): Promise<import("../../types/common.js").MessageResult>;
+export declare function increaseUndernameLimitCLICommand(o: CLIWriteOptionsFromAoParams<IncreaseUndernameLimitParams>): Promise<import("../../types/common.js").MessageResult>;
+export declare function requestPrimaryNameCLICommand(o: CLIWriteOptionsFromAoParams<ArNSPurchaseParams>): Promise<Omit<import("../../types/common.js").PrimaryNameRequest, "initiator"> & {
     initiator: import("../../types/common.js").WalletAddress;
 }>;
-export declare function setPrimaryNameCLICommand(o: CLIWriteOptionsFromAoParams<AoArNSPurchaseParams>): Promise<import("../../types/common.js").AoMessageResult>;
+export declare function setPrimaryNameCLICommand(o: CLIWriteOptionsFromAoParams<ArNSPurchaseParams>): Promise<import("../../types/common.js").MessageResult>;
+/**
+ * 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 declare function syncAttributesCLICommand(o: CLIWriteOptionsFromAoParams<{
+    name: string;
+}>): Promise<import("../../types/common.js").MessageResult>;

package/lib/types/cli/commands/escrowCommands.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 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 type { JsonSerializable } from '../types.js';
+interface EscrowGlobalOptions {
+    rpcUrl?: string;
+    walletFile?: string;
+    privateKey?: string;
+    escrowProgramId?: string;
+}
+interface AntMintOptions extends EscrowGlobalOptions {
+    ant?: string;
+}
+interface DepositOptions extends AntMintOptions {
+    recipientArweave?: string;
+    recipientEthereum?: string;
+}
+interface UpdateRecipientOptions extends AntMintOptions {
+    newRecipientArweave?: string;
+    newRecipientEthereum?: string;
+}
+interface ClaimArweaveOptions extends AntMintOptions {
+    signatureFile?: string;
+    saltLen?: string;
+    claimant?: string;
+}
+interface ClaimEthereumOptions extends AntMintOptions {
+    signatureFile?: string;
+    claimant?: string;
+}
+/** `ar.io escrow status --ant <mint>` */
+export declare function escrowStatusCLICommand(o: AntMintOptions): Promise<JsonSerializable>;
+/** `ar.io escrow deposit --ant <mint> --recipient-{arweave|ethereum} ...` */
+export declare function escrowDepositCLICommand(o: DepositOptions): Promise<JsonSerializable>;
+/** `ar.io escrow cancel --ant <mint>` */
+export declare function escrowCancelCLICommand(o: AntMintOptions): Promise<JsonSerializable>;
+/** `ar.io escrow update-recipient --ant <mint> --new-recipient-{arweave|ethereum} ...` */
+export declare function escrowUpdateRecipientCLICommand(o: UpdateRecipientOptions): Promise<JsonSerializable>;
+/** `ar.io escrow claim-arweave --ant <mint> --signature-file <bin> --claimant <pubkey> [--salt-len 32]` */
+export declare function escrowClaimArweaveCLICommand(o: ClaimArweaveOptions): Promise<JsonSerializable>;
+/** `ar.io escrow claim-ethereum --ant <mint> --signature-file <bin> --claimant <pubkey>` */
+export declare function escrowClaimEthereumCLICommand(o: ClaimEthereumOptions): Promise<JsonSerializable>;
+export {};

package/lib/types/cli/commands/gatewayWriteCommands.d.ts

@@ -1,38 +1,39 @@
 import { AddressAndVaultIdCLIWriteOptions, DecreaseDelegateStakeCLIOptions, JoinNetworkCLIOptions, OperatorStakeCLIOptions, RedelegateStakeCLIOptions, TransferCLIOptions, UpdateGatewaySettingsCLIOptions, WriteActionCLIOptions } from '../types.js';
 export declare function joinNetwork(options: JoinNetworkCLIOptions): Promise<{
-    joinNetworkResult: import("../../types/common.js").AoMessageResult<Record<string, string | number | boolean | null>>;
+    joinNetworkResult: import("../../types/common.js").MessageResult<Record<string, string | number | boolean | null>>;
     joinedAddress: string;
     message: string;
 }>;
 export declare function updateGatewaySettings(options: UpdateGatewaySettingsCLIOptions): Promise<{
-    updateGatewaySettingsResult: import("../../types/common.js").AoMessageResult<Record<string, string | number | boolean | null>>;
+    updateGatewaySettingsResult: import("../../types/common.js").MessageResult<Record<string, string | number | boolean | null>>;
     updatedGatewayAddress: string;
     message: string;
 }>;
-export declare function leaveNetwork(options: WriteActionCLIOptions): Promise<import("../../types/common.js").AoMessageResult>;
+export declare function leaveNetwork(options: WriteActionCLIOptions): Promise<import("../../types/common.js").MessageResult>;
 export declare function saveObservations(o: WriteActionCLIOptions & {
     failedGateways?: string[];
     transactionId?: string;
-}): Promise<import("../../types/common.js").AoMessageResult<Record<string, string | number | boolean | null>>>;
-export declare function increaseOperatorStake(o: OperatorStakeCLIOptions): Promise<import("../../types/common.js").AoMessageResult<Record<string, string | number | boolean | null>>>;
-export declare function decreaseOperatorStake(o: OperatorStakeCLIOptions): Promise<import("../../types/common.js").AoMessageResult<Record<string, string | number | boolean | null>>>;
-export declare function instantWithdrawal(o: AddressAndVaultIdCLIWriteOptions): Promise<import("../../types/common.js").AoMessageResult<Record<string, string | number | boolean | null>>>;
-export declare function cancelWithdrawal(o: AddressAndVaultIdCLIWriteOptions): Promise<import("../../types/common.js").AoMessageResult<Record<string, string | number | boolean | null>>>;
+}): Promise<import("../../types/common.js").MessageResult<Record<string, string | number | boolean | null>>>;
+export declare function increaseOperatorStake(o: OperatorStakeCLIOptions): Promise<import("../../types/common.js").MessageResult<Record<string, string | number | boolean | null>>>;
+export declare function decreaseOperatorStake(o: OperatorStakeCLIOptions): Promise<import("../../types/common.js").MessageResult<Record<string, string | number | boolean | null>>>;
+export declare function claimWithdrawal(o: AddressAndVaultIdCLIWriteOptions): Promise<import("../../types/common.js").MessageResult>;
+export declare function instantWithdrawal(o: AddressAndVaultIdCLIWriteOptions): Promise<import("../../types/common.js").MessageResult<Record<string, string | number | boolean | null>>>;
+export declare function cancelWithdrawal(o: AddressAndVaultIdCLIWriteOptions): Promise<import("../../types/common.js").MessageResult<Record<string, string | number | boolean | null>>>;
 export declare function delegateStake(options: TransferCLIOptions): Promise<{
     senderAddress: string;
-    transferResult: import("../../types/common.js").AoMessageResult<Record<string, string | number | boolean | null>>;
+    transferResult: import("../../types/common.js").MessageResult<Record<string, string | number | boolean | null>>;
     message: string;
 } | {
     message: string;
 }>;
 export declare function decreaseDelegateStake(options: DecreaseDelegateStakeCLIOptions): Promise<{
     targetGateway: string;
-    decreaseDelegateStakeResult: import("../../types/common.js").AoMessageResult<Record<string, string | number | boolean | null>>;
+    decreaseDelegateStakeResult: import("../../types/common.js").MessageResult<Record<string, string | number | boolean | null>>;
     message: string;
 }>;
 export declare function redelegateStake(options: RedelegateStakeCLIOptions): Promise<{
     sourceGateway: string;
     targetGateway: string;
-    redelegateStakeResult: import("../../types/common.js").AoMessageResult<Record<string, string | number | boolean | null>>;
+    redelegateStakeResult: import("../../types/common.js").MessageResult<Record<string, string | number | boolean | null>>;
     message: string;
 }>;