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

package/lib/esm/solana/escrow.js

@@ -0,0 +1,839 @@
+/**
+ * Copyright (C) 2022-2024 Permanent Data Solutions, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Solana 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 { 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, } 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}`);
+        }
+    }
+}
+/**
+ * Forward clock-skew buffer (seconds) added to `vault_end_timestamp` before
+ * the SDK considers a vault claimable. The SDK reads wall-clock time
+ * (`Date.now()`) while the on-chain gate reads Solana cluster time, and
+ * the two can disagree by several seconds. The buffer biases every skew
+ * race into the *friendly* direction: the SDK rejects when the chain
+ * would actually accept (user retries 30s later, succeeds), never the
+ * reverse (user submits a doomed tx and sees the raw on-chain error).
+ *
+ * 30s is conservative — Solana cluster clock typically drifts <2s vs
+ * wall clock — but matches the order of magnitude of the previously-used
+ * `60s` introspection tolerance in the removed `vault_introspect` module.
+ */
+export const CLOCK_SKEW_TOLERANCE_SECONDS = 30n;
+/**
+ * Returns `true` when a vault escrow is past its unlock timestamp by at
+ * least {@link CLOCK_SKEW_TOLERANCE_SECONDS}. Non-throwing companion to
+ * {@link assertVaultClaimable} for UI gating (e.g. enabling/disabling a
+ * Submit button without showing an error).
+ */
+export function isVaultClaimable(escrow) {
+    const nowSeconds = BigInt(Math.floor(Date.now() / 1000));
+    return nowSeconds >= escrow.vaultEndTimestamp + CLOCK_SKEW_TOLERANCE_SECONDS;
+}
+/**
+ * Pre-flight the on-chain `VaultStillLocked` gate (ADR-022): refuse to build
+ * a claim tx while the vault is still locked, with a small forward
+ * {@link CLOCK_SKEW_TOLERANCE_SECONDS} buffer so wall/cluster clock skew
+ * biases into the friendly direction. Surfaces the unlock timestamp so
+ * callers / UIs can show "claimable after <date>" instead of a doomed tx.
+ *
+ * Exported for unit-testability; not part of the public SDK surface — call the
+ * high-level `claimVaultArweave` / `claimVaultEthereum` instead, which invoke
+ * this guard internally.
+ *
+ * @internal
+ */
+export function assertVaultClaimable(escrow) {
+    if (!isVaultClaimable(escrow)) {
+        const unlockIso = new Date(Number(escrow.vaultEndTimestamp) * 1000).toISOString();
+        throw new Error(`Vault escrow is still locked until ${unlockIso} ` +
+            `(vault_end_timestamp=${escrow.vaultEndTimestamp}; ` +
+            `the SDK adds a ${CLOCK_SKEW_TOLERANCE_SECONDS}s clock-skew buffer ` +
+            `before allowing a claim). Active (still-locked) vault claims are ` +
+            `rejected on-chain with VaultStillLocked (ADR-022) — wait until ` +
+            `after the unlock timestamp + buffer, then claim again to receive ` +
+            `the tokens liquid.`);
+    }
+}
+/** 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 });
+    }
+    /**
+     * **Use {@link claimVaultArweaveIx} instead** — this single-send wrapper
+     * cannot work end-to-end for the Arweave attested vault-claim path,
+     * because the on-chain `claim_vault_arweave_attested` handler requires
+     * an Ed25519Program native sigverify ix at idx-1 of the claim ix
+     * (introspected via `instructions_sysvar`). That sigverify ix carries
+     * the attestor's Ed25519 signature over the canonical claim message
+     * and is built by the *integrator* (who calls the off-chain attestor
+     * service for the signature, per ADR-017) — the SDK has no attestor
+     * URL or client to do this for the caller.
+     *
+     * Calling this method instead of composing via
+     * {@link claimVaultArweaveIx} will hit `MissingAttestation` on-chain.
+     * It is kept only for ABI continuity; new code must use
+     * {@link claimVaultArweaveIx} and prepend the attestor sigverify ix.
+     *
+     * @deprecated cannot succeed alone — see {@link claimVaultArweaveIx}.
+     */
+    async claimVaultArweave(_args) {
+        throw new Error('claimVaultArweave cannot complete the Arweave attested vault-claim ' +
+            'in a single SDK call: the on-chain handler requires an ' +
+            'Ed25519Program sigverify ix at idx-1 of the claim ix, which ' +
+            'must carry the attestor service’s signature over the canonical ' +
+            'claim message (ADR-017). The SDK does not know your attestor URL. ' +
+            'Use claimVaultArweaveIx() instead and bundle the sigverify ix ' +
+            'yourself: ' +
+            '[createAtaIx?, ed25519SigverifyIx, claimVaultArweaveIx, ...]. ' +
+            'See ar-io-solana-escrow-app/src/pages/ClaimPage.tsx for the ' +
+            'reference composition, and ADR-022 / VaultStillLocked for the ' +
+            'still-locked rejection (use isVaultClaimable() to pre-flight).');
+    }
+    /**
+     * Build a `claim_vault_arweave_attested` instruction (without sending).
+     * Mirror of {@link claimTokensArweaveIx} for the vault-claim path:
+     * returns the bare claim ix so the caller can prepend the attestor's
+     * Ed25519Program sigverify ix and submit the bundle in one tx.
+     *
+     * The on-chain handler:
+     * - Reads the preceding Ed25519Program native sigverify ix from
+     *   `instructions_sysvar` to confirm the attestor signed the canonical
+     *   claim message.
+     * - Rejects with `VaultStillLocked` if `clock < vault_end_timestamp`
+     *   (ADR-022). Callers should pre-flight with {@link isVaultClaimable}
+     *   (non-throwing) or {@link assertVaultClaimable} (throws with the
+     *   unlock timestamp) before composing the tx.
+     * - On the expired path, transfers the escrowed amount liquid to
+     *   `claimantTokenAccount` and closes the escrow PDA.
+     *
+     * Composition (frontend pattern):
+     *   ```ts
+     *   const escrow = await tokenEscrow.requireVaultEscrow(depositor, assetId);
+     *   assertVaultClaimable(escrow);                       // pre-flight
+     *   const canonical = canonicalMessage({ ... });        // build message
+     *   const attestation = await attestor.attest({ ... }); // attestor service
+     *   const ed25519Ix = buildEd25519SigverifyIx(
+     *     attestation.attestorPubkey, attestation.signature, canonical,
+     *   );
+     *   const claimIx = await tokenEscrow.claimVaultArweaveIx({
+     *     depositor, assetId, claimant, claimantTokenAccount,
+     *     escrowTokenAccount, messageNonce: escrow.nonce,
+     *   });
+     *   // Idempotent-create the claimant ATA if it's the canonical derivation.
+     *   await sendTx([createAtaIx?, ed25519Ix, claimIx]);
+     *   ```
+     */
+    async claimVaultArweaveIx(args) {
+        if (args.messageNonce.length !== 32) {
+            throw new Error('messageNonce must be 32 bytes');
+        }
+        const signer = this.requireSigner('claimVaultArweaveIx');
+        const [escrowPda] = await getEscrowVaultPDA(args.depositor, args.assetId, this.programId);
+        return getClaimVaultArweaveAttestedInstruction({
+            escrow: escrowPda,
+            escrowTokenAccount: args.escrowTokenAccount,
+            claimantTokenAccount: args.claimantTokenAccount,
+            claimant: args.claimant,
+            depositor: args.depositor,
+            payer: signer,
+            messageNonce: args.messageNonce,
+        }, { programAddress: this.programId });
+    }
+    /**
+     * Submit an Ethereum ECDSA signature to release escrowed vault tokens. See
+     * {@link claimVaultArweave} — same lock semantics: vaults are only claimable
+     * after `vault_end_timestamp`; active (still-locked) claims throw pre-flight
+     * and are rejected on-chain with `VaultStillLocked` (ADR-022 / BD-107).
+     */
+    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`);
+        }
+        assertVaultClaimable(escrow);
+        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,
+            claimant: args.claimant,
+            depositor: args.depositor,
+            payer: signer,
+            messageNonce: escrow.nonce,
+            signature: args.signature,
+        }, { programAddress: this.programId });
+        const createClaimantAtaIx = await this._createClaimantAtaIfCanonical(args.claimant, args.claimantTokenAccount, escrow.arioMint);
+        const ixs = createClaimantAtaIx
+            ? [createClaimantAtaIx, claimIx]
+            : [claimIx];
+        return this.send(ixs);
+    }
+    /**
+    /**
+     * Idempotent-create the claimant's canonical ATA when needed.
+     *
+     * The claim handler delivers liquid tokens directly to
+     * `claimantTokenAccount` (post-ADR-022 there's only the liquid path for
+     * vaults). 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);
+    }
+    // -------------------------------------------------------------------
+    // 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}`);
+        }
+    }
+}