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

package/lib/cjs/solana/escrow.js

@@ -0,0 +1,744 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenEscrow = exports.ANTEscrow = void 0;
+const logger_js_1 = require("../common/logger.js");
+const ata_js_1 = require("./ata.js");
+const constants_js_1 = require("./constants.js");
+const index_js_1 = require("./generated/ant-escrow/index.js");
+const vaultCounter_js_1 = require("./generated/core/accounts/vaultCounter.js");
+const vaultedTransfer_js_1 = require("./generated/core/instructions/vaultedTransfer.js");
+const pda_js_1 = require("./pda.js");
+const send_js_1 = require("./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 === constants_js_1.ESCROW_PROTOCOL_ARWEAVE ? 'arweave' : 'ethereum';
+    const expectedLen = recipientProtocol === 'arweave'
+        ? constants_js_1.ESCROW_ARWEAVE_PUBKEY_LEN
+        : constants_js_1.ESCROW_ETHEREUM_PUBKEY_LEN;
+    if (raw.recipientProtocol !== constants_js_1.ESCROW_PROTOCOL_ARWEAVE &&
+        raw.recipientProtocol !== constants_js_1.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' ? constants_js_1.ESCROW_PROTOCOL_ARWEAVE : constants_js_1.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`.
+ */
+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 ?? constants_js_1.ARIO_ANT_ESCROW_PROGRAM_ID;
+        this.commitment = config.commitment ?? 'confirmed';
+        this.logger = config.logger ?? logger_js_1.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 (0, pda_js_1.getEscrowAntPDA)(antMint, this.programId);
+        const account = await (0, index_js_1.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 (0, pda_js_1.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 (0, pda_js_1.getEscrowAntPDA)(args.antMint, this.programId);
+        return (0, index_js_1.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 (0, pda_js_1.getEscrowAntPDA)(args.antMint, this.programId);
+        const ix = (0, index_js_1.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 (0, pda_js_1.getEscrowAntPDA)(args.antMint, this.programId);
+        const ix = (0, index_js_1.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);
+    }
+    async claimArweaveIx(args) {
+        if (args.signature.length !== 512) {
+            throw new Error('arweave signature must be 512 bytes');
+        }
+        if (args.messageNonce.length !== 32) {
+            throw new Error('messageNonce must be 32 bytes');
+        }
+        const signer = this.requireSigner('claimArweave');
+        const [escrow] = await (0, pda_js_1.getEscrowAntPDA)(args.antMint, this.programId);
+        return (0, index_js_1.getClaimAntArweaveInstruction)({
+            escrow,
+            antAsset: args.antMint,
+            claimant: args.claimant,
+            depositor: args.depositor,
+            payer: signer,
+            messageNonce: args.messageNonce,
+            signature: args.signature,
+            saltLen: args.saltLen,
+        }, { 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 (0, pda_js_1.getEscrowAntPDA)(args.antMint, this.programId);
+        return (0, index_js_1.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 (0, send_js_1.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'
+            ? constants_js_1.ESCROW_ARWEAVE_PUBKEY_LEN
+            : constants_js_1.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}`);
+        }
+    }
+}
+exports.ANTEscrow = ANTEscrow;
+/** 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 === constants_js_1.ESCROW_PROTOCOL_ARWEAVE ? 'arweave' : 'ethereum';
+    if (raw.recipientProtocol !== constants_js_1.ESCROW_PROTOCOL_ARWEAVE &&
+        raw.recipientProtocol !== constants_js_1.ESCROW_PROTOCOL_ETHEREUM) {
+        throw new Error(`EscrowToken: unknown protocol byte ${raw.recipientProtocol}`);
+    }
+    const expectedLen = recipientProtocol === 'arweave'
+        ? constants_js_1.ESCROW_ARWEAVE_PUBKEY_LEN
+        : constants_js_1.ESCROW_ETHEREUM_PUBKEY_LEN;
+    return {
+        version: raw.version,
+        bump: raw.bump,
+        depositor: raw.depositor,
+        assetType: raw.assetType === constants_js_1.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}.
+ */
+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 ?? constants_js_1.ARIO_ANT_ESCROW_PROGRAM_ID;
+        this.coreProgram = config.coreProgram ?? constants_js_1.ARIO_CORE_PROGRAM_ID;
+        this.commitment = config.commitment ?? 'confirmed';
+        this.logger = config.logger ?? logger_js_1.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 (0, pda_js_1.getEscrowTokenPDA)(depositor, assetId, this.programId);
+        const account = await (0, index_js_1.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 (0, pda_js_1.getEscrowVaultPDA)(depositor, assetId, this.programId);
+        const account = await (0, index_js_1.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 (0, pda_js_1.getEscrowTokenPDA)(depositor, assetId, this.programId);
+        return pda;
+    }
+    /** Address of the EscrowVault PDA (no RPC call). */
+    async getVaultPda(depositor, assetId) {
+        const [pda] = await (0, pda_js_1.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 (0, pda_js_1.getEscrowTokenPDA)(signer.address, args.assetId, this.programId);
+        // Derive the escrow PDA's ATA for the ARIO mint.
+        const escrowAta = await (0, ata_js_1.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 = (0, index_js_1.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 (0, pda_js_1.getEscrowVaultPDA)(signer.address, args.assetId, this.programId);
+        const escrowAta = await (0, ata_js_1.getAssociatedTokenAddressKit)(args.arioMint, escrow, true);
+        const createAtaIx = buildCreateAtaIdempotentIx(signer.address, escrowAta, escrow, args.arioMint);
+        const depositIx = (0, index_js_1.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,
+        });
+        // RSA-PSS-4096 verification is CU-intensive; use 400K.
+        return this.send([ix], 400_000);
+    }
+    async claimTokensArweaveIx(args) {
+        if (args.signature.length !== 512) {
+            throw new Error('arweave signature must be 512 bytes');
+        }
+        if (args.messageNonce.length !== 32) {
+            throw new Error('messageNonce must be 32 bytes');
+        }
+        const signer = this.requireSigner('claimTokensArweave');
+        const [escrow] = await (0, pda_js_1.getEscrowTokenPDA)(args.depositor, args.assetId, this.programId);
+        return (0, index_js_1.getClaimTokensArweaveInstruction)({
+            escrow,
+            escrowTokenAccount: args.escrowTokenAccount,
+            claimantTokenAccount: args.claimantTokenAccount,
+            claimant: args.claimant,
+            depositor: args.depositor,
+            payer: signer,
+            messageNonce: args.messageNonce,
+            signature: args.signature,
+            saltLen: args.saltLen,
+        }, { 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,
+        });
+        return this.send([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 (0, pda_js_1.getEscrowTokenPDA)(args.depositor, args.assetId, this.programId);
+        return (0, index_js_1.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 (0, pda_js_1.getEscrowVaultPDA)(args.depositor, args.assetId, this.programId);
+        const claimIx = (0, index_js_1.getClaimVaultArweaveInstruction)({
+            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,
+            saltLen: args.saltLen ?? 32,
+        }, { 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 (0, pda_js_1.getEscrowVaultPDA)(args.depositor, args.assetId, this.programId);
+        const claimIx = (0, index_js_1.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.
+     */
+    async maybeBundleVaultedTransfer(escrow, args, claimIx) {
+        const nowSeconds = BigInt(Math.floor(Date.now() / 1000));
+        const remaining = escrow.vaultEndTimestamp - nowSeconds;
+        if (remaining <= 0n) {
+            return [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);
+        const vaultedIx = await (0, vaultedTransfer_js_1.getVaultedTransferInstructionAsync)({
+            vault: vaultPda,
+            senderTokenAccount: args.payerTokenAccount,
+            vaultTokenAccount: vaultATA,
+            recipient: args.claimant,
+            sender: signer,
+            amount: escrow.amount,
+            lockDurationSeconds: remaining,
+            revocable: escrow.vaultRevocable,
+        }, { programAddress: this.coreProgram });
+        return [claimIx, 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 (0, pda_js_1.getVaultCounterPDA)(owner, this.coreProgram);
+        const account = await (0, vaultCounter_js_1.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' ? pda_js_1.getEscrowVaultPDA : pda_js_1.getEscrowTokenPDA;
+        const [escrow] = await pdaFn(signer.address, args.assetId, this.programId);
+        const ix = args.assetType === 'vault'
+            ? (0, index_js_1.getCancelVaultDepositInstruction)({
+                escrow,
+                escrowTokenAccount: args.escrowTokenAccount,
+                depositorTokenAccount: args.depositorTokenAccount,
+                depositor: signer,
+            }, { programAddress: this.programId })
+            : (0, index_js_1.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' ? pda_js_1.getEscrowVaultPDA : pda_js_1.getEscrowTokenPDA;
+        const [escrow] = await pdaFn(signer.address, args.assetId, this.programId);
+        const ix = args.assetType === 'vault'
+            ? (0, index_js_1.getUpdateVaultRecipientInstruction)({
+                escrow,
+                depositor: signer,
+                newProtocol: protocolToByte(args.newRecipient.protocol),
+                newPubkey: args.newRecipient.publicKey,
+            }, { programAddress: this.programId })
+            : (0, index_js_1.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 (0, send_js_1.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'
+            ? constants_js_1.ESCROW_ARWEAVE_PUBKEY_LEN
+            : constants_js_1.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}`);
+        }
+    }
+}
+exports.TokenEscrow = TokenEscrow;