@veilo/sdk-core 0.4.0 → 0.5.0

package/dist/src/client.d.ts

@@ -1,407 +0,0 @@
-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>;