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

package/lib/esm/solana/escrow.js

@@ -0,0 +1,797 @@
+/**
+ * Solana ANT-escrow and Token-escrow clients — `ario-ant-escrow` program.
+ *
+ * ANTEscrow holds a Metaplex Core ANT NFT in trustless custody and
+ * releases it after on-chain verification of an Arweave RSA-PSS-4096 or
+ * Ethereum ECDSA signature over a canonical claim message.
+ *
+ * TokenEscrow holds ARIO SPL tokens (liquid or vaulted) in trustless
+ * custody with the same multi-protocol claim flow.
+ *
+ * Design: `docs/ANT_ESCROW_DESIGN.md` (account model, canonical message
+ * format, threat model). Plan: `docs/ANT_ESCROW_IMPLEMENTATION_PLAN.md`.
+ *
+ * All instruction encoding is delegated to the Codama-generated builders
+ * in `./generated/ant-escrow/instructions/` — they own the discriminator,
+ * Borsh codec, and account-meta wiring derived from the on-chain IDL.
+ */
+import { fetchMaybeEscrowAnt, fetchMaybeEscrowToken, getCancelDepositInstruction, getCancelTokenDepositInstruction, getCancelVaultDepositInstruction, getClaimAntArweaveAttestedInstruction, getClaimAntEthereumInstruction, getClaimTokensArweaveAttestedInstruction, getClaimTokensEthereumInstruction, getClaimVaultArweaveAttestedInstruction, getClaimVaultEthereumInstruction, getDepositAntInstruction, getDepositTokensInstruction, getDepositVaultInstruction, getUpdateRecipientInstruction, getUpdateTokenRecipientInstruction, getUpdateVaultRecipientInstruction, } from '@ar.io/solana-contracts/ant-escrow';
+import { fetchMaybeVaultCounter, getVaultedTransferInstructionAsync, } from '@ar.io/solana-contracts/core';
+import { Logger } from '../common/logger.js';
+import { getAssociatedTokenAddressKit } from './ata.js';
+import { ARIO_ANT_ESCROW_PROGRAM_ID, ARIO_CORE_PROGRAM_ID, ESCROW_ARWEAVE_PUBKEY_LEN, ESCROW_ASSET_TYPE_VAULT, ESCROW_ETHEREUM_PUBKEY_LEN, ESCROW_PROTOCOL_ARWEAVE, ESCROW_PROTOCOL_ETHEREUM, } from './constants.js';
+import { getEscrowAntPDA, getEscrowTokenPDA, getEscrowVaultPDA, getVaultCounterPDA, getVaultPDA, } from './pda.js';
+import { sendAndConfirm } from './send.js';
+/** Map the Codama-generated `EscrowAnt` raw decoded type to our public
+ *  `EscrowAntState` with protocol enum + active-prefix pubkey slice. */
+function toEscrowAntState(raw) {
+    const recipientProtocol = raw.recipientProtocol === ESCROW_PROTOCOL_ARWEAVE ? 'arweave' : 'ethereum';
+    const expectedLen = recipientProtocol === 'arweave'
+        ? ESCROW_ARWEAVE_PUBKEY_LEN
+        : ESCROW_ETHEREUM_PUBKEY_LEN;
+    if (raw.recipientProtocol !== ESCROW_PROTOCOL_ARWEAVE &&
+        raw.recipientProtocol !== ESCROW_PROTOCOL_ETHEREUM) {
+        throw new Error(`EscrowAnt: unknown protocol byte ${raw.recipientProtocol}`);
+    }
+    return {
+        version: raw.version,
+        bump: raw.bump,
+        depositor: raw.depositor,
+        antMint: raw.antMint,
+        recipientProtocol,
+        recipientPubkey: new Uint8Array(raw.recipientPubkey.subarray(0, expectedLen)),
+        nonce: new Uint8Array(raw.nonce),
+        depositSlot: raw.depositSlot,
+    };
+}
+function protocolToByte(p) {
+    return p === 'arweave' ? ESCROW_PROTOCOL_ARWEAVE : ESCROW_PROTOCOL_ETHEREUM;
+}
+/**
+ * Solana-backed client for the trustless ANT-escrow program. All write
+ * methods require both `rpcSubscriptions` and `signer`; read methods
+ * only need `rpc`.
+ */
+export class ANTEscrow {
+    rpc;
+    rpcSubscriptions;
+    signer;
+    programId;
+    commitment;
+    logger;
+    constructor(config) {
+        this.rpc = config.rpc;
+        this.rpcSubscriptions = config.rpcSubscriptions;
+        this.signer = config.signer;
+        this.programId = config.programId ?? ARIO_ANT_ESCROW_PROGRAM_ID;
+        this.commitment = config.commitment ?? 'confirmed';
+        this.logger = config.logger ?? Logger.default;
+    }
+    static init(config) {
+        return new ANTEscrow(config);
+    }
+    // -------------------------------------------------------------------
+    // Reads
+    // -------------------------------------------------------------------
+    /** Fetch the on-chain `EscrowAnt` for an ANT mint, or `null` if no
+     *  active escrow exists. Uses the Codama-generated decoder. */
+    async get(antMint) {
+        const [pda] = await getEscrowAntPDA(antMint, this.programId);
+        const account = await fetchMaybeEscrowAnt(this.rpc, pda, {
+            commitment: this.commitment,
+        });
+        if (!account.exists)
+            return null;
+        return toEscrowAntState(account.data);
+    }
+    /** Address of the EscrowAnt PDA for an ANT mint (no RPC call). */
+    async getPda(antMint) {
+        const [pda] = await getEscrowAntPDA(antMint, this.programId);
+        return pda;
+    }
+    // -------------------------------------------------------------------
+    // Write — depositor-side
+    // -------------------------------------------------------------------
+    /**
+     * Lock an ANT into escrow. The signer (depositor) must currently own
+     * the asset; mpl-core's TransferV1 CPI enforces this.
+     *
+     * `recipient.publicKey` length must match `recipient.protocol`:
+     * - `'arweave'` → 512-byte RSA-4096 modulus (the JWK `n` field)
+     * - `'ethereum'` → 20-byte address
+     */
+    async deposit(args) {
+        const signer = this.requireSigner('deposit');
+        const ix = await this.depositIx(args, signer);
+        return this.send([ix]);
+    }
+    async depositIx(args, depositor) {
+        this.assertPubkeyLen(args.recipient);
+        const [escrow] = await getEscrowAntPDA(args.antMint, this.programId);
+        return getDepositAntInstruction({
+            escrow,
+            antAsset: args.antMint,
+            depositor,
+            recipientProtocol: protocolToByte(args.recipient.protocol),
+            recipientPubkey: args.recipient.publicKey,
+        }, { programAddress: this.programId });
+    }
+    /**
+     * Re-target the escrow at a new recipient identity. Rotates the
+     * on-chain nonce, invalidating any in-flight claim signatures bound
+     * to the prior recipient.
+     */
+    async updateRecipient(args) {
+        const signer = this.requireSigner('updateRecipient');
+        this.assertPubkeyLen(args.newRecipient);
+        const [escrow] = await getEscrowAntPDA(args.antMint, this.programId);
+        const ix = getUpdateRecipientInstruction({
+            escrow,
+            depositor: signer,
+            newProtocol: protocolToByte(args.newRecipient.protocol),
+            newPubkey: args.newRecipient.publicKey,
+        }, { programAddress: this.programId });
+        return this.send([ix]);
+    }
+    /**
+     * Pull an escrowed ANT back to the depositor. Closes the escrow PDA
+     * and refunds rent.
+     */
+    async cancel(args) {
+        const signer = this.requireSigner('cancel');
+        const [escrow] = await getEscrowAntPDA(args.antMint, this.programId);
+        const ix = getCancelDepositInstruction({
+            escrow,
+            antAsset: args.antMint,
+            depositor: signer,
+        }, { programAddress: this.programId });
+        return this.send([ix]);
+    }
+    // -------------------------------------------------------------------
+    // Write — claim
+    // -------------------------------------------------------------------
+    /**
+     * Submit an Arweave RSA-PSS-4096 signature to release the ANT.
+     * Anyone can submit (the fee payer = `signer`); only `claimant`
+     * receives the ANT, and only the original `depositor` receives rent.
+     */
+    async claimArweave(args) {
+        const escrow = await this.requireEscrow(args.antMint);
+        if (escrow.recipientProtocol !== 'arweave') {
+            throw new Error(`escrow recipient is ${escrow.recipientProtocol}, not arweave`);
+        }
+        const ix = await this.claimArweaveIx({
+            ...args,
+            saltLen: args.saltLen ?? 32,
+            depositor: escrow.depositor,
+            messageNonce: escrow.nonce,
+        });
+        // RSA-PSS-4096 verification via sol_big_mod_exp is CU-intensive
+        // (~200K+ for the full claim including Transfer CPI). Use 400K to
+        // provide comfortable headroom.
+        return this.send([ix], 400_000);
+    }
+    /**
+     * Build the ANT-claim-via-Arweave-attested instruction.
+     *
+     * **API note**: this method previously took user-side RSA-PSS params
+     * (`signature`, `saltLen`, `messageNonce`). The on-chain ix was
+     * renamed to `claim_ant_arweave_attested` (canonical contracts
+     * `ar-io-solana-contracts` PR-19+): verification is now via
+     * instruction-introspection of a preceding Ed25519 sigverify ix
+     * issued by the off-chain attestor (see
+     * `migration/attestor/`). Those data args are no longer fed to the
+     * builder. Callers MUST prepend the attestor's sigverify ix to the
+     * transaction or it will fail on-chain. A higher-level helper that
+     * fetches the attestor's signature and assembles the full tx is
+     * tracked as a follow-up.
+     *
+     * @deprecated Args `signature`, `saltLen`, `messageNonce` are
+     * ignored. Use the new attested flow.
+     */
+    async claimArweaveIx(args) {
+        if (args.messageNonce.length !== 32) {
+            throw new Error('messageNonce must be 32 bytes');
+        }
+        const signer = this.requireSigner('claimArweave');
+        const [escrow] = await getEscrowAntPDA(args.antMint, this.programId);
+        return getClaimAntArweaveAttestedInstruction({
+            escrow,
+            antAsset: args.antMint,
+            claimant: args.claimant,
+            depositor: args.depositor,
+            payer: signer,
+            messageNonce: args.messageNonce,
+        }, { programAddress: this.programId });
+    }
+    /** Submit an Ethereum ECDSA secp256k1 + EIP-191 signature. */
+    async claimEthereum(args) {
+        const escrow = await this.requireEscrow(args.antMint);
+        if (escrow.recipientProtocol !== 'ethereum') {
+            throw new Error(`escrow recipient is ${escrow.recipientProtocol}, not ethereum`);
+        }
+        const ix = await this.claimEthereumIx({
+            ...args,
+            depositor: escrow.depositor,
+            messageNonce: escrow.nonce,
+        });
+        return this.send([ix]);
+    }
+    async claimEthereumIx(args) {
+        if (args.signature.length !== 65) {
+            throw new Error('ethereum signature must be 65 bytes (r||s||v)');
+        }
+        if (args.messageNonce.length !== 32) {
+            throw new Error('messageNonce must be 32 bytes');
+        }
+        const signer = this.requireSigner('claimEthereum');
+        const [escrow] = await getEscrowAntPDA(args.antMint, this.programId);
+        return getClaimAntEthereumInstruction({
+            escrow,
+            antAsset: args.antMint,
+            claimant: args.claimant,
+            depositor: args.depositor,
+            payer: signer,
+            messageNonce: args.messageNonce,
+            signature: args.signature,
+        }, { programAddress: this.programId });
+    }
+    // -------------------------------------------------------------------
+    // Internals
+    // -------------------------------------------------------------------
+    async send(instructions, computeUnitLimit = 200_000) {
+        const signer = this.requireSigner('send');
+        if (!this.rpcSubscriptions) {
+            throw new Error('ANTEscrow: rpcSubscriptions required for write operations');
+        }
+        return sendAndConfirm({
+            rpc: this.rpc,
+            rpcSubscriptions: this.rpcSubscriptions,
+            signer,
+            instructions,
+            commitment: this.commitment,
+            computeUnitLimit,
+        });
+    }
+    requireSigner(op) {
+        if (!this.signer) {
+            throw new Error(`ANTEscrow.${op}: signer is required for writes`);
+        }
+        return this.signer;
+    }
+    async requireEscrow(antMint) {
+        const escrow = await this.get(antMint);
+        if (!escrow) {
+            throw new Error(`no escrow found for ANT ${antMint}`);
+        }
+        return escrow;
+    }
+    assertPubkeyLen(recipient) {
+        const expected = recipient.protocol === 'arweave'
+            ? ESCROW_ARWEAVE_PUBKEY_LEN
+            : ESCROW_ETHEREUM_PUBKEY_LEN;
+        if (recipient.publicKey.length !== expected) {
+            throw new Error(`recipient.publicKey: expected ${expected} bytes for protocol=${recipient.protocol}, got ${recipient.publicKey.length}`);
+        }
+    }
+}
+/** Map the Codama-generated `EscrowToken` raw decoded type to our public
+ *  `EscrowTokenState` with protocol enum + active-prefix pubkey slice. */
+function toEscrowTokenState(raw) {
+    const recipientProtocol = raw.recipientProtocol === ESCROW_PROTOCOL_ARWEAVE ? 'arweave' : 'ethereum';
+    if (raw.recipientProtocol !== ESCROW_PROTOCOL_ARWEAVE &&
+        raw.recipientProtocol !== ESCROW_PROTOCOL_ETHEREUM) {
+        throw new Error(`EscrowToken: unknown protocol byte ${raw.recipientProtocol}`);
+    }
+    const expectedLen = recipientProtocol === 'arweave'
+        ? ESCROW_ARWEAVE_PUBKEY_LEN
+        : ESCROW_ETHEREUM_PUBKEY_LEN;
+    return {
+        version: raw.version,
+        bump: raw.bump,
+        depositor: raw.depositor,
+        assetType: raw.assetType === ESCROW_ASSET_TYPE_VAULT ? 'vault' : 'token',
+        amount: raw.amount,
+        arioMint: raw.arioMint,
+        assetId: new Uint8Array(raw.assetId),
+        recipientProtocol,
+        recipientPubkey: new Uint8Array(raw.recipientPubkey.subarray(0, expectedLen)),
+        nonce: new Uint8Array(raw.nonce),
+        depositSlot: raw.depositSlot,
+        vaultEndTimestamp: raw.vaultEndTimestamp,
+        vaultRevocable: raw.vaultRevocable,
+    };
+}
+// =========================================
+// ATA helper
+// =========================================
+/** Associated Token Account program address. */
+const ATA_PROGRAM_ADDRESS = 'ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL';
+/**
+ * Build a `CreateAssociatedTokenAccountIdempotent` instruction.
+ * Uses instruction index 1 (idempotent variant) of the ATA program.
+ */
+function buildCreateAtaIdempotentIx(payer, ata, owner, mint) {
+    const SYSTEM_PROGRAM = '11111111111111111111111111111111';
+    const TOKEN_PROGRAM = 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA';
+    return {
+        programAddress: ATA_PROGRAM_ADDRESS,
+        accounts: [
+            { address: payer, role: 3 }, // writable signer
+            { address: ata, role: 1 }, // writable
+            { address: owner, role: 0 }, // readonly
+            { address: mint, role: 0 }, // readonly
+            { address: SYSTEM_PROGRAM, role: 0 }, // readonly
+            { address: TOKEN_PROGRAM, role: 0 }, // readonly
+        ],
+        data: new Uint8Array([1]), // CreateIdempotent = instruction discriminator 1
+    };
+}
+// =========================================
+// TokenEscrow client
+// =========================================
+/**
+ * Solana-backed client for the trustless token/vault escrow program. All
+ * write methods require both `rpcSubscriptions` and `signer`; read methods
+ * only need `rpc`.
+ *
+ * Uses the same config shape as {@link ANTEscrow}.
+ */
+export class TokenEscrow {
+    rpc;
+    rpcSubscriptions;
+    signer;
+    programId;
+    coreProgram;
+    commitment;
+    logger;
+    constructor(config) {
+        this.rpc = config.rpc;
+        this.rpcSubscriptions = config.rpcSubscriptions;
+        this.signer = config.signer;
+        this.programId = config.programId ?? ARIO_ANT_ESCROW_PROGRAM_ID;
+        this.coreProgram = config.coreProgram ?? ARIO_CORE_PROGRAM_ID;
+        this.commitment = config.commitment ?? 'confirmed';
+        this.logger = config.logger ?? Logger.default;
+    }
+    static init(config) {
+        return new TokenEscrow(config);
+    }
+    // -------------------------------------------------------------------
+    // Reads
+    // -------------------------------------------------------------------
+    /**
+     * Fetch the on-chain `EscrowToken` for a depositor and asset ID, or
+     * `null` if no active escrow exists. Uses the Codama-generated decoder.
+     */
+    async get(depositor, assetId) {
+        const [pda] = await getEscrowTokenPDA(depositor, assetId, this.programId);
+        const account = await fetchMaybeEscrowToken(this.rpc, pda, {
+            commitment: this.commitment,
+        });
+        if (!account.exists)
+            return null;
+        return toEscrowTokenState(account.data);
+    }
+    /**
+     * Fetch the on-chain `EscrowToken` for a vault escrow, or `null` if
+     * no active escrow exists.
+     */
+    async getVault(depositor, assetId) {
+        const [pda] = await getEscrowVaultPDA(depositor, assetId, this.programId);
+        const account = await fetchMaybeEscrowToken(this.rpc, pda, {
+            commitment: this.commitment,
+        });
+        if (!account.exists)
+            return null;
+        return toEscrowTokenState(account.data);
+    }
+    /** Address of the EscrowToken PDA (no RPC call). */
+    async getTokenPda(depositor, assetId) {
+        const [pda] = await getEscrowTokenPDA(depositor, assetId, this.programId);
+        return pda;
+    }
+    /** Address of the EscrowVault PDA (no RPC call). */
+    async getVaultPda(depositor, assetId) {
+        const [pda] = await getEscrowVaultPDA(depositor, assetId, this.programId);
+        return pda;
+    }
+    // -------------------------------------------------------------------
+    // Write — deposit
+    // -------------------------------------------------------------------
+    /**
+     * Deposit liquid ARIO tokens into escrow for a designated Arweave or
+     * Ethereum recipient. Prepends a create-ATA-idempotent instruction for
+     * the escrow PDA's token account in the same transaction.
+     */
+    async depositTokens(args) {
+        const signer = this.requireSigner('depositTokens');
+        this.assertPubkeyLen(args.recipient);
+        this.assertAssetIdLen(args.assetId);
+        const [escrow] = await getEscrowTokenPDA(signer.address, args.assetId, this.programId);
+        // Derive the escrow PDA's ATA for the ARIO mint.
+        const escrowAta = await getAssociatedTokenAddressKit(args.arioMint, escrow, true);
+        // Prepend create-ATA-idempotent so the escrow token account exists.
+        const createAtaIx = buildCreateAtaIdempotentIx(signer.address, escrowAta, escrow, args.arioMint);
+        const depositIx = getDepositTokensInstruction({
+            escrow,
+            depositorTokenAccount: args.depositorTokenAccount,
+            escrowTokenAccount: escrowAta,
+            arioMint: args.arioMint,
+            depositor: signer,
+            assetId: args.assetId,
+            amount: args.amount,
+            recipientProtocol: protocolToByte(args.recipient.protocol),
+            recipientPubkey: args.recipient.publicKey,
+        }, { programAddress: this.programId });
+        return this.send([createAtaIx, depositIx]);
+    }
+    /**
+     * Deposit ARIO tokens into escrow as a vaulted (time-locked) position.
+     * Same as `depositTokens` but additionally records the lock duration
+     * and revocability flag. Uses the vault PDA seed.
+     */
+    async depositVault(args) {
+        const signer = this.requireSigner('depositVault');
+        this.assertPubkeyLen(args.recipient);
+        this.assertAssetIdLen(args.assetId);
+        const [escrow] = await getEscrowVaultPDA(signer.address, args.assetId, this.programId);
+        const escrowAta = await getAssociatedTokenAddressKit(args.arioMint, escrow, true);
+        const createAtaIx = buildCreateAtaIdempotentIx(signer.address, escrowAta, escrow, args.arioMint);
+        const depositIx = getDepositVaultInstruction({
+            escrow,
+            depositorTokenAccount: args.depositorTokenAccount,
+            escrowTokenAccount: escrowAta,
+            arioMint: args.arioMint,
+            depositor: signer,
+            assetId: args.assetId,
+            amount: args.amount,
+            lockDurationSeconds: args.lockDurationSeconds,
+            revocable: args.revocable,
+            recipientProtocol: protocolToByte(args.recipient.protocol),
+            recipientPubkey: args.recipient.publicKey,
+        }, { programAddress: this.programId });
+        return this.send([createAtaIx, depositIx]);
+    }
+    // -------------------------------------------------------------------
+    // Write — claim
+    // -------------------------------------------------------------------
+    /**
+     * Submit an Arweave RSA-PSS-4096 signature to release escrowed tokens.
+     * Anyone can submit (fee payer = `signer`); only `claimant` receives
+     * the tokens, and `depositor` receives rent.
+     */
+    async claimTokensArweave(args) {
+        const escrow = await this.requireTokenEscrow(args.depositor, args.assetId);
+        if (escrow.recipientProtocol !== 'arweave') {
+            throw new Error(`escrow recipient is ${escrow.recipientProtocol}, not arweave`);
+        }
+        const ix = await this.claimTokensArweaveIx({
+            ...args,
+            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(createAtaIx ? [createAtaIx, ix] : [ix], 400_000);
+    }
+    /**
+     * @deprecated Args `signature`, `saltLen`, `messageNonce` are ignored.
+     * Use the new attested flow — see `claimArweaveIx` doc.
+     */
+    async claimTokensArweaveIx(args) {
+        if (args.messageNonce.length !== 32) {
+            throw new Error('messageNonce must be 32 bytes');
+        }
+        const signer = this.requireSigner('claimTokensArweave');
+        const [escrow] = await getEscrowTokenPDA(args.depositor, args.assetId, this.programId);
+        return getClaimTokensArweaveAttestedInstruction({
+            escrow,
+            escrowTokenAccount: args.escrowTokenAccount,
+            claimantTokenAccount: args.claimantTokenAccount,
+            claimant: args.claimant,
+            depositor: args.depositor,
+            payer: signer,
+            messageNonce: args.messageNonce,
+        }, { programAddress: this.programId });
+    }
+    /**
+     * Submit an Ethereum ECDSA secp256k1 + EIP-191 signature to release
+     * escrowed tokens.
+     */
+    async claimTokensEthereum(args) {
+        const escrow = await this.requireTokenEscrow(args.depositor, args.assetId);
+        if (escrow.recipientProtocol !== 'ethereum') {
+            throw new Error(`escrow recipient is ${escrow.recipientProtocol}, not ethereum`);
+        }
+        const ix = await this.claimTokensEthereumIx({
+            ...args,
+            messageNonce: escrow.nonce,
+        });
+        // 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) {
+            throw new Error('ethereum signature must be 65 bytes (r||s||v)');
+        }
+        if (args.messageNonce.length !== 32) {
+            throw new Error('messageNonce must be 32 bytes');
+        }
+        const signer = this.requireSigner('claimTokensEthereum');
+        const [escrow] = await getEscrowTokenPDA(args.depositor, args.assetId, this.programId);
+        return getClaimTokensEthereumInstruction({
+            escrow,
+            escrowTokenAccount: args.escrowTokenAccount,
+            claimantTokenAccount: args.claimantTokenAccount,
+            claimant: args.claimant,
+            depositor: args.depositor,
+            payer: signer,
+            messageNonce: args.messageNonce,
+            signature: args.signature,
+        }, { programAddress: this.programId });
+    }
+    /**
+     * Submit an Arweave RSA-PSS-4096 signature to release escrowed vault tokens.
+     *
+     * The on-chain handler routes by vault state via instructions-sysvar
+     * introspection: an expired vault sends tokens straight to
+     * `claimantTokenAccount`; an active (still-locked) vault routes them to
+     * `payerTokenAccount` and requires a matching `ario_core::vaulted_transfer`
+     * sibling instruction in the same transaction.
+     *
+     * This method auto-detects the path from `vaultEndTimestamp` and bundles
+     * the sibling `vaulted_transfer` ix automatically when the vault is still
+     * active — callers do not need to construct it themselves.
+     */
+    async claimVaultArweave(args) {
+        const escrow = await this.requireVaultEscrow(args.depositor, args.assetId);
+        if (escrow.recipientProtocol !== 'arweave') {
+            throw new Error(`escrow recipient is ${escrow.recipientProtocol}, not arweave`);
+        }
+        const signer = this.requireSigner('claimVaultArweave');
+        const [escrowPda] = await getEscrowVaultPDA(args.depositor, args.assetId, this.programId);
+        // `args.signature` and `args.saltLen` are no longer fed to the
+        // builder — the on-chain `claim_vault_arweave_attested` ix verifies
+        // the attestor's Ed25519 signature via instruction-introspection
+        // of a preceding sigverify ix. See doc on `claimArweaveIx`.
+        const claimIx = getClaimVaultArweaveAttestedInstruction({
+            escrow: escrowPda,
+            escrowTokenAccount: args.escrowTokenAccount,
+            claimantTokenAccount: args.claimantTokenAccount,
+            payerTokenAccount: args.payerTokenAccount,
+            claimant: args.claimant,
+            depositor: args.depositor,
+            payer: signer,
+            messageNonce: escrow.nonce,
+        }, { programAddress: this.programId });
+        const ixs = await this.maybeBundleVaultedTransfer(escrow, args, claimIx);
+        return this.send(ixs, 400_000);
+    }
+    /**
+     * Submit an Ethereum ECDSA signature to release escrowed vault tokens. See
+     * {@link claimVaultArweave} for the expired/active vault routing semantics.
+     * Auto-bundles the sibling `vaulted_transfer` ix for active vaults.
+     */
+    async claimVaultEthereum(args) {
+        const escrow = await this.requireVaultEscrow(args.depositor, args.assetId);
+        if (escrow.recipientProtocol !== 'ethereum') {
+            throw new Error(`escrow recipient is ${escrow.recipientProtocol}, not ethereum`);
+        }
+        const signer = this.requireSigner('claimVaultEthereum');
+        const [escrowPda] = await getEscrowVaultPDA(args.depositor, args.assetId, this.programId);
+        const claimIx = getClaimVaultEthereumInstruction({
+            escrow: escrowPda,
+            escrowTokenAccount: args.escrowTokenAccount,
+            claimantTokenAccount: args.claimantTokenAccount,
+            payerTokenAccount: args.payerTokenAccount,
+            claimant: args.claimant,
+            depositor: args.depositor,
+            payer: signer,
+            messageNonce: escrow.nonce,
+            signature: args.signature,
+        }, { programAddress: this.programId });
+        const ixs = await this.maybeBundleVaultedTransfer(escrow, args, claimIx);
+        return this.send(ixs);
+    }
+    /**
+     * If the vault escrow is still locked (`vaultEndTimestamp` in the future),
+     * return `[claimIx, vaultedTransferIx]` so the on-chain claim handler can
+     * see the sibling (via `instructions_sysvar`) and re-vault tokens for the
+     * claimant. If the vault has expired, just `[claimIx]` — the on-chain
+     * handler delivers tokens directly to `claimantTokenAccount`.
+     *
+     * **Ordering matters at runtime**: `claim` must execute first so it can
+     * move tokens `escrow → payerTokenAccount`. `vaulted_transfer` then pulls
+     * from `payerTokenAccount` into the new vault. Reversing the order makes
+     * `vaulted_transfer` fail with `insufficient funds` because nothing has
+     * funded `payerTokenAccount` yet. The introspection check in
+     * `vault_introspect::verify_vaulted_transfer_in_tx` is presence-based
+     * (reads `instructions_sysvar`) so the *sibling* ordering doesn't matter
+     * for the check itself — only for atomic execution.
+     *
+     * `lockDurationSeconds` is set to the SDK-local `remaining` value. The
+     * on-chain handler accepts `lock_duration >= remaining_at_execution - 60s`
+     * (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 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) {
+            // 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 getVaultPDA(args.claimant, nextId, this.coreProgram);
+        const vaultATA = await 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 getVaultedTransferInstructionAsync({
+            vault: vaultPda,
+            senderTokenAccount: args.payerTokenAccount,
+            vaultTokenAccount: vaultATA,
+            recipient: args.claimant,
+            sender: signer,
+            amount: escrow.amount,
+            lockDurationSeconds: remaining,
+            revocable: escrow.vaultRevocable,
+        }, { programAddress: this.coreProgram });
+        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). */
+    async getNextVaultId(owner) {
+        const [counterPda] = await getVaultCounterPDA(owner, this.coreProgram);
+        const account = await fetchMaybeVaultCounter(this.rpc, counterPda, {
+            commitment: this.commitment,
+        });
+        return account.exists ? account.data.nextId : 0n;
+    }
+    // -------------------------------------------------------------------
+    // Write — cancel
+    // -------------------------------------------------------------------
+    /**
+     * Cancel a token or vault escrow deposit and return the tokens to the
+     * depositor. Only callable by the original depositor.
+     */
+    async cancel(args) {
+        const signer = this.requireSigner('cancel');
+        this.assertAssetIdLen(args.assetId);
+        const pdaFn = args.assetType === 'vault' ? getEscrowVaultPDA : getEscrowTokenPDA;
+        const [escrow] = await pdaFn(signer.address, args.assetId, this.programId);
+        const ix = args.assetType === 'vault'
+            ? getCancelVaultDepositInstruction({
+                escrow,
+                escrowTokenAccount: args.escrowTokenAccount,
+                depositorTokenAccount: args.depositorTokenAccount,
+                depositor: signer,
+            }, { programAddress: this.programId })
+            : getCancelTokenDepositInstruction({
+                escrow,
+                escrowTokenAccount: args.escrowTokenAccount,
+                depositorTokenAccount: args.depositorTokenAccount,
+                depositor: signer,
+            }, { programAddress: this.programId });
+        return this.send([ix]);
+    }
+    // -------------------------------------------------------------------
+    // Write — update recipient
+    // -------------------------------------------------------------------
+    /**
+     * Re-target the escrow at a new recipient identity. Rotates the
+     * on-chain nonce, invalidating any in-flight claim signatures.
+     */
+    async updateRecipient(args) {
+        const signer = this.requireSigner('updateRecipient');
+        this.assertPubkeyLen(args.newRecipient);
+        this.assertAssetIdLen(args.assetId);
+        const pdaFn = args.assetType === 'vault' ? getEscrowVaultPDA : getEscrowTokenPDA;
+        const [escrow] = await pdaFn(signer.address, args.assetId, this.programId);
+        const ix = args.assetType === 'vault'
+            ? getUpdateVaultRecipientInstruction({
+                escrow,
+                depositor: signer,
+                newProtocol: protocolToByte(args.newRecipient.protocol),
+                newPubkey: args.newRecipient.publicKey,
+            }, { programAddress: this.programId })
+            : getUpdateTokenRecipientInstruction({
+                escrow,
+                depositor: signer,
+                newProtocol: protocolToByte(args.newRecipient.protocol),
+                newPubkey: args.newRecipient.publicKey,
+            }, { programAddress: this.programId });
+        return this.send([ix]);
+    }
+    // -------------------------------------------------------------------
+    // Internals
+    // -------------------------------------------------------------------
+    async send(instructions, computeUnitLimit = 200_000) {
+        const signer = this.requireSigner('send');
+        if (!this.rpcSubscriptions) {
+            throw new Error('TokenEscrow: rpcSubscriptions required for write operations');
+        }
+        return sendAndConfirm({
+            rpc: this.rpc,
+            rpcSubscriptions: this.rpcSubscriptions,
+            signer,
+            instructions,
+            commitment: this.commitment,
+            computeUnitLimit,
+        });
+    }
+    requireSigner(op) {
+        if (!this.signer) {
+            throw new Error(`TokenEscrow.${op}: signer is required for writes`);
+        }
+        return this.signer;
+    }
+    async requireTokenEscrow(depositor, assetId) {
+        const escrow = await this.get(depositor, assetId);
+        if (!escrow) {
+            throw new Error(`no token escrow found for depositor=${depositor}`);
+        }
+        return escrow;
+    }
+    async requireVaultEscrow(depositor, assetId) {
+        const escrow = await this.getVault(depositor, assetId);
+        if (!escrow) {
+            throw new Error(`no vault escrow found for depositor=${depositor}`);
+        }
+        return escrow;
+    }
+    assertPubkeyLen(recipient) {
+        const expected = recipient.protocol === 'arweave'
+            ? ESCROW_ARWEAVE_PUBKEY_LEN
+            : ESCROW_ETHEREUM_PUBKEY_LEN;
+        if (recipient.publicKey.length !== expected) {
+            throw new Error(`recipient.publicKey: expected ${expected} bytes for protocol=${recipient.protocol}, got ${recipient.publicKey.length}`);
+        }
+    }
+    assertAssetIdLen(assetId) {
+        if (assetId.length !== 32) {
+            throw new Error(`assetId must be 32 bytes, got ${assetId.length}`);
+        }
+    }
+}