@hula-privacy/mixer 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,933 @@
+import { PublicKey, TransactionInstruction, Keypair, Connection } from '@solana/web3.js';
+import { BN, Program } from '@coral-xyz/anchor';
+import { Poseidon } from 'circomlibjs';
+
+/**
+ * Type definitions for Hula Privacy SDK
+ */
+
+/**
+ * UTXO (Unspent Transaction Output) in the privacy pool
+ */
+interface UTXO {
+    /** Amount in raw token units */
+    value: bigint;
+    /** Token mint address as bigint */
+    mintTokenAddress: bigint;
+    /** Owner hash (derived from spending key) */
+    owner: bigint;
+    /** Random blinding factor */
+    secret: bigint;
+    /** Poseidon hash commitment */
+    commitment: bigint;
+    /** Index in the merkle tree */
+    leafIndex: number;
+    /** Which tree this UTXO is in */
+    treeIndex: number;
+}
+/**
+ * Serializable UTXO for storage/transmission
+ */
+interface SerializableUTXO {
+    value: string;
+    mintTokenAddress: string;
+    owner: string;
+    secret: string;
+    commitment: string;
+    leafIndex: number;
+    treeIndex: number;
+    /** Token mint public key */
+    mint: string;
+    /** Whether this UTXO has been spent */
+    spent: boolean;
+    /** Transaction that spent this UTXO */
+    spentTx?: string;
+    /** Transaction that created this UTXO */
+    createdTx: string;
+    /** Timestamp when created */
+    createdAt: string;
+}
+/**
+ * Wallet keys derived from spending key
+ */
+interface WalletKeys {
+    /** Master spending key - KEEP SECRET */
+    spendingKey: bigint;
+    /** Owner hash - public identifier for receiving funds */
+    owner: bigint;
+    /** Viewing key - for decrypting notes */
+    viewingKey: bigint;
+    /** Nullifier key - for computing nullifiers */
+    nullifierKey: bigint;
+    /** X25519 keypair for note encryption */
+    encryptionKeyPair: {
+        publicKey: Uint8Array;
+        secretKey: Uint8Array;
+    };
+}
+/**
+ * Encrypted note attached to transactions
+ */
+interface EncryptedNote {
+    /** Ephemeral public key for ECDH */
+    ephemeralPubKey: Uint8Array;
+    /** Encrypted ciphertext */
+    ciphertext: Uint8Array;
+    /** Nonce for decryption */
+    nonce: Uint8Array;
+}
+/**
+ * Merkle path for proving inclusion
+ */
+interface MerklePath {
+    /** Sibling hashes at each level */
+    pathElements: bigint[];
+    /** Direction at each level (0 = left, 1 = right) */
+    pathIndices: number[];
+    /** Root of the tree */
+    root: bigint;
+}
+/**
+ * Leaf data from the relayer
+ */
+interface LeafData {
+    id: string;
+    treeIndex: number;
+    leafIndex: number;
+    commitment: string;
+    slot: string;
+    createdAt: string;
+}
+/**
+ * Circuit inputs for ZK proof generation
+ */
+interface CircuitInputs {
+    merkleRoot: string;
+    nullifiers: string[];
+    outputCommitments: string[];
+    publicDeposit: string;
+    publicWithdraw: string;
+    recipient: string;
+    mintTokenAddress: string;
+    fee: string;
+    inputSpendingKeys: string[];
+    inputValues: string[];
+    inputSecrets: string[];
+    inputLeafIndices: string[];
+    inputPathElements: string[][];
+    inputPathIndices: number[][];
+    outputValues: string[];
+    outputOwners: string[];
+    outputSecrets: string[];
+}
+/**
+ * Public inputs for the on-chain verifier
+ */
+interface PublicInputs {
+    merkleRoot: number[];
+    nullifiers: number[][];
+    outputCommitments: number[][];
+    publicDeposit: bigint;
+    publicWithdraw: bigint;
+    recipient: PublicKey;
+    mintTokenAddress: PublicKey;
+    fee: bigint;
+}
+/**
+ * Output UTXO specification
+ */
+interface OutputSpec {
+    /** Owner hash (bigint) or "self" for own wallet */
+    owner: bigint | "self";
+    /** Amount in raw token units */
+    amount: bigint;
+    /** Encryption public key for encrypted note (optional) */
+    encryptionPubKey?: Uint8Array;
+}
+/**
+ * Transaction request for building a privacy transaction
+ */
+interface TransactionRequest {
+    /** Amount to deposit from public wallet */
+    depositAmount?: bigint;
+    /** Input UTXOs to spend */
+    inputUtxos?: UTXO[];
+    /** Output UTXOs to create */
+    outputs?: OutputSpec[];
+    /** Amount to withdraw to public wallet */
+    withdrawAmount?: bigint;
+    /** Recipient public key for withdrawal */
+    recipient?: PublicKey;
+    /** Relayer fee */
+    fee?: bigint;
+    /** Token mint address */
+    mint: PublicKey;
+}
+/**
+ * Built transaction ready for submission
+ */
+interface BuiltTransaction {
+    /** Proof bytes (256 bytes) */
+    proof: Uint8Array;
+    /** Public inputs for the circuit */
+    publicInputs: PublicInputs;
+    /** Encrypted notes for outputs */
+    encryptedNotes: Buffer[];
+    /** Created output UTXOs (for tracking) */
+    outputUtxos: UTXO[];
+    /** Nullifiers being spent */
+    nullifiers: bigint[];
+    /** Input tree index */
+    inputTreeIndex: number;
+    /** Output tree index (current tree) */
+    outputTreeIndex: number;
+}
+/**
+ * Paginated response from relayer
+ */
+interface PaginatedResponse<T> {
+    items: T[];
+    nextCursor: string | null;
+    hasMore: boolean;
+}
+/**
+ * Pool data from relayer
+ */
+interface PoolData {
+    authority: string;
+    commitmentCount: string;
+    merkleRoot: string;
+    paused: boolean;
+    currentTreeIndex: number;
+    lastSlot: string;
+}
+/**
+ * Tree data from relayer
+ */
+interface TreeData {
+    id: string;
+    treeIndex: number;
+    nextIndex: number;
+    root: string;
+}
+/**
+ * Transaction data from relayer
+ */
+interface TransactionData {
+    id: string;
+    signature: string;
+    slot: string;
+    blockTime?: string;
+    payer: string;
+    mint: string;
+    outputTreeIndex: number;
+    publicDeposit: string;
+    publicWithdraw: string;
+    fee: string;
+    success: boolean;
+    nullifiers: string[];
+    encryptedNotes: {
+        noteIndex: number;
+        data: string;
+    }[];
+}
+/**
+ * Encrypted note data from relayer
+ */
+interface NoteData {
+    id: string;
+    noteIndex: number;
+    encryptedData: string;
+    txSignature: string;
+    slot: string;
+    mint: string;
+    treeIndex: number;
+}
+/**
+ * Stats from relayer
+ */
+interface StatsData {
+    pool: {
+        commitmentCount: string;
+        currentTreeIndex: number;
+        paused: boolean;
+    } | null;
+    treeCount: number;
+    leafCount: number;
+    transactionCount: number;
+    nullifierCount: number;
+}
+/**
+ * SDK configuration
+ */
+interface HulaSDKConfig {
+    /** Solana RPC endpoint */
+    rpcUrl: string;
+    /** Relayer API endpoint */
+    relayerUrl: string;
+    /** Program ID for the Hula Privacy program */
+    programId?: PublicKey;
+    /** Path to circuit WASM file */
+    circuitWasmPath?: string;
+    /** Path to circuit zkey file */
+    circuitZkeyPath?: string;
+    /** Network: localnet | devnet | mainnet */
+    network?: "localnet" | "devnet" | "mainnet";
+}
+/**
+ * Wallet sync progress
+ */
+interface SyncProgress {
+    stage: "notes" | "nullifiers" | "complete";
+    current: number;
+    total: number;
+}
+/**
+ * Wallet sync result
+ */
+interface SyncResult {
+    newUtxos: number;
+    spentUtxos: number;
+    errors: string[];
+}
+
+/**
+ * Transaction building for Hula Privacy Protocol
+ *
+ * Builds privacy transactions with ZK proofs
+ */
+
+/**
+ * Build a privacy transaction
+ *
+ * This handles all transaction types: deposits, transfers, and withdrawals.
+ */
+declare function buildTransaction(request: TransactionRequest, walletKeys: WalletKeys, relayerUrl?: string): Promise<BuiltTransaction>;
+/**
+ * Build Solana transaction accounts and instructions
+ *
+ * This creates the account list and any pre-instructions needed for the transaction.
+ */
+declare function buildTransactionAccounts(builtTx: BuiltTransaction, payer: PublicKey, mint: PublicKey, depositAmount: bigint, withdrawAmount: bigint, recipient?: PublicKey): {
+    accounts: {
+        payer: PublicKey;
+        mint: PublicKey;
+        pool: PublicKey;
+        inputTree: PublicKey;
+        merkleTree: PublicKey;
+        vault: PublicKey;
+        depositorTokenAccount: PublicKey | null;
+        depositor: PublicKey | null;
+        recipientTokenAccount: PublicKey | null;
+        feeRecipientTokenAccount: PublicKey | null;
+        nullifierAccount0: PublicKey | null;
+        nullifierAccount1: PublicKey | null;
+        tokenProgram: PublicKey;
+        systemProgram: PublicKey;
+    };
+    preInstructions: TransactionInstruction[];
+    inputTreeIndex: number | null;
+};
+/**
+ * Convert built transaction to Anchor-compatible format
+ */
+declare function toAnchorPublicInputs(builtTx: BuiltTransaction): {
+    merkleRoot: number[];
+    nullifiers: number[][];
+    outputCommitments: number[][];
+    publicDeposit: BN;
+    publicWithdraw: BN;
+    recipient: PublicKey;
+    mintTokenAddress: PublicKey;
+    fee: BN;
+};
+
+/**
+ * Wallet management for Hula Privacy Protocol
+ *
+ * High-level wallet abstraction that manages keys, UTXOs, and syncing
+ */
+
+/**
+ * Hula Privacy Wallet
+ *
+ * High-level abstraction for managing privacy transactions
+ */
+declare class HulaWallet {
+    private connection;
+    private relayerUrl;
+    private programId;
+    private keys;
+    private signer?;
+    private utxos;
+    private lastSyncedSlot;
+    private initialized;
+    private constructor();
+    /**
+     * Create a new wallet with a random spending key
+     */
+    static create(config: HulaSDKConfig): Promise<HulaWallet>;
+    /**
+     * Create a wallet from a Solana keypair
+     *
+     * Derives the spending key deterministically from the keypair's secret key.
+     */
+    static fromKeypair(keypair: Keypair, config: HulaSDKConfig): Promise<HulaWallet>;
+    /**
+     * Create a wallet from an existing spending key
+     */
+    static fromSpendingKey(spendingKey: bigint, config: HulaSDKConfig): Promise<HulaWallet>;
+    /**
+     * Create a wallet from a Solana signature (deterministic derivation)
+     *
+     * This allows recovery as long as the user can sign with their Solana wallet.
+     */
+    static fromSignature(signature: Uint8Array, config: HulaSDKConfig): Promise<HulaWallet>;
+    /**
+     * Get wallet's owner hash (public identifier)
+     */
+    get owner(): bigint;
+    /**
+     * Get wallet's owner hash as hex string
+     */
+    getOwnerHash(): string;
+    /**
+     * Get wallet's encryption public key as hex string
+     */
+    getEncryptionPublicKey(): string;
+    /**
+     * Get wallet's encryption public key as bytes
+     */
+    get encryptionPublicKey(): Uint8Array;
+    /**
+     * Get spending key (CAREFUL - this is sensitive!)
+     */
+    get spendingKey(): bigint;
+    /**
+     * Get all wallet keys
+     */
+    get walletKeys(): WalletKeys;
+    /**
+     * Get the connection
+     */
+    getConnection(): Connection;
+    /**
+     * Get the signer keypair (if available)
+     */
+    getSigner(): Keypair | undefined;
+    /**
+     * Set the signer keypair
+     */
+    setSigner(signer: Keypair): void;
+    /**
+     * Sync wallet with relayer
+     *
+     * Fetches new encrypted notes and checks for spent UTXOs.
+     */
+    sync(onProgress?: (progress: SyncProgress) => void): Promise<SyncResult>;
+    /**
+     * Get all unspent UTXOs
+     */
+    getUnspentUTXOs(): UTXO[];
+    /**
+     * Get all UTXOs (including spent)
+     */
+    getAllUTXOs(): SerializableUTXO[];
+    /**
+     * Get balance for a specific mint
+     */
+    getBalance(mint: PublicKey): bigint;
+    /**
+     * Import UTXOs (for wallet recovery or manual import)
+     */
+    importUTXOs(utxos: SerializableUTXO[]): void;
+    /**
+     * Export UTXOs for backup
+     */
+    exportUTXOs(): SerializableUTXO[];
+    /**
+     * Deposit tokens into the privacy pool
+     *
+     * @param mint - Token mint address
+     * @param amount - Amount in raw token units
+     * @returns Transaction signature
+     */
+    deposit(mint: PublicKey, amount: bigint): Promise<string>;
+    /**
+     * Transfer tokens privately to another user
+     *
+     * @param mint - Token mint address
+     * @param amount - Amount in raw token units
+     * @param recipientOwner - Recipient's owner hash (bigint)
+     * @param recipientEncryptionPubKey - Recipient's encryption public key
+     * @returns Transaction signature
+     */
+    transfer(mint: PublicKey, amount: bigint, recipientOwner: bigint, recipientEncryptionPubKey: Uint8Array): Promise<string>;
+    /**
+     * Withdraw tokens from the privacy pool to a public address
+     *
+     * @param mint - Token mint address
+     * @param amount - Amount in raw token units
+     * @param recipient - Public key to receive the tokens
+     * @returns Transaction signature
+     */
+    withdraw(mint: PublicKey, amount: bigint, recipient: PublicKey): Promise<string>;
+    /**
+     * Build a custom transaction
+     */
+    buildTransaction(request: Omit<TransactionRequest, "mint"> & {
+        mint: PublicKey;
+    }): Promise<{
+        transaction: ReturnType<typeof buildTransaction> extends Promise<infer T> ? T : never;
+        instructions: TransactionInstruction[];
+    }>;
+    /**
+     * Submit a transaction using an Anchor program
+     *
+     * @param program - Anchor program instance (any type to avoid IDL complexity)
+     * @param payer - Keypair for signing
+     * @param builtTx - Built transaction from buildTransaction()
+     * @param mint - Token mint
+     * @param depositAmount - Amount being deposited (if any)
+     * @param withdrawAmount - Amount being withdrawn (if any)
+     * @param recipient - Recipient for withdrawal (if any)
+     */
+    submitTransaction(program: Program<any>, payer: Keypair, builtTx: Awaited<ReturnType<typeof buildTransaction>>, mint: PublicKey, depositAmount?: bigint, withdrawAmount?: bigint, recipient?: PublicKey): Promise<string>;
+}
+/**
+ * Create a deterministic message for wallet key derivation
+ */
+declare function getKeyDerivationMessage(): Uint8Array;
+/**
+ * Quick initialization for SDK usage
+ */
+declare function initHulaSDK(): Promise<void>;
+
+/**
+ * Relayer API Client
+ *
+ * Fetches data from the relayer with cursor-based pagination
+ */
+
+/**
+ * API client for the Hula Privacy relayer
+ */
+declare class RelayerClient {
+    private baseUrl;
+    constructor(baseUrl?: string);
+    private fetch;
+    /**
+     * Health check
+     */
+    health(): Promise<{
+        status: string;
+        timestamp: string;
+    }>;
+    /**
+     * Get protocol stats
+     */
+    getStats(): Promise<StatsData>;
+    /**
+     * Get pool data
+     */
+    getPool(): Promise<PoolData>;
+    /**
+     * Get all merkle trees
+     */
+    getTrees(): Promise<{
+        trees: TreeData[];
+    }>;
+    /**
+     * Get tree by index
+     */
+    getTree(treeIndex: number): Promise<TreeData>;
+    /**
+     * Get leaves with cursor pagination
+     */
+    getLeaves(cursor?: string, limit?: number, treeIndex?: number): Promise<PaginatedResponse<LeafData>>;
+    /**
+     * Get leaves after a specific index (for syncing)
+     */
+    getLeavesAfter(treeIndex: number, afterLeafIndex: number, limit?: number): Promise<{
+        items: {
+            treeIndex: number;
+            leafIndex: number;
+            commitment: string;
+            slot: string;
+        }[];
+        hasMore: boolean;
+        lastLeafIndex: number;
+    }>;
+    /**
+     * Get all leaves for a tree (auto-paginated)
+     */
+    getAllLeavesForTree(treeIndex: number): Promise<LeafData[]>;
+    /**
+     * Get all commitment values for a tree as bigints
+     */
+    getCommitmentsForTree(treeIndex: number): Promise<bigint[]>;
+    /**
+     * Get transactions with cursor pagination
+     */
+    getTransactions(cursor?: string, limit?: number, mint?: string): Promise<PaginatedResponse<TransactionData>>;
+    /**
+     * Get transaction by signature
+     */
+    getTransaction(signature: string): Promise<TransactionData>;
+    /**
+     * Check if nullifier is spent
+     */
+    checkNullifier(nullifier: string): Promise<{
+        nullifier: string;
+        spent: boolean;
+        spentAt?: string;
+    }>;
+    /**
+     * Check multiple nullifiers at once
+     */
+    checkNullifiersBatch(nullifiers: string[]): Promise<{
+        results: {
+            nullifier: string;
+            spent: boolean;
+        }[];
+    }>;
+    /**
+     * Get encrypted notes with cursor pagination
+     */
+    getNotes(cursor?: string, limit?: number, afterSlot?: string): Promise<PaginatedResponse<NoteData>>;
+    /**
+     * Get all notes (auto-paginated)
+     */
+    getAllNotes(afterSlot?: string): Promise<NoteData[]>;
+}
+/**
+ * Get or create the default relayer client
+ */
+declare function getRelayerClient(url?: string): RelayerClient;
+/**
+ * Set the default relayer URL
+ */
+declare function setDefaultRelayerUrl(url: string): void;
+
+/**
+ * Cryptographic utilities for Hula Privacy Protocol
+ *
+ * Includes Poseidon hashing, key derivation, and encryption
+ */
+
+/**
+ * Initialize Poseidon hasher (must be called once before using hash functions)
+ */
+declare function initPoseidon(): Promise<void>;
+/**
+ * Check if Poseidon is initialized
+ */
+declare function isPoseidonInitialized(): boolean;
+/**
+ * Get Poseidon instance (throws if not initialized)
+ */
+declare function getPoseidon(): Poseidon;
+/**
+ * Poseidon hash of inputs
+ */
+declare function poseidonHash(inputs: bigint[]): bigint;
+/**
+ * Convert bytes to bigint (big-endian)
+ */
+declare function bytesToBigInt(bytes: Uint8Array): bigint;
+/**
+ * Convert bigint to bytes (big-endian)
+ */
+declare function bigIntToBytes(value: bigint, length: number): Uint8Array;
+/**
+ * Convert bigint to 32-byte array (big-endian)
+ */
+declare function bigIntToBytes32(value: bigint): Uint8Array;
+/**
+ * Convert hex string to bytes
+ */
+declare function hexToBytes(hex: string): Uint8Array;
+/**
+ * Convert bytes to hex string
+ */
+declare function bytesToHex(bytes: Uint8Array): string;
+/**
+ * Convert PublicKey to bigint
+ */
+declare function pubkeyToBigInt(pubkey: {
+    toBytes(): Uint8Array;
+}): bigint;
+/**
+ * Generate a new random spending key
+ */
+declare function generateSpendingKey(): bigint;
+/**
+ * Derive all wallet keys from spending key
+ */
+declare function deriveKeys(spendingKey: bigint): WalletKeys;
+/**
+ * Derive spending key from wallet signature
+ *
+ * This allows deterministic key derivation from a Solana wallet signature,
+ * enabling wallet recovery as long as the user has access to their wallet.
+ */
+declare function deriveSpendingKeyFromSignature(signature: Uint8Array): bigint;
+/**
+ * Encrypt a note for a recipient
+ *
+ * The note contains the UTXO data needed for the recipient to claim it.
+ * Optimized for size:
+ * - mintTokenAddress: only first 8 bytes (can match on-chain by prefix)
+ * - leafIndex: omitted (recipient can query relayer with commitment)
+ */
+declare function encryptNote(noteData: {
+    value: bigint;
+    mintTokenAddress: bigint;
+    secret: bigint;
+    leafIndex?: number;
+}, recipientEncryptionPubKey: Uint8Array): EncryptedNote;
+/**
+ * Decrypt an encrypted note
+ *
+ * Returns null if decryption fails (not intended for this recipient)
+ * Note: leafIndex is not included in encrypted notes to save space.
+ * The recipient should query the relayer with the computed commitment.
+ */
+declare function decryptNote(encryptedNote: EncryptedNote, encryptionSecretKey: Uint8Array): {
+    value: bigint;
+    mintPrefix: string;
+    secret: bigint;
+} | null;
+/**
+ * Serialize encrypted note for on-chain storage
+ */
+declare function serializeEncryptedNote(note: EncryptedNote): Uint8Array;
+/**
+ * Deserialize encrypted note from on-chain data
+ */
+declare function deserializeEncryptedNote(data: Uint8Array): EncryptedNote;
+/**
+ * Format a commitment/nullifier for display (truncated hex)
+ */
+declare function formatCommitment(value: bigint | Uint8Array, length?: number): string;
+
+/**
+ * UTXO (Unspent Transaction Output) management
+ *
+ * Provides functions for creating, scanning, and managing UTXOs
+ */
+
+/**
+ * Compute UTXO commitment
+ * commitment = Poseidon(value, mintTokenAddress, owner, secret)
+ */
+declare function computeCommitment(value: bigint, mintTokenAddress: bigint, owner: bigint, secret: bigint): bigint;
+/**
+ * Compute nullifier for spending a UTXO
+ * nullifier = Poseidon(nullifierKey, commitment, leafIndex)
+ */
+declare function computeNullifier(spendingKey: bigint, commitment: bigint, leafIndex: number): bigint;
+/**
+ * Compute nullifier from wallet keys
+ */
+declare function computeNullifierFromKeys(keys: WalletKeys, commitment: bigint, leafIndex: number): bigint;
+/**
+ * Create a new UTXO with random secret
+ */
+declare function createUTXO(value: bigint, mintTokenAddress: bigint, owner: bigint, leafIndex: number, treeIndex?: number): UTXO;
+/**
+ * Create a dummy (zero) UTXO for padding
+ */
+declare function createDummyUTXO(): UTXO;
+/**
+ * Serialize UTXO for storage
+ */
+declare function serializeUTXO(utxo: UTXO, mint: string, createdTx: string, spent?: boolean, spentTx?: string): SerializableUTXO;
+/**
+ * Deserialize UTXO from storage
+ */
+declare function deserializeUTXO(data: SerializableUTXO): UTXO;
+/**
+ * Scan encrypted notes for UTXOs belonging to this wallet
+ *
+ * This attempts to decrypt each note with the wallet's encryption key.
+ * If successful, the note belongs to this wallet.
+ */
+declare function scanNotesForUTXOs(notes: Array<{
+    encryptedData: string;
+    treeIndex: number;
+    mint: string;
+    txSignature: string;
+}>, walletKeys: WalletKeys, commitments: Map<number, Map<number, bigint>>): SerializableUTXO[];
+/**
+ * Sync wallet UTXOs from relayer
+ *
+ * This fetches all encrypted notes and attempts to decrypt them.
+ * Also checks which UTXOs have been spent.
+ */
+declare function syncUTXOs(walletKeys: WalletKeys, existingUTXOs: SerializableUTXO[], relayerUrl?: string, afterSlot?: string): Promise<{
+    newUTXOs: SerializableUTXO[];
+    spentUTXOs: string[];
+}>;
+/**
+ * Select UTXOs for spending (greedy algorithm)
+ *
+ * Selects the largest UTXOs first until the target amount is reached.
+ */
+declare function selectUTXOs(utxos: UTXO[], targetAmount: bigint, mint?: bigint): UTXO[];
+/**
+ * Calculate total balance of UTXOs
+ */
+declare function calculateBalance(utxos: UTXO[], mint?: bigint): bigint;
+
+/**
+ * Merkle Tree utilities for Hula Privacy Protocol
+ *
+ * Provides functions for building merkle paths from relayer data
+ */
+
+/**
+ * Compute zero hashes for the merkle tree using Poseidon
+ * ZEROS[0] = 0 (empty leaf)
+ * ZEROS[i+1] = Poseidon(ZEROS[i], ZEROS[i])
+ */
+declare function computeZeros(): bigint[];
+/**
+ * Get zero value at a specific level
+ */
+declare function getZeroAtLevel(level: number): bigint;
+/**
+ * Get the root of an empty merkle tree
+ */
+declare function getEmptyTreeRoot(): bigint;
+/**
+ * Compute merkle path from a list of leaves
+ *
+ * This builds the full tree locally and extracts the path for the given leaf.
+ * Use this when you have fetched all leaves from the relayer.
+ */
+declare function computeMerklePathFromLeaves(leafIndex: number, leaves: bigint[]): MerklePath;
+/**
+ * Compute merkle root from leaves
+ */
+declare function computeMerkleRoot(leaves: bigint[]): bigint;
+/**
+ * Verify a merkle path is valid
+ */
+declare function verifyMerklePath(leafValue: bigint, path: MerklePath): boolean;
+/**
+ * Fetch merkle path for a UTXO from the relayer
+ *
+ * This fetches all leaves for the tree and computes the path locally.
+ */
+declare function fetchMerklePath(treeIndex: number, leafIndex: number, relayerUrl?: string): Promise<MerklePath>;
+/**
+ * Fetch current merkle root for a tree from the relayer
+ */
+declare function fetchMerkleRoot(treeIndex: number, relayerUrl?: string): Promise<bigint>;
+/**
+ * Get next leaf index for a tree
+ */
+declare function getNextLeafIndex(treeIndex: number, relayerUrl?: string): Promise<number>;
+/**
+ * Get current active tree index
+ */
+declare function getCurrentTreeIndex(relayerUrl?: string): Promise<number>;
+
+/**
+ * ZK Proof generation utilities
+ *
+ * Uses snarkjs to generate Groth16 proofs for the transaction circuit
+ */
+
+/**
+ * Set circuit file paths
+ */
+declare function setCircuitPaths(wasmPath: string, zkeyPath: string): void;
+/**
+ * Get circuit file paths (with fallback to default locations)
+ */
+declare function getCircuitPaths(): {
+    wasmPath: string;
+    zkeyPath: string;
+};
+/**
+ * Verify circuit files exist
+ */
+declare function verifyCircuitFiles(): void;
+/**
+ * Parse snarkjs proof JSON into 256-byte proof array
+ *
+ * Format: proof_a (64 bytes) + proof_b (128 bytes) + proof_c (64 bytes)
+ */
+declare function parseProof(proofJson: {
+    pi_a: string[];
+    pi_b: string[][];
+    pi_c: string[];
+}): Uint8Array;
+/**
+ * Generate ZK proof using snarkjs CLI (subprocess for Bun compatibility)
+ *
+ * This spawns snarkjs as a subprocess to avoid web-worker issues with Bun.
+ * Works in both Node.js and Bun environments.
+ */
+declare function generateProof(circuitInputs: CircuitInputs): Promise<{
+    proof: Uint8Array;
+    publicSignals: string[];
+}>;
+/**
+ * Generate proof using snarkjs in-memory (for Node.js environments)
+ *
+ * This is more efficient but may not work in all environments.
+ */
+declare function generateProofInMemory(circuitInputs: CircuitInputs): Promise<{
+    proof: Uint8Array;
+    publicSignals: string[];
+}>;
+
+/**
+ * Constants for Hula Privacy Protocol
+ */
+
+/** Hula Privacy Program ID */
+declare const PROGRAM_ID: PublicKey;
+/** Token 2022 Program ID */
+declare const TOKEN_2022_PROGRAM_ID: PublicKey;
+declare const POOL_SEED: Buffer<ArrayBuffer>;
+declare const VAULT_SEED: Buffer<ArrayBuffer>;
+declare const MERKLE_TREE_SEED: Buffer<ArrayBuffer>;
+declare const NULLIFIER_SEED: Buffer<ArrayBuffer>;
+/** Number of input UTXOs in circuit */
+declare const NUM_INPUT_UTXOS = 2;
+/** Number of output UTXOs in circuit */
+declare const NUM_OUTPUT_UTXOS = 2;
+/** Depth of merkle tree */
+declare const MERKLE_TREE_DEPTH = 10;
+/** Maximum leaves per tree (2^DEPTH) */
+declare const MAX_LEAVES: number;
+/** Size of proof in bytes */
+declare const PROOF_SIZE = 256;
+declare const DOMAIN_OWNER = 0n;
+declare const DOMAIN_VIEWING = 1n;
+declare const DOMAIN_NULLIFIER = 2n;
+declare const DOMAIN_ENCRYPTION = 3n;
+/** BN254 field prime */
+declare const FIELD_PRIME: bigint;
+/**
+ * Derive Pool PDA
+ */
+declare function getPoolPDA(): [PublicKey, number];
+/**
+ * Derive Merkle Tree PDA for a specific tree index
+ */
+declare function getMerkleTreePDA(treeIndex?: number): [PublicKey, number];
+/**
+ * Derive Vault PDA for a specific mint
+ */
+declare function getVaultPDA(mint: PublicKey): [PublicKey, number];
+/**
+ * Derive Nullifier PDA for a nullifier hash
+ */
+declare function getNullifierPDA(nullifier: Uint8Array): [PublicKey, number];
+
+export { type BuiltTransaction, type CircuitInputs, DOMAIN_ENCRYPTION, DOMAIN_NULLIFIER, DOMAIN_OWNER, DOMAIN_VIEWING, type EncryptedNote, FIELD_PRIME, type HulaSDKConfig, HulaWallet, type LeafData, MAX_LEAVES, MERKLE_TREE_DEPTH, MERKLE_TREE_SEED, type MerklePath, NULLIFIER_SEED, NUM_INPUT_UTXOS, NUM_OUTPUT_UTXOS, type NoteData, type OutputSpec, POOL_SEED, PROGRAM_ID, PROOF_SIZE, type PaginatedResponse, type PoolData, type PublicInputs, RelayerClient, type SerializableUTXO, type StatsData, type SyncProgress, type SyncResult, TOKEN_2022_PROGRAM_ID, type TransactionData, type TransactionRequest, type TreeData, type UTXO, VAULT_SEED, type WalletKeys, bigIntToBytes, bigIntToBytes32, buildTransaction, buildTransactionAccounts, bytesToBigInt, bytesToHex, calculateBalance, computeCommitment, computeMerklePathFromLeaves, computeMerkleRoot, computeNullifier, computeNullifierFromKeys, computeZeros, createDummyUTXO, createUTXO, decryptNote, deriveKeys, deriveSpendingKeyFromSignature, deserializeEncryptedNote, deserializeUTXO, encryptNote, fetchMerklePath, fetchMerkleRoot, formatCommitment, generateProof, generateProofInMemory, generateSpendingKey, getCircuitPaths, getCurrentTreeIndex, getEmptyTreeRoot, getKeyDerivationMessage, getMerkleTreePDA, getNextLeafIndex, getNullifierPDA, getPoolPDA, getPoseidon, getRelayerClient, getVaultPDA, getZeroAtLevel, hexToBytes, initHulaSDK, initPoseidon, isPoseidonInitialized, parseProof, poseidonHash, pubkeyToBigInt, scanNotesForUTXOs, selectUTXOs, serializeEncryptedNote, serializeUTXO, setCircuitPaths, setDefaultRelayerUrl, syncUTXOs, toAnchorPublicInputs, verifyCircuitFiles, verifyMerklePath };