@veilo/sdk-core 0.3.3 → 0.4.0

package/dist/src/client.js

@@ -0,0 +1,951 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPoolPdas = getPoolPdas;
+exports.getNoteTreePda = getNoteTreePda;
+exports.getGlobalConfigPda = getGlobalConfigPda;
+exports.getNullifierMarkerPda = getNullifierMarkerPda;
+exports.fetchPoolConfig = fetchPoolConfig;
+exports.checkNullifierSpent = checkNullifierSpent;
+exports.getTreeInfo = getTreeInfo;
+exports.getAllTreeInfo = getAllTreeInfo;
+exports.getBestTreeForDeposit = getBestTreeForDeposit;
+exports.parseOnChainError = parseOnChainError;
+exports.initializeGlobalConfig = initializeGlobalConfig;
+exports.initializePool = initializePool;
+exports.updatePoolConfig = updatePoolConfig;
+exports.addMerkleTree = addMerkleTree;
+exports.getPoolConfig = getPoolConfig;
+exports.addRelayer = addRelayer;
+exports.setPaused = setPaused;
+exports.transact = transact;
+exports.deposit = deposit;
+exports.withdraw = withdraw;
+exports.privateTransfer = privateTransfer;
+exports.updateGlobalConfig = updateGlobalConfig;
+exports.getSwapExecutorPda = getSwapExecutorPda;
+exports.fundNativeSource = fundNativeSource;
+exports.transactSwap = transactSwap;
+const anchor = __importStar(require("@coral-xyz/anchor"));
+// Pulled off the namespace rather than named-imported. @coral-xyz/anchor is CJS
+// with no `exports` map, and Node ESM's named-export detection cannot see `BN`
+// (it is re-exported from bn.js), so `import { BN }` throws at runtime under ESM.
+const { BN } = anchor;
+const web3_js_1 = require("@solana/web3.js");
+const spl_token_1 = require("@solana/spl-token");
+const proof_js_1 = require("./proof.js");
+const utxo_js_1 = require("./utxo.js");
+const config_js_1 = require("./config.js");
+const retry_js_1 = require("./retry.js");
+// -----------------------------------------------------------------------------
+// PDA Helpers
+// -----------------------------------------------------------------------------
+/**
+ * Get pool PDAs for a given mint address.
+ * Note: All seeds use "v3" suffix.
+ */
+function getPoolPdas(programId, mintAddress) {
+    const [config] = web3_js_1.PublicKey.findProgramAddressSync([Buffer.from("privacy_config_v3"), mintAddress.toBuffer()], programId);
+    const [vault] = web3_js_1.PublicKey.findProgramAddressSync([Buffer.from("privacy_vault_v3"), mintAddress.toBuffer()], programId);
+    const [nullifiers] = web3_js_1.PublicKey.findProgramAddressSync([Buffer.from("privacy_nullifiers_v3"), mintAddress.toBuffer()], programId);
+    return { config, vault, nullifiers };
+}
+/**
+ * Get the note tree PDA for a specific tree ID.
+ */
+function getNoteTreePda(programId, mintAddress, treeId) {
+    const treeIdBuffer = Buffer.alloc(2);
+    treeIdBuffer.writeUInt16LE(treeId);
+    const [noteTree] = web3_js_1.PublicKey.findProgramAddressSync([Buffer.from("privacy_note_tree_v3"), mintAddress.toBuffer(), treeIdBuffer], programId);
+    return noteTree;
+}
+/**
+ * Get the global config PDA.
+ */
+function getGlobalConfigPda(programId) {
+    const [globalConfig] = web3_js_1.PublicKey.findProgramAddressSync([Buffer.from("global_config_v1")], programId);
+    return globalConfig;
+}
+/**
+ * Get the nullifier marker PDA for a specific nullifier.
+ * NOTE: Nullifier markers are global (no tree_id) to prevent cross-tree double-spend.
+ */
+function getNullifierMarkerPda(programId, mintAddress, nullifier) {
+    const [marker] = web3_js_1.PublicKey.findProgramAddressSync([Buffer.from("nullifier_v3"), mintAddress.toBuffer(), nullifier], programId);
+    return marker;
+}
+// -----------------------------------------------------------------------------
+// On-Chain Account Fetchers
+// -----------------------------------------------------------------------------
+/**
+ * Fetch and decode the on-chain PrivacyConfig account for a pool.
+ */
+async function fetchPoolConfig(program, mintAddress) {
+    const { config } = getPoolPdas(program.programId, mintAddress);
+    return program.account.privacyConfig.fetch(config);
+}
+/**
+ * Check whether a nullifier has been spent on-chain.
+ * Returns true if the nullifier marker PDA exists (funds already spent).
+ */
+async function checkNullifierSpent(program, mintAddress, nullifier) {
+    const marker = getNullifierMarkerPda(program.programId, mintAddress, nullifier);
+    const info = await program.provider.connection.getAccountInfo(marker);
+    return info !== null;
+}
+const TREE_CAPACITY = Math.pow(2, 22); // 4,194,304 leaves (depth 22)
+/**
+ * Fetch utilization info for a specific tree.
+ * Returns null if the tree does not exist yet.
+ */
+async function getTreeInfo(program, mintAddress, treeId) {
+    try {
+        const treePDA = getNoteTreePda(program.programId, mintAddress, treeId);
+        const tree = await program.account.merkleTreeAccount.fetch(treePDA);
+        const leafCount = Number(tree.nextIndex);
+        const remainingCapacity = TREE_CAPACITY - leafCount;
+        return {
+            treeId,
+            leafCount,
+            capacity: TREE_CAPACITY,
+            utilizationPercent: (leafCount / TREE_CAPACITY) * 100,
+            remainingCapacity,
+            isFull: leafCount >= TREE_CAPACITY,
+            treePDA,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Fetch utilization info for all trees in a pool.
+ */
+async function getAllTreeInfo(program, mintAddress) {
+    try {
+        const { config } = getPoolPdas(program.programId, mintAddress);
+        const cfg = await program.account.privacyConfig.fetch(config);
+        const numTrees = Number(cfg.numTrees);
+        const results = [];
+        for (let id = 0; id < numTrees; id++) {
+            const info = await getTreeInfo(program, mintAddress, id);
+            if (info)
+                results.push(info);
+        }
+        return results;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Find the best tree to deposit into.
+ *
+ * Strategy (matches veilo-dapp):
+ * 1. Discard full trees.
+ * 2. Prefer the LOWEST tree ID with remaining capacity ≥ minCapacity (default 0.01%).
+ * 3. Ensures trees fill sequentially: 0 → 1 → 2 → …
+ * 4. Fallback to the tree with the most remaining capacity.
+ */
+async function getBestTreeForDeposit(program, mintAddress, minCapacity = Math.floor(TREE_CAPACITY * 0.0001)) {
+    const trees = await getAllTreeInfo(program, mintAddress);
+    const available = trees.filter((t) => !t.isFull);
+    if (available.length === 0)
+        return null;
+    // Prefer lowest-id tree that still has meaningful capacity
+    const preferred = available
+        .filter((t) => t.remainingCapacity >= minCapacity)
+        .sort((a, b) => a.treeId - b.treeId);
+    if (preferred.length > 0)
+        return preferred[0];
+    // Fallback: most remaining capacity
+    return available.sort((a, b) => b.remainingCapacity - a.remainingCapacity)[0];
+}
+// -----------------------------------------------------------------------------
+// Error Parsing
+// -----------------------------------------------------------------------------
+/**
+ * Convert a Solana/Anchor transaction error into a user-friendly message.
+ * Maps privacy_pool program error codes (6000–6060) to readable strings.
+ * Mirrors relayer-server/src/controllers/transaction.helpers.ts `parseOnChainError`.
+ */
+function parseOnChainError(error) {
+    const raw = (error?.message ?? error?.toString() ?? "").toLowerCase();
+    const hexMatch = raw.match(/custom program error:\s*0x([0-9a-f]+)/);
+    const numMatch = raw.match(/error number:\s*(\d+)/);
+    const code = hexMatch
+        ? parseInt(hexMatch[1], 16)
+        : numMatch
+            ? parseInt(numMatch[1], 10)
+            : null;
+    const PROGRAM_ERRORS = {
+        6000: "The pool is temporarily paused. Please try again later.",
+        6001: "No denominations configured for this pool.",
+        6002: "Too many denominations configured.",
+        6003: "Bad denomination index.",
+        6004: "Math overflow in the contract. Please try again.",
+        6005: "These funds have already been spent.",
+        6006: "The nullifier table is full. Please contact support.",
+        6007: "The relayer is out of sync with the network. Please wait a moment and try again.",
+        6008: "This relayer is not authorised for this pool.",
+        6009: "The pool does not have enough funds to fulfil this request.",
+        6010: "Too many relayers registered for this pool.",
+        6011: "Proof encoding is invalid. Please try again.",
+        6012: "Zero-knowledge proof verification failed. Please try again.",
+        6013: "The pool is at capacity. Please try again later.",
+        6014: "Merkle hash computation failed. Please try again.",
+        6015: "Transaction data mismatch. Please refresh and try again.",
+        6016: "Recipient address mismatch.",
+        6017: "Invalid token address.",
+        6018: "The fee exceeds the allowed limit.",
+        6019: "The relayer fee was insufficient. Please try again.",
+        6020: "Arithmetic error in the contract. Please try again.",
+        6021: "Your balance is not enough to cover the withdrawal including network fees.",
+        6022: "Your balance is not enough to cover the fee.",
+        6023: "Invalid transaction amount. Please try again.",
+        6024: "Invalid fee amount. Please try again.",
+        6025: "Duplicate fund inputs detected. Please refresh and try again.",
+        6026: "Duplicate output detected. Please refresh and try again.",
+        6027: "Token account required for SPL token operations.",
+        6028: "Token program required for SPL token operations.",
+        6029: "Invalid token account authority.",
+        6030: "Relayer account does not match the expected relayer.",
+        6031: "Relayer token account not owned by the expected relayer.",
+        6032: "Recipient token account not owned by the expected recipient.",
+        6033: "Depositor token account not owned or delegated to the relayer.",
+        6034: "Private transfers must have zero fee and refund.",
+        6035: "Amount is below the pool minimum.",
+        6036: "Amount exceeds the pool maximum.",
+        6037: "Withdrawal amount is below the pool minimum.",
+        6038: "Withdrawal amount exceeds the pool maximum.",
+        6039: "Invalid pool configuration: minimum exceeds maximum.",
+        6040: "Fee basis points exceed the maximum allowed (1%).",
+        6041: "Fee error margin exceeds the maximum allowed (50%).",
+        6042: "Only the authorized admin can initialize.",
+        6043: "Unauthorized: only admin or relayers can perform this action.",
+        6044: "Invalid tree ID: tree does not exist.",
+        6045: "Maximum number of Merkle trees reached for this pool.",
+        6046: "Deposits must use zero nullifiers (no notes consumed).",
+        6047: "Nullifier cannot be zero for withdrawals or transfers.",
+        6048: "Output commitment cannot be zero.",
+        6049: "Token account must be owned by SPL Token Program.",
+        6050: "Vault token account must be the canonical Associated Token Account.",
+        6051: "Amount is too small to cover the minimum fee. Try a larger amount.",
+        6052: "Nullifier marker account does not correspond to zero nullifier for deposits.",
+        6053: "Insufficient token delegation for deposit.",
+        6054: "Invalid swap program. Please try again.",
+        6055: "Invalid swap accounts. Please refresh and try again.",
+        6056: "Jupiter swap requires additional routing accounts.",
+        6057: "Swap instruction is invalid or unsupported. Please try again.",
+        6058: "Swap parameters are inconsistent. Please refresh and try again.",
+        6059: "Missing required swap instructions in transaction. Both fund_native_source and transact_swap must be present.",
+        6060: "The transaction deadline expired. Please try again.",
+    };
+    if (code !== null && PROGRAM_ERRORS[code])
+        return PROGRAM_ERRORS[code];
+    if (raw.includes("blockhash not found") ||
+        raw.includes("block height exceeded"))
+        return "The transaction expired before it could be confirmed. Please try again.";
+    if (raw.includes("insufficient funds") ||
+        raw.includes("insufficient lamports"))
+        return "Insufficient SOL to pay for the transaction fee.";
+    if (raw.includes("timeout") || raw.includes("timed out"))
+        return "The request timed out. Please try again.";
+    if (raw.includes("simulation failed"))
+        return "Transaction simulation failed. Please refresh and try again.";
+    return "The transaction could not be completed. Your funds are safe — please try again.";
+}
+// -----------------------------------------------------------------------------
+// Global Config Initialization
+// -----------------------------------------------------------------------------
+/**
+ * Initialize the global config (one-time setup).
+ */
+async function initializeGlobalConfig(params) {
+    const { program, admin, payer } = params;
+    const globalConfig = getGlobalConfigPda(program.programId);
+    await program.methods
+        .initializeGlobalConfig()
+        .accounts({
+        globalConfig,
+        admin: admin.publicKey,
+        payer: payer.publicKey,
+        systemProgram: web3_js_1.SystemProgram.programId,
+    })
+        .signers([payer])
+        .rpc();
+}
+// -----------------------------------------------------------------------------
+// Pool Initialization
+// -----------------------------------------------------------------------------
+/**
+ * Initialize a privacy pool with the new parameters.
+ * Creates the first merkle tree (tree ID 0).
+ */
+async function initializePool(params) {
+    const { program, admin, payer, feeBps, mintAddress, minDepositAmount, maxDepositAmount, minWithdrawAmount, maxWithdrawAmount, } = params;
+    const { config, vault, nullifiers } = getPoolPdas(program.programId, mintAddress);
+    const noteTree = getNoteTreePda(program.programId, mintAddress, 0);
+    await program.methods
+        .initialize(feeBps, mintAddress, minDepositAmount ? new BN(minDepositAmount.toString()) : null, maxDepositAmount ? new BN(maxDepositAmount.toString()) : null, minWithdrawAmount ? new BN(minWithdrawAmount.toString()) : null, maxWithdrawAmount ? new BN(maxWithdrawAmount.toString()) : null)
+        .accounts({
+        config,
+        vault,
+        noteTree,
+        nullifiers,
+        admin: admin.publicKey,
+        payer: payer.publicKey,
+        systemProgram: web3_js_1.SystemProgram.programId,
+    })
+        .signers([payer])
+        .rpc();
+}
+// -----------------------------------------------------------------------------
+// Pool Config Updates
+// -----------------------------------------------------------------------------
+/**
+ * Update pool configuration.
+ */
+async function updatePoolConfig(params) {
+    const { program, admin, mintAddress, minDepositAmount, maxDepositAmount, minWithdrawAmount, maxWithdrawAmount, feeBps, feeErrorMarginBps, minWithdrawalFee, minSwapFee, swapFeeBps, } = params;
+    const { config } = getPoolPdas(program.programId, mintAddress);
+    await program.methods
+        .updatePoolConfig(mintAddress, minDepositAmount ? new BN(minDepositAmount.toString()) : null, maxDepositAmount ? new BN(maxDepositAmount.toString()) : null, minWithdrawAmount ? new BN(minWithdrawAmount.toString()) : null, maxWithdrawAmount ? new BN(maxWithdrawAmount.toString()) : null, feeBps != null ? new BN(feeBps) : null, minWithdrawalFee ? new BN(minWithdrawalFee.toString()) : null, feeErrorMarginBps != null ? new BN(feeErrorMarginBps) : null, minSwapFee ? new BN(minSwapFee.toString()) : null, swapFeeBps != null ? new BN(swapFeeBps) : null)
+        .accounts({
+        config,
+        admin: admin.publicKey,
+    })
+        .rpc();
+}
+/**
+ * Add a new Merkle tree to the pool.
+ * The treeId must equal the current num_trees value in the pool config.
+ */
+async function addMerkleTree(params) {
+    const { program, relayer, mintAddress, treeId } = params;
+    const { config } = getPoolPdas(program.programId, mintAddress);
+    const noteTree = getNoteTreePda(program.programId, mintAddress, treeId);
+    await program.methods
+        .addMerkleTree(mintAddress, treeId)
+        .accounts({
+        config,
+        noteTree,
+        relayer: relayer.publicKey,
+        systemProgram: web3_js_1.SystemProgram.programId,
+    })
+        .signers([relayer])
+        .rpc();
+}
+/**
+ * Get the pool configuration account.
+ */
+async function getPoolConfig(program, mintAddress) {
+    const { config } = getPoolPdas(program.programId, mintAddress);
+    const account = await program.account.privacyConfig.fetch(config);
+    return {
+        bump: account.bump,
+        vaultBump: account.vaultBump,
+        admin: account.admin,
+        feeBps: account.feeBps,
+        feeErrorMarginBps: account.feeErrorMarginBps,
+        minWithdrawalFee: BigInt(account.minWithdrawalFee.toString()),
+        minSwapFee: account.minSwapFee != null ? BigInt(account.minSwapFee.toString()) : 0n,
+        swapFeeBps: account.swapFeeBps ?? 0,
+        totalTvl: BigInt(account.totalTvl.toString()),
+        mintAddress: account.mintAddress,
+        minDepositAmount: BigInt(account.minDepositAmount.toString()),
+        maxDepositAmount: BigInt(account.maxDepositAmount.toString()),
+        minWithdrawAmount: BigInt(account.minWithdrawAmount.toString()),
+        maxWithdrawAmount: BigInt(account.maxWithdrawAmount.toString()),
+        numRelayers: account.numRelayers,
+        relayers: account.relayers,
+        numTrees: account.numTrees,
+        nextTreeIndex: account.nextTreeIndex,
+    };
+}
+// -----------------------------------------------------------------------------
+// Relayer Management
+// -----------------------------------------------------------------------------
+/**
+ * Add a relayer to the pool.
+ */
+async function addRelayer(params) {
+    const { program, admin, mintAddress, newRelayer } = params;
+    const { config } = getPoolPdas(program.programId, mintAddress);
+    await program.methods
+        .addRelayer(mintAddress, newRelayer)
+        .accounts({
+        config,
+        admin: admin.publicKey,
+    })
+        .rpc();
+}
+// -----------------------------------------------------------------------------
+// Pause/Unpause
+// -----------------------------------------------------------------------------
+/**
+ * Set the paused state of a pool.
+ */
+async function setPaused(params) {
+    const { program, admin, mintAddress, paused } = params;
+    const { config } = getPoolPdas(program.programId, mintAddress);
+    await program.methods
+        .setPaused(mintAddress, paused)
+        .accounts({
+        config,
+        admin: admin.publicKey,
+    })
+        .rpc();
+}
+// -----------------------------------------------------------------------------
+// Main Transaction Instruction
+// -----------------------------------------------------------------------------
+/**
+ * Execute a transaction on the privacy pool.
+ * This is the low-level function that calls the on-chain `transact` instruction.
+ *
+ * @param publicAmount - Positive for deposits, negative for withdrawals, 0 for transfers
+ * @param inputTreeId - The tree ID where input UTXOs are located
+ * @param outputTreeId - The tree ID where output commitments will be inserted
+ */
+async function transact(params) {
+    const { program, relayer, recipient, mintAddress, root, inputTreeId, outputTreeId, publicAmount, inputNullifiers, outputCommitments, extData, proof, deadline = 0n, vaultTokenAccount, userTokenAccount, recipientTokenAccount, relayerTokenAccount, } = params;
+    const { config, vault, nullifiers } = getPoolPdas(program.programId, mintAddress);
+    const globalConfig = getGlobalConfigPda(program.programId);
+    const inputTree = getNoteTreePda(program.programId, mintAddress, inputTreeId);
+    const outputTree = getNoteTreePda(program.programId, mintAddress, outputTreeId);
+    // Nullifier markers are global (no tree_id) to prevent cross-tree double-spend
+    const nullifierMarker0 = getNullifierMarkerPda(program.programId, mintAddress, inputNullifiers[0]);
+    const nullifierMarker1 = getNullifierMarkerPda(program.programId, mintAddress, inputNullifiers[1]);
+    const extDataHash = (0, proof_js_1.computeExtDataHash)(extData);
+    const isNativeSol = mintAddress.equals(config_js_1.NATIVE_SOL_MINT);
+    // For SPL tokens, resolve token accounts
+    let vaultTA = vaultTokenAccount;
+    let userTA = userTokenAccount;
+    let recipientTA = recipientTokenAccount;
+    let relayerTA = relayerTokenAccount;
+    if (!isNativeSol) {
+        if (!vaultTA) {
+            vaultTA = await (0, spl_token_1.getAssociatedTokenAddress)(mintAddress, vault, true);
+        }
+        if (!userTA) {
+            userTA = await (0, spl_token_1.getAssociatedTokenAddress)(mintAddress, relayer.publicKey);
+        }
+        if (!recipientTA) {
+            recipientTA = await (0, spl_token_1.getAssociatedTokenAddress)(mintAddress, recipient);
+        }
+        if (!relayerTA) {
+            relayerTA = await (0, spl_token_1.getAssociatedTokenAddress)(mintAddress, relayer.publicKey);
+        }
+    }
+    const tx = program.methods
+        .transact(Array.from(root), inputTreeId, outputTreeId, new BN(publicAmount.toString()), Array.from(extDataHash), mintAddress, Array.from(inputNullifiers[0]), Array.from(inputNullifiers[1]), Array.from(outputCommitments[0]), Array.from(outputCommitments[1]), new BN(deadline.toString()), {
+        recipient: extData.recipient,
+        relayer: extData.relayer,
+        fee: new BN(extData.fee.toString()),
+        refund: new BN(extData.refund.toString()),
+    }, {
+        proofA: proof.proofA,
+        proofB: proof.proofB,
+        proofC: proof.proofC,
+    })
+        .accounts({
+        config,
+        globalConfig,
+        vault,
+        inputTree,
+        outputTree,
+        nullifiers,
+        nullifierMarker0,
+        nullifierMarker1,
+        relayer: relayer.publicKey,
+        recipient,
+        vaultTokenAccount: vaultTA ?? vault,
+        userTokenAccount: userTA ?? relayer.publicKey,
+        recipientTokenAccount: recipientTA ?? recipient,
+        relayerTokenAccount: relayerTA ?? relayer.publicKey,
+        tokenProgram: isNativeSol ? web3_js_1.SystemProgram.programId : spl_token_1.TOKEN_PROGRAM_ID,
+        systemProgram: web3_js_1.SystemProgram.programId,
+    })
+        .signers([relayer]);
+    return (0, retry_js_1.withRpcRetry)(() => tx.rpc());
+}
+/**
+ * Build an unsigned deposit {@link Transaction} for the privacy pool.
+ *
+ * For deposits, we use zero input UTXOs (amount=0) and create output UTXOs
+ * with the deposit amount. `publicAmount` is positive. The caller is
+ * responsible for signing and submitting the returned transaction, and then
+ * calling `commit()` once it confirms.
+ *
+ * @param amount - Amount to deposit in lamports/token units
+ * @param recipientPubkey - UTXO public key that will own the deposited funds
+ * @param treeId - The tree ID to deposit into (defaults to 0)
+ */
+async function deposit(params) {
+    const { program, depositor, amount, mintAddress, recipientPubkey, tree, proofBuilder, treeId = 0, extData: partialExtData, } = params;
+    // Create a random keypair for the zero inputs (they don't matter since amount is 0)
+    const zeroKeypair = (0, utxo_js_1.generateKeypair)();
+    // Create zero input UTXOs (for deposits, we don't spend any existing UTXOs)
+    const zeroInput0 = (0, utxo_js_1.createOwnedZeroUTXO)(zeroKeypair.privateKey, mintAddress);
+    const zeroInput1 = (0, utxo_js_1.createOwnedZeroUTXO)(zeroKeypair.privateKey, mintAddress);
+    // The circuit skips the Merkle proof check for zero-amount inputs (amount == 0
+    // causes `enabled = 0` in MerkleProofIfEnabled). So we provide a dummy path using
+    // the tree's pre-computed zero chain without inserting anything into the tree.
+    const dummyPath = tree.zeroes.slice(0, tree.depth);
+    const currentRoot = tree.root;
+    const inputUTXOs = [
+        {
+            ...zeroInput0,
+            pathIndex: 0,
+            pathElements: dummyPath,
+            privateKey: zeroKeypair.privateKey,
+        },
+        {
+            ...zeroInput1,
+            pathIndex: 0,
+            pathElements: dummyPath,
+            privateKey: zeroKeypair.privateKey,
+        },
+    ];
+    const outputUTXO0 = (0, utxo_js_1.createUTXO)({
+        amount: amount,
+        pubkey: recipientPubkey,
+        mintAddress,
+    });
+    const outputUTXO1 = (0, utxo_js_1.createUTXO)({
+        amount: 0n,
+        pubkey: recipientPubkey,
+        mintAddress,
+    });
+    const outputUTXOs = [
+        outputUTXO0,
+        outputUTXO1,
+    ];
+    const depositorPubkey = depositor.publicKey;
+    const extData = {
+        recipient: partialExtData?.recipient ?? depositorPubkey,
+        relayer: partialExtData?.relayer ?? depositorPubkey,
+        fee: partialExtData?.fee ?? 0n,
+        refund: partialExtData?.refund ?? 0n,
+        claimant: partialExtData?.claimant ?? web3_js_1.SystemProgram.programId,
+    };
+    const circuitInputs = (0, proof_js_1.prepareTransactionInputs)({
+        inputUTXOs,
+        outputUTXOs,
+        root: currentRoot,
+        publicAmount: amount, // Positive for deposits
+        extData,
+        mintAddress,
+    });
+    const rawProof = await proofBuilder(circuitInputs);
+    const proof = (0, proof_js_1.encodeSnarkjsProofToTransactionProof)(rawProof);
+    // -----------------------------------------------------------------------
+    // Build the transact instruction inline (duplicated from `transact()`).
+    //
+    // We intentionally don't reuse the `transact()` helper: it submits via
+    // anchor's `.rpc()` with `.signers([relayer])`, which assumes the caller
+    // holds a real Keypair. For deposit, we want to return an unsigned
+    // Transaction so the caller (typically a browser wallet) can sign it
+    // themselves. Duplicating ~40 lines here keeps the change contained to
+    // this function and leaves the relayer path (`transact()` →
+    // `withdraw`/`privateTransfer`/`transactSwap`) completely untouched.
+    // -----------------------------------------------------------------------
+    const { config, vault, nullifiers } = getPoolPdas(program.programId, mintAddress);
+    const globalConfig = getGlobalConfigPda(program.programId);
+    const inputTree = getNoteTreePda(program.programId, mintAddress, treeId);
+    const outputTree = getNoteTreePda(program.programId, mintAddress, treeId);
+    const nullifierMarker0 = getNullifierMarkerPda(program.programId, mintAddress, circuitInputs.inputNullifiers[0]);
+    const nullifierMarker1 = getNullifierMarkerPda(program.programId, mintAddress, circuitInputs.inputNullifiers[1]);
+    const extDataHash = (0, proof_js_1.computeExtDataHash)(extData);
+    const isNativeSol = mintAddress.equals(config_js_1.NATIVE_SOL_MINT);
+    let vaultTA;
+    let userTA;
+    let recipientTA;
+    let relayerTA;
+    if (!isNativeSol) {
+        vaultTA = await (0, spl_token_1.getAssociatedTokenAddress)(mintAddress, vault, true);
+        userTA = await (0, spl_token_1.getAssociatedTokenAddress)(mintAddress, depositorPubkey);
+        recipientTA = await (0, spl_token_1.getAssociatedTokenAddress)(mintAddress, extData.recipient);
+        relayerTA = await (0, spl_token_1.getAssociatedTokenAddress)(mintAddress, depositorPubkey);
+    }
+    const builtTx = await program.methods
+        .transact(Array.from(currentRoot), treeId, treeId, new BN(amount.toString()), Array.from(extDataHash), mintAddress, Array.from(circuitInputs.inputNullifiers[0]), Array.from(circuitInputs.inputNullifiers[1]), Array.from(circuitInputs.outputCommitments[0]), Array.from(circuitInputs.outputCommitments[1]), new BN(Math.floor(Date.now() / 1000) + 3600), // 1-hour window from build time
+    {
+        recipient: extData.recipient,
+        relayer: extData.relayer,
+        fee: new BN(extData.fee.toString()),
+        refund: new BN(extData.refund.toString()),
+    }, {
+        proofA: proof.proofA,
+        proofB: proof.proofB,
+        proofC: proof.proofC,
+    })
+        .accounts({
+        config,
+        globalConfig,
+        vault,
+        inputTree,
+        outputTree,
+        nullifiers,
+        nullifierMarker0,
+        nullifierMarker1,
+        relayer: depositorPubkey,
+        recipient: extData.recipient,
+        vaultTokenAccount: vaultTA ?? vault,
+        userTokenAccount: userTA ?? depositorPubkey,
+        recipientTokenAccount: recipientTA ?? extData.recipient,
+        relayerTokenAccount: relayerTA ?? depositorPubkey,
+        tokenProgram: isNativeSol ? web3_js_1.SystemProgram.programId : spl_token_1.TOKEN_PROGRAM_ID,
+        systemProgram: web3_js_1.SystemProgram.programId,
+    })
+        .transaction();
+    // Add compute budget instruction for higher CU limit
+    const computeBudgetIx = web3_js_1.ComputeBudgetProgram.setComputeUnitLimit({
+        units: 1400000,
+    });
+    builtTx.instructions.unshift(computeBudgetIx);
+    // Populate feePayer + recentBlockhash so the wallet only has to sign.
+    const provider = program.provider;
+    builtTx.feePayer = depositorPubkey;
+    const { blockhash } = await provider.connection.getLatestBlockhash();
+    builtTx.recentBlockhash = blockhash;
+    const commit = () => {
+        const { index: outIdx0 } = tree.insert(outputUTXOs[0].commitment);
+        const { index: outIdx1, root: newRoot } = tree.insert(outputUTXOs[1].commitment);
+        return {
+            outputUTXOs,
+            leafIndices: [outIdx0, outIdx1],
+            root: newRoot,
+        };
+    };
+    return {
+        transaction: builtTx,
+        outputUTXOs,
+        commit,
+    };
+}
+/**
+ * Withdraw funds from the privacy pool.
+ *
+ * For withdrawals, we spend input UTXOs and create change output UTXOs.
+ * The publicAmount is negative (funds flowing out).
+ *
+ * @param withdrawAmount - Amount to withdraw in lamports/token units
+ * @param inputUTXOs - The UTXOs being spent
+ * @param changePubkey - UTXO public key for the change output
+ * @param inputTreeId - The tree ID where input UTXOs are located
+ * @param outputTreeId - The tree ID where change outputs will be inserted
+ */
+async function withdraw(params) {
+    const { program, relayer, recipient, mintAddress, inputUTXOs, changePubkey, withdrawAmount, fee, refund, root, inputTreeId, outputTreeId, tree, proofBuilder, } = params;
+    const totalInput = inputUTXOs[0].amount + inputUTXOs[1].amount;
+    const changeAmount = totalInput - withdrawAmount - fee;
+    if (changeAmount < 0n) {
+        throw new Error("Insufficient input balance for withdrawal");
+    }
+    const changeUTXO = (0, utxo_js_1.createUTXO)({
+        amount: changeAmount,
+        pubkey: changePubkey,
+        mintAddress,
+    });
+    const zeroUTXO = (0, utxo_js_1.createUTXO)({
+        amount: 0n,
+        pubkey: changePubkey,
+        mintAddress,
+    });
+    const outputUTXOs = [changeUTXO, zeroUTXO];
+    const extData = {
+        recipient,
+        relayer: relayer.publicKey,
+        fee,
+        refund,
+        claimant: web3_js_1.SystemProgram.programId,
+    };
+    // publicAmount is negative for withdrawals
+    const publicAmount = -withdrawAmount;
+    const circuitInputs = (0, proof_js_1.prepareTransactionInputs)({
+        inputUTXOs,
+        outputUTXOs,
+        root,
+        publicAmount,
+        extData,
+        mintAddress,
+    });
+    const rawProof = await proofBuilder(circuitInputs);
+    const proof = (0, proof_js_1.encodeSnarkjsProofToTransactionProof)(rawProof);
+    await transact({
+        program,
+        relayer,
+        recipient,
+        mintAddress,
+        root,
+        inputTreeId,
+        outputTreeId,
+        publicAmount,
+        inputNullifiers: circuitInputs.inputNullifiers,
+        outputCommitments: circuitInputs.outputCommitments,
+        extData,
+        proof,
+    });
+    const { index: changeIdx, root: newRoot } = tree.insert(changeUTXO.commitment);
+    tree.insert(zeroUTXO.commitment);
+    return {
+        changeUTXO,
+        leafIndex: changeIdx,
+        root: newRoot,
+    };
+}
+/**
+ * Execute a private transfer within the pool.
+ *
+ * For transfers, the publicAmount is 0 (no funds enter or leave the pool).
+ * Input amounts must equal output amounts.
+ *
+ * @param inputUTXOs - The UTXOs being spent
+ * @param outputPubkeys - UTXO public keys for the recipients
+ * @param outputAmounts - Amounts for each output (must sum to input total)
+ * @param inputTreeId - The tree ID where input UTXOs are located
+ * @param outputTreeId - The tree ID where output commitments will be inserted
+ */
+async function privateTransfer(params) {
+    const { program, relayer, mintAddress, inputUTXOs, outputPubkeys, outputAmounts, root, inputTreeId, outputTreeId, tree, proofBuilder, fee = 0n, } = params;
+    const totalInput = inputUTXOs[0].amount + inputUTXOs[1].amount;
+    const totalOutput = outputAmounts[0] + outputAmounts[1] + fee;
+    if (totalInput !== totalOutput) {
+        throw new Error(`Balance mismatch: inputs=${totalInput}, outputs=${totalOutput}`);
+    }
+    const outputUTXO0 = (0, utxo_js_1.createUTXO)({
+        amount: outputAmounts[0],
+        pubkey: outputPubkeys[0],
+        mintAddress,
+    });
+    const outputUTXO1 = (0, utxo_js_1.createUTXO)({
+        amount: outputAmounts[1],
+        pubkey: outputPubkeys[1],
+        mintAddress,
+    });
+    const outputUTXOs = [
+        outputUTXO0,
+        outputUTXO1,
+    ];
+    // Prepare ext data (for transfers, recipient can be anyone)
+    const extData = {
+        recipient: relayer.publicKey, // No external recipient for transfers
+        relayer: relayer.publicKey,
+        fee,
+        refund: 0n,
+        claimant: web3_js_1.SystemProgram.programId,
+    };
+    // publicAmount is 0 for transfers
+    const publicAmount = 0n;
+    const circuitInputs = (0, proof_js_1.prepareTransactionInputs)({
+        inputUTXOs,
+        outputUTXOs,
+        root,
+        publicAmount,
+        extData,
+        mintAddress,
+    });
+    const rawProof = await proofBuilder(circuitInputs);
+    const proof = (0, proof_js_1.encodeSnarkjsProofToTransactionProof)(rawProof);
+    await transact({
+        program,
+        relayer,
+        recipient: relayer.publicKey,
+        mintAddress,
+        root,
+        inputTreeId,
+        outputTreeId,
+        publicAmount,
+        inputNullifiers: circuitInputs.inputNullifiers,
+        outputCommitments: circuitInputs.outputCommitments,
+        extData,
+        proof,
+    });
+    const { index: outIdx0 } = tree.insert(outputUTXOs[0].commitment);
+    const { index: outIdx1, root: newRoot } = tree.insert(outputUTXOs[1].commitment);
+    return {
+        outputUTXOs,
+        leafIndices: [outIdx0, outIdx1],
+        root: newRoot,
+    };
+}
+// -----------------------------------------------------------------------------
+// Global Config
+// -----------------------------------------------------------------------------
+/**
+ * Update the global config.
+ * Currently takes no extra args — only admin verification.
+ */
+async function updateGlobalConfig(params) {
+    const { program, admin } = params;
+    const globalConfig = getGlobalConfigPda(program.programId);
+    await program.methods
+        .updateGlobalConfig()
+        .accounts({
+        globalConfig,
+        admin: admin.publicKey,
+    })
+        .rpc();
+}
+// -----------------------------------------------------------------------------
+// Swap Helpers
+// -----------------------------------------------------------------------------
+/**
+ * Get the swap executor PDA.
+ * Seeds: ["swap_executor", source_mint, dest_mint, input_nullifier_0, relayer]
+ */
+function getSwapExecutorPda(programId, sourceMint, destMint, inputNullifier0, relayer) {
+    const [executor] = web3_js_1.PublicKey.findProgramAddressSync([
+        Buffer.from("swap_executor"),
+        sourceMint.toBuffer(),
+        destMint.toBuffer(),
+        inputNullifier0,
+        relayer.toBuffer(),
+    ], programId);
+    return executor;
+}
+/**
+ * Build the `fund_native_source` instruction that pre-funds the swap executor
+ * with native SOL from the source vault. Only for native SOL source pools.
+ *
+ * This instruction MUST be the first instruction in the same atomic transaction
+ * as `transactSwap`. Call `transactSwap` directly — it handles this internally.
+ */
+async function fundNativeSource(params) {
+    const { program, relayer, sourceMint, destMint, inputNullifier0, swapAmount, } = params;
+    const { vault: sourceVault, config: sourceConfig } = getPoolPdas(program.programId, sourceMint);
+    const executor = getSwapExecutorPda(program.programId, sourceMint, destMint, inputNullifier0, relayer.publicKey);
+    const executorSourceToken = await (0, spl_token_1.getAssociatedTokenAddress)(spl_token_1.NATIVE_MINT, executor, true);
+    return program.methods
+        .fundNativeSource(sourceMint, destMint, Array.from(inputNullifier0), new BN(swapAmount.toString()))
+        .accounts({
+        executor,
+        executorSourceToken,
+        sourceVault,
+        sourceConfig,
+        sourceMintAccount: spl_token_1.NATIVE_MINT,
+        relayer: relayer.publicKey,
+        instructionsSysvar: web3_js_1.SYSVAR_INSTRUCTIONS_PUBKEY,
+        tokenProgram: spl_token_1.TOKEN_PROGRAM_ID,
+        systemProgram: web3_js_1.SystemProgram.programId,
+        associatedTokenProgram: spl_token_1.ASSOCIATED_TOKEN_PROGRAM_ID,
+    })
+        .instruction();
+}
+/**
+ * Execute an atomic cross-pool private swap.
+ *
+ * For native SOL source pools (`sourceMint === NATIVE_SOL_MINT`), this function
+ * automatically prepends the `fund_native_source` instruction in the same
+ * transaction so the on-chain atomicity requirement is always satisfied.
+ *
+ * @param swapProgram          - Jupiter/Raydium CPMM/AMM program ID
+ * @param swapData             - Raw DEX instruction bytes
+ */
+async function transactSwap(params) {
+    const { program, relayer, sourceMint, destMint, sourceRoot, sourceTreeId, destTreeId, inputNullifiers, outputCommitments, proof, swapParams, swapAmount, swapData, extData, sourceVaultTokenAccount, sourceMintAccount, destVaultTokenAccount, destMintAccount, relayerTokenAccount, swapProgram, jupiterEventAuthority, } = params;
+    const { config: sourceConfig, vault: sourceVault, nullifiers: sourceNullifiers, } = getPoolPdas(program.programId, sourceMint);
+    const { config: destConfig, vault: destVault } = getPoolPdas(program.programId, destMint);
+    const globalConfig = getGlobalConfigPda(program.programId);
+    const sourceTree = getNoteTreePda(program.programId, sourceMint, sourceTreeId);
+    const destTree = getNoteTreePda(program.programId, destMint, destTreeId);
+    const sourceNullifierMarker0 = getNullifierMarkerPda(program.programId, sourceMint, inputNullifiers[0]);
+    const sourceNullifierMarker1 = getNullifierMarkerPda(program.programId, sourceMint, inputNullifiers[1]);
+    const executor = getSwapExecutorPda(program.programId, sourceMint, destMint, inputNullifiers[0], relayer.publicKey);
+    const executorSourceToken = await (0, spl_token_1.getAssociatedTokenAddress)(sourceMintAccount, executor, true);
+    const executorDestToken = await (0, spl_token_1.getAssociatedTokenAddress)(destMintAccount, executor, true);
+    const swapIx = await program.methods
+        .transactSwap({
+        proofA: proof.proofA,
+        proofB: proof.proofB,
+        proofC: proof.proofC,
+    }, Array.from(sourceRoot), sourceTreeId, sourceMint, Array.from(inputNullifiers[0]), Array.from(inputNullifiers[1]), destTreeId, destMint, Array.from(outputCommitments[0]), Array.from(outputCommitments[1]), {
+        minAmountOut: new BN(swapParams.minAmountOut.toString()),
+        deadline: new BN(swapParams.deadline.toString()),
+        sourceMint: swapParams.sourceMint,
+        destMint: swapParams.destMint,
+        destAmount: new BN(swapParams.destAmount.toString()),
+        swapDataHash: Array.from(swapParams.swapDataHash),
+    }, new BN(swapAmount.toString()), swapData, {
+        recipient: extData.recipient,
+        relayer: extData.relayer,
+        fee: new BN(extData.fee.toString()),
+        refund: new BN(extData.refund.toString()),
+    })
+        .accounts({
+        sourceConfig,
+        globalConfig,
+        sourceVault,
+        sourceTree,
+        sourceNullifiers,
+        sourceNullifierMarker0,
+        sourceNullifierMarker1,
+        sourceVaultTokenAccount,
+        sourceMintAccount,
+        destConfig,
+        destVault,
+        destTree,
+        destVaultTokenAccount,
+        destMintAccount,
+        executor,
+        executorSourceToken,
+        executorDestToken,
+        relayer: relayer.publicKey,
+        relayerTokenAccount,
+        swapProgram,
+        jupiterEventAuthority,
+        tokenProgram: spl_token_1.TOKEN_PROGRAM_ID,
+        systemProgram: web3_js_1.SystemProgram.programId,
+        associatedTokenProgram: spl_token_1.ASSOCIATED_TOKEN_PROGRAM_ID,
+    })
+        .instruction();
+    const provider = program.provider;
+    const tx = new web3_js_1.Transaction();
+    if (sourceMint.equals(config_js_1.NATIVE_SOL_MINT)) {
+        const fundIx = await fundNativeSource({
+            program,
+            relayer,
+            sourceMint,
+            destMint,
+            inputNullifier0: inputNullifiers[0],
+            swapAmount,
+        });
+        tx.add(fundIx);
+    }
+    tx.add(swapIx);
+    return (0, retry_js_1.withRpcRetry)(() => provider.sendAndConfirm(tx, [relayer]));
+}