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

package/lib/cjs/cli/cli.js

@@ -58,6 +58,7 @@ const antCommands_js_1 = require("./commands/antCommands.js");
 const arnsPurchaseCommands_js_1 = require("./commands/arnsPurchaseCommands.js");
 const escrowCommands_js_1 = require("./commands/escrowCommands.js");
 const gatewayWriteCommands_js_1 = require("./commands/gatewayWriteCommands.js");
+const pruneCommands_js_1 = require("./commands/pruneCommands.js");
 const readCommands_js_1 = require("./commands/readCommands.js");
 const transfer_js_1 = require("./commands/transfer.js");
 const options_js_1 = require("./options.js");
@@ -491,6 +492,77 @@ const utils_js_1 = require("./utils.js");
     options: options_js_1.arnsPurchaseOptions,
     action: arnsPurchaseCommands_js_1.setPrimaryNameCLICommand,
 });
+// # Prune / cleanup (Solana-only — permissionless crank surface)
+(0, utils_js_1.makeCommand)({
+    name: 'prune-expired-names',
+    description: 'Batch-prune expired ArnsRecord PDAs (Solana-only). Discovers eligible records ' +
+        'via getExpiredArnsRecords if --arns-records is omitted.',
+    options: [...options_js_1.writeActionOptions, options_js_1.optionMap.max, options_js_1.optionMap.arnsRecords],
+    action: pruneCommands_js_1.pruneExpiredNamesCLICommand,
+});
+(0, utils_js_1.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: [...options_js_1.writeActionOptions, options_js_1.optionMap.name],
+    action: pruneCommands_js_1.pruneNameToReturnedCLICommand,
+});
+(0, utils_js_1.makeCommand)({
+    name: 'prune-returned-names',
+    description: 'Batch-prune expired ReturnedName PDAs (Solana-only). Discovers via ' +
+        'getExpiredReturnedNames if --returned-names is omitted.',
+    options: [...options_js_1.writeActionOptions, options_js_1.optionMap.max, options_js_1.optionMap.returnedNames],
+    action: pruneCommands_js_1.pruneReturnedNamesCLICommand,
+});
+(0, utils_js_1.makeCommand)({
+    name: 'prune-expired-reservation',
+    description: 'Close an expired ReservedName PDA (Solana-only).',
+    options: [...options_js_1.writeActionOptions, options_js_1.optionMap.name],
+    action: pruneCommands_js_1.pruneExpiredReservationCLICommand,
+});
+(0, utils_js_1.makeCommand)({
+    name: 'prune-gateway',
+    description: 'Slash + remove a deficient gateway (≥30 consecutive failures). Solana-only.',
+    options: [...options_js_1.writeActionOptions, options_js_1.optionMap.gateway],
+    action: pruneCommands_js_1.pruneGatewayCLICommand,
+});
+(0, utils_js_1.makeCommand)({
+    name: 'finalize-gone',
+    description: 'GC a Leaving/Gone gateway whose leave window has fully elapsed. Solana-only.',
+    options: [...options_js_1.writeActionOptions, options_js_1.optionMap.gateway],
+    action: pruneCommands_js_1.finalizeGoneCLICommand,
+});
+(0, utils_js_1.makeCommand)({
+    name: 'close-observation',
+    description: 'Reclaim rent from an Observation PDA whose epoch has been distributed. Solana-only.',
+    options: [...options_js_1.writeActionOptions, options_js_1.optionMap.epochIndex, options_js_1.optionMap.observer],
+    action: pruneCommands_js_1.closeObservationCLICommand,
+});
+(0, utils_js_1.makeCommand)({
+    name: 'close-empty-delegation',
+    description: 'Close an empty Delegation PDA (amount == 0). Rent refunds to the original delegator. Solana-only.',
+    options: [...options_js_1.writeActionOptions, options_js_1.optionMap.gateway, options_js_1.optionMap.delegator],
+    action: pruneCommands_js_1.closeEmptyDelegationCLICommand,
+});
+(0, utils_js_1.makeCommand)({
+    name: 'close-drained-withdrawal',
+    description: 'Close a drained Withdrawal PDA (amount == 0). Rent refunds to the original owner. Solana-only.',
+    options: [...options_js_1.writeActionOptions, options_js_1.optionMap.owner, options_js_1.optionMap.withdrawalId],
+    action: pruneCommands_js_1.closeDrainedWithdrawalCLICommand,
+});
+(0, utils_js_1.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: [...options_js_1.writeActionOptions, options_js_1.optionMap.vaultId, options_js_1.optionMap.owner],
+    action: pruneCommands_js_1.releaseVaultCLICommand,
+});
+(0, utils_js_1.makeCommand)({
+    name: 'close-expired-request',
+    description: 'Close an expired PrimaryNameRequest PDA. Solana-only.',
+    options: [...options_js_1.writeActionOptions, options_js_1.optionMap.initiator],
+    action: pruneCommands_js_1.closeExpiredRequestCLICommand,
+});
 // # ANT Registry
 (0, utils_js_1.makeCommand)({
     name: 'get-ants-for-address',

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

@@ -0,0 +1,179 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pruneExpiredNamesCLICommand = pruneExpiredNamesCLICommand;
+exports.pruneNameToReturnedCLICommand = pruneNameToReturnedCLICommand;
+exports.pruneReturnedNamesCLICommand = pruneReturnedNamesCLICommand;
+exports.pruneExpiredReservationCLICommand = pruneExpiredReservationCLICommand;
+exports.pruneGatewayCLICommand = pruneGatewayCLICommand;
+exports.finalizeGoneCLICommand = finalizeGoneCLICommand;
+exports.closeObservationCLICommand = closeObservationCLICommand;
+exports.closeEmptyDelegationCLICommand = closeEmptyDelegationCLICommand;
+exports.closeDrainedWithdrawalCLICommand = closeDrainedWithdrawalCLICommand;
+exports.releaseVaultCLICommand = releaseVaultCLICommand;
+exports.closeExpiredRequestCLICommand = closeExpiredRequestCLICommand;
+const utils_js_1 = require("../utils.js");
+function rejectAoBackend(o, command) {
+    if (o.ao) {
+        throw new Error(`${command} is Solana-only — Lua's tick() handles the equivalent on AO. Drop --ao.`);
+    }
+}
+async function getSolanaWriter(o) {
+    const { ario } = await (0, utils_js_1.writeARIOFromOptions)(o);
+    return ario;
+}
+function parseMaxNames(o) {
+    const raw = o.max;
+    if (raw === undefined) {
+        throw new Error('--max <count> is required (u8 batch size, 1-255)');
+    }
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 1 || n > 255) {
+        throw new Error(`--max must be an integer 1-255 (got ${raw})`);
+    }
+    return n;
+}
+// =========================================
+// ArNS prune
+// =========================================
+async function pruneExpiredNamesCLICommand(o) {
+    rejectAoBackend(o, 'prune-expired-names');
+    const max = parseMaxNames(o);
+    const ario = await getSolanaWriter(o);
+    // If `--arns-records` wasn't provided, discover them via the readable's
+    // helper. Cap at `max` so we never overshoot the ix's u8 batch parameter.
+    let records = o.arnsRecords ?? [];
+    if (records.length === 0) {
+        const now = Math.floor(Date.now() / 1000);
+        const expired = await ario.getExpiredArnsRecords(now);
+        records = expired.slice(0, max).map((r) => r.pubkey);
+        if (records.length === 0) {
+            return { message: 'No expired ArnsRecords to prune' };
+        }
+    }
+    else {
+        records = records.slice(0, max);
+    }
+    await (0, utils_js_1.assertConfirmationPrompt)(`Prune ${records.length} expired ArnsRecord(s)?`, o);
+    return ario.pruneExpiredNames({ maxNames: max, arnsRecords: records });
+}
+async function pruneNameToReturnedCLICommand(o) {
+    rejectAoBackend(o, 'prune-name-to-returned');
+    const name = (0, utils_js_1.requiredStringFromOptions)(o, 'name');
+    const ario = await getSolanaWriter(o);
+    await (0, utils_js_1.assertConfirmationPrompt)(`Convert expired lease for "${name}" to a ReturnedName (Dutch auction)?`, o);
+    return ario.pruneNameToReturned({ name });
+}
+async function pruneReturnedNamesCLICommand(o) {
+    rejectAoBackend(o, 'prune-returned-names');
+    const max = parseMaxNames(o);
+    const ario = await getSolanaWriter(o);
+    let returned = o.returnedNames ?? [];
+    if (returned.length === 0) {
+        const now = Math.floor(Date.now() / 1000);
+        const expired = await ario.getExpiredReturnedNames(now);
+        returned = expired.slice(0, max).map((r) => r.pubkey);
+        if (returned.length === 0) {
+            return { message: 'No expired ReturnedNames to prune' };
+        }
+    }
+    else {
+        returned = returned.slice(0, max);
+    }
+    await (0, utils_js_1.assertConfirmationPrompt)(`Prune ${returned.length} expired ReturnedName(s)?`, o);
+    return ario.pruneReturnedNames({
+        maxNames: max,
+        returnedNames: returned,
+    });
+}
+async function pruneExpiredReservationCLICommand(o) {
+    rejectAoBackend(o, 'prune-expired-reservation');
+    const name = (0, utils_js_1.requiredStringFromOptions)(o, 'name');
+    const ario = await getSolanaWriter(o);
+    await (0, utils_js_1.assertConfirmationPrompt)(`Close expired reservation for "${name}"?`, o);
+    return ario.pruneExpiredReservation({ name });
+}
+// =========================================
+// Gateway prune
+// =========================================
+async function pruneGatewayCLICommand(o) {
+    rejectAoBackend(o, 'prune-gateway');
+    const gateway = (0, utils_js_1.requiredStringFromOptions)(o, 'gateway');
+    const ario = await getSolanaWriter(o);
+    await (0, utils_js_1.assertConfirmationPrompt)(`Slash + remove deficient gateway ${gateway}?`, o);
+    return ario.pruneGateway({ gateway });
+}
+async function finalizeGoneCLICommand(o) {
+    rejectAoBackend(o, 'finalize-gone');
+    const gateway = (0, utils_js_1.requiredStringFromOptions)(o, 'gateway');
+    const ario = await getSolanaWriter(o);
+    await (0, utils_js_1.assertConfirmationPrompt)(`Finalize-GC departed gateway ${gateway} (reclaim PDA rent)?`, o);
+    return ario.finalizeGone({ gateway });
+}
+// =========================================
+// Rent reclaim
+// =========================================
+async function closeObservationCLICommand(o) {
+    rejectAoBackend(o, 'close-observation');
+    const epochIndexStr = (0, utils_js_1.requiredStringFromOptions)(o, 'epochIndex');
+    const observer = (0, utils_js_1.requiredStringFromOptions)(o, 'observer');
+    const epochIndex = Number(epochIndexStr);
+    if (!Number.isInteger(epochIndex) || epochIndex < 0) {
+        throw new Error(`--epoch-index must be a non-negative integer (got ${epochIndexStr})`);
+    }
+    const ario = await getSolanaWriter(o);
+    await (0, utils_js_1.assertConfirmationPrompt)(`Close Observation PDA (epoch ${epochIndex}, observer ${observer})?`, o);
+    return ario.closeObservation({ epochIndex, observer });
+}
+async function closeEmptyDelegationCLICommand(o) {
+    rejectAoBackend(o, 'close-empty-delegation');
+    const gateway = (0, utils_js_1.requiredStringFromOptions)(o, 'gateway');
+    const delegator = (0, utils_js_1.requiredStringFromOptions)(o, 'delegator');
+    const ario = await getSolanaWriter(o);
+    await (0, utils_js_1.assertConfirmationPrompt)(`Close empty Delegation PDA (gateway=${gateway}, delegator=${delegator})?`, o);
+    return ario.closeEmptyDelegation({ gateway, delegator });
+}
+async function closeDrainedWithdrawalCLICommand(o) {
+    rejectAoBackend(o, 'close-drained-withdrawal');
+    const owner = (0, utils_js_1.requiredStringFromOptions)(o, 'owner');
+    const withdrawalIdStr = (0, utils_js_1.requiredStringFromOptions)(o, 'withdrawalId');
+    // Validate before BigInt() — `BigInt('0xff')` and `BigInt('  1  ')` succeed
+    // and `BigInt('abc')` throws an opaque SyntaxError. Restrict to the u64
+    // decimal form the on-chain seed encoder expects so the CLI fails with a
+    // clear message instead of a downstream parser error.
+    if (!/^\d+$/.test(withdrawalIdStr)) {
+        throw new Error(`--withdrawal-id must be a non-negative decimal integer (got "${withdrawalIdStr}")`);
+    }
+    const withdrawalId = BigInt(withdrawalIdStr);
+    const ario = await getSolanaWriter(o);
+    await (0, utils_js_1.assertConfirmationPrompt)(`Close drained Withdrawal PDA (owner=${owner}, id=${withdrawalIdStr})?`, o);
+    return ario.closeDrainedWithdrawal({ owner, withdrawalId });
+}
+// =========================================
+// Vault + primary-name request
+// =========================================
+async function releaseVaultCLICommand(o) {
+    rejectAoBackend(o, 'release-vault');
+    // The on-chain handler requires `owner: Signer` — the SDK uses the
+    // configured signer as the owner. The `--owner` flag is accepted as
+    // documentation but ignored unless it matches the signer; fail loud if
+    // it doesn't, so users don't think they can release someone else's vault.
+    const ario = await getSolanaWriter(o);
+    if (o.owner) {
+        const signerAddr = (await (0, utils_js_1.writeARIOFromOptions)(o)).signerAddress;
+        if (o.owner !== signerAddr) {
+            throw new Error(`release-vault: --owner ${o.owner} does not match signer ${signerAddr}. ` +
+                `release_vault is owner-signed; use the owner's wallet to call it.`);
+        }
+    }
+    const vaultIdStr = (0, utils_js_1.requiredStringFromOptions)(o, 'vaultId');
+    const vaultId = vaultIdStr;
+    await (0, utils_js_1.assertConfirmationPrompt)(`Release expired vault id=${vaultIdStr} (transfer tokens back to owner)?`, o);
+    return ario.releaseVault({ vaultId });
+}
+async function closeExpiredRequestCLICommand(o) {
+    rejectAoBackend(o, 'close-expired-request');
+    const initiator = (0, utils_js_1.requiredStringFromOptions)(o, 'initiator');
+    const ario = await getSolanaWriter(o);
+    await (0, utils_js_1.assertConfirmationPrompt)(`Close expired primary-name request from ${initiator}?`, o);
+    return ario.closeExpiredRequest({ initiator });
+}

package/lib/cjs/cli/options.js

@@ -424,6 +424,35 @@ exports.optionMap = {
         description: 'Reassign all affiliated names to the new process',
         type: 'boolean',
     },
+    // -----------------------------------------------------------------
+    // Prune / cleanup flags (Solana-only — see pruneCommands.ts)
+    // -----------------------------------------------------------------
+    gateway: {
+        alias: '--gateway <gateway>',
+        description: 'The gateway operator address (prune / finalize commands)',
+    },
+    delegator: {
+        alias: '--delegator <delegator>',
+        description: 'The delegator address (close-empty-delegation)',
+    },
+    observer: {
+        alias: '--observer <observer>',
+        description: 'The observer address (close-observation)',
+    },
+    max: {
+        alias: '--max <max>',
+        description: 'Per-tx batch size (1-255, u8) for prune-expired-names / prune-returned-names',
+    },
+    arnsRecords: {
+        alias: '--arns-records <arnsRecords...>',
+        description: 'Explicit ArnsRecord PDAs to prune. Default: discover via getExpiredArnsRecords.',
+        type: 'array',
+    },
+    returnedNames: {
+        alias: '--returned-names <returnedNames...>',
+        description: 'Explicit ReturnedName PDAs to prune. Default: discover via getExpiredReturnedNames.',
+        type: 'array',
+    },
 };
 exports.walletOptions = [
     exports.optionMap.walletFile,

package/lib/cjs/solana/deserialize.js

@@ -330,6 +330,9 @@ function deserializeGateway(data) {
     const statusIdx = r.readU8(); // 0=Joined, 1=Leaving
     const startTimestamp = r.readI64AsNumber();
     const leaveTimestamp = r.readOptionI64();
+    // leave_epoch_duration: i64 — snapshot of epoch_settings.epoch_duration captured
+    // at leave_network/prune_gateway. Not surfaced on AoGateway; consume to stay aligned.
+    r.skip(8);
     // GatewayStats
     const passedEpochCount = r.readU32();
     const failedEpochCount = r.readU32();
@@ -338,17 +341,17 @@ function deserializeGateway(data) {
     const observedEpochCount = r.readU32();
     const failedConsecutiveEpochs = r.readU8();
     const passedConsecutiveEpochs = r.readU8();
-    // GatewayWeights (6 x u64)
+    // GatewayWeights (7 x u64 — 7th is weights_epoch, set by tally_weights)
     const stakeWeight = r.readU64AsNumber();
     const tenureWeight = r.readU64AsNumber();
     const gatewayPerformanceRatio = r.readU64AsNumber();
     const observerPerformanceRatio = r.readU64AsNumber();
     const compositeWeight = r.readU64AsNumber();
     const normalizedCompositeWeight = r.readU64AsNumber();
-    // GatewaySettings2
+    r.skip(8); // weights_epoch — not surfaced on AoGatewayWeights
+    // GatewaySettings2 (auto_stake removed in cfc7a8b2 — never existed on Solana)
     const allowDelegatedStaking = r.readBool();
     const delegateRewardShareRatio = r.readU16();
-    const autoStake = r.readBool();
     const minDelegatedStake = r.readU64AsNumber();
     const allowlistEnabled = r.readBool();
     // RegistryIndex (index: u32, _reserved: u8 — was is_registered:bool)
@@ -386,7 +389,7 @@ function deserializeGateway(data) {
         delegateRewardShareRatio,
         allowedDelegates: [], // populated separately from allowlist PDAs
         minDelegatedStake,
-        autoStake,
+        autoStake: false, // not an on-chain field on Solana; preserved on AoGatewaySettings for AO parity
         label,
         note,
         properties,

package/lib/cjs/solana/escrow.js

@@ -463,8 +463,12 @@ class TokenEscrow {
             saltLen: args.saltLen ?? 32,
             messageNonce: escrow.nonce,
         });
+        // The on-chain claim handler delivers liquid tokens to
+        // `claimantTokenAccount`; for fresh-wallet claimants the canonical ATA
+        // doesn't exist yet (#3012). Idempotent-create when canonical.
+        const createAtaIx = await this._createClaimantAtaIfCanonical(args.claimant, args.claimantTokenAccount, escrow.arioMint);
         // RSA-PSS-4096 verification is CU-intensive; use 400K.
-        return this.send([ix], 400_000);
+        return this.send(createAtaIx ? [createAtaIx, ix] : [ix], 400_000);
     }
     async claimTokensArweaveIx(args) {
         if (args.signature.length !== 512) {
@@ -500,7 +504,10 @@ class TokenEscrow {
             ...args,
             messageNonce: escrow.nonce,
         });
-        return this.send([ix]);
+        // Same fresh-wallet #3012 vector as claimTokensArweave — bundle a
+        // canonical-ATA idempotent-create when applicable.
+        const createAtaIx = await this._createClaimantAtaIfCanonical(args.claimant, args.claimantTokenAccount, escrow.arioMint);
+        return this.send(createAtaIx ? [createAtaIx, ix] : [ix]);
     }
     async claimTokensEthereumIx(args) {
         if (args.signature.length !== 65) {
@@ -604,16 +611,53 @@ class TokenEscrow {
      * (see the introspection function's tolerance), so any modest clock skew
      * between client and chain is absorbed.
      */
+    /**
+     * Idempotent-create the claimant's canonical ATA when needed.
+     *
+     * The on-chain claim handler delivers liquid tokens directly to
+     * `claimantTokenAccount` for expired vaults AND for token escrows.
+     * For active vaults, the `claim_vault_*` Anchor Accounts struct still
+     * declares `claimant_token_account: Account<TokenAccount>`, which forces
+     * Anchor's account-load-time validation to require the account exist
+     * even though the active path doesn't write to it. Either way: if the
+     * claimant is a fresh wallet that has never held this mint, the ATA
+     * doesn't exist and the tx fails with `AccountNotInitialized` (#3012).
+     *
+     * Returns `null` when the caller passed a non-canonical
+     * `claimantTokenAccount` (manually-created non-ATA token account,
+     * presumably already exists — caller's responsibility).
+     */
+    async _createClaimantAtaIfCanonical(claimant, claimantTokenAccount, mint) {
+        const canonical = await (0, ata_js_1.getAssociatedTokenAddressKit)(mint, claimant);
+        if (claimantTokenAccount !== canonical)
+            return null;
+        const signer = this.requireSigner('createClaimantAtaIfCanonical');
+        return buildCreateAtaIdempotentIx(signer.address, canonical, claimant, mint);
+    }
     async maybeBundleVaultedTransfer(escrow, args, claimIx) {
         const nowSeconds = BigInt(Math.floor(Date.now() / 1000));
         const remaining = escrow.vaultEndTimestamp - nowSeconds;
         if (remaining <= 0n) {
-            return [claimIx];
+            // Expired vault → claim handler delivers liquid to claimantTokenAccount.
+            // Idempotent-create that ATA if it's the canonical derivation so a
+            // first-time recipient just works.
+            const createClaimantAtaIx = await this._createClaimantAtaIfCanonical(args.claimant, args.claimantTokenAccount, escrow.arioMint);
+            return createClaimantAtaIx ? [createClaimantAtaIx, claimIx] : [claimIx];
         }
         const signer = this.requireSigner('maybeBundleVaultedTransfer');
         const nextId = await this.getNextVaultId(args.claimant);
         const [vaultPda] = await (0, pda_js_1.getVaultPDA)(args.claimant, nextId, this.coreProgram);
         const vaultATA = await (0, ata_js_1.getAssociatedTokenAddressKit)(escrow.arioMint, vaultPda, true);
+        // Active-vault path: `claim_vault_*` still validates the claimant ATA
+        // at account-load-time (Anchor `Account<TokenAccount>` constraint),
+        // even though no liquid is written to it. Idempotent-create so a fresh
+        // claimant doesn't fail the ix with AccountNotInitialized (#3012).
+        const createClaimantAtaIx = await this._createClaimantAtaIfCanonical(args.claimant, args.claimantTokenAccount, escrow.arioMint);
+        // The new vault PDA's ATA must exist before `vaulted_transfer` reads it
+        // (else `AccountNotInitialized` #3012). Idempotent so a retry after a
+        // partial-failure tx is safe. Placed after the claim ix to preserve
+        // the "claim first" tx ordering invariant.
+        const createVaultAtaIx = buildCreateAtaIdempotentIx(signer.address, vaultATA, vaultPda, escrow.arioMint);
         const vaultedIx = await (0, vaultedTransfer_js_1.getVaultedTransferInstructionAsync)({
             vault: vaultPda,
             senderTokenAccount: args.payerTokenAccount,
@@ -624,7 +668,8 @@ class TokenEscrow {
             lockDurationSeconds: remaining,
             revocable: escrow.vaultRevocable,
         }, { programAddress: this.coreProgram });
-        return [claimIx, vaultedIx];
+        const head = createClaimantAtaIx ? [createClaimantAtaIx] : [];
+        return [...head, claimIx, createVaultAtaIx, vaultedIx];
     }
     /** Read the recipient's `VaultCounter.nextId`, defaulting to 0n if the
      *  counter PDA hasn't been initialised yet (first vault for that owner). */