@veilo/sdk-core 0.3.3 → 0.4.0

package/dist/esm/shield/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/utxo.d.ts

@@ -0,0 +1,235 @@
+import { PublicKey } from "@solana/web3.js";
+/**
+ * Keypair for UTXO ownership.
+ * Public key is derived via Poseidon: pubkey = Poseidon(privateKey)
+ */
+export type Keypair = {
+    privateKey: bigint;
+    publicKey: bigint;
+};
+/**
+ * UTXO structure matching the circuit's UTXOCommitment template.
+ * commitment = Poseidon(amount, pubkey, blinding, mintAddress)
+ */
+export type UTXO = {
+    /** Amount in lamports/token units */
+    amount: bigint;
+    /** Owner's public key (derived from private key via Poseidon) */
+    pubkey: bigint;
+    /** Random blinding factor for commitment privacy */
+    blinding: bigint;
+    /** Token mint address as field element */
+    mintAddress: bigint;
+};
+/**
+ * Serialized UTXO with precomputed commitment and optional ownership data.
+ */
+export type SerializedUTXO = UTXO & {
+    /** 32-byte commitment: Poseidon(amount, pubkey, blinding, mintAddress) */
+    commitment: Uint8Array;
+    /** Private key for spending (only present for owned UTXOs) */
+    privateKey?: bigint;
+    /** Leaf index in the Merkle tree (set after insertion) */
+    pathIndex?: number;
+};
+/**
+ * Input UTXO with Merkle proof data for spending.
+ */
+export type InputUTXO = SerializedUTXO & {
+    /** Leaf index in the Merkle tree */
+    pathIndex: number;
+    /** Merkle path elements (sibling hashes from leaf to root) */
+    pathElements: Uint8Array[];
+    /** Private key for nullifier derivation */
+    privateKey: bigint;
+};
+/**
+ * Generate a random keypair.
+ * Private key is a random 32-byte scalar.
+ * Public key is derived via Poseidon: pubkey = Poseidon(privateKey)
+ */
+export declare function generateKeypair(): Keypair;
+/**
+ * Derive public key from private key.
+ * Matches circuit's Keypair template: publicKey = Poseidon(privateKey)
+ */
+export declare function derivePublicKey(privateKey: bigint): bigint;
+/**
+ * Create keypair from a known private key.
+ */
+export declare function keypairFromPrivateKey(privateKey: bigint): Keypair;
+/**
+ * Compute UTXO commitment.
+ * Matches circuit's UTXOCommitment template:
+ *   commitment = Poseidon(amount, pubkey, blinding, mintAddress)
+ */
+export declare function commitUTXO(utxo: UTXO): Uint8Array;
+/**
+ * Create a random UTXO with the given parameters.
+ */
+export declare function createUTXO(params: {
+    amount: bigint;
+    pubkey: bigint;
+    mintAddress: PublicKey;
+}): SerializedUTXO;
+/**
+ * Create a UTXO with a specified private key (for owned UTXOs).
+ */
+export declare function createOwnedUTXO(params: {
+    amount: bigint;
+    privateKey: bigint;
+    mintAddress: PublicKey;
+}): SerializedUTXO;
+/**
+ * Create a zero UTXO (for deposits where no input exists).
+ * Zero UTXOs have amount=0 and are used as placeholders in 2-in-2-out transactions.
+ */
+export declare function createZeroUTXO(pubkey: bigint, mintAddress: PublicKey): SerializedUTXO;
+/**
+ * Create a zero UTXO with private key (for owned zero UTXOs).
+ */
+export declare function createOwnedZeroUTXO(privateKey: bigint, mintAddress: PublicKey): SerializedUTXO;
+/**
+ * Compute signature for nullifier derivation.
+ * Matches circuit's Signature template:
+ *   signature = Poseidon(privateKey, commitment, pathIndex)
+ */
+export declare function computeSignature(privateKey: bigint, commitment: bigint, pathIndex: bigint): bigint;
+/**
+ * Derive nullifier for a UTXO.
+ * Matches circuit's UTXONullifier template:
+ *   signature = Poseidon(privateKey, commitment, pathIndex)
+ *   nullifier = Poseidon(commitment, pathIndex, signature)
+ *
+ * The signature-based nullifier ensures only the private key holder can spend.
+ */
+export declare function deriveNullifier(utxo: SerializedUTXO, pathIndex: number, privateKey: bigint): Uint8Array;
+/**
+ * Convert InputUTXO to the format expected by the circuit.
+ */
+export declare function inputUTXOToCircuitFormat(input: InputUTXO): {
+    amount: bigint;
+    pubkey: bigint;
+    blinding: bigint;
+    pathElements: bigint[];
+    pathIndex: number;
+    privateKey: bigint;
+};
+/**
+ * Encrypted UTXO note — can be broadcast alongside a transaction so the
+ * recipient can recover their note without a server.
+ */
+export type EncryptedNote = {
+    /** 24-byte NaCl box nonce */
+    nonce: Uint8Array;
+    /** Ciphertext containing amount + blinding + privateKey */
+    ciphertext: Uint8Array;
+    /** Sender's ephemeral 32-byte X25519 public key */
+    senderEphemeralPubkey: Uint8Array;
+};
+/**
+ * Derive a NaCl X25519 encryption keypair from a UTXO private key.
+ * The keypair is deterministic: same privateKey always yields the same pair.
+ */
+export declare function deriveEncryptionKeypair(privateKey: bigint): {
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
+};
+/**
+ * Encrypt a UTXO so the recipient can recover it from on-chain events.
+ *
+ * Plaintext layout (72 bytes):
+ *   [0..8]   amount  — 8-byte little-endian u64
+ *   [8..40]  blinding — 32-byte big-endian field element
+ *   [40..72] privateKey — 32-byte big-endian field element
+ *
+ * Uses ephemeral-key NaCl box so the sender key is single-use.
+ */
+export declare function encryptUTXONote(utxo: SerializedUTXO & {
+    privateKey: bigint;
+}, recipientEncPubkey: Uint8Array): EncryptedNote;
+/**
+ * Try to decrypt an encrypted UTXO note using the recipient's private key.
+ * Returns the SerializedUTXO if decryption succeeds and the commitment
+ * matches, or `null` if the note was not intended for this key.
+ */
+export declare function decryptUTXONote(note: EncryptedNote, recipientPrivateKey: bigint, commitment: Uint8Array, mintAddress: PublicKey): SerializedUTXO | null;
+/** Note data stored inside a Blind Mailbox encrypted blob */
+export type BlindMailboxNoteData = {
+    blinding: Uint8Array;
+    leafIndex: number;
+    commitment: Uint8Array;
+    amount: bigint;
+    mintAddress: string;
+    treeId: number;
+};
+/** Encrypted note as returned by the relayer's /api/notes endpoint */
+export type BlindMailboxNote = {
+    commitment: string;
+    ephemeralPublicKey: string;
+    encryptedBlob: string;
+    timestamp?: number;
+    blockHeight?: number;
+    txSignature?: string;
+};
+/** Decrypted note data after calling decryptBlindMailboxNote */
+export type DecryptedNote = {
+    blinding: Uint8Array;
+    leafIndex: number;
+    commitment: Uint8Array;
+    amount: bigint;
+    timestamp: number;
+    mintAddress?: string;
+    treeId: number;
+};
+/** Derive 32-byte encryption key from a shared secret using SHA-512 truncated.
+ *  Must match the production "sha256" helper which uses nacl.hash (SHA-512) [0:32].
+ *
+ *  DO NOT "fix" this to real SHA-256. The name in the sibling implementations
+ *  (`sha256ForNotes`) is a misnomer, but the bytes are load-bearing: changing the
+ *  KDF makes every historical note undecryptable.
+ *
+ *  @internal Exported for `compactNote.ts`. Not part of the stable public API. */
+export declare function kdfSHA512_256(secret: Uint8Array): Uint8Array;
+/** Convert an Ed25519 private seed (32 bytes) to an X25519 scalar.
+ *  Equivalent to ed2curve.convertSecretKey(seed).
+ *
+ *  @internal Exported for `compactNote.ts`. Not part of the stable public API. */
+export declare function ed25519SeedToX25519Private(seed: Uint8Array): Uint8Array;
+/** Convert an Ed25519 compressed public key (32 bytes) to X25519.
+ *  Equivalent to ed2curve.convertPublicKey(pubkey).
+ *  Edwards y-coord → Montgomery u via: u = (1 + y) / (1 - y) (mod p).
+ *
+ *  @internal Exported for `compactNote.ts`. Not part of the stable public API. */
+export declare function ed25519PublicKeyToX25519(pubkey: Uint8Array): Uint8Array;
+/**
+ * Encrypt a UTXO note for a recipient identified by their Solana wallet public key.
+ * Produces a blob the relayer will store and serve via POST /notes/save.
+ *
+ * @param recipientWalletPubkey  32-byte Ed25519 public key (wallet.publicKey.toBytes())
+ * @param noteData               UTXO details to encrypt
+ */
+export declare function encryptBlindMailboxNote(recipientWalletPubkey: Uint8Array, noteData: BlindMailboxNoteData): {
+    ephemeralPublicKey: Uint8Array;
+    encryptedBlob: string;
+};
+/**
+ * Decrypt a Blind Mailbox note using the recipient's Solana wallet private seed.
+ *
+ * @param walletSecretKey  Full 64-byte wallet.secretKey — the first 32 bytes are the seed
+ * @param ephemeralPublicKey  32-byte raw public key stored alongside the encrypted blob.
+ *                            This may be either an Ed25519 pubkey (from Keypair.generate())
+ *                            or a raw X25519 pubkey — the decryption path handles both:
+ *                            if it is an Ed25519 key it is converted; otherwise used directly.
+ * @param encryptedBlob      Base64 string as stored by the relayer
+ */
+export declare function decryptBlindMailboxNote(walletSecretKey: Uint8Array, ephemeralPublicKey: Uint8Array, encryptedBlob: string): DecryptedNote;
+/**
+ * Fetch all encrypted notes for a wallet from the relayer's Blind Mailbox endpoint
+ * and decrypt them using the wallet's secret key.
+ *
+ * @param walletPublicKey  Base58 wallet address used to query the relayer
+ * @param walletSecretKey  Full 64-byte keypair.secretKey for decryption
+ * @param relayerUrl       Relayer base URL (e.g. "https://relay.veilo.app")
+ */
+export declare function fetchAndDecryptNotes(walletPublicKey: string, walletSecretKey: Uint8Array, relayerUrl: string): Promise<DecryptedNote[]>;

package/dist/esm/utxo.js

@@ -1,7 +1,7 @@
-import { randomBytes } from "crypto";
+import { randomBytes } from "./random.js";
 import nacl from "tweetnacl";
 import { sha256 } from "@noble/hashes/sha256";
-import { BN254_FR_MODULUS, bigIntToBytesBE, bytesToBigIntBE, poseidon1, poseidon3, poseidon4, pubkeyToField, } from "./poseidon";
+import { BN254_FR_MODULUS, bigIntToBytesBE, bytesToBigIntBE, poseidon1, poseidon3, poseidon4, pubkeyToField, } from "./poseidon.js";
 // -----------------------------------------------------------------------------
 // Keypair Functions
 // -----------------------------------------------------------------------------
@@ -203,13 +203,21 @@ export function decryptUTXONote(note, recipientPrivateKey, commitment, mintAddre
 }
 // -- Internal crypto helpers (no extra dependencies) --------------------------
 /** Derive 32-byte encryption key from a shared secret using SHA-512 truncated.
- *  Must match the production "sha256" helper which uses nacl.hash (SHA-512) [0:32]. */
-function kdfSHA512_256(secret) {
+ *  Must match the production "sha256" helper which uses nacl.hash (SHA-512) [0:32].
+ *
+ *  DO NOT "fix" this to real SHA-256. The name in the sibling implementations
+ *  (`sha256ForNotes`) is a misnomer, but the bytes are load-bearing: changing the
+ *  KDF makes every historical note undecryptable.
+ *
+ *  @internal Exported for `compactNote.ts`. Not part of the stable public API. */
+export function kdfSHA512_256(secret) {
     return nacl.hash(secret).slice(0, 32);
 }
 /** Convert an Ed25519 private seed (32 bytes) to an X25519 scalar.
- *  Equivalent to ed2curve.convertSecretKey(seed). */
-function ed25519SeedToX25519Private(seed) {
+ *  Equivalent to ed2curve.convertSecretKey(seed).
+ *
+ *  @internal Exported for `compactNote.ts`. Not part of the stable public API. */
+export function ed25519SeedToX25519Private(seed) {
     const h = nacl.hash(seed); // SHA-512
     const scalar = h.slice(0, 32);
     scalar[0] &= 248;
@@ -231,8 +239,10 @@ function modpow25519(b, e) {
 }
 /** Convert an Ed25519 compressed public key (32 bytes) to X25519.
  *  Equivalent to ed2curve.convertPublicKey(pubkey).
- *  Edwards y-coord → Montgomery u via: u = (1 + y) / (1 - y) (mod p). */
-function ed25519PublicKeyToX25519(pubkey) {
+ *  Edwards y-coord → Montgomery u via: u = (1 + y) / (1 - y) (mod p).
+ *
+ *  @internal Exported for `compactNote.ts`. Not part of the stable public API. */
+export function ed25519PublicKeyToX25519(pubkey) {
     const pk = new Uint8Array(pubkey);
     pk[31] &= 0x7f; // clear sign bit to get y as LE integer
     // Decode little-endian y

package/dist/src/client.d.ts

@@ -0,0 +1,407 @@
+import * as anchor from "@coral-xyz/anchor";
+import type { Program, Idl } from "@coral-xyz/anchor";
+import { PublicKey, Transaction, Keypair } from "@solana/web3.js";
+import { TransactionProofStruct, TransactionProofBuilder, ExtData } from "./proof.js";
+import { SerializedUTXO, InputUTXO } from "./utxo.js";
+import { MerkleTree } from "./merkle.js";
+import { PrivacyConfigAccount } from "./config.js";
+/**
+ * Get pool PDAs for a given mint address.
+ * Note: All seeds use "v3" suffix.
+ */
+export declare function getPoolPdas(programId: PublicKey, mintAddress: PublicKey): {
+    config: anchor.web3.PublicKey;
+    vault: anchor.web3.PublicKey;
+    nullifiers: anchor.web3.PublicKey;
+};
+/**
+ * Get the note tree PDA for a specific tree ID.
+ */
+export declare function getNoteTreePda(programId: PublicKey, mintAddress: PublicKey, treeId: number): PublicKey;
+/**
+ * Get the global config PDA.
+ */
+export declare function getGlobalConfigPda(programId: PublicKey): PublicKey;
+/**
+ * Get the nullifier marker PDA for a specific nullifier.
+ * NOTE: Nullifier markers are global (no tree_id) to prevent cross-tree double-spend.
+ */
+export declare function getNullifierMarkerPda(programId: PublicKey, mintAddress: PublicKey, nullifier: Uint8Array): PublicKey;
+/**
+ * Fetch and decode the on-chain PrivacyConfig account for a pool.
+ */
+export declare function fetchPoolConfig<T extends Idl>(program: Program<T>, mintAddress: PublicKey): Promise<PrivacyConfigAccount>;
+/**
+ * Check whether a nullifier has been spent on-chain.
+ * Returns true if the nullifier marker PDA exists (funds already spent).
+ */
+export declare function checkNullifierSpent<T extends Idl>(program: Program<T>, mintAddress: PublicKey, nullifier: Uint8Array): Promise<boolean>;
+/** On-chain tree utilization info */
+export type TreeInfo = {
+    treeId: number;
+    leafCount: number;
+    capacity: number;
+    utilizationPercent: number;
+    remainingCapacity: number;
+    isFull: boolean;
+    treePDA: PublicKey;
+};
+/**
+ * Fetch utilization info for a specific tree.
+ * Returns null if the tree does not exist yet.
+ */
+export declare function getTreeInfo<T extends Idl>(program: Program<T>, mintAddress: PublicKey, treeId: number): Promise<TreeInfo | null>;
+/**
+ * Fetch utilization info for all trees in a pool.
+ */
+export declare function getAllTreeInfo<T extends Idl>(program: Program<T>, mintAddress: PublicKey): Promise<TreeInfo[]>;
+/**
+ * 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 declare function getBestTreeForDeposit<T extends Idl>(program: Program<T>, mintAddress: PublicKey, minCapacity?: number): Promise<TreeInfo | null>;
+/**
+ * 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 declare function parseOnChainError(error: any): string;
+/**
+ * Initialize the global config (one-time setup).
+ */
+export declare function initializeGlobalConfig<T extends Idl>(params: {
+    program: Program<T>;
+    admin: anchor.Wallet;
+    payer: Keypair;
+}): Promise<void>;
+/**
+ * Initialize a privacy pool with the new parameters.
+ * Creates the first merkle tree (tree ID 0).
+ */
+export declare function initializePool<T extends Idl>(params: {
+    program: Program<T>;
+    admin: anchor.Wallet;
+    payer: Keypair;
+    feeBps: number;
+    mintAddress: PublicKey;
+    minDepositAmount?: bigint;
+    maxDepositAmount?: bigint;
+    minWithdrawAmount?: bigint;
+    maxWithdrawAmount?: bigint;
+}): Promise<void>;
+/**
+ * Update pool configuration.
+ */
+export declare function updatePoolConfig<T extends Idl>(params: {
+    program: Program<T>;
+    admin: anchor.Wallet;
+    mintAddress: PublicKey;
+    minDepositAmount?: bigint;
+    maxDepositAmount?: bigint;
+    minWithdrawAmount?: bigint;
+    maxWithdrawAmount?: bigint;
+    feeBps?: number;
+    feeErrorMarginBps?: number;
+    minWithdrawalFee?: bigint;
+    minSwapFee?: bigint;
+    swapFeeBps?: number;
+}): Promise<void>;
+/**
+ * Add a new Merkle tree to the pool.
+ * The treeId must equal the current num_trees value in the pool config.
+ */
+export declare function addMerkleTree<T extends Idl>(params: {
+    program: Program<T>;
+    relayer: Keypair;
+    mintAddress: PublicKey;
+    treeId: number;
+}): Promise<void>;
+/**
+ * Get the pool configuration account.
+ */
+export declare function getPoolConfig<T extends Idl>(program: Program<T>, mintAddress: PublicKey): Promise<PrivacyConfigAccount>;
+/**
+ * Add a relayer to the pool.
+ */
+export declare function addRelayer<T extends Idl>(params: {
+    program: Program<T>;
+    admin: anchor.Wallet;
+    mintAddress: PublicKey;
+    newRelayer: PublicKey;
+}): Promise<void>;
+/**
+ * Set the paused state of a pool.
+ */
+export declare function setPaused<T extends Idl>(params: {
+    program: Program<T>;
+    admin: anchor.Wallet;
+    mintAddress: PublicKey;
+    paused: boolean;
+}): Promise<void>;
+/**
+ * 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 0 (no deadline). */
+    deadline?: bigint;
+    vaultTokenAccount?: PublicKey;
+    userTokenAccount?: PublicKey;
+    recipientTokenAccount?: PublicKey;
+    relayerTokenAccount?: PublicKey;
+}): Promise<string>;
+/**
+ * Result of a deposit operation, produced by `DepositBuild.commit()` after the
+ * caller has successfully submitted the deposit transaction on-chain.
+ */
+export type DepositResult = {
+    /** The output UTXOs created by the deposit */
+    outputUTXOs: [SerializedUTXO, SerializedUTXO];
+    /** The leaf indices where the UTXOs were inserted */
+    leafIndices: [number, number];
+    /** The new Merkle root after insertion */
+    root: Uint8Array;
+};
+/**
+ * The return of `deposit()`. Instead of submitting the transaction itself,
+ * `deposit()` hands back an unsigned {@link Transaction} so the caller can
+ * sign it with whatever wallet they control (Solana wallet-adapter, Ledger,
+ * anchor NodeWallet, etc.) and submit it on their own terms.
+ *
+ * Usage pattern (browser / wallet-adapter):
+ *
+ *     const { transaction, commit } = await deposit({ ... });
+ *     const signed = await wallet.signTransaction(transaction);
+ *     const sig = await connection.sendRawTransaction(signed.serialize());
+ *     await connection.confirmTransaction(sig, "confirmed");
+ *     const result = commit();   // updates the local tree, returns DepositResult
+ */
+export type DepositBuild = {
+    /**
+     * Unsigned {@link Transaction} for the deposit. `feePayer` and
+     * `recentBlockhash` are already populated, so the caller only needs to sign
+     * and send.
+     */
+    transaction: Transaction;
+    /**
+     * Output UTXOs created by this deposit. Safe to read before submission —
+     * the commitment values are deterministic from the circuit inputs and do
+     * not depend on the on-chain result.
+     */
+    outputUTXOs: [SerializedUTXO, SerializedUTXO];
+    /**
+     * Inserts the two output commitments into the local {@link MerkleTree} and
+     * returns the receipt. Call this **only after** the on-chain transaction
+     * has been confirmed — deferring the insert keeps the local tree
+     * consistent with chain state if the submission fails.
+     *
+     * Calling `commit()` more than once is unsupported and will corrupt the
+     * local tree.
+     */
+    commit: () => DepositResult;
+};
+/**
+ * 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 declare function deposit<T extends Idl>(params: {
+    program: Program<T>;
+    /**
+     * Account that will pay for and sign the deposit transaction. Only
+     * `publicKey` is read — `deposit()` never touches a secret key. A browser
+     * wallet-adapter wallet, a Node `anchor.Wallet`, or a raw `Keypair` are all
+     * structurally acceptable.
+     */
+    depositor: {
+        publicKey: PublicKey;
+    };
+    amount: bigint;
+    mintAddress: PublicKey;
+    recipientPubkey: bigint;
+    tree: MerkleTree;
+    proofBuilder: TransactionProofBuilder;
+    treeId?: number;
+    extData?: Partial<ExtData>;
+}): Promise<DepositBuild>;
+/**
+ * Result of a withdrawal operation.
+ */
+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;
+}): Promise<WithdrawResult>;
+/**
+ * Result of a private transfer operation.
+ */
+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;
+    fee?: bigint;
+}): Promise<TransferResult>;
+/**
+ * Update the global config.
+ * Currently takes no extra args — only admin verification.
+ */
+export declare function updateGlobalConfig<T extends Idl>(params: {
+    program: Program<T>;
+    admin: anchor.Wallet;
+}): Promise<void>;
+/**
+ * Get the swap executor PDA.
+ * Seeds: ["swap_executor", source_mint, dest_mint, input_nullifier_0, relayer]
+ */
+export declare function getSwapExecutorPda(programId: PublicKey, sourceMint: PublicKey, destMint: PublicKey, inputNullifier0: Uint8Array, relayer: PublicKey): PublicKey;
+/**
+ * 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 declare function fundNativeSource<T extends Idl>(params: {
+    program: Program<T>;
+    relayer: Keypair;
+    sourceMint: PublicKey;
+    destMint: PublicKey;
+    inputNullifier0: Uint8Array;
+    swapAmount: bigint;
+}): Promise<anchor.web3.TransactionInstruction>;
+/**
+ * Swap proof struct (same encoding as TransactionProofStruct).
+ */
+export type SwapProofStruct = TransactionProofStruct;
+/**
+ * Swap params committed to in the ZK proof.
+ */
+export type SwapParams = {
+    minAmountOut: bigint;
+    deadline: bigint;
+    sourceMint: PublicKey;
+    destMint: PublicKey;
+    destAmount: bigint;
+    /** SHA-256 of raw swap instruction bytes; use all-zeros for CPMM/AMM swaps. */
+    swapDataHash: Uint8Array;
+};
+/**
+ * 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 declare function transactSwap<T extends Idl>(params: {
+    program: Program<T>;
+    relayer: Keypair;
+    sourceMint: PublicKey;
+    destMint: PublicKey;
+    sourceRoot: Uint8Array;
+    sourceTreeId: number;
+    destTreeId: number;
+    inputNullifiers: [Uint8Array, Uint8Array];
+    outputCommitments: [Uint8Array, Uint8Array];
+    proof: SwapProofStruct;
+    swapParams: SwapParams;
+    swapAmount: bigint;
+    swapData: Buffer;
+    extData: ExtData;
+    sourceVaultTokenAccount: PublicKey;
+    sourceMintAccount: PublicKey;
+    destVaultTokenAccount: PublicKey;
+    destMintAccount: PublicKey;
+    relayerTokenAccount: PublicKey;
+    swapProgram: PublicKey;
+    jupiterEventAuthority: PublicKey;
+}): Promise<string>;