@veilo/sdk-core 0.3.3 → 0.5.0

package/dist/cjs/transactions/swap.js

@@ -0,0 +1,184 @@
+"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.getSwapExecutorPda = getSwapExecutorPda;
+exports.fundNativeSource = fundNativeSource;
+exports.buildTransactSwapInstruction = buildTransactSwapInstruction;
+exports.buildPrivateSwapInstructions = buildPrivateSwapInstructions;
+exports.transactSwap = transactSwap;
+const anchor = __importStar(require("@coral-xyz/anchor"));
+const web3_js_1 = require("@solana/web3.js");
+const spl_token_1 = require("@solana/spl-token");
+const config_js_1 = require("../config.js");
+const retry_js_1 = require("../retry.js");
+const pdas_js_1 = require("../accounts/pdas.js");
+const { BN } = anchor;
+/** Seeds: ["swap_executor", source_mint, dest_mint, 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 `fund_native_source`. It must immediately precede `transact_swap`. */
+async function fundNativeSource(params) {
+    const { program, relayer, sourceMint, destMint, inputNullifier0, swapAmount, sourceMintAccount = spl_token_1.NATIVE_MINT, } = params;
+    const { vault: sourceVault, config: sourceConfig } = (0, pdas_js_1.getPoolPdas)(program.programId, sourceMint);
+    const executor = getSwapExecutorPda(program.programId, sourceMint, destMint, inputNullifier0, relayer.publicKey);
+    const executorSourceToken = await (0, spl_token_1.getAssociatedTokenAddress)(sourceMintAccount, executor, true);
+    return program.methods
+        .fundNativeSource(sourceMint, destMint, Array.from(inputNullifier0), new BN(swapAmount.toString()))
+        .accountsStrict({
+        executor,
+        executorSourceToken,
+        sourceVault,
+        sourceConfig,
+        sourceMintAccount,
+        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();
+}
+function encodeNoteCiphers(noteCiphers) {
+    return noteCiphers
+        ? {
+            note0EphemeralKey: Array.from(noteCiphers.note0EphemeralKey),
+            note0Encrypted: Array.from(noteCiphers.note0Encrypted),
+            note0ViewTag: noteCiphers.note0ViewTag,
+            note1EphemeralKey: Array.from(noteCiphers.note1EphemeralKey),
+            note1Encrypted: Array.from(noteCiphers.note1Encrypted),
+            note1ViewTag: noteCiphers.note1ViewTag,
+        }
+        : null;
+}
+/** Build the current IDL's `transact_swap` instruction without submitting it. */
+async function buildTransactSwapInstruction(params) {
+    const { program, relayer, sourceMint, destMint, sourceRoot, sourceTreeId, destTreeId, inputNullifiers, outputCommitments, proof, swapParams, swapAmount, swapData, extData, noteCiphers = null, sourceVaultTokenAccount, sourceMintAccount, destVaultTokenAccount, destMintAccount, relayerTokenAccount, swapProgram, jupiterEventAuthority, remainingAccounts = [], } = params;
+    if (!extData.relayer.equals(relayer.publicKey)) {
+        throw new Error("extData.relayer must match the relayer account");
+    }
+    if (swapParams.deadline <= 0n) {
+        throw new Error("swapParams.deadline must be a positive Unix timestamp");
+    }
+    if (swapParams.swapDataHash.length !== 32) {
+        throw new Error("swapParams.swapDataHash must be 32 bytes");
+    }
+    const { config: sourceConfig, vault: sourceVault, nullifiers: sourceNullifiers, } = (0, pdas_js_1.getPoolPdas)(program.programId, sourceMint);
+    const { config: destConfig, vault: destVault } = (0, pdas_js_1.getPoolPdas)(program.programId, destMint);
+    const globalConfig = (0, pdas_js_1.getGlobalConfigPda)(program.programId);
+    const sourceTree = (0, pdas_js_1.getNoteTreePda)(program.programId, sourceMint, sourceTreeId);
+    const destTree = (0, pdas_js_1.getNoteTreePda)(program.programId, destMint, destTreeId);
+    const sourceNullifierMarker0 = (0, pdas_js_1.getNullifierMarkerPda)(program.programId, sourceMint, inputNullifiers[0]);
+    const sourceNullifierMarker1 = (0, pdas_js_1.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);
+    let method = program.methods
+        .transactSwap(sourceTreeId, sourceMint, Array.from(inputNullifiers[0]), Array.from(inputNullifiers[1]), destTreeId, destMint, { proofA: proof.proofA, proofB: proof.proofB, proofC: proof.proofC }, Array.from(sourceRoot), Array.from(outputCommitments[0]), Array.from(outputCommitments[1]), {
+        minAmountOut: new BN(swapParams.minAmountOut.toString()),
+        deadline: new BN(swapParams.deadline.toString()),
+        destAmount: new BN(swapParams.destAmount.toString()),
+        swapDataHash: Array.from(swapParams.swapDataHash),
+    }, new BN(swapAmount.toString()), Buffer.from(swapData), {
+        recipient: extData.recipient,
+        relayer: extData.relayer,
+        fee: new BN(extData.fee.toString()),
+        refund: new BN(extData.refund.toString()),
+        claimant: extData.claimant,
+    }, encodeNoteCiphers(noteCiphers))
+        .accountsStrict({
+        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,
+    });
+    // Jupiter account order and duplicates are part of the CPI contract.
+    method = method.remainingAccounts(remainingAccounts);
+    return method.instruction();
+}
+/** Build the atomic instruction sequence, including native-source funding. */
+async function buildPrivateSwapInstructions(params) {
+    const instructions = [];
+    if (params.sourceMint.equals(config_js_1.NATIVE_SOL_MINT)) {
+        instructions.push(await fundNativeSource({
+            program: params.program,
+            relayer: params.relayer,
+            sourceMint: params.sourceMint,
+            destMint: params.destMint,
+            inputNullifier0: params.inputNullifiers[0],
+            swapAmount: params.swapAmount,
+            sourceMintAccount: params.sourceMintAccount,
+        }));
+    }
+    instructions.push(await buildTransactSwapInstruction(params));
+    return instructions;
+}
+/**
+ * Submit the parity-correct instructions as a legacy transaction. For Jupiter
+ * routes, prefer `buildPrivateSwapInstructions` and compile v0 with route ALTs.
+ */
+async function transactSwap(params) {
+    const instructions = await buildPrivateSwapInstructions(params);
+    const transaction = new web3_js_1.Transaction().add(...instructions);
+    const provider = params.program.provider;
+    return (0, retry_js_1.withRpcRetry)(() => provider.sendAndConfirm(transaction, [params.relayer]));
+}

package/dist/cjs/transactions/transact.d.ts

@@ -0,0 +1,34 @@
+import type { Program, Idl } from "@coral-xyz/anchor";
+import { Keypair, PublicKey } from "@solana/web3.js";
+import type { ExtData, TransactionProofStruct } from "../proofs/types.js";
+import type { NoteCiphers } from "../compactNote.js";
+/**
+ * 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 declare function transact<T extends Idl>(params: {
+    program: Program<T>;
+    relayer: Keypair;
+    recipient: PublicKey;
+    mintAddress: PublicKey;
+    root: Uint8Array;
+    inputTreeId: number;
+    outputTreeId: number;
+    publicAmount: bigint;
+    inputNullifiers: [Uint8Array, Uint8Array];
+    outputCommitments: [Uint8Array, Uint8Array];
+    extData: ExtData;
+    proof: TransactionProofStruct;
+    /** Unix timestamp after which the tx is invalid. Defaults to 10 minutes from build time. */
+    deadline?: bigint;
+    /** Optional compact recovery payload emitted with the two output commitments. */
+    noteCiphers?: NoteCiphers | null;
+    vaultTokenAccount?: PublicKey;
+    userTokenAccount?: PublicKey;
+    recipientTokenAccount?: PublicKey;
+    relayerTokenAccount?: PublicKey;
+}): Promise<string>;

package/dist/cjs/transactions/transact.js

@@ -0,0 +1,146 @@
+"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.transact = transact;
+const anchor = __importStar(require("@coral-xyz/anchor"));
+const web3_js_1 = require("@solana/web3.js");
+const spl_token_1 = require("@solana/spl-token");
+const transaction_js_1 = require("../proofs/transaction.js");
+const config_js_1 = require("../config.js");
+const retry_js_1 = require("../retry.js");
+const pdas_js_1 = require("../accounts/pdas.js");
+// Anchor is CJS and does not expose BN as a detectable Node ESM named export.
+const { BN } = anchor;
+// -----------------------------------------------------------------------------
+// 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 = BigInt(Math.floor(Date.now() / 1000) + 600), noteCiphers = null, vaultTokenAccount, userTokenAccount, recipientTokenAccount, relayerTokenAccount, } = params;
+    if (!recipient.equals(extData.recipient)) {
+        throw new Error("recipient account must match extData.recipient");
+    }
+    if (!relayer.publicKey.equals(extData.relayer)) {
+        throw new Error("relayer account must match extData.relayer");
+    }
+    if (deadline <= 0n) {
+        throw new Error("deadline must be a positive Unix timestamp");
+    }
+    if (publicAmount === 0n && (extData.fee !== 0n || extData.refund !== 0n)) {
+        throw new Error("Private transfers require extData fee and refund to be zero");
+    }
+    const { config, vault, nullifiers } = (0, pdas_js_1.getPoolPdas)(program.programId, mintAddress);
+    const globalConfig = (0, pdas_js_1.getGlobalConfigPda)(program.programId);
+    const inputTree = (0, pdas_js_1.getNoteTreePda)(program.programId, mintAddress, inputTreeId);
+    const outputTree = (0, pdas_js_1.getNoteTreePda)(program.programId, mintAddress, outputTreeId);
+    // Nullifier markers are global (no tree_id) to prevent cross-tree double-spend
+    const nullifierMarker0 = (0, pdas_js_1.getNullifierMarkerPda)(program.programId, mintAddress, inputNullifiers[0]);
+    const nullifierMarker1 = (0, pdas_js_1.getNullifierMarkerPda)(program.programId, mintAddress, inputNullifiers[1]);
+    const extDataHash = (0, transaction_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);
+        }
+    }
+    else {
+        vaultTA ?? (vaultTA = relayer.publicKey);
+        userTA ?? (userTA = relayer.publicKey);
+        recipientTA ?? (recipientTA = relayer.publicKey);
+        relayerTA ?? (relayerTA = 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()),
+        claimant: extData.claimant,
+    }, {
+        proofA: proof.proofA,
+        proofB: proof.proofB,
+        proofC: proof.proofC,
+    }, noteCiphers
+        ? {
+            note0EphemeralKey: Array.from(noteCiphers.note0EphemeralKey),
+            note0Encrypted: Array.from(noteCiphers.note0Encrypted),
+            note0ViewTag: noteCiphers.note0ViewTag,
+            note1EphemeralKey: Array.from(noteCiphers.note1EphemeralKey),
+            note1Encrypted: Array.from(noteCiphers.note1Encrypted),
+            note1ViewTag: noteCiphers.note1ViewTag,
+        }
+        : null)
+        .accountsStrict({
+        config,
+        globalConfig,
+        vault,
+        inputTree,
+        outputTree,
+        nullifiers,
+        nullifierMarker0,
+        nullifierMarker1,
+        relayer: relayer.publicKey,
+        recipient,
+        vaultTokenAccount: vaultTA,
+        userTokenAccount: userTA,
+        recipientTokenAccount: recipientTA,
+        relayerTokenAccount: relayerTA,
+        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());
+}

package/dist/cjs/transactions/transfer.d.ts

@@ -0,0 +1,51 @@
+import type { Program, Idl } from "@coral-xyz/anchor";
+import { Keypair, PublicKey } from "@solana/web3.js";
+import type { TransactionProofBuilder } from "../proofs/types.js";
+import type { InputUTXO, SerializedUTXO } from "../notes/model.js";
+import { MerkleTree } from "../merkle.js";
+import { type NoteCiphers } from "../compactNote.js";
+export type TransferResult = {
+    /** Output UTXOs created by the transfer */
+    outputUTXOs: [SerializedUTXO, SerializedUTXO];
+    /** Leaf indices where the UTXOs were inserted */
+    leafIndices: [number, number];
+    /** New Merkle root after insertion */
+    root: Uint8Array;
+};
+/**
+ * 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 declare function privateTransfer<T extends Idl>(params: {
+    program: Program<T>;
+    relayer: Keypair;
+    mintAddress: PublicKey;
+    inputUTXOs: [InputUTXO, InputUTXO];
+    outputPubkeys: [bigint, bigint];
+    outputAmounts: [bigint, bigint];
+    root: Uint8Array;
+    inputTreeId: number;
+    outputTreeId: number;
+    tree: MerkleTree;
+    proofBuilder: TransactionProofBuilder;
+    /** Must be zero: the program rejects fees on publicAmount=0 transfers. */
+    fee?: bigint;
+    deadline?: bigint;
+    /** Public recipient account committed in ExtData (no funds are sent to it). */
+    externalRecipient?: PublicKey;
+    /** Wallet keys used to encrypt output notes for on-chain recovery. */
+    noteRecipientWallets?: [
+        PublicKey | Uint8Array | null,
+        PublicKey | Uint8Array | null
+    ];
+    /** Prebuilt note ciphers. Takes precedence over noteRecipientWallets. */
+    noteCiphers?: NoteCiphers | null;
+}): Promise<TransferResult>;

package/dist/cjs/transactions/transfer.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.privateTransfer = privateTransfer;
+const web3_js_1 = require("@solana/web3.js");
+const transaction_js_1 = require("../proofs/transaction.js");
+const encoding_js_1 = require("../proofs/encoding.js");
+const model_js_1 = require("../notes/model.js");
+const transact_js_1 = require("./transact.js");
+const poseidon_js_1 = require("../poseidon.js");
+const compactNote_js_1 = require("../compactNote.js");
+/**
+ * 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, deadline = BigInt(Math.floor(Date.now() / 1000) + 600), externalRecipient = web3_js_1.Keypair.generate().publicKey, noteRecipientWallets, noteCiphers, } = params;
+    if (fee !== 0n) {
+        throw new Error("Private transact transfers require fee=0; represent any relayer fee in the output amounts");
+    }
+    const totalInput = inputUTXOs[0].amount + inputUTXOs[1].amount;
+    const totalOutput = outputAmounts[0] + outputAmounts[1];
+    if (totalInput !== totalOutput) {
+        throw new Error(`Balance mismatch: inputs=${totalInput}, outputs=${totalOutput}`);
+    }
+    const outputUTXO0 = (0, model_js_1.createUTXO)({
+        amount: outputAmounts[0],
+        pubkey: outputPubkeys[0],
+        mintAddress,
+    });
+    const outputUTXO1 = (0, model_js_1.createUTXO)({
+        amount: outputAmounts[1],
+        pubkey: outputPubkeys[1],
+        mintAddress,
+    });
+    const outputUTXOs = [
+        outputUTXO0,
+        outputUTXO1,
+    ];
+    const extData = {
+        recipient: externalRecipient,
+        relayer: relayer.publicKey,
+        fee: 0n,
+        refund: 0n,
+        claimant: web3_js_1.SystemProgram.programId,
+    };
+    // publicAmount is 0 for transfers
+    const publicAmount = 0n;
+    const circuitInputs = (0, transaction_js_1.prepareTransactionInputs)({
+        inputUTXOs,
+        outputUTXOs,
+        root,
+        publicAmount,
+        extData,
+        mintAddress,
+    });
+    const rawProof = await proofBuilder(circuitInputs);
+    const proof = (0, encoding_js_1.encodeSnarkjsProofToTransactionProof)(rawProof);
+    const walletBytes = (wallet) => wallet instanceof web3_js_1.PublicKey ? wallet.toBytes() : wallet;
+    const transferNoteCiphers = noteCiphers ??
+        (noteRecipientWallets
+            ? (0, compactNote_js_1.createNoteCiphers)(noteRecipientWallets[0]
+                ? {
+                    recipientWalletPubkey: walletBytes(noteRecipientWallets[0]),
+                    blinding: (0, poseidon_js_1.bigIntToBytesBE)(outputUTXOs[0].blinding),
+                    amount: outputUTXOs[0].amount,
+                }
+                : null, noteRecipientWallets[1]
+                ? {
+                    recipientWalletPubkey: walletBytes(noteRecipientWallets[1]),
+                    blinding: (0, poseidon_js_1.bigIntToBytesBE)(outputUTXOs[1].blinding),
+                    amount: outputUTXOs[1].amount,
+                }
+                : null)
+            : null);
+    await (0, transact_js_1.transact)({
+        program,
+        relayer,
+        recipient: externalRecipient,
+        mintAddress,
+        root,
+        inputTreeId,
+        outputTreeId,
+        publicAmount,
+        inputNullifiers: circuitInputs.inputNullifiers,
+        outputCommitments: circuitInputs.outputCommitments,
+        extData,
+        proof,
+        deadline,
+        noteCiphers: transferNoteCiphers,
+    });
+    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,
+    };
+}

package/dist/cjs/transactions/withdraw.d.ts

@@ -0,0 +1,52 @@
+import type { Program, Idl } from "@coral-xyz/anchor";
+import { Keypair, PublicKey } from "@solana/web3.js";
+import type { TransactionProofBuilder } from "../proofs/types.js";
+import type { InputUTXO, SerializedUTXO } from "../notes/model.js";
+import { MerkleTree } from "../merkle.js";
+import { type NoteCiphers } from "../compactNote.js";
+export type WithdrawResult = {
+    /** Change UTXO (remaining balance) */
+    changeUTXO: SerializedUTXO;
+    /** Leaf index of the change UTXO */
+    leafIndex: number;
+    /** New Merkle root after insertion */
+    root: Uint8Array;
+};
+/**
+ * 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 declare function withdraw<T extends Idl>(params: {
+    program: Program<T>;
+    relayer: Keypair;
+    recipient: PublicKey;
+    mintAddress: PublicKey;
+    inputUTXOs: [InputUTXO, InputUTXO];
+    changePubkey: bigint;
+    withdrawAmount: bigint;
+    fee: bigint;
+    refund: bigint;
+    root: Uint8Array;
+    inputTreeId: number;
+    outputTreeId: number;
+    tree: MerkleTree;
+    proofBuilder: TransactionProofBuilder;
+    /** When true, the fee is debited in addition to withdrawAmount. */
+    feeOnTop?: boolean;
+    deadline?: bigint;
+    /** Solana wallet key used to encrypt the change note for chain recovery. */
+    changeNoteRecipientWallet?: PublicKey | Uint8Array;
+    /** Prebuilt recovery payload. Takes precedence over changeNoteRecipientWallet. */
+    noteCiphers?: NoteCiphers | null;
+}): Promise<WithdrawResult>;
+/**
+ * Result of a private transfer operation.
+ */

package/dist/cjs/transactions/withdraw.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withdraw = withdraw;
+const web3_js_1 = require("@solana/web3.js");
+const transaction_js_1 = require("../proofs/transaction.js");
+const encoding_js_1 = require("../proofs/encoding.js");
+const model_js_1 = require("../notes/model.js");
+const transact_js_1 = require("./transact.js");
+const poseidon_js_1 = require("../poseidon.js");
+const compactNote_js_1 = require("../compactNote.js");
+/**
+ * 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, feeOnTop = false, deadline = BigInt(Math.floor(Date.now() / 1000) + 600), changeNoteRecipientWallet, noteCiphers, } = params;
+    const totalInput = inputUTXOs[0].amount + inputUTXOs[1].amount;
+    const outflowAmount = feeOnTop ? withdrawAmount + fee : withdrawAmount;
+    const changeAmount = totalInput - outflowAmount;
+    if (withdrawAmount <= 0n) {
+        throw new Error("Withdrawal amount must be positive");
+    }
+    if (fee < 0n || refund < 0n || fee + refund > outflowAmount) {
+        throw new Error("Withdrawal fee and refund must fit within the public outflow");
+    }
+    if (changeAmount < 0n) {
+        throw new Error("Insufficient input balance for withdrawal");
+    }
+    const changeUTXO = (0, model_js_1.createUTXO)({
+        amount: changeAmount,
+        pubkey: changePubkey,
+        mintAddress,
+    });
+    const zeroUTXO = (0, model_js_1.createUTXO)({
+        amount: 0n,
+        pubkey: (0, model_js_1.generateKeypair)().publicKey,
+        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 = -outflowAmount;
+    const circuitInputs = (0, transaction_js_1.prepareTransactionInputs)({
+        inputUTXOs,
+        outputUTXOs,
+        root,
+        publicAmount,
+        extData,
+        mintAddress,
+    });
+    const rawProof = await proofBuilder(circuitInputs);
+    const proof = (0, encoding_js_1.encodeSnarkjsProofToTransactionProof)(rawProof);
+    const withdrawNoteCiphers = noteCiphers !== undefined
+        ? noteCiphers
+        : changeNoteRecipientWallet && changeAmount > 0n
+            ? (0, compactNote_js_1.createNoteCiphers)({
+                recipientWalletPubkey: changeNoteRecipientWallet instanceof web3_js_1.PublicKey
+                    ? changeNoteRecipientWallet.toBytes()
+                    : changeNoteRecipientWallet,
+                blinding: (0, poseidon_js_1.bigIntToBytesBE)(changeUTXO.blinding),
+                amount: changeAmount,
+            }, null)
+            : null;
+    await (0, transact_js_1.transact)({
+        program,
+        relayer,
+        recipient,
+        mintAddress,
+        root,
+        inputTreeId,
+        outputTreeId,
+        publicAmount,
+        inputNullifiers: circuitInputs.inputNullifiers,
+        outputCommitments: circuitInputs.outputCommitments,
+        extData,
+        proof,
+        deadline,
+        noteCiphers: withdrawNoteCiphers,
+    });
+    const { index: changeIdx } = tree.insert(changeUTXO.commitment);
+    const { root: newRoot } = tree.insert(zeroUTXO.commitment);
+    return {
+        changeUTXO,
+        leafIndex: changeIdx,
+        root: newRoot,
+    };
+}
+/**
+ * Result of a private transfer operation.
+ */