@veilo/sdk-core 0.3.3 → 0.5.0

package/dist/esm/client.js

@@ -1,887 +1,3 @@
-import { BN } from "@coral-xyz/anchor";
-import { PublicKey, SystemProgram, Transaction, SYSVAR_INSTRUCTIONS_PUBKEY, ComputeBudgetProgram, } from "@solana/web3.js";
-import { TOKEN_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID, NATIVE_MINT, getAssociatedTokenAddress, } from "@solana/spl-token";
-import { computeExtDataHash, prepareTransactionInputs, encodeSnarkjsProofToTransactionProof, } from "./proof";
-import { createUTXO, createOwnedZeroUTXO, generateKeypair, } from "./utxo";
-import { NATIVE_SOL_MINT } from "./config";
-import { withRpcRetry } from "./retry";
-// -----------------------------------------------------------------------------
-// PDA Helpers
-// -----------------------------------------------------------------------------
-/**
- * Get pool PDAs for a given mint address.
- * Note: All seeds use "v3" suffix.
- */
-export function getPoolPdas(programId, mintAddress) {
-    const [config] = PublicKey.findProgramAddressSync([Buffer.from("privacy_config_v3"), mintAddress.toBuffer()], programId);
-    const [vault] = PublicKey.findProgramAddressSync([Buffer.from("privacy_vault_v3"), mintAddress.toBuffer()], programId);
-    const [nullifiers] = PublicKey.findProgramAddressSync([Buffer.from("privacy_nullifiers_v3"), mintAddress.toBuffer()], programId);
-    return { config, vault, nullifiers };
-}
-/**
- * Get the note tree PDA for a specific tree ID.
- */
-export function getNoteTreePda(programId, mintAddress, treeId) {
-    const treeIdBuffer = Buffer.alloc(2);
-    treeIdBuffer.writeUInt16LE(treeId);
-    const [noteTree] = PublicKey.findProgramAddressSync([Buffer.from("privacy_note_tree_v3"), mintAddress.toBuffer(), treeIdBuffer], programId);
-    return noteTree;
-}
-/**
- * Get the global config PDA.
- */
-export function getGlobalConfigPda(programId) {
-    const [globalConfig] = 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.
- */
-export function getNullifierMarkerPda(programId, mintAddress, nullifier) {
-    const [marker] = 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.
- */
-export 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).
- */
-export 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.
- */
-export 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.
- */
-export 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.
- */
-export 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`.
- */
-export 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).
- */
-export 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: SystemProgram.programId,
-    })
-        .signers([payer])
-        .rpc();
-}
-// -----------------------------------------------------------------------------
-// Pool Initialization
-// -----------------------------------------------------------------------------
-/**
- * Initialize a privacy pool with the new parameters.
- * Creates the first merkle tree (tree ID 0).
- */
-export 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: SystemProgram.programId,
-    })
-        .signers([payer])
-        .rpc();
-}
-// -----------------------------------------------------------------------------
-// Pool Config Updates
-// -----------------------------------------------------------------------------
-/**
- * Update pool configuration.
- */
-export 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.
- */
-export 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: SystemProgram.programId,
-    })
-        .signers([relayer])
-        .rpc();
-}
-/**
- * Get the pool configuration account.
- */
-export 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.
- */
-export 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.
- */
-export 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
- */
-export 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 = computeExtDataHash(extData);
-    const isNativeSol = mintAddress.equals(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 getAssociatedTokenAddress(mintAddress, vault, true);
-        }
-        if (!userTA) {
-            userTA = await getAssociatedTokenAddress(mintAddress, relayer.publicKey);
-        }
-        if (!recipientTA) {
-            recipientTA = await getAssociatedTokenAddress(mintAddress, recipient);
-        }
-        if (!relayerTA) {
-            relayerTA = await 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 ? SystemProgram.programId : TOKEN_PROGRAM_ID,
-        systemProgram: SystemProgram.programId,
-    })
-        .signers([relayer]);
-    return 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)
- */
-export 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 = generateKeypair();
-    // Create zero input UTXOs (for deposits, we don't spend any existing UTXOs)
-    const zeroInput0 = createOwnedZeroUTXO(zeroKeypair.privateKey, mintAddress);
-    const zeroInput1 = 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 = createUTXO({
-        amount: amount,
-        pubkey: recipientPubkey,
-        mintAddress,
-    });
-    const outputUTXO1 = 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 ?? SystemProgram.programId,
-    };
-    const circuitInputs = prepareTransactionInputs({
-        inputUTXOs,
-        outputUTXOs,
-        root: currentRoot,
-        publicAmount: amount, // Positive for deposits
-        extData,
-        mintAddress,
-    });
-    const rawProof = await proofBuilder(circuitInputs);
-    const proof = 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 = computeExtDataHash(extData);
-    const isNativeSol = mintAddress.equals(NATIVE_SOL_MINT);
-    let vaultTA;
-    let userTA;
-    let recipientTA;
-    let relayerTA;
-    if (!isNativeSol) {
-        vaultTA = await getAssociatedTokenAddress(mintAddress, vault, true);
-        userTA = await getAssociatedTokenAddress(mintAddress, depositorPubkey);
-        recipientTA = await getAssociatedTokenAddress(mintAddress, extData.recipient);
-        relayerTA = await 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 ? SystemProgram.programId : TOKEN_PROGRAM_ID,
-        systemProgram: SystemProgram.programId,
-    })
-        .transaction();
-    // Add compute budget instruction for higher CU limit
-    const computeBudgetIx = 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
- */
-export 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 = createUTXO({
-        amount: changeAmount,
-        pubkey: changePubkey,
-        mintAddress,
-    });
-    const zeroUTXO = createUTXO({
-        amount: 0n,
-        pubkey: changePubkey,
-        mintAddress,
-    });
-    const outputUTXOs = [changeUTXO, zeroUTXO];
-    const extData = {
-        recipient,
-        relayer: relayer.publicKey,
-        fee,
-        refund,
-        claimant: SystemProgram.programId,
-    };
-    // publicAmount is negative for withdrawals
-    const publicAmount = -withdrawAmount;
-    const circuitInputs = prepareTransactionInputs({
-        inputUTXOs,
-        outputUTXOs,
-        root,
-        publicAmount,
-        extData,
-        mintAddress,
-    });
-    const rawProof = await proofBuilder(circuitInputs);
-    const proof = 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
- */
-export 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 = createUTXO({
-        amount: outputAmounts[0],
-        pubkey: outputPubkeys[0],
-        mintAddress,
-    });
-    const outputUTXO1 = 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: SystemProgram.programId,
-    };
-    // publicAmount is 0 for transfers
-    const publicAmount = 0n;
-    const circuitInputs = prepareTransactionInputs({
-        inputUTXOs,
-        outputUTXOs,
-        root,
-        publicAmount,
-        extData,
-        mintAddress,
-    });
-    const rawProof = await proofBuilder(circuitInputs);
-    const proof = 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.
- */
-export 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]
- */
-export function getSwapExecutorPda(programId, sourceMint, destMint, inputNullifier0, relayer) {
-    const [executor] = 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.
- */
-export 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 getAssociatedTokenAddress(NATIVE_MINT, executor, true);
-    return program.methods
-        .fundNativeSource(sourceMint, destMint, Array.from(inputNullifier0), new BN(swapAmount.toString()))
-        .accounts({
-        executor,
-        executorSourceToken,
-        sourceVault,
-        sourceConfig,
-        sourceMintAccount: NATIVE_MINT,
-        relayer: relayer.publicKey,
-        instructionsSysvar: SYSVAR_INSTRUCTIONS_PUBKEY,
-        tokenProgram: TOKEN_PROGRAM_ID,
-        systemProgram: SystemProgram.programId,
-        associatedTokenProgram: 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
- */
-export 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 getAssociatedTokenAddress(sourceMintAccount, executor, true);
-    const executorDestToken = await 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: TOKEN_PROGRAM_ID,
-        systemProgram: SystemProgram.programId,
-        associatedTokenProgram: ASSOCIATED_TOKEN_PROGRAM_ID,
-    })
-        .instruction();
-    const provider = program.provider;
-    const tx = new Transaction();
-    if (sourceMint.equals(NATIVE_SOL_MINT)) {
-        const fundIx = await fundNativeSource({
-            program,
-            relayer,
-            sourceMint,
-            destMint,
-            inputNullifier0: inputNullifiers[0],
-            swapAmount,
-        });
-        tx.add(fundIx);
-    }
-    tx.add(swapIx);
-    return withRpcRetry(() => provider.sendAndConfirm(tx, [relayer]));
-}
+// Backward-compatible entry point. Implementations are grouped by domain.
+export * from "./accounts/index.js";
+export * from "./transactions/index.js";