@cloak.dev/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,3430 @@
+import { PublicKey, Transaction, Connection, TransactionInstruction, Keypair, SendOptions, AddressLookupTableAccount, VersionedTransaction } from '@solana/web3.js';
+
+type ComplianceTxType = "deposit" | "withdraw" | "send" | "swap";
+interface TransactionMetadata {
+    amount: number;
+    recipient: string;
+    timestamp: number;
+    txType: ComplianceTxType;
+    commitment: string;
+    signature?: string;
+    outputMint?: string;
+}
+interface EncryptedMetadataBundle {
+    encrypted_user: string;
+    encrypted_compliance: string;
+    user_pubkey: string;
+    commitment: string;
+    timestamp: number;
+    tx_type?: ComplianceTxType;
+    wallet_signature?: string;
+    viewing_key?: string;
+}
+
+/**
+ * Supported Solana networks
+ */
+type Network = "localnet" | "devnet" | "mainnet" | "testnet";
+/**
+ * Minimal wallet adapter interface
+ * Compatible with @solana/wallet-adapter-base
+ */
+interface WalletAdapter {
+    publicKey: PublicKey | null;
+    signTransaction?<T extends Transaction>(transaction: T): Promise<T>;
+    signAllTransactions?<T extends Transaction>(transactions: T[]): Promise<T[]>;
+    sendTransaction?(transaction: Transaction, connection: any, options?: any): Promise<string>;
+}
+/**
+ * Cloak-specific error with categorization
+ */
+declare class CloakError extends Error {
+    category: "network" | "indexer" | "prover" | "relay" | "validation" | "wallet" | "environment" | "service";
+    retryable: boolean;
+    originalError?: Error | undefined;
+    constructor(message: string, category: "network" | "indexer" | "prover" | "relay" | "validation" | "wallet" | "environment" | "service", retryable?: boolean, originalError?: Error | undefined);
+}
+/**
+ * Cloak Note - Represents a private transaction commitment
+ *
+ * A note contains all the information needed to withdraw funds from the Cloak protocol.
+ * Keep this safe and secret - anyone with access to this note can withdraw the funds!
+ */
+interface CloakNote {
+    /** Protocol version */
+    version: string;
+    /** Amount in lamports */
+    amount: number;
+    /** Commitment hash (hex) */
+    commitment: string;
+    /** Spending secret key (hex, 64 chars) */
+    sk_spend: string;
+    /** Randomness value (hex, 64 chars) */
+    r: string;
+    /** Transaction signature from deposit (optional until deposited) */
+    depositSignature?: string;
+    /** Solana slot when deposited (optional until deposited) */
+    depositSlot?: number;
+    /** Index in the Merkle tree (optional until deposited) */
+    leafIndex?: number;
+    /** Historical Merkle root at time of deposit (optional until deposited) */
+    root?: string;
+    /** Merkle proof at time of deposit (optional until deposited) */
+    merkleProof?: MerkleProof;
+    /** Creation timestamp */
+    timestamp: number;
+    /** Network where this note was created */
+    network: Network;
+}
+/**
+ * Merkle proof for a leaf in the commitment tree
+ */
+interface MerkleProof {
+    /** Sibling hashes along the path (hex strings) */
+    pathElements: string[];
+    /** Path directions (0 = left, 1 = right) */
+    pathIndices: number[];
+    /** Optional root for backward compatibility */
+    root?: string;
+}
+/**
+ * Transfer recipient - used in privateTransfer
+ */
+interface Transfer {
+    /** Recipient's Solana public key */
+    recipient: PublicKey;
+    /** Amount to send in lamports */
+    amount: number;
+}
+/**
+ * Type-safe array with maximum length constraint
+ * Used to enforce 1-5 recipients in privateTransfer
+ */
+type MaxLengthArray<T, Max extends number, A extends T[] = []> = A['length'] extends Max ? A : A | MaxLengthArray<T, Max, [T, ...A]>;
+/**
+ * Result from a private transfer
+ */
+interface TransferResult {
+    /** Solana transaction signature */
+    signature: string;
+    /** Recipients and amounts that were sent */
+    outputs: Array<{
+        recipient: string;
+        amount: number;
+    }>;
+    /** Nullifier used (prevents double-spending) */
+    nullifier: string;
+    /** Merkle root that was proven against */
+    root: string;
+}
+/**
+ * Result from a deposit operation
+ */
+interface DepositResult {
+    /** The created note (save this securely!) */
+    note: CloakNote;
+    /** Solana transaction signature */
+    signature: string;
+    /** Leaf index in the Merkle tree */
+    leafIndex: number;
+    /** Current Merkle root */
+    root: string;
+}
+/**
+ * Configuration for the Cloak SDK
+ */
+interface CloakConfig {
+    /** Solana network */
+    network?: Network;
+    /**
+     * Keypair bytes for signing (deprecated - use wallet instead)
+     * @deprecated Use wallet parameter for better integration
+     */
+    keypairBytes?: Uint8Array;
+    /**
+     * Wallet adapter for signing transactions
+     * Required unless using keypairBytes
+     */
+    wallet?: WalletAdapter;
+    /**
+     * Cloak key pair for v2.0 features (note scanning, encryption)
+     * Optional but recommended for full functionality
+     */
+    cloakKeys?: any;
+    /** Optional: Proof generation timeout in milliseconds (default: 5 minutes) */
+    proofTimeout?: number;
+    /** Optional: Program ID (defaults to Cloak mainnet program) */
+    programId?: PublicKey;
+    /** Optional: Pool account address (auto-derived from program ID if not provided) */
+    poolAddress?: PublicKey;
+    /** Optional: Merkle tree account address (auto-derived if not provided) */
+    merkleTreeAddress?: PublicKey;
+    /** Optional: Treasury account address (auto-derived if not provided) */
+    treasuryAddress?: PublicKey;
+    /**
+     * Enable debug logging with structured output similar to Rust tracing.
+     *
+     * When enabled, logs SDK operations with timestamps, module paths,
+     * and key-value pairs for context:
+     *
+     * ```
+     * 2026-01-23T00:51:46.489000Z  INFO cloak::sdk: 📥 Deposit completed signature=42XB... leaf_index=757
+     * ```
+     *
+     * Can also be enabled via environment variable:
+     * - `CLOAK_DEBUG=1`
+     * - `DEBUG=cloak:*`
+     *
+     * Default: false
+     */
+    debug?: boolean;
+}
+/**
+ * Deposit progress status
+ */
+type DepositStatus = "generating_note" | "awaiting_note_acknowledgment" | "note_saved" | "creating_transaction" | "simulating" | "sending" | "confirming" | "submitting_to_indexer" | "fetching_proof" | "complete";
+/**
+ * Options for deposit operation
+ */
+interface DepositOptions {
+    /** Optional callback for progress updates with detailed status */
+    onProgress?: (status: DepositStatus | string, details?: {
+        message?: string;
+        step?: number;
+        totalSteps?: number;
+        retryAttempt?: number;
+    }) => void;
+    /** Callback when transaction is sent (before confirmation) */
+    onTransactionSent?: (signature: string) => void;
+    /** Callback when transaction is confirmed */
+    onConfirmed?: (signature: string, slot: number) => void;
+    /**
+     * CRITICAL: Callback when note is generated, BEFORE any on-chain transaction.
+     *
+     * This is your chance to safely persist the note. If you don't save the note
+     * and the deposit succeeds but the browser crashes, your funds could be lost!
+     *
+     * The callback receives the note with all secrets needed for withdrawal.
+     * The deposit will NOT proceed until this callback completes.
+     *
+     * @example
+     * ```typescript
+     * onNoteGenerated: async (note) => {
+     *   // Save to secure storage BEFORE deposit proceeds
+     *   await localStorage.setItem(`pending_note_${note.commitment}`, JSON.stringify(note));
+     *   // Or show user a modal to copy/download the note
+     * }
+     * ```
+     */
+    onNoteGenerated?: (note: CloakNote) => Promise<void> | void;
+    /**
+     * If true, require user to acknowledge the note before proceeding with deposit.
+     * When enabled with onNoteGenerated, the deposit will wait for the callback to complete.
+     * Default: true when onNoteGenerated is provided
+     */
+    requireNoteAcknowledgment?: boolean;
+    /** Skip simulation (default: false) */
+    skipPreflight?: boolean;
+    /**
+     * Compute units to request.
+     * - If `optimizeCU` is true, this is ignored and CU is determined via simulation
+     * - Otherwise defaults to 40,000 (suitable for typical deposits)
+     */
+    computeUnits?: number;
+    /**
+     * Enable simulation-based CU optimization.
+     * When true, simulates the transaction first to determine actual CU usage,
+     * then sets an optimal limit (simulated + 20% buffer).
+     *
+     * **Note: Only works in keypair mode (Node.js/scripts).**
+     * In wallet/browser mode, this is ignored because simulation would require
+     * the user to sign twice (simulation + actual tx) which is bad UX.
+     *
+     * Trade-offs:
+     * - ✅ Optimal block scheduling priority
+     * - ❌ Adds ~200-500ms latency (extra RPC call)
+     * - ❌ Only available in keypair mode
+     *
+     * Default: false (uses fixed 40K CU which is ~75% efficient for typical deposits)
+     */
+    optimizeCU?: boolean;
+    /** Priority fee in micro-lamports (default: 10,000) */
+    priorityFee?: number;
+    /**
+     * Loaded accounts data size limit in bytes.
+     *
+     * Without this, Solana defaults to 64MB which incurs CU overhead
+     * (charged at 8 CU per 32KB). Setting a lower limit improves priority.
+     *
+     * **Note for Cloak deposits:**
+     * The Shield Pool program is ~104KB, so the minimum practical limit is ~128KB.
+     *
+     * Default: 256 * 1024 (256KB) - provides safety margin above program size.
+     * Set to 0 to disable (use Solana 64MB default).
+     *
+     * @see https://www.anza.xyz/blog/cu-optimization-with-setloadedaccountsdatasizelimit
+     */
+    loadedAccountsDataSizeLimit?: number;
+    /**
+     * Optional: Encrypt output for specific recipient's view key
+     * If not provided, encrypts for the wallet's own view key (for self-scanning)
+     */
+    recipientViewKey?: string;
+    /**
+     * Skip privacy warning on testnet (default: false)
+     * Warning: Only skip if you understand the privacy limitations
+     */
+    skipPrivacyWarning?: boolean;
+}
+/**
+ * Options for private transfer/withdraw operation
+ */
+interface TransferOptions {
+    /**
+     * Optional callback for progress updates
+     * Note: relayFeeBps is automatically calculated from protocol fees
+     */
+    onProgress?: (status: string) => void;
+    /** Optional callback for proof generation progress (0-100) */
+    onProofProgress?: (percent: number) => void;
+    /**
+     * Metadata bundle for compliance tracking.
+     * On first transaction, should include viewing_key for compliance registration.
+     */
+    metadataBundle?: {
+        encrypted_user: string;
+        encrypted_compliance: string;
+        user_pubkey: string;
+        commitment: string;
+        timestamp: number;
+        tx_type?: ComplianceTxType;
+        viewing_key?: string;
+    };
+}
+/**
+ * Options for withdrawal (convenience method with single recipient)
+ */
+interface WithdrawOptions extends TransferOptions {
+    /** Whether to withdraw full amount minus fees (default: true) */
+    withdrawAll?: boolean;
+    /** Specific amount to withdraw in lamports (if not withdrawing all) */
+    amount?: number;
+}
+/**
+ * Merkle root response from indexer
+ */
+interface MerkleRootResponse {
+    root: string;
+    next_index: number;
+}
+/**
+ * Transaction status from relay service
+ */
+interface TxStatus {
+    status: "pending" | "processing" | "completed" | "failed";
+    txId?: string;
+    error?: string;
+}
+/**
+ * Swap parameters for token swaps
+ */
+interface SwapParams {
+    /** Output token mint address */
+    output_mint: string;
+    /** Slippage tolerance in basis points (e.g., 100 = 1%) */
+    slippage_bps: number;
+    /** Minimum output amount in token's smallest unit */
+    min_output_amount: number;
+}
+/**
+ * Options for swap operation
+ */
+interface SwapOptions extends TransferOptions {
+    /** Output token mint address */
+    outputMint: string;
+    /** Slippage tolerance in basis points (default: 100 = 1%) */
+    slippageBps?: number;
+    /** Minimum output amount (will be calculated from quote if not provided) */
+    minOutputAmount?: number;
+    /** Optional callback to get swap quote */
+    getQuote?: (amountLamports: number, outputMint: string, slippageBps: number) => Promise<{
+        outAmount: number;
+        minOutputAmount: number;
+    }>;
+    /**
+     * Recipient's associated token account for the output token.
+     * If not provided, will be computed automatically (requires @solana/spl-token).
+     * For browser environments, it's recommended to compute this in the frontend
+     * where @solana/spl-token is properly bundled.
+     */
+    recipientAta?: string;
+}
+/**
+ * Result from a swap operation
+ */
+interface SwapResult extends TransferResult {
+    /** Output token mint address */
+    outputMint: string;
+    /** Minimum output amount that was guaranteed */
+    minOutputAmount: number;
+    /** Actual output amount received (may be higher than min) */
+    actualOutputAmount?: number;
+}
+
+/**
+ * Cloak Key Hierarchy (v2.0)
+ *
+ * Implements view/spend key separation for privacy-preserving note scanning:
+ * - Master Seed → Spend Key → View Key → Public View Key
+ * - Enables note discovery without exposing spending authority
+ * - Compatible with v1.0 notes (backward compatible)
+ */
+interface MasterKey {
+    seed: Uint8Array;
+    seedHex: string;
+}
+interface SpendKey {
+    sk_spend: Uint8Array;
+    pk_spend: Uint8Array;
+    sk_spend_hex: string;
+    pk_spend_hex: string;
+}
+interface ViewKey {
+    vk_secret: Uint8Array;
+    pvk: Uint8Array;
+    vk_secret_hex: string;
+    pvk_hex: string;
+}
+interface CloakKeyPair {
+    master: MasterKey;
+    spend: SpendKey;
+    view: ViewKey;
+}
+interface EncryptedNote$1 {
+    ephemeral_pk: string;
+    ciphertext: string;
+    nonce: string;
+}
+interface NoteData {
+    amount: number;
+    r: string;
+    sk_spend: string;
+    commitment: string;
+}
+/**
+ * Generate a new master seed from secure randomness
+ */
+declare function generateMasterSeed(): MasterKey;
+/**
+ * Derive spend key from master seed
+ */
+declare function deriveSpendKey(masterSeed: Uint8Array): SpendKey;
+/**
+ * Derive view key from spend key
+ */
+declare function deriveViewKey(sk_spend: Uint8Array): ViewKey;
+/**
+ * Generate complete key hierarchy from master seed
+ */
+declare function generateCloakKeys(masterSeed?: Uint8Array): CloakKeyPair;
+/**
+ * Encrypt note data for a recipient using their public view key
+ *
+ * Uses X25519 ECDH + XSalsa20-Poly1305 authenticated encryption
+ */
+declare function encryptNoteForRecipient(noteData: NoteData, recipientPvk: Uint8Array): EncryptedNote$1;
+/**
+ * Attempt to decrypt an encrypted note using view key
+ *
+ * Returns null if decryption fails (note doesn't belong to this wallet)
+ * Returns NoteData if successful
+ */
+declare function tryDecryptNote(encryptedNote: EncryptedNote$1, viewKey: ViewKey): NoteData | null;
+/**
+ * Scan a batch of encrypted outputs and return notes belonging to this wallet
+ */
+declare function scanNotesForWallet(encryptedOutputs: string[], // Base64 encoded encrypted note JSON
+viewKey: ViewKey): NoteData[];
+/**
+ * Export keys for backup (WARNING: contains secrets!)
+ */
+declare function exportKeys(keys: CloakKeyPair): string;
+/**
+ * Import keys from backup
+ */
+declare function importKeys(exported: string): CloakKeyPair;
+
+/**
+ * Storage Interface
+ *
+ * Defines a pluggable storage interface for notes and keys.
+ * Applications can implement their own storage (localStorage, IndexedDB, file system, etc.)
+ */
+
+/**
+ * Storage adapter interface
+ *
+ * Implement this interface to provide custom storage for notes and keys.
+ * The SDK will use this adapter for all persistence operations.
+ */
+interface StorageAdapter {
+    /**
+     * Save a note
+     */
+    saveNote(note: CloakNote): Promise<void> | void;
+    /**
+     * Load all notes
+     */
+    loadAllNotes(): Promise<CloakNote[]> | CloakNote[];
+    /**
+     * Update a note
+     */
+    updateNote(commitment: string, updates: Partial<CloakNote>): Promise<void> | void;
+    /**
+     * Delete a note
+     */
+    deleteNote(commitment: string): Promise<void> | void;
+    /**
+     * Clear all notes
+     */
+    clearAllNotes(): Promise<void> | void;
+    /**
+     * Save wallet keys
+     */
+    saveKeys(keys: CloakKeyPair): Promise<void> | void;
+    /**
+     * Load wallet keys
+     */
+    loadKeys(): Promise<CloakKeyPair | null> | CloakKeyPair | null;
+    /**
+     * Delete wallet keys
+     */
+    deleteKeys(): Promise<void> | void;
+}
+/**
+ * In-memory storage adapter (default, no persistence)
+ *
+ * Useful for testing or when storage is handled externally
+ */
+declare class MemoryStorageAdapter implements StorageAdapter {
+    private notes;
+    private keys;
+    saveNote(note: CloakNote): void;
+    loadAllNotes(): CloakNote[];
+    updateNote(commitment: string, updates: Partial<CloakNote>): void;
+    deleteNote(commitment: string): void;
+    clearAllNotes(): void;
+    saveKeys(keys: CloakKeyPair): void;
+    loadKeys(): CloakKeyPair | null;
+    deleteKeys(): void;
+}
+/**
+ * Browser localStorage adapter (optional, for browser environments)
+ *
+ * Only use this if you're in a browser environment and want localStorage persistence.
+ * Import from a separate browser-specific module.
+ */
+declare class LocalStorageAdapter implements StorageAdapter {
+    private notesKey;
+    private keysKey;
+    constructor(notesKey?: string, keysKey?: string);
+    private getStorage;
+    saveNote(note: CloakNote): void;
+    loadAllNotes(): CloakNote[];
+    updateNote(commitment: string, updates: Partial<CloakNote>): void;
+    deleteNote(commitment: string): void;
+    clearAllNotes(): void;
+    saveKeys(keys: CloakKeyPair): void;
+    loadKeys(): CloakKeyPair | null;
+    deleteKeys(): void;
+}
+
+/** Default Cloak Program ID on Solana */
+declare const CLOAK_PROGRAM_ID: PublicKey;
+/**
+ * Main Cloak SDK
+ *
+ * Provides high-level API for interacting with the Cloak protocol,
+ * including deposits, withdrawals, and private transfers.
+ *
+ * Supports two modes:
+ * 1. Node.js mode with keypairBytes - for scripts and backend services
+ * 2. Wallet adapter mode - for browser applications with wallet integration
+ */
+declare class CloakSDK {
+    private config;
+    private keypair?;
+    private wallet?;
+    private cloakKeys?;
+    private relay;
+    private storage;
+    /**
+    * Create a new Cloak SDK client
+     *
+     * @param config - Client configuration
+     *
+     * @example Node.js mode (with keypair)
+     * ```typescript
+     * const sdk = new CloakSDK({
+     *   keypairBytes: keypair.secretKey,
+     *   network: "devnet"
+     * });
+     * ```
+     *
+     * @example Browser mode (with wallet adapter)
+     * ```typescript
+     * const sdk = new CloakSDK({
+     *   wallet: walletAdapter,
+     *   network: "devnet"
+     * });
+     * ```
+     */
+    constructor(config: {
+        /** Keypair bytes for signing (Node.js mode) */
+        keypairBytes?: Uint8Array;
+        /** Wallet adapter for signing (Browser mode) */
+        wallet?: WalletAdapter;
+        network?: Network;
+        cloakKeys?: CloakKeyPair;
+        storage?: StorageAdapter;
+        programId?: PublicKey;
+        relayUrl?: string;
+        /** Enable debug logging with structured output */
+        debug?: boolean;
+    });
+    /**
+     * Get the public key for deposits (from keypair or wallet)
+     */
+    getPublicKey(): PublicKey;
+    /**
+     * Check if the SDK is using a wallet adapter
+     */
+    isWalletMode(): boolean;
+    /**
+     * Deposit SOL into the Cloak protocol
+     *
+     * Creates a new note (or uses a provided one), submits a deposit transaction,
+     * and registers with the indexer.
+     *
+     * @param connection - Solana connection
+     * @param payer - Payer wallet with sendTransaction method
+     * @param amountOrNote - Amount in lamports OR an existing note to deposit
+     * @param options - Optional configuration
+     * @returns Deposit result with note and transaction info
+     *
+     * @example
+     * ```typescript
+     * // Generate and deposit in one step
+     * const result = await client.deposit(
+     *   connection,
+     *   wallet,
+     *   1_000_000_000,
+     *   {
+     *     onProgress: (status) => console.log(status)
+     *   }
+     * );
+     *
+     * // Or deposit a pre-generated note
+     * const note = client.generateNote(1_000_000_000);
+     * const result = await client.deposit(connection, wallet, note);
+     * ```
+     */
+    deposit(connection: Connection, amountOrNote: number | CloakNote, options?: DepositOptions): Promise<DepositResult>;
+    /**
+     * Private transfer with up to 5 recipients
+     *
+     * Handles the complete private transfer flow:
+     * 1. If note is not deposited, deposits it first and waits for confirmation
+     * 2. Generates a zero-knowledge proof
+     * 3. Submits the withdrawal via relay service to recipients
+     *
+     * This is the main method for performing private transfers - it handles everything!
+     *
+     * @param connection - Solana connection (required for deposit if not already deposited)
+     * @param payer - Payer wallet (required for deposit if not already deposited)
+     * @param note - Note to spend (can be deposited or not)
+     * @param recipients - Array of 1-5 recipients with amounts
+     * @param options - Optional configuration
+     * @returns Transfer result with signature and outputs
+     *
+     * @example
+     * ```typescript
+     * // Create a note (not deposited yet)
+     * const note = client.generateNote(1_000_000_000);
+     *
+     * // privateTransfer handles the full flow: deposit + withdraw
+     * const result = await client.privateTransfer(
+     *   connection,
+     *   wallet,
+     *   note,
+     *   [
+     *     { recipient: new PublicKey("..."), amount: 500_000_000 },
+     *     { recipient: new PublicKey("..."), amount: 492_500_000 }
+     *   ],
+     *   {
+     *     relayFeeBps: 50, // 0.5%
+     *     onProgress: (status) => console.log(status),
+     *     onProofProgress: (pct) => console.log(`Proof: ${pct}%`)
+     *   }
+     * );
+     * console.log(`Success! TX: ${result.signature}`);
+     * ```
+     */
+    privateTransfer(connection: Connection, note: CloakNote, recipients: MaxLengthArray<Transfer, 5>, options?: TransferOptions): Promise<TransferResult>;
+    /**
+     * Withdraw to a single recipient
+     *
+     * Convenience method for withdrawing to one address.
+     * Handles the complete flow: deposits if needed, then withdraws.
+     *
+     * @param connection - Solana connection
+     * @param payer - Payer wallet
+     * @param note - Note to spend
+     * @param recipient - Recipient address
+     * @param options - Optional configuration
+     * @returns Transfer result
+     *
+     * @example
+     * ```typescript
+     * const note = client.generateNote(1_000_000_000);
+     * const result = await client.withdraw(
+     *   connection,
+     *   wallet,
+     *   note,
+     *   new PublicKey("..."),
+     *   { withdrawAll: true }
+     * );
+     * ```
+     */
+    withdraw(connection: Connection, note: CloakNote, recipient: PublicKey, options?: WithdrawOptions): Promise<TransferResult>;
+    /**
+     * Send SOL privately to multiple recipients
+     *
+     * Convenience method that wraps privateTransfer with a simpler API.
+     * Handles the complete flow: deposits if needed, then sends to recipients.
+     *
+     * @param connection - Solana connection
+     * @param note - Note to spend
+     * @param recipients - Array of 1-5 recipients with amounts
+     * @param options - Optional configuration
+     * @returns Transfer result
+     *
+     * @example
+     * ```typescript
+     * const note = client.generateNote(1_000_000_000);
+     * const result = await client.send(
+     *   connection,
+     *   note,
+     *   [
+     *     { recipient: new PublicKey("..."), amount: 500_000_000 },
+     *     { recipient: new PublicKey("..."), amount: 492_500_000 }
+     *   ]
+     * );
+     * ```
+     */
+    send(connection: Connection, note: CloakNote, recipients: MaxLengthArray<Transfer, 5>, options?: TransferOptions): Promise<TransferResult>;
+    /**
+     * Swap SOL for tokens privately
+     *
+     * Withdraws SOL from a note and swaps it for tokens via the relay service.
+     * Handles the complete flow: deposits if needed, generates proof, and submits swap.
+     *
+     * @param connection - Solana connection
+     * @param note - Note to spend
+     * @param recipient - Recipient address (will receive tokens)
+     * @param options - Swap configuration
+     * @returns Swap result with transaction signature
+     *
+     * @example
+     * ```typescript
+     * const note = client.generateNote(1_000_000_000);
+     * const result = await client.swap(
+     *   connection,
+     *   note,
+     *   new PublicKey("..."), // recipient
+     *   {
+     *     outputMint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // USDC
+     *     slippageBps: 100, // 1%
+     *     getQuote: async (amount, mint, slippage) => {
+     *       // Fetch quote from your swap API
+     *       const quote = await fetchSwapQuote(amount, mint, slippage);
+     *       return {
+     *         outAmount: quote.outAmount,
+     *         minOutputAmount: quote.minOutputAmount
+     *       };
+     *     }
+     *   }
+     * );
+     * ```
+     */
+    swap(connection: Connection, note: CloakNote, recipient: PublicKey, options: SwapOptions): Promise<SwapResult>;
+    /**
+     * Generate a new note without depositing
+     *
+     * @param amountLamports - Amount for the note
+     * @param useWalletKeys - Whether to use wallet keys (v2.0 recommended)
+     * @returns New note (not yet deposited)
+     */
+    generateNote(amountLamports: number, useWalletKeys?: boolean): Promise<CloakNote>;
+    /**
+     * Parse a note from JSON string
+     *
+     * @param jsonString - JSON representation
+     * @returns Parsed note
+     */
+    parseNote(jsonString: string): CloakNote;
+    /**
+     * Export a note to JSON string
+     *
+     * @param note - Note to export
+     * @param pretty - Format with indentation
+     * @returns JSON string
+     */
+    exportNote(note: CloakNote, pretty?: boolean): string;
+    /**
+     * Check if a note is ready for withdrawal
+     *
+     * @param note - Note to check
+     * @returns True if withdrawable
+     */
+    isWithdrawable(note: CloakNote): boolean;
+    /**
+     * Get Merkle proof for a leaf index directly from on-chain state
+     *
+     * @param connection - Solana connection
+     * @param leafIndex - Leaf index in tree
+     * @returns Merkle proof computed from on-chain data
+     */
+    getMerkleProof(connection: Connection, leafIndex: number): Promise<MerkleProof>;
+    /**
+     * Get current Merkle root directly from on-chain state
+     *
+     * @param connection - Solana connection
+     * @returns Current root hash from on-chain tree
+     */
+    getCurrentRoot(connection: Connection): Promise<string>;
+    /**
+     * Get transaction status from relay service
+     *
+     * @param requestId - Request ID from previous submission
+     * @returns Current status
+     */
+    getTransactionStatus(requestId: string): Promise<TxStatus>;
+    /**
+     * Fetch and decrypt this user's transaction metadata history.
+     * DEPRECATED: This functionality is no longer supported
+     */
+    getTransactionMetadata(_options?: {
+        _after?: number;
+        _before?: number;
+    }): Promise<TransactionMetadata[]>;
+    /**
+     * Load all notes from storage
+     *
+     * @returns Array of saved notes
+     */
+    loadNotes(): Promise<CloakNote[]>;
+    /**
+     * Save a note to storage
+     *
+     * @param note - Note to save
+     */
+    saveNote(note: CloakNote): Promise<void>;
+    /**
+     * Find a note by its commitment
+     *
+     * @param commitment - Commitment hash
+     * @returns Note if found
+     */
+    findNote(commitment: string): Promise<CloakNote | undefined>;
+    /**
+     * Import wallet keys from JSON
+     *
+     * @param keysJson - JSON string containing keys
+     */
+    importWalletKeys(keysJson: string): Promise<void>;
+    /**
+     * Export wallet keys to JSON
+     *
+     * WARNING: This exports secret keys! Store securely.
+     *
+     * @returns JSON string with keys
+     */
+    exportWalletKeys(): string;
+    /**
+     * Get the configuration
+     */
+    getConfig(): CloakConfig;
+    /**
+     * Wrap errors with better categorization and user-friendly messages
+     *
+     * @private
+     */
+    private wrapError;
+}
+
+/**
+ * Serialize a note to JSON string
+ *
+ * @param note - Note to serialize
+ * @param pretty - Whether to format with indentation (default: false)
+ * @returns JSON string
+ *
+ * @example
+ * ```typescript
+ * const json = serializeNote(note, true);
+ * console.log(json);
+ * // Or save to file, copy to clipboard, etc.
+ * ```
+ */
+declare function serializeNote(note: CloakNote, pretty?: boolean): string;
+/**
+ * Export note as downloadable JSON (browser only)
+ *
+ * @param note - Note to export
+ * @param filename - Optional custom filename
+ */
+declare function downloadNote(note: CloakNote, filename?: string): void;
+/**
+ * Copy note to clipboard as JSON (browser only)
+ *
+ * @param note - Note to copy
+ * @returns Promise that resolves when copied
+ */
+declare function copyNoteToClipboard(note: CloakNote): Promise<void>;
+
+/**
+ * Fee calculation utilities for Cloak Protocol
+ *
+ * The protocol charges a fixed fee plus a variable percentage fee
+ * to prevent sybil attacks and cover operational costs.
+ *
+ * IMPORTANT: These constants are the single source of truth for fee calculations.
+ * When updating fees, only change these values - all other code should import from here.
+ */
+/** Lamports per SOL */
+declare const LAMPORTS_PER_SOL = 1000000000;
+/** Fixed fee: 0.005 SOL (5M lamports) */
+declare const FIXED_FEE_LAMPORTS = 5000000;
+/** Variable fee numerator (3 = 0.3%) */
+declare const VARIABLE_FEE_NUMERATOR = 3;
+/** Variable fee denominator (1000 = divide by 1000) */
+declare const VARIABLE_FEE_DENOMINATOR = 1000;
+/** Variable fee rate as decimal: 0.3% = 0.003 */
+declare const VARIABLE_FEE_RATE: number;
+/** Minimum deposit amount to prevent dust/UX footguns (0.01 SOL). */
+declare const MIN_DEPOSIT_LAMPORTS = 10000000;
+/**
+ * Calculate the total protocol fee for a given amount
+ *
+ * Formula: FIXED_FEE + floor((amount * VARIABLE_FEE_NUMERATOR) / VARIABLE_FEE_DENOMINATOR)
+ *
+ * @param amountLamports - Amount in lamports
+ * @returns Total fee in lamports
+ *
+ * @example
+ * ```typescript
+ * const fee = calculateFee(1_000_000_000); // 1 SOL
+ * // Returns: 5_000_000 (fixed) + 3_000_000 (0.3%) = 8_000_000 lamports
+ * ```
+ */
+declare function calculateFee(amountLamports: number): number;
+/**
+ * Bigint version of calculateFee (for UTXO flows that use bigint lamports).
+ */
+declare function calculateFeeBigint(amountLamports: bigint): bigint;
+/**
+ * Returns true if a withdrawal amount can pay fees and still leave >0 lamports.
+ * (On-chain uses the same integer math and enforces this as well.)
+ */
+declare function isWithdrawAmountSufficient(amountLamports: bigint): boolean;
+/**
+ * Calculate the distributable amount after protocol fees
+ *
+ * This is the amount available to send to recipients.
+ *
+ * @param amountLamports - Total note amount in lamports
+ * @returns Amount available for recipients in lamports
+ *
+ * @example
+ * ```typescript
+ * const distributable = getDistributableAmount(1_000_000_000);
+ * // Returns: 1_000_000_000 - 7_500_000 = 992_500_000 lamports
+ * ```
+ */
+declare function getDistributableAmount(amountLamports: number): number;
+/**
+ * Format lamports as SOL string
+ *
+ * @param lamports - Amount in lamports
+ * @param decimals - Number of decimal places (default: 9)
+ * @returns Formatted string (e.g., "1.000000000")
+ *
+ * @example
+ * ```typescript
+ * formatAmount(1_000_000_000); // "1.000000000"
+ * formatAmount(1_500_000_000); // "1.500000000"
+ * formatAmount(123_456_789, 4); // "0.1235"
+ * ```
+ */
+declare function formatAmount(lamports: number, decimals?: number): string;
+/**
+ * Parse SOL string to lamports
+ *
+ * @param sol - SOL amount as string (e.g., "1.5")
+ * @returns Amount in lamports
+ * @throws Error if invalid format
+ *
+ * @example
+ * ```typescript
+ * parseAmount("1.5"); // 1_500_000_000
+ * parseAmount("0.001"); // 1_000_000
+ * ```
+ */
+declare function parseAmount(sol: string): number;
+/**
+ * Validate that outputs sum equals expected amount
+ *
+ * @param outputs - Array of output amounts
+ * @param expectedTotal - Expected total amount
+ * @returns True if amounts match
+ */
+declare function validateOutputsSum(outputs: Array<{
+    amount: number;
+}>, expectedTotal: number): boolean;
+/**
+ * Calculate relay fee from basis points
+ *
+ * @param amountLamports - Amount in lamports
+ * @param feeBps - Fee in basis points (100 bps = 1%)
+ * @returns Relay fee in lamports
+ *
+ * @example
+ * ```typescript
+ * calculateRelayFee(1_000_000_000, 50); // 0.5% = 5_000_000 lamports
+ * ```
+ */
+declare function calculateRelayFee(amountLamports: number, feeBps: number): number;
+
+/**
+ * Note Manager
+ *
+ * Standalone note management - no browser dependencies.
+ * Storage is handled externally via StorageAdapter.
+ *
+ * Core functionality:
+ * - Generate notes (v1.0 and v2.0)
+ * - Parse and validate notes
+ * - Note utilities (formatting, fees, etc.)
+ * - Key management (without storage)
+ */
+
+/**
+ * Generate a new note without wallet keys (legacy v1.0)
+ * Uses Poseidon hashing to match circuit implementation
+ * @deprecated Use generateNoteFromWallet instead for enhanced security
+ */
+declare function generateNote(amountLamports: number, network?: Network): Promise<CloakNote>;
+/**
+ * Generate a note using wallet's spend key (v2.0 recommended)
+ * Uses Poseidon hashing to match circuit implementation
+ */
+declare function generateNoteFromWallet(amountLamports: number, keys: CloakKeyPair, network?: Network): Promise<CloakNote>;
+/**
+ * Parse and validate a note from JSON string
+ */
+declare function parseNote(jsonString: string): CloakNote;
+/**
+ * Export note to JSON string
+ */
+declare function exportNote(note: CloakNote, pretty?: boolean): string;
+/**
+ * Check if a note is withdrawable (has been deposited)
+ * Note: merkleProof is optional - it may be fetched lazily at withdrawal time
+ */
+declare function isWithdrawable(note: CloakNote): boolean;
+/**
+ * Update note with deposit information
+ * Returns a new note object with deposit info added
+ */
+declare function updateNoteWithDeposit(note: CloakNote, depositInfo: {
+    signature: string;
+    slot: number;
+    leafIndex: number;
+    root: string;
+    merkleProof?: {
+        pathElements: string[];
+        pathIndices: number[];
+    };
+}): CloakNote;
+/**
+ * Find note by commitment from an array
+ */
+declare function findNoteByCommitment(notes: CloakNote[], commitment: string): CloakNote | undefined;
+/**
+ * Filter notes by network
+ */
+declare function filterNotesByNetwork(notes: CloakNote[], network: Network): CloakNote[];
+/**
+ * Filter notes that can be withdrawn
+ */
+declare function filterWithdrawableNotes(notes: CloakNote[]): CloakNote[];
+/**
+ * Export keys to JSON string
+ * WARNING: This exports secret keys! Store securely.
+ */
+declare function exportWalletKeys(keys: CloakKeyPair): string;
+/**
+ * Import keys from JSON string
+ */
+declare function importWalletKeys(keysJson: string): CloakKeyPair;
+/**
+ * Get public view key from keys
+ */
+declare function getPublicViewKey(keys: CloakKeyPair): string;
+/**
+ * Get view key from keys
+ */
+declare function getViewKey(keys: CloakKeyPair): ViewKey;
+/**
+ * Get recipient amount after fees
+ */
+declare function getRecipientAmount(amountLamports: number): number;
+
+interface ViewingKeyPair {
+    privateKey: Uint8Array;
+    publicKey: Uint8Array;
+}
+/** Zcash-style expanded spend key: ask (auth), nsk (nullifier/nk), ovk (outgoing view) */
+interface ExpandedSpendKey {
+    ask: Uint8Array;
+    nsk: Uint8Array;
+    ovk: Uint8Array;
+}
+/**
+ * Expand spend key into (ask, nsk, ovk) — Zcash-style.
+ * - ask: spend authorization (future)
+ * - nsk: base for incoming viewing (nk) — chain note decryption
+ * - ovk: outgoing viewing (future)
+ */
+declare function expandSpendKey(skSpend: Uint8Array): ExpandedSpendKey;
+/**
+ * Derive chain note viewing key from nk (Zcash-style IVK component).
+ * Used for trial-decrypting incoming chain notes.
+ *
+ * @param nk 32-byte nk (from expandSpendKey(...).nsk — the incoming view base)
+ */
+declare function deriveViewingKeyFromNk(nk: Uint8Array): ViewingKeyPair;
+/**
+ * Derive diversifier for per-output chain note encryption (Phase 3).
+ * d = BLAKE3("cloak_div_v1" || nk || commitmentHex || outputIndex)[0:11]
+ */
+declare function deriveDiversifier(nk: Uint8Array, commitmentHex: string, outputIndex: number): Uint8Array;
+/**
+ * Derive per-output viewing key pair from nk + diversifier (Phase 3).
+ * sk_d = BLAKE3("cloak_sk_d_v1" || nk || d) → clamp → X25519 keypair
+ */
+declare function deriveDiversifiedViewingKey(nk: Uint8Array, diversifier: Uint8Array): ViewingKeyPair;
+/**
+ * Derive chain note viewing key from spend key (Zcash-style).
+ * Expands to (ask, nsk, ovk) and uses nsk (nk) for chain note decryption.
+ */
+declare function deriveViewingKeyFromSpendKey(skSpend: Uint8Array): ViewingKeyPair;
+/**
+ * Derive chain note viewing key from UTXO private key (Zcash-style).
+ * New UTXO (new keypair) => new viewing key.
+ *
+ * @param utxoPrivateKey UTXO keypair.privateKey (Poseidon field bigint)
+ */
+declare function deriveViewingKeyFromUtxoPrivateKey(utxoPrivateKey: bigint): ViewingKeyPair;
+/**
+ * Get nk (incoming viewing base) from UTXO private key for Phase 3 diversified chain notes.
+ */
+declare function getNkFromUtxoPrivateKey(utxoPrivateKey: bigint): Uint8Array;
+/**
+ * Generate a random viewing key pair (for tests/examples that need ephemeral keys).
+ * Uses deriveViewingKeyFromSpendKey with random bytes.
+ */
+declare function generateViewingKeyPair(): ViewingKeyPair;
+/**
+ * Derive the user-specific scalar from the relay-provided compliance master public key.
+ */
+declare function deriveUserComplianceScalar(masterCompliancePublicKey: Uint8Array, userPublicKey: PublicKey): Promise<Uint8Array>;
+/**
+ * Derive a per-user compliance public key from the relay's master compliance public key.
+ *
+ * Formula:
+ * - factor = Poseidon(master_compliance_public_key, user_wallet_pubkey)
+ * - user_compliance_public = X25519(factor, master_compliance_public_key)
+ */
+declare function deriveUserCompliancePublicKey(masterCompliancePublicKey: Uint8Array, userPublicKey: PublicKey): Promise<Uint8Array>;
+/**
+ * Legacy sign-in message retained for wallet-seed derivation compatibility in web/examples.
+ * Viewing-key registration auth now uses one-time relay challenge messages.
+ */
+declare const SIGN_IN_MESSAGE = "Cloak: Sign in\n\nSign this message to securely access your Cloak account.\nThis does NOT authorize any transaction or spend any funds.";
+/**
+ * Register nk (Phase 3) with relay for compliance scanning.
+ * Relay stores nk and derives sk_d per note when exporting.
+ * Registration is authenticated via one-time nonce challenge.
+ */
+declare function registerViewingKey(relayUrl: string, userPubkey: PublicKey, nk: Uint8Array, signMessage: (message: Uint8Array) => Promise<Uint8Array>): Promise<void>;
+
+interface EncryptMetadataContext {
+    userPubkey?: PublicKey | string;
+}
+/**
+ * Encrypt a metadata object under:
+ * 1. User view key public key
+ * 2. User-specific compliance public key
+ */
+declare function encryptTransactionMetadata(metadata: TransactionMetadata, userViewKeyPublic: Uint8Array, complianceKeyPublic: Uint8Array, context?: EncryptMetadataContext): Promise<EncryptedMetadataBundle>;
+/**
+ * Encrypt metadata using viewing key for both user and compliance.
+ * This is used in the new viewing key-based compliance flow.
+ *
+ * @param metadata - Transaction metadata to encrypt
+ * @param viewingKeyPrivate - The user's viewing key private key (32 bytes)
+ * @param userPubkey - The user's wallet public key
+ * @returns Encrypted metadata bundle
+ */
+declare function encryptTransactionMetadataBundle(metadata: TransactionMetadata, viewingKeyPrivate: Uint8Array, userPubkey: PublicKey): Promise<{
+    encrypted_user: string;
+    encrypted_compliance: string;
+    user_pubkey: string;
+    commitment: string;
+    timestamp: number;
+    tx_type?: string;
+}>;
+/**
+ * Decrypt metadata with the direct recipient secret key.
+ *
+ * - For user blobs: pass `view.vk_secret`
+ * - For compliance blobs: pass the derived per-user compliance private key
+ */
+declare function decryptTransactionMetadata(encrypted: string, viewKeySecret: Uint8Array): Promise<TransactionMetadata>;
+/**
+ * Decrypt compliance metadata using the master compliance private key.
+ *
+ * This mirrors relay-side decryption:
+ * shared = X25519(master_private, X25519(user_factor, ephemeral_pk))
+ */
+declare function decryptComplianceMetadataWithMasterKey(encrypted: string, masterCompliancePrivateKey: Uint8Array, masterCompliancePublicKey: Uint8Array, userPublicKey: PublicKey): Promise<TransactionMetadata>;
+
+/**
+ * Compute Poseidon hash of field elements
+ * Uses circomlibjs Poseidon which matches the circuit implementation
+ */
+declare function poseidonHash(inputs: bigint[]): Promise<bigint>;
+/**
+ * Split a 256-bit value into two 128-bit limbs
+ * Returns [lo, hi] where lo is the lower 128 bits
+ */
+declare function splitTo2Limbs(value: bigint): [bigint, bigint];
+/**
+ * Convert a PublicKey (32 bytes) to two 128-bit limbs
+ * Uses duck typing to handle cross-module PublicKey instances
+ */
+declare function pubkeyToLimbs(pubkey: Uint8Array | PublicKey | {
+    toBytes: () => Uint8Array;
+}): [bigint, bigint];
+/**
+ * Compute Merkle root from leaf and path
+ *
+ * This matches the test implementation
+ *
+ * @param leaf - Leaf value as bigint
+ * @param pathElements - Sibling hashes along the path
+ * @param pathIndices - Path directions (0 = left, 1 = right)
+ * @returns Merkle root as bigint
+ */
+declare function computeMerkleRoot(leaf: bigint, pathElements: bigint[], pathIndices: number[]): Promise<bigint>;
+/**
+ * Convert hex string to bigint
+ */
+declare function hexToBigint$1(hex: string): bigint;
+/**
+ * Compute commitment = Poseidon(amount, r0, r1, pk_spend)
+ * where pk_spend = Poseidon(sk0, sk1)
+ * (matching withdraw_regular.circom)
+ *
+ * This is the test-style function that takes bigints directly
+ *
+ * @param amount - Amount as bigint
+ * @param r - Randomness as bigint
+ * @param sk_spend - Spending secret key as bigint
+ * @returns Commitment hash as bigint
+ */
+declare function computeCommitment$1(amount: bigint, r: bigint, sk_spend: bigint): Promise<bigint>;
+/**
+ * Generate a Poseidon commitment for a note
+ *
+ * Formula: Poseidon(amount, r0, r1, pk_spend)
+ * where pk_spend = Poseidon(sk0, sk1)
+ *
+ * This matches the withdraw_regular.circom circuit
+ *
+ * @param amountLamports - Amount in lamports
+ * @param r - Randomness bytes (32 bytes)
+ * @param skSpend - Spending secret key bytes (32 bytes)
+ * @returns Commitment hash as bigint
+ */
+declare function generateCommitmentAsync(amountLamports: number, r: Uint8Array, skSpend: Uint8Array): Promise<bigint>;
+/**
+ * Generate a Poseidon commitment for a note (sync wrapper)
+ * Returns bytes instead of bigint for backward compatibility
+ *
+ * @deprecated Use generateCommitmentAsync instead
+ */
+declare function generateCommitment(_amountLamports: number, _r: Uint8Array, _skSpend: Uint8Array): Uint8Array;
+/**
+ * Compute nullifier = Poseidon(sk0, sk1, leaf_index)
+ * (matching withdraw_regular.circom)
+ *
+ * This is the test-style function that takes bigint directly
+ *
+ * @param sk_spend - Spending secret key as bigint
+ * @param leafIndex - Index in the Merkle tree as bigint
+ * @returns Nullifier as bigint
+ */
+declare function computeNullifier$1(sk_spend: bigint, leafIndex: bigint): Promise<bigint>;
+/**
+ * Compute nullifier from spending key and leaf index
+ *
+ * Formula: Poseidon(sk0, sk1, leaf_index)
+ *
+ * This matches the circuit's nullifier computation
+ *
+ * @param skSpend - Spending secret key bytes (32 bytes) or hex string
+ * @param leafIndex - Index in the Merkle tree
+ * @returns Nullifier as bigint
+ */
+declare function computeNullifierAsync(skSpend: Uint8Array | string, leafIndex: number): Promise<bigint>;
+/**
+ * Compute nullifier (sync wrapper for backward compatibility)
+ * @deprecated Use computeNullifierAsync instead
+ */
+declare function computeNullifierSync(_skSpend: Uint8Array, _leafIndex: number): Uint8Array;
+/**
+ * Compute outputs hash from recipients and amounts
+ *
+ * Formula: Chain of Poseidon(prev_hash, addr_lo, addr_hi, amount) for each active output
+ *
+ * This matches the withdraw_regular.circom circuit's outputs hash computation
+ *
+ * @param outputs - Array of {recipient: PublicKey, amount: number}
+ * @returns Outputs hash as bigint
+ */
+declare function computeOutputsHashAsync(outputs: Array<{
+    recipient: PublicKey;
+    amount: number;
+}>): Promise<bigint>;
+/**
+ * Compute outputs hash for withdraw_regular circuit
+ * outputs_hash = chain of Poseidon(prev_hash, addr_lo, addr_hi, amount) for each active output
+ *
+ * This is the test-style function that takes raw limbs
+ *
+ * @param outAddr - Array of [lo, hi] limb pairs for each address (5x2 array)
+ * @param outAmount - Array of amounts as bigints (5 elements)
+ * @param outFlags - Array of flags (1 = active, 0 = inactive) (5 elements)
+ * @returns Outputs hash as bigint
+ */
+declare function computeOutputsHash(outAddr: bigint[][], outAmount: bigint[], outFlags: number[]): Promise<bigint>;
+/**
+ * Compute outputs hash (sync wrapper for backward compatibility)
+ * @deprecated Use computeOutputsHashAsync instead
+ */
+declare function computeOutputsHashSync(_outputs: Array<{
+    recipient: PublicKey;
+    amount: number;
+}>): Uint8Array;
+/**
+ * Compute outputs hash for withdraw_swap circuit
+ * outputs_hash = Poseidon(input_mint limbs, output_mint limbs, recipient_ata limbs, min_output_amount, public_amount)
+ *
+ * This is the test-style function that takes raw limbs
+ *
+ * @param inputMintLimbs - Input mint address as [lo, hi] limbs
+ * @param outputMintLimbs - Output mint address as [lo, hi] limbs
+ * @param recipientAtaLimbs - Recipient ATA as [lo, hi] limbs
+ * @param minOutputAmount - Minimum output amount as bigint
+ * @param publicAmount - Public amount as bigint
+ * @returns Outputs hash as bigint
+ */
+declare function computeSwapOutputsHash(inputMintLimbs: [bigint, bigint], outputMintLimbs: [bigint, bigint], recipientAtaLimbs: [bigint, bigint], minOutputAmount: bigint, publicAmount: bigint): Promise<bigint>;
+/**
+ * Compute outputs hash for swap transactions
+ *
+ * Formula: Poseidon(input_mint_lo, input_mint_hi, output_mint_lo, output_mint_hi,
+ *                   recipient_ata_lo, recipient_ata_hi, min_output_amount, public_amount)
+ *
+ * This matches the withdraw_swap.circom circuit
+ *
+ * @param inputMint - Input token mint address (SOL = SystemProgram)
+ * @param outputMint - Output token mint address
+ * @param recipientAta - Recipient's associated token account
+ * @param minOutputAmount - Minimum output amount in token's smallest unit
+ * @param amount - Note amount in lamports (public_amount)
+ * @returns Outputs hash as bigint
+ */
+declare function computeSwapOutputsHashAsync(inputMint: PublicKey, outputMint: PublicKey, recipientAta: PublicKey, minOutputAmount: number, amount: number): Promise<bigint>;
+/**
+ * Compute swap outputs hash (sync wrapper for backward compatibility)
+ * @deprecated Use computeSwapOutputsHashAsync instead
+ */
+declare function computeSwapOutputsHashSync(_outputMint: PublicKey, _recipientAta: PublicKey, _minOutputAmount: number, _amount: number): Uint8Array;
+/**
+ * Convert bigint to 32-byte big-endian Uint8Array
+ */
+declare function bigintToBytes32$1(n: bigint): Uint8Array;
+/**
+ * Convert hex string to Uint8Array
+ *
+ * @param hex - Hex string (with or without 0x prefix)
+ * @returns Decoded bytes
+ */
+declare function hexToBytes(hex: string): Uint8Array;
+/**
+ * Convert Uint8Array to hex string
+ *
+ * @param bytes - Bytes to encode
+ * @param prefix - Whether to include 0x prefix (default: false)
+ * @returns Hex-encoded string
+ */
+declare function bytesToHex(bytes: Uint8Array, prefix?: boolean): string;
+/**
+ * Generate random bytes using Web Crypto API
+ *
+ * @param length - Number of bytes to generate
+ * @returns Random bytes
+ */
+declare function randomBytes(length: number): Uint8Array;
+/**
+ * Validate a hex string format
+ *
+ * @param hex - Hex string to validate
+ * @param expectedLength - Expected length in bytes (optional)
+ * @returns True if valid hex string
+ */
+declare function isValidHex(hex: string, expectedLength?: number): boolean;
+/**
+ * Groth16 proof structure from snarkjs
+ */
+interface Groth16Proof {
+    pi_a: string[];
+    pi_b: string[][];
+    pi_c: string[];
+    protocol: string;
+    curve: string;
+}
+/**
+ * Convert snarkjs Groth16 proof to 256-byte format for Solana (pinocchio-groth16 format)
+ *
+ * Based on pinocchio-groth16/src/proof_parser.rs convert_proof function:
+ * - Proof_a: Must be NEGATED (as G1 point) and converted from LE to BE
+ * - Proof_b: Converted from LE to BE (reversing each 64-byte chunk)
+ * - Proof_c: Converted from LE to BE (reversing each 32-byte chunk)
+ *
+ * Format: pi_a (64) + pi_b (128) + pi_c (64) = 256 bytes
+ */
+declare function proofToBytes(proof: Groth16Proof): Uint8Array;
+/**
+ * Build public inputs bytes for on-chain verification
+ * Format: root (32) + nullifier (32) + outputs_hash (32) + public_amount (8) = 104 bytes
+ */
+declare function buildPublicInputsBytes(root: bigint, nullifier: bigint, outputsHash: bigint, publicAmount: bigint): Uint8Array;
+
+/**
+ * Validate a Solana public key
+ *
+ * @param address - Address string to validate
+ * @returns True if valid Solana address
+ */
+declare function isValidSolanaAddress(address: string): boolean;
+/**
+ * Validate a Cloak note structure
+ *
+ * @param note - Note object to validate
+ * @throws Error if invalid
+ */
+declare function validateNote(note: any): asserts note is CloakNote;
+/**
+ * Validate that a note is ready for withdrawal
+ *
+ * @param note - Note to validate
+ * @throws Error if note cannot be used for withdrawal
+ */
+declare function validateWithdrawableNote(note: CloakNote): void;
+/**
+ * Validate transfer recipients
+ *
+ * @param recipients - Array of transfers to validate
+ * @param totalAmount - Total amount available
+ * @throws Error if invalid
+ */
+declare function validateTransfers(recipients: Array<{
+    recipient: PublicKey;
+    amount: number;
+}>, totalAmount: number): void;
+
+/**
+ * Network Utilities
+ *
+ * Helper functions for network detection and configuration
+ */
+
+/**
+ * Detect network from RPC URL
+ *
+ * Attempts to detect the Solana network from common RPC URL patterns.
+ * Falls back to devnet if unable to detect.
+ */
+declare function detectNetworkFromRpcUrl(rpcUrl?: string): Network;
+/**
+ * Get the standard RPC URL for a network
+ */
+declare function getRpcUrlForNetwork(network: Network): string;
+/**
+ * Validate RPC URL format
+ */
+declare function isValidRpcUrl(url: string): boolean;
+/**
+ * Get explorer URL for a transaction
+ */
+declare function getExplorerUrl(signature: string, network?: Network): string;
+/**
+ * Get explorer URL for an address
+ */
+declare function getAddressExplorerUrl(address: string, network?: Network): string;
+
+/**
+ * Error Utilities
+ *
+ * Helper functions for parsing and presenting user-friendly error messages.
+ * This is the single source of truth for error codes and messages.
+ */
+
+/**
+ * Error thrown when the Merkle root used in a proof is no longer
+ * in the on-chain root history (stale root).
+ *
+ * This happens when many deposits occur between proof generation and
+ * transaction submission, pushing the proof's root out of history.
+ *
+ * The fix is to regenerate the proof with a fresh Merkle root.
+ */
+declare class RootNotFoundError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Check if an error message indicates a RootNotFound (0x1001) error
+ */
+declare function isRootNotFoundError(error: unknown): boolean;
+/**
+ * Parse a relay error response (e.g. 400 RootNotFound) and extract current_root when present.
+ * The relay returns { error: true, message: "...", current_root?: string } for RootNotFound.
+ */
+declare function parseRelayErrorResponse(responseText: string): {
+    isRootNotFound: boolean;
+    currentRoot?: string;
+};
+/**
+ * Shield Pool Program Error Codes
+ *
+ * Maps on-chain program error codes to user-friendly error messages.
+ * These codes match the program's error enum.
+ */
+declare const ShieldPoolErrors: Record<number, string>;
+/**
+ * Error categories for UI display
+ */
+type ErrorCategory = "wallet" | "network" | "validation" | "service" | "transaction" | "unknown";
+/**
+ * Structured error result for UI
+ */
+interface UserFriendlyError {
+    /** User-facing title */
+    title: string;
+    /** User-facing description */
+    message: string;
+    /** Error category for styling */
+    category: ErrorCategory;
+    /** Optional suggestion for the user */
+    suggestion?: string;
+    /** Whether the error is recoverable (user can retry) */
+    recoverable: boolean;
+    /** Original error for debugging (not shown to user) */
+    originalError?: string;
+}
+/**
+ * Parse any error and return a user-friendly error object
+ */
+declare function parseError(error: unknown): UserFriendlyError;
+/**
+ * Parse transaction error and return user-friendly message
+ *
+ * Attempts to extract meaningful error information from various
+ * error formats (program errors, RPC errors, custom errors)
+ */
+declare function parseTransactionError(error: any): string;
+/**
+ * Create a CloakError with appropriate categorization
+ */
+declare function createCloakError(error: unknown, _context: string): CloakError;
+/**
+ * Format error for logging
+ */
+declare function formatErrorForLogging(error: unknown): string;
+
+/**
+ * Structured Logger for Cloak SDK
+ *
+ * Provides structured logging similar to Rust tracing format:
+ * 2026-01-23T00:51:46.489317Z  INFO cloak::module: 📥 Message key=value
+ *
+ * Enable via:
+ * - SDK config: new CloakSDK({ debug: true })
+ * - Environment: CLOAK_DEBUG=1 or DEBUG=cloak:*
+ */
+type LogLevel = "DEBUG" | "INFO" | "WARN" | "ERROR";
+/**
+ * Enable or disable debug logging globally
+ */
+declare function setDebugMode(enabled: boolean): void;
+/**
+ * Check if debug mode is enabled
+ */
+declare function isDebugEnabled(): boolean;
+/**
+ * Logger interface
+ */
+interface Logger {
+    debug: (message: string, kvPairs?: Record<string, unknown>) => void;
+    info: (message: string, kvPairs?: Record<string, unknown>) => void;
+    warn: (message: string, kvPairs?: Record<string, unknown>) => void;
+    error: (message: string, kvPairs?: Record<string, unknown>) => void;
+}
+/**
+ * Create a logger for a specific module
+ *
+ * @param module - Module name (e.g., "cloak::sdk", "cloak::indexer")
+ * @returns Logger instance with debug, info, warn, error methods
+ *
+ * @example
+ * ```typescript
+ * const log = createLogger("cloak::deposit");
+ * log.info("Depositing", { amount: 100000000 });
+ * // Output: 2026-01-23T00:51:46.489000Z  INFO cloak::deposit: Depositing amount=100000000
+ * ```
+ */
+declare function createLogger(module: string): Logger;
+/**
+ * Measure and return duration of an async operation
+ *
+ * @param _logger - Logger instance (reserved for future debug logging)
+ * @param _operation - Operation name (reserved for future debug logging)
+ * @param fn - Async function to measure
+ * @returns Result and duration in milliseconds
+ */
+declare function withTiming<T>(_logger: Logger, _operation: string, fn: () => Promise<T>): Promise<{
+    result: T;
+    durationMs: number;
+}>;
+/**
+ * Format lamports as SOL with proper decimals
+ */
+declare function formatSol(lamports: number | bigint): string;
+/**
+ * Truncate a string (useful for signatures, hashes)
+ */
+declare function truncate(str: string, len?: number): string;
+/**
+ * Default SDK logger instance
+ */
+declare const sdkLogger: Logger;
+
+/**
+ * Result from submitting a withdrawal that includes the request ID
+ * for potential recovery/resume scenarios
+ */
+interface WithdrawSubmissionResult {
+    /** The relay request ID - persist this for recovery */
+    requestId: string;
+    /** The final transaction signature */
+    signature: string;
+}
+/**
+ * Relay Service Client
+ *
+ * Handles submission of withdrawal transactions through a relay service
+ * that pays for transaction fees and submits the transaction on-chain.
+ */
+declare class RelayService {
+    private baseUrl;
+    /**
+     * Create a new Relay Service client
+     *
+     * @param baseUrl - Relay service base URL
+     */
+    constructor(baseUrl: string);
+    /**
+     * Submit a withdrawal transaction via relay
+     *
+     * The relay service will validate the proof, pay for transaction fees,
+     * and submit the transaction on-chain.
+     *
+     * @param params - Withdrawal parameters
+     * @param onStatusUpdate - Optional callback for status updates
+     * @param onRequestId - CRITICAL: Callback when request_id is received.
+     *                      Persist this ID to recover if browser crashes during polling.
+     * @returns Transaction signature when completed
+     *
+     * @example
+     * ```typescript
+     * const signature = await relay.submitWithdraw({
+     *   proof: proofHex,
+     *   publicInputs: { root, nf, outputs_hash, amount },
+     *   outputs: [{ recipient: addr, amount: lamports }],
+     *   feeBps: 50
+     * }, (status) => console.log(`Status: ${status}`),
+     *    (requestId) => localStorage.setItem('pending_withdraw', requestId));
+     * console.log(`Transaction: ${signature}`);
+     * ```
+     */
+    submitWithdraw(params: {
+        proof: string;
+        publicInputs: {
+            root: string;
+            nf: string;
+            outputs_hash: string;
+            amount: number;
+        };
+        outputs: Array<{
+            recipient: string;
+            amount: number;
+        }>;
+        feeBps: number;
+        metadataBundle?: EncryptedMetadataBundle;
+    }, onStatusUpdate?: (status: string) => void, onRequestId?: (requestId: string) => void): Promise<string>;
+    /**
+     * Resume polling for a withdrawal that was previously started
+     *
+     * Use this after page reload to check status of a pending withdrawal.
+     * The requestId should have been persisted via the onRequestId callback.
+     *
+     * @param requestId - Request ID from a previous submitWithdraw call
+     * @param onStatusUpdate - Optional callback for status updates
+     * @returns Transaction signature if completed, null if still pending/failed
+     *
+     * @example
+     * ```typescript
+     * // On page load, check for pending withdrawal
+     * const pendingId = localStorage.getItem('pending_withdraw');
+     * if (pendingId) {
+     *   const result = await relay.resumeWithdraw(pendingId);
+     *   if (result.status === 'completed') {
+     *     console.log('Withdrawal completed:', result.signature);
+     *     localStorage.removeItem('pending_withdraw');
+     *   }
+     * }
+     * ```
+     */
+    resumeWithdraw(requestId: string, onStatusUpdate?: (status: string) => void): Promise<{
+        status: 'completed' | 'failed' | 'pending';
+        signature?: string;
+        error?: string;
+    }>;
+    /**
+     * Poll for withdrawal completion
+     *
+     * @param requestId - Request ID from relay service
+     * @param onStatusUpdate - Optional callback for status updates
+     * @returns Transaction signature when completed
+     */
+    private pollForCompletion;
+    /**
+     * Submit a swap transaction via relay
+     *
+     * Similar to submitWithdraw but includes swap parameters for token swaps.
+     * The relay service will validate the proof, execute the swap, pay for fees,
+     * and submit the transaction on-chain.
+     *
+     * @param params - Swap parameters
+     * @param onStatusUpdate - Optional callback for status updates
+     * @returns Transaction signature when completed
+     *
+     * @example
+     * ```typescript
+     * const signature = await relay.submitSwap({
+     *   proof: proofHex,
+     *   publicInputs: { root, nf, outputs_hash, amount },
+     *   outputs: [{ recipient: addr, amount: lamports }],
+     *   feeBps: 50,
+     *   swap: {
+     *     output_mint: tokenMint.toBase58(),
+     *     slippage_bps: 100,
+     *     min_output_amount: minAmount
+     *   }
+     * }, (status) => console.log(`Status: ${status}`));
+     * console.log(`Transaction: ${signature}`);
+     * ```
+     */
+    submitSwap(params: {
+        proof: string;
+        publicInputs: {
+            root: string;
+            nf: string;
+            outputs_hash: string;
+            amount: number;
+        };
+        outputs: Array<{
+            recipient: string;
+            amount: number;
+        }>;
+        feeBps: number;
+        swap: {
+            output_mint: string;
+            slippage_bps: number;
+            min_output_amount: number;
+        };
+        metadataBundle?: EncryptedMetadataBundle;
+    }, onStatusUpdate?: (status: string) => void, onRequestId?: (requestId: string) => void): Promise<string>;
+    /**
+     * Get transaction status
+     *
+     * @param requestId - Request ID from previous submission
+     * @returns Current status
+     *
+     * @example
+     * ```typescript
+     * const status = await relay.getStatus(requestId);
+     * console.log(`Status: ${status.status}`);
+     * if (status.status === 'completed') {
+     *   console.log(`TX: ${status.txId}`);
+     * }
+     * ```
+     */
+    getStatus(requestId: string): Promise<TxStatus>;
+    /**
+     * Register viewing key with relay for compliance decryption.
+     * This is a one-time operation - the viewing key is stored by the relay.
+     *
+     * The user must sign a one-time relay challenge proving wallet ownership.
+     *
+     * @param userPubkey - User's wallet public key (base58)
+     * @param viewingKey - Viewing key private key (32 bytes, hex encoded)
+     * @param signMessage - Function to sign challenge message bytes
+     *
+     * @example
+     * ```typescript
+     * await relay.registerViewingKey(
+     *   userPublicKey.toBase58(),
+     *   viewingKeyHex,
+     *   signatureBase64
+     * );
+     * ```
+     */
+    registerViewingKey(userPubkey: string, viewingKey: string, signMessage: (message: Uint8Array) => Promise<Uint8Array>): Promise<boolean>;
+    /**
+     * Fetch relay compliance master public key.
+     * DEPRECATED: This endpoint is no longer used
+     */
+    getCompliancePublicKey(): Promise<Uint8Array>;
+    /**
+     * Convert bytes to base64 string
+     */
+    private bytesToBase64;
+    /**
+     * Sleep utility
+     */
+    private sleep;
+    private computeViewingKeyIdentifier;
+}
+
+/**
+ * Risk Oracle Service
+ *
+ * Self-contained module for fetching Switchboard risk quote instructions
+ * using the Range Risk API. Eliminates the need for an external web endpoint
+ * (e.g. `/api/risk-quote`) by calling Switchboard directly from the SDK.
+ *
+ * Uses dynamic imports for @switchboard-xyz packages so they are only loaded
+ * when fetchRiskQuoteIx is actually called — not at SDK import time. This
+ * prevents the heavy Node.js-only Switchboard code from being bundled into
+ * browser builds (Next.js, etc.).
+ *
+ * Usage:
+ *   const { instruction, queue } = await fetchRiskQuoteIx(connection, wallet, rangeApiKey);
+ */
+
+/**
+ * Fetch a Switchboard risk quote instruction directly from Range + Switchboard.
+ *
+ * This removes the need for an external `/api/risk-quote` endpoint. The SDK
+ * calls Switchboard's crossbar oracle network directly with the Range API key.
+ *
+ * @param connection - Solana RPC connection
+ * @param wallet - Depositor's public key (the wallet being risk-scored)
+ * @param rangeApiKey - Range.org API key for the risk score lookup
+ * @returns The Ed25519 sig-verify instruction to prepend at index 0, plus the queue pubkey
+ */
+declare function fetchRiskQuoteIx(connection: Connection, wallet: PublicKey, rangeApiKey: string): Promise<{
+    instruction: TransactionInstruction;
+    queue: PublicKey;
+}>;
+
+/**
+ * Encrypted Output Helpers
+ *
+ * Functions for creating encrypted outputs that enable note scanning
+ */
+
+/**
+ * Prepare encrypted output for scanning by wallet owner
+ *
+ * @param note - Note to encrypt
+ * @param cloakKeys - Wallet's Cloak keys (for self-encryption)
+ * @returns Base64-encoded encrypted output
+ */
+declare function prepareEncryptedOutput(note: CloakNote, cloakKeys: CloakKeyPair): string;
+/**
+ * Prepare encrypted output for a specific recipient
+ *
+ * @param note - Note to encrypt
+ * @param recipientPvkHex - Recipient's public view key (hex)
+ * @returns Base64-encoded encrypted output
+ */
+declare function prepareEncryptedOutputForRecipient(note: CloakNote, recipientPvkHex: string): string;
+/**
+ * Simple base64 encoding for v1.0 notes (no encryption)
+ *
+ * @param note - Note to encode
+ * @returns Base64-encoded note data
+ */
+declare function encodeNoteSimple(note: CloakNote): string;
+
+/**
+ * Wallet Integration Helpers
+ *
+ * Helper functions for working with Solana Wallet Adapters
+ */
+
+/**
+ * Validate wallet is connected and has public key
+ */
+declare function validateWalletConnected(wallet: WalletAdapter | Keypair): void;
+/**
+ * Get public key from wallet or keypair
+ */
+declare function getPublicKey(wallet: WalletAdapter | Keypair): PublicKey;
+/**
+ * Send transaction using wallet adapter or keypair
+ */
+declare function sendTransaction(transaction: Transaction, wallet: WalletAdapter | Keypair, connection: Connection, options?: SendOptions): Promise<string>;
+/**
+ * Sign transaction using wallet adapter or keypair
+ */
+declare function signTransaction<T extends Transaction>(transaction: T, wallet: WalletAdapter | Keypair): Promise<T>;
+/**
+ * Create a keypair adapter for testing
+ */
+declare function keypairToAdapter(keypair: Keypair): WalletAdapter;
+
+/**
+ * Create a deposit instruction
+ *
+ * Deposits SOL into the Cloak protocol by creating a commitment.
+ *
+ * Instruction format:
+ * - Byte 0: Discriminant (0x01 for Deposit, per ShieldPoolInstruction enum)
+ * - Bytes 1-8: Amount (u64, little-endian)
+ * - Bytes 9-40: Commitment (32 bytes)
+ *
+ * @param params - Deposit parameters
+ * @returns Transaction instruction
+ *
+ * @example
+ * ```typescript
+ * const instruction = createDepositInstruction({
+ *   programId: CLOAK_PROGRAM_ID,
+ *   payer: wallet.publicKey,
+ *   pool: POOL_ADDRESS,
+ *   commitments: COMMITMENTS_ADDRESS,
+ *   amount: 1_000_000_000, // 1 SOL
+ *   commitment: commitmentBytes
+ * });
+ * ```
+ */
+declare function createDepositInstruction(params: {
+    programId: PublicKey;
+    payer: PublicKey;
+    pool: PublicKey;
+    merkleTree: PublicKey;
+    amount: number;
+    commitment: Uint8Array;
+}): TransactionInstruction;
+/**
+ * Deposit instruction parameters for type safety
+ */
+interface DepositInstructionParams {
+    programId: PublicKey;
+    payer: PublicKey;
+    pool: PublicKey;
+    merkleTree: PublicKey;
+    amount: number;
+    commitment: Uint8Array;
+}
+/**
+ * Validate deposit instruction parameters
+ *
+ * @param params - Parameters to validate
+ * @throws Error if invalid
+ */
+declare function validateDepositParams(params: DepositInstructionParams): void;
+
+/**
+ * Program Derived Address (PDA) utilities for Shield Pool
+ *
+ * These functions derive deterministic addresses from the program ID and seeds.
+ * This matches the behavior in tooling/test/src/shared.rs::get_pda_addresses()
+ */
+
+interface ShieldPoolPDAs {
+    pool: PublicKey;
+    merkleTree: PublicKey;
+    vaultAuthority: PublicKey;
+    treasury: PublicKey;
+}
+/**
+ * Derive all Shield Pool PDAs from program ID + pool mint
+ *
+ * Seeds match the on-chain mint-scoped program:
+ * - pool: [b"pool", mint]
+ * - merkle_tree: [b"merkle_tree", mint]
+ * - treasury: [b"treasury", mint]
+ * - vault_authority: [b"vault_authority", mint]
+ *
+ * @param programId - Optional program ID (defaults to CLOAK_PROGRAM_ID)
+ * @param mint - Pool mint (defaults to NATIVE_SOL_MINT / WSOL sentinel)
+ */
+declare function getShieldPoolPDAs(programId?: PublicKey, mint?: PublicKey): ShieldPoolPDAs;
+/**
+ * Derive the nullifier PDA for a specific pool + nullifier hash.
+ *
+ * With the new PDA-per-nullifier design, each nullifier has its own PDA
+ * instead of being stored in a shared shard. The PDA is created when
+ * the nullifier is used during withdrawal.
+ *
+ * Seeds: ["nullifier", pool_pubkey, nullifier_hash]
+ *
+ * @param poolPubkey - Pool PDA that scopes nullifier domain
+ * @param nullifier - 32-byte nullifier hash
+ * @param programId - Optional program ID (defaults to CLOAK_PROGRAM_ID)
+ * @returns [PublicKey, bump] - The nullifier PDA and its bump seed
+ */
+declare function getNullifierPDA(poolPubkey: PublicKey, nullifier: Uint8Array | Buffer, programId?: PublicKey): [PublicKey, number];
+/**
+ * Derive the swap state PDA for a given pool + nullifier.
+ *
+ * Seeds: ["swap_state", pool_pubkey, nullifier_hash]
+ *
+ * @param poolPubkey - Pool PDA used for swap state domain separation
+ * @param nullifier - 32-byte nullifier hash
+ * @param programId - Optional program ID (defaults to CLOAK_PROGRAM_ID)
+ * @returns [PublicKey, bump] - The swap state PDA and its bump seed
+ */
+declare function getSwapStatePDA(poolPubkey: PublicKey, nullifier: Uint8Array | Buffer, programId?: PublicKey): [PublicKey, number];
+
+/**
+ * On-chain Merkle proof computation
+ *
+ * Computes Merkle proofs directly from on-chain tree state,
+ * eliminating the need for an indexer for proof generation.
+ */
+
+/**
+ * Merkle proof result
+ */
+interface OnchainMerkleProof {
+    pathElements: string[];
+    pathIndices: number[];
+    root: string;
+}
+interface MerkleTreeState {
+    nextIndex: number;
+    root: string;
+    subtrees: string[];
+}
+/**
+ * Read the Merkle tree state from on-chain account
+ * @param forceConfirmed - If true, forces "confirmed" commitment level for fresh data
+ * @param relayUrl - Optional relay URL to query for current root (bypasses RPC caching)
+ * @param mint - Optional pool mint used when querying relay /merkle-root
+ */
+declare function readMerkleTreeState(connection: Connection, merkleTreePDA: PublicKey, forceConfirmed?: boolean, relayUrl?: string, 
+/** When true, skip relay root and use chain directly (avoids stale relay root causing ProofInvalid) */
+skipRelayRoot?: boolean, mint?: PublicKey): Promise<MerkleTreeState>;
+/**
+ * Compute Merkle proof for a leaf at a given index using on-chain state
+ *
+ * This works by:
+ * 1. Reading the subtrees (frontier) from the on-chain account
+ * 2. For each level, determining the sibling:
+ *    - If index is odd: sibling is the stored subtree (left sibling)
+ *    - If index is even: sibling is either a subsequent subtree or zero value
+ *
+ * Note: This works best for recent leaves where siblings are zero values.
+ * For older leaves with non-zero siblings that aren't stored in subtrees,
+ * an indexer may still be needed.
+ *
+ * @param connection - Solana connection
+ * @param merkleTreePDA - PDA of the merkle tree account
+ * @param leafIndex - Index of the leaf to compute proof for
+ * @param forceConfirmed - If true, forces "confirmed" commitment level for fresh data
+ * @returns Merkle proof with path elements and indices
+ */
+declare function computeProofFromChain(connection: Connection, merkleTreePDA: PublicKey, leafIndex: number, forceConfirmed?: boolean): Promise<OnchainMerkleProof>;
+/**
+ * Compute proof for the most recently inserted leaf
+ *
+ * This is the most reliable case - immediately after your deposit,
+ * all siblings to the right are zero values, and siblings to the left
+ * are stored in the subtrees.
+ */
+declare function computeProofForLatestDeposit(connection: Connection, merkleTreePDA: PublicKey): Promise<OnchainMerkleProof & {
+    leafIndex: number;
+}>;
+
+/**
+ * Merkle Tree implementation for computing proofs
+ *
+ * This tree stores all leaves and can compute the correct Merkle path
+ * for any leaf index.
+ */
+declare const MERKLE_TREE_HEIGHT = 32;
+/**
+ * Merkle Tree class that stores all leaves and computes proofs
+ */
+declare class MerkleTree {
+    private levels;
+    private capacity;
+    private layers;
+    private zeros;
+    private poseidon;
+    /**
+     * Create a new Merkle tree
+     * @param levels Number of levels in the tree (height)
+     * @param leaves Initial leaves to insert
+     * @param zeros Precomputed zero values for each level
+     * @param poseidon Pre-initialized Poseidon instance (avoids async in constructor)
+     */
+    constructor(levels: number, leaves: bigint[], zeros: bigint[], poseidon: any);
+    /**
+     * Create a new MerkleTree with async initialization
+     */
+    static create(levels?: number, leaves?: bigint[]): Promise<MerkleTree>;
+    /**
+     * Rebuild the tree from the leaves (synchronous — poseidon must be initialized)
+     */
+    private _rebuildSync;
+    /**
+     * Get the tree root
+     */
+    root(): bigint;
+    /**
+     * Get the number of leaves in the tree
+     */
+    get length(): number;
+    /**
+     * Insert a new leaf into the tree
+     */
+    insert(leaf: bigint): void;
+    /**
+     * Insert multiple leaves
+     */
+    bulkInsert(leaves: bigint[]): void;
+    /**
+     * Update the path from a leaf to the root
+     */
+    private _updatePath;
+    /**
+     * Get the Merkle path for a leaf at the given index
+     * @param index Leaf index
+     * @returns pathElements and pathIndices for the proof
+     */
+    path(index: number): {
+        pathElements: bigint[];
+        pathIndices: number;
+    };
+    /**
+     * Find the index of a leaf in the tree
+     * @param leaf Leaf value to find
+     * @returns Index if found, -1 otherwise
+     */
+    indexOf(leaf: bigint): number;
+    /**
+     * Get all leaves
+     */
+    leaves(): bigint[];
+}
+/**
+ * Build a MerkleTree from commitment values
+ * @param commitments Array of commitment bigints
+ * @param height Tree height (default: 32)
+ */
+declare function buildMerkleTree(commitments: bigint[], height?: number): Promise<MerkleTree>;
+
+/**
+ * Relay client utilities for fetching data from the relay service
+ */
+
+interface CommitmentEntry {
+    index: number;
+    commitment: string;
+}
+interface CommitmentsResponse {
+    commitments: CommitmentEntry[];
+    count: number;
+    target_reached?: boolean;
+    canonical?: boolean;
+    canonical_reason?: string | null;
+}
+interface FetchCommitmentsOptions {
+    mint?: PublicKey;
+    timeoutMs?: number;
+    maxRetries?: number;
+    sync?: boolean;
+    repair?: boolean;
+    requireTarget?: boolean;
+    requireCanonical?: boolean;
+    fromIndex?: number;
+    limit?: number;
+    waitForIndex?: number;
+}
+/**
+ * Fetch all commitments from the relay
+ * @param relayUrl Base URL of the relay service (may include cache-busting query params)
+ * @param options Timeout and retry options
+ * @returns Array of commitment entries
+ */
+declare function fetchCommitments(relayUrl: string, options?: FetchCommitmentsOptions): Promise<CommitmentEntry[]>;
+/**
+ * Build a Merkle tree from relay commitments
+ * @param relayUrl Base URL of the relay service
+ * @param options When sync is true, triggers on-demand sync on relay before fetching (for freshness when relay is behind chain)
+ * @returns MerkleTree instance with all commitments loaded
+ *
+ * Supports sparse indices by zero-filling missing leaves, including missing prefixes.
+ * Non-contiguous gaps (e.g. 0,1,2,3,22,23,30,31,32,33) are reconstructed with
+ * zero leaves to match the on-chain Merkle tree structure.
+ */
+declare function buildMerkleTreeFromRelay(relayUrl: string, options?: {
+    mint?: PublicKey;
+    sync?: boolean;
+    repair?: boolean;
+    requireTarget?: boolean;
+    requireCanonical?: boolean;
+    timeoutMs?: number;
+    maxRetries?: number;
+    waitForIndex?: number;
+}): Promise<MerkleTree>;
+declare function buildMerkleTreeFromChain(connection: Connection, programId: PublicKey, merkleTree: PublicKey, onProgress?: (message: string) => void): Promise<MerkleTree>;
+/**
+ * Pre-flight root validation
+ *
+ * Validates that a Merkle root is still valid before generating a proof.
+ * This prevents wasted time generating proofs that will fail on-chain.
+ *
+ * @param relayUrl Relay service URL
+ * @param rootHex Root to validate (hex string, with or without 0x prefix)
+ * @returns Validation result with status and helpful message
+ */
+declare function validateRoot(relayUrl: string, rootHex: string): Promise<{
+    valid: boolean;
+    currentRoot?: string;
+    message: string;
+    isRecent: boolean;
+}>;
+/**
+ * Wait for root to be valid
+ *
+ * Polls the relay until the given root is accepted or timeout.
+ * Useful when you know a transaction is being processed but root hasn't updated yet.
+ *
+ * @param relayUrl Relay service URL
+ * @param rootHex Root to wait for
+ * @param timeoutMs Maximum time to wait (default: 30000ms)
+ * @param pollIntervalMs Polling interval (default: 1000ms)
+ * @returns Whether root became valid in time
+ */
+declare function waitForRoot(relayUrl: string, rootHex: string, timeoutMs?: number, pollIntervalMs?: number): Promise<{
+    success: boolean;
+    currentRoot?: string;
+    waitedMs: number;
+}>;
+/**
+ * Smart pre-flight check with automatic retry suggestion
+ *
+ * Checks root validity and provides actionable guidance:
+ * - If root is current: proceed
+ * - If root is old: suggest fetching fresh Merkle proofs
+ * - If root is very old: suggest full tree rebuild
+ *
+ * @param relayUrl Relay service URL
+ * @param rootHex Root to check
+ * @returns Action recommendation
+ */
+declare function preflightCheck(relayUrl: string, rootHex: string): Promise<{
+    shouldProceed: boolean;
+    action: "proceed" | "refresh_proofs" | "rebuild_tree" | "wait";
+    message: string;
+    estimatedWaitMs?: number;
+}>;
+
+/**
+ * Direct Circom WASM Proof Generation
+ *
+ * This module provides direct proof generation using snarkjs and Circom WASM,
+ * matching the approach used in services-new/tests/src/proof.ts
+ *
+ * This uses pinned S3-hosted circuit artifacts and does not require
+ * a backend prover service.
+ */
+
+/**
+ * Default URL for fetching circuit artifacts
+ * Hosted in S3 and versioned by build.
+ */
+declare const DEFAULT_CIRCUITS_URL = "https://cloak-circuits.s3.us-east-1.amazonaws.com/circuits/0.1.0";
+interface WithdrawRegularInputs {
+    root: bigint;
+    nullifier: bigint;
+    outputs_hash: bigint;
+    public_amount: bigint;
+    amount: bigint;
+    leaf_index: bigint;
+    sk: [bigint, bigint];
+    r: [bigint, bigint];
+    pathElements: bigint[];
+    pathIndices: number[];
+    num_outputs: number;
+    out_addr: bigint[][];
+    out_amount: bigint[];
+    out_flags: number[];
+    var_fee: bigint;
+    rem: bigint;
+}
+interface WithdrawSwapInputs {
+    sk_spend: bigint;
+    r: bigint;
+    amount: bigint;
+    leaf_index: bigint;
+    path_elements: bigint[];
+    path_indices: number[];
+    root: bigint;
+    nullifier: bigint;
+    outputs_hash: bigint;
+    public_amount: bigint;
+    input_mint: bigint[];
+    output_mint: bigint[];
+    recipient_ata: bigint[];
+    min_output_amount: bigint;
+    var_fee: bigint;
+    rem: bigint;
+}
+interface ProofResult {
+    proof: Groth16Proof;
+    publicSignals: string[];
+    proofBytes: Uint8Array;
+    publicInputsBytes: Uint8Array;
+}
+/**
+ * Generate Groth16 proof for regular withdrawal using Circom WASM
+ *
+ * This matches the approach in services-new/tests/src/proof.ts
+ *
+ * @param inputs - Circuit inputs
+ * @param circuitsPath - Ignored. Proof generation always uses pinned S3 circuits.
+ */
+declare function generateWithdrawRegularProof(inputs: WithdrawRegularInputs, circuitsPath: string): Promise<ProofResult>;
+/**
+ * Generate Groth16 proof for swap withdrawal using Circom WASM
+ *
+ * This matches the approach in services-new/tests/src/proof.ts
+ *
+ * @param inputs - Circuit inputs
+ * @param circuitsPath - Ignored. Proof generation always uses pinned S3 circuits.
+ */
+declare function generateWithdrawSwapProof(inputs: WithdrawSwapInputs, circuitsPath: string): Promise<ProofResult>;
+/**
+ * Check if circuits are available from the pinned S3 source.
+ */
+declare function areCircuitsAvailable(circuitsPath: string): Promise<boolean>;
+/**
+ * Get default circuits URL.
+ */
+declare function getDefaultCircuitsPath(): Promise<string>;
+/**
+ * Pinned circuit artifact hashes (SHA-256).
+ *
+ * These hashes must be updated whenever the trusted circuit artifacts change.
+ */
+declare const EXPECTED_CIRCUIT_HASHES: {
+    withdraw_regular_wasm: string;
+    withdraw_regular_zkey: string;
+    withdraw_swap_wasm: string;
+    withdraw_swap_zkey: string;
+};
+/**
+ * Circuit verification result
+ */
+interface CircuitVerificationResult {
+    /** Whether verification passed */
+    valid: boolean;
+    /** Which circuit was checked */
+    circuit: 'withdraw_regular' | 'withdraw_swap';
+    /** Error message if verification failed */
+    error?: string;
+    computed?: {
+        wasm: string;
+        zkey: string;
+    };
+    expected?: {
+        wasm: string;
+        zkey: string;
+    };
+}
+/**
+ * Verify circuit integrity by checking verification key hashes
+ *
+ * This function fetches the verification key and computes its hash,
+ * then compares against the expected hash embedded in the SDK.
+ *
+ * IMPORTANT: If the hashes don't match, the circuit may produce proofs
+ * that will be rejected by the on-chain verifier!
+ *
+ * @param circuitsPath - Ignored. Verification always uses pinned S3 circuits.
+ * @param circuit - Which circuit to verify ('withdraw_regular' or 'withdraw_swap')
+ * @returns Verification result
+ *
+ * @example
+ * ```typescript
+ * const result = await verifyCircuitIntegrity('https://cloak-circuits.s3.us-east-1.amazonaws.com/circuits/0.1.0', 'withdraw_regular');
+ * if (!result.valid) {
+ *   console.error('Circuit verification failed:', result.error);
+ *   // Don't proceed with proof generation!
+ * }
+ * ```
+ */
+declare function verifyCircuitIntegrity(circuitsPath: string, circuit: 'withdraw_regular' | 'withdraw_swap'): Promise<CircuitVerificationResult>;
+/**
+ * Verify all circuits before use
+ *
+ * Call this at SDK initialization to ensure circuits are valid.
+ *
+ * @param circuitsPath - Ignored. Verification always uses pinned S3 circuits.
+ * @returns Array of verification results (one per circuit)
+ */
+declare function verifyAllCircuits(circuitsPath: string): Promise<CircuitVerificationResult[]>;
+
+/**
+ * Pending Operations Manager
+ *
+ * Utility for persisting pending deposit/withdrawal operations in browser storage.
+ * This enables recovery if the browser crashes or user navigates away mid-operation.
+ *
+ * IMPORTANT: This uses localStorage by default which has security implications.
+ * Notes contain sensitive spending keys - consider using more secure storage
+ * in production (e.g., encrypted IndexedDB, secure enclave).
+ */
+
+/**
+ * Pending deposit record
+ */
+interface PendingDeposit {
+    /** The note (contains spending secrets!) */
+    note: CloakNote;
+    /** When the deposit was initiated */
+    startedAt: number;
+    /** Transaction signature if available */
+    txSignature?: string;
+    /** Status of the deposit */
+    status: "pending" | "tx_sent" | "confirmed" | "failed";
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Pending withdrawal record
+ */
+interface PendingWithdrawal {
+    /** The relay request ID (for resumption) */
+    requestId: string;
+    /** The note commitment being withdrawn */
+    commitment: string;
+    /** The nullifier being used */
+    nullifier: string;
+    /** When the withdrawal was initiated */
+    startedAt: number;
+    /** Status of the withdrawal */
+    status: "pending" | "processing" | "completed" | "failed";
+    /** Transaction signature if completed */
+    txSignature?: string;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Save a pending deposit
+ * Call this BEFORE sending the on-chain transaction to ensure note is persisted
+ */
+declare function savePendingDeposit(deposit: PendingDeposit): void;
+/**
+ * Load all pending deposits
+ */
+declare function loadPendingDeposits(): PendingDeposit[];
+/**
+ * Update a pending deposit status
+ */
+declare function updatePendingDeposit(commitment: string, updates: Partial<PendingDeposit>): void;
+/**
+ * Remove a pending deposit (e.g., after successful confirmation)
+ */
+declare function removePendingDeposit(commitment: string): void;
+/**
+ * Clear all pending deposits
+ */
+declare function clearPendingDeposits(): void;
+/**
+ * Save a pending withdrawal
+ * Call this when you receive the request_id from the relay
+ */
+declare function savePendingWithdrawal(withdrawal: PendingWithdrawal): void;
+/**
+ * Load all pending withdrawals
+ */
+declare function loadPendingWithdrawals(): PendingWithdrawal[];
+/**
+ * Update a pending withdrawal status
+ */
+declare function updatePendingWithdrawal(requestId: string, updates: Partial<PendingWithdrawal>): void;
+/**
+ * Remove a pending withdrawal (e.g., after successful completion)
+ */
+declare function removePendingWithdrawal(requestId: string): void;
+/**
+ * Clear all pending withdrawals
+ */
+declare function clearPendingWithdrawals(): void;
+/**
+ * Check if there are any pending operations that need recovery
+ * Call this on page load to determine if recovery UI should be shown
+ */
+declare function hasPendingOperations(): boolean;
+/**
+ * Get summary of pending operations for recovery UI
+ */
+declare function getPendingOperationsSummary(): {
+    deposits: PendingDeposit[];
+    withdrawals: PendingWithdrawal[];
+    totalPending: number;
+};
+/**
+ * Clean up stale pending operations
+ * Call this periodically to remove old failed/completed operations
+ *
+ * @param maxAgeMs Maximum age in milliseconds before an operation is removed (default: 24 hours)
+ */
+declare function cleanupStalePendingOperations(maxAgeMs?: number): {
+    removedDeposits: number;
+    removedWithdrawals: number;
+};
+
+/**
+ * UTXO (Unspent Transaction Output) Model
+ *
+ * This module implements the UTXO model for the Cloak privacy protocol.
+ * UTXOs allow for:
+ * - Shield-to-shield transfers (privacy preserved)
+ * - Partial withdrawals (change stays shielded)
+ * - Combining multiple small deposits
+ * - Multi-token support (SOL + any SPL token)
+ */
+
+declare const NATIVE_SOL_MINT: PublicKey;
+/**
+ * UTXO Keypair for ownership verification
+ *
+ * Uses Poseidon hash for key derivation:
+ * - privateKey: random field element (kept secret)
+ * - publicKey: Poseidon(privateKey, 0) - can be shared
+ */
+interface UtxoKeypair {
+    /** Private key (random 252-bit field element) */
+    privateKey: bigint;
+    /** Public key derived as Poseidon(privateKey, 0) */
+    publicKey: bigint;
+}
+/**
+ * UTXO represents an unspent transaction output
+ *
+ * Contains all information needed to spend the UTXO:
+ * - amount: Value in the smallest unit (lamports for SOL)
+ * - keypair: Ownership keys
+ * - blinding: Randomness for hiding
+ * - mintAddress: Token type (SOL or SPL token)
+ * - index: Leaf index in Merkle tree (set after deposit/creation)
+ */
+interface Utxo {
+    /** Amount in the smallest unit (lamports for SOL, token units for SPL) */
+    amount: bigint;
+    /** Keypair for ownership */
+    keypair: UtxoKeypair;
+    /** Random blinding factor */
+    blinding: bigint;
+    /** Token mint address (NATIVE_SOL_MINT for SOL) */
+    mintAddress: PublicKey;
+    /** Leaf index in Merkle tree (set after the UTXO is in the tree) */
+    index?: number;
+    /** Commitment hash (computed from amount, pubkey, blinding, mint) */
+    commitment?: bigint;
+    /** Nullifier hash (computed when spending) */
+    nullifier?: bigint;
+    /**
+     * Sibling commitment at level 0 of the Merkle tree.
+     * Required for Merkle proofs since siblings aren't stored on-chain.
+     * This is the commitment of the other output in the same transaction.
+     */
+    siblingCommitment?: bigint;
+}
+/**
+ * Encrypted UTXO note for recipient discovery
+ *
+ * When creating an output UTXO for someone else, the data is encrypted
+ * so only the recipient can discover and spend it.
+ */
+interface EncryptedNote {
+    /** Encrypted UTXO data (ECIES/ChaCha20 encrypted) */
+    ciphertext: Uint8Array;
+    /** Ephemeral public key for ECDH */
+    ephemeralPubkey: Uint8Array;
+    /** MAC for integrity verification */
+    mac: Uint8Array;
+}
+/**
+ * Transaction parameters for a UTXO transaction
+ */
+interface TransactParams {
+    /** Input UTXOs to spend (max 2) */
+    inputUtxos: Utxo[];
+    /** Output UTXOs to create (max 2) */
+    outputUtxos: Utxo[];
+    /** External recipient for withdrawal (optional) */
+    recipient?: PublicKey;
+    /** Net external amount: positive = deposit, negative = withdraw */
+    externalAmount?: bigint;
+    /** Depositor address (for deposits, the source of funds) */
+    depositor?: PublicKey;
+}
+/**
+ * Result from a UTXO transaction
+ */
+interface TransactResult {
+    /** Transaction signature */
+    signature: string;
+    /** Nullifiers of spent inputs */
+    inputNullifiers: bigint[];
+    /** Commitments of created outputs */
+    outputCommitments: bigint[];
+    /** New Merkle root after the transaction */
+    newRoot: string;
+    /** Merkle tree indices where output commitments were inserted */
+    commitmentIndices: [number, number];
+    /**
+     * Sibling commitments for each output.
+     * For output[0], sibling is output[1] and vice versa.
+     * These are needed for Merkle proofs since siblings aren't stored on-chain.
+     */
+    siblingCommitments: [bigint, bigint];
+    /**
+     * Left sibling from before the transaction (for odd-index handling).
+     * When the first output ends up at an odd index due to concurrent access,
+     * its sibling at index-1 comes from a previous transaction.
+     * This value captures subtrees[0] before our transaction to enable
+     * correct Merkle proof computation for odd indices.
+     */
+    preTransactionLeftSibling?: bigint;
+    /**
+     * The actual output UTXOs created by this transaction.
+     * These have all the data needed to spend them later (keypair, blinding, etc).
+     * The UTXOs are already updated with their indices and sibling commitments.
+     */
+    outputUtxos: Utxo[];
+    /**
+     * Whether the viewing key was registered with the relay for compliance.
+     * True on first transaction when metadataBundle includes viewing_key.
+     * Once registered, subsequent transactions don't need to send metadataBundle.
+     */
+    viewingKeyRegistered?: boolean;
+    /**
+     * The Merkle tree used/built for this transaction, with output commitments inserted.
+     * Pass this as `cachedMerkleTree` in the next transaction to skip relay fetching
+     * and avoid needing `waitForCommitmentIndex`.
+     */
+    merkleTree?: MerkleTree;
+    /**
+     * Address lookup table used for v0 transaction (when chain notes or risk oracle require it).
+     * Pass this as `addressLookupTableAccounts` in the next deposit to avoid creating a new ALT.
+     */
+    addressLookupTableAccounts?: AddressLookupTableAccount[];
+}
+/**
+ * Generate a random field element suitable for BN254
+ */
+declare function randomFieldElement(): bigint;
+/**
+ * Generate a new UTXO keypair
+ *
+ * @returns A new keypair with random private key and derived public key
+ */
+declare function generateUtxoKeypair(): Promise<UtxoKeypair>;
+/**
+ * Derive a deterministic UTXO keypair from a wallet's spend key.
+ * Use this for deposits and change outputs so all chain notes use the same nk,
+ * enabling the compliance scan (scanTransactions + toComplianceReport) to decrypt them.
+ *
+ * @param skSpend - 32-byte spend key (from wallet key derivation)
+ * @returns UtxoKeypair with deterministic private/public keys
+ */
+declare function deriveUtxoKeypairFromSpendKey(skSpend: Uint8Array): Promise<UtxoKeypair>;
+/**
+ * Derive public key from private key
+ *
+ * @param privateKey The private key
+ * @returns The corresponding public key
+ */
+declare function derivePublicKey(privateKey: bigint): Promise<bigint>;
+/**
+ * Create a new UTXO
+ *
+ * @param amount Amount in smallest unit
+ * @param keypair Owner's keypair
+ * @param mintAddress Token mint (defaults to native SOL)
+ * @returns A new UTXO (commitment will be computed)
+ */
+declare function createUtxo(amount: bigint, keypair: UtxoKeypair, mintAddress?: PublicKey): Promise<Utxo>;
+/**
+ * Create a zero/padding UTXO
+ *
+ * Zero UTXOs are used as padding when we need fewer than 2 inputs/outputs.
+ * They have zero amount and don't require valid Merkle proofs.
+ * Uses salt-based keypair (privateKey = salt) with blinding=0 to match the circuit
+ * test. By default, salt is random to avoid cross-process collisions under concurrency.
+ * Callers can pass an explicit salt for deterministic behavior.
+ *
+ * @param mintAddress Token mint (defaults to native SOL)
+ * @param salt Optional salt; if omitted, uses timestamp+counter for uniqueness
+ */
+declare function createZeroUtxo(mintAddress?: PublicKey, salt?: bigint): Promise<Utxo>;
+/**
+ * Convert PublicKey to field element for circuit
+ *
+ * @param pubkey Solana PublicKey
+ * @returns Field element representation
+ */
+declare function pubkeyToFieldElement(pubkey: PublicKey): bigint;
+/**
+ * Compute the commitment for a UTXO
+ *
+ * commitment = Poseidon(amount, pubkey, blinding, mintAddress)
+ *
+ * @param utxo The UTXO to compute commitment for
+ * @returns The commitment as a bigint
+ */
+declare function computeCommitment(utxo: Utxo): Promise<bigint>;
+/**
+ * Compute the signature for nullifier derivation
+ *
+ * signature = Poseidon(privateKey, commitment, pathIndex)
+ *
+ * @param privateKey Owner's private key
+ * @param commitment The UTXO commitment
+ * @param pathIndex Merkle tree path index
+ * @returns The signature
+ */
+declare function computeSignature(privateKey: bigint, commitment: bigint, pathIndex: bigint): Promise<bigint>;
+/**
+ * Compute the nullifier for a UTXO
+ *
+ * nullifier = Poseidon(commitment, pathIndex, signature)
+ *
+ * The nullifier is a unique identifier that gets recorded on-chain
+ * to prevent double-spending.
+ *
+ * @param utxo The UTXO being spent
+ * @returns The nullifier
+ */
+declare function computeNullifier(utxo: Utxo): Promise<bigint>;
+/**
+ * Serialize a UTXO to bytes for encryption
+ */
+declare function serializeUtxo(utxo: Utxo): Uint8Array;
+/**
+ * Deserialize a UTXO from bytes
+ */
+declare function deserializeUtxo(bytes: Uint8Array): Promise<Utxo>;
+/**
+ * Convert bigint to hex string (64 chars, padded)
+ */
+declare function bigintToHex(value: bigint): string;
+/**
+ * Convert hex string to bigint
+ */
+declare function hexToBigint(hex: string): bigint;
+/**
+ * Convert bigint to 32-byte array (big-endian for circuits)
+ */
+declare function bigintToBytes32(value: bigint): Uint8Array;
+/**
+ * Check if two UTXOs are equal (same commitment)
+ */
+declare function utxoEquals(a: Utxo, b: Utxo): Promise<boolean>;
+/**
+ * Calculate total amount from an array of UTXOs
+ */
+declare function sumUtxoAmounts(utxos: Utxo[]): bigint;
+/**
+ * Select UTXOs to cover a target amount
+ *
+ * @param available Available UTXOs (sorted by amount descending)
+ * @param targetAmount Target amount to cover
+ * @returns Selected UTXOs that cover the target, or null if insufficient
+ */
+declare function selectUtxos(available: Utxo[], targetAmount: bigint): Utxo[] | null;
+
+/**
+ * UTXO Transaction Methods
+ *
+ * This module provides high-level methods for UTXO transactions:
+ * - transact(): Core UTXO transaction
+ * - transfer(): Shield-to-shield transfer
+ * - partialWithdraw(): Withdraw with change
+ */
+
+declare const DEFAULT_TRANSACTION_CIRCUITS_URL = "https://cloak-circuits.s3.us-east-1.amazonaws.com/circuits/0.1.0";
+/**
+ * Set circuits base path: local directory containing `transaction_js/` and `transaction_final.zkey`,
+ * or an `http(s)` base URL to those artifacts (Node will download once per process to a temp dir).
+ */
+declare function setCircuitsPath(next: string): void;
+/**
+ * Get the current circuits path
+ */
+declare function getCircuitsPath(): string;
+declare function computeChainNoteHash(publicAmount: bigint, extDataHash: bigint, noteTimestamp: bigint, noteCommitment: bigint): Promise<bigint>;
+/**
+ * Compute extDataHash for binding proof to external parameters
+ *
+ * extDataHash = Poseidon(recipient, relayerFee, relayer)
+ */
+declare function computeExtDataHash(recipient: PublicKey | null, relayerFee: bigint, relayer: PublicKey | null): Promise<bigint>;
+/**
+ * Options for transact operation
+ */
+interface TransactOptions {
+    /** Connection to Solana */
+    connection: Connection;
+    /** Program ID */
+    programId: PublicKey;
+    /** Callback for progress updates */
+    onProgress?: (status: string) => void;
+    /** Callback for proof generation progress */
+    onProofProgress?: (percent: number) => void;
+    /** Relayer fee in lamports */
+    relayerFee?: bigint;
+    /** Relayer address for fee payment */
+    relayer?: PublicKey;
+    /** Relay service URL for submitting transactions */
+    relayUrl?: string;
+    /** Keypair of the depositor (signs the deposit transaction) - for programmatic use */
+    depositorKeypair?: Keypair;
+    /**
+     * Wallet adapter sign function - for web app use
+     * If provided (along with depositorPublicKey), user will sign deposits via wallet.
+     * Accepts both legacy Transaction and VersionedTransaction (for V0 with ALTs).
+     */
+    signTransaction?: <T extends Transaction | VersionedTransaction>(transaction: T) => Promise<T>;
+    /** Wallet adapter signMessage for viewing-key registration auth. */
+    signMessage?: (message: Uint8Array) => Promise<Uint8Array>;
+    /** Public key of the depositor when using signTransaction */
+    depositorPublicKey?: PublicKey;
+    /** Wallet public key for relay submissions when depositor keypair isn't used. */
+    walletPublicKey?: PublicKey;
+    /** Maximum retries on RootNotFound error (default: 5) */
+    maxRootRetries?: number;
+    /** Delay between retries in ms (default: 3000) */
+    retryDelayMs?: number;
+    /**
+     * Switchboard oracle queue for risk check on deposits.
+     * Required when program has risk oracle enabled and depositor signs directly.
+     */
+    riskOracleQueue?: PublicKey;
+    /**
+     * URL for fetching the risk quote instruction (Range/Switchboard).
+     * Used for deposits when riskOracleQueue is set. The backend must return a signed
+     * quote instruction for the depositor wallet so the program can verify at index 0.
+     * Defaults to `${relayUrl}/range-quote` when relayUrl is set.
+     */
+    riskQuoteUrl?: string;
+    /**
+     * Optional: provide the risk quote instruction directly (e.g. from your backend).
+     * If set, used instead of riskQuoteUrl for deposits with risk oracle.
+     */
+    getRiskQuoteInstruction?: (wallet: PublicKey) => Promise<TransactionInstruction>;
+    /**
+     * Pre-built ALT addresses (base58 strings) for V0 transactions.
+     * When relayUrl is set, ALTs are also fetched from relay /health.
+     * Pass explicitly (e.g. from your config) instead of relying on env.
+     */
+    altAddresses?: string[];
+    /**
+     * Address lookup table accounts for V0 transactions.
+     * Required when risk oracle deposits exceed the legacy 1232-byte transaction limit.
+     * The ALT should contain common read-only accounts (sysvars, system program, etc.)
+     * to compress account addresses from 32 bytes to 1-byte indices.
+     */
+    addressLookupTableAccounts?: AddressLookupTableAccount[];
+    /**
+     * Optional Range.org API key for direct SDK-side quote fetching.
+     *
+     * Prefer relay-managed quoting via `relayUrl` (default), where the relay owns
+     * the Range API key and serves signed quotes from `${relayUrl}/range-quote`.
+     *
+     * This option is intended for server-side fallback/no-relay scenarios only.
+     * In browser/client apps, do not expose Range API keys.
+     *
+     * When relayUrl is set and riskQuoteUrl is not provided, SDK defaults to
+     * relay `${relayUrl}/range-quote` regardless of rangeApiKey. This keeps
+     * protocol-default risk checks working out of the box via relay.
+     *
+     * Priority: getRiskQuoteInstruction > riskQuoteUrl > rangeApiKey.
+     * If getRiskQuoteInstruction or riskQuoteUrl is also set, those take precedence.
+     */
+    rangeApiKey?: string;
+    /**
+     * Metadata bundle for compliance tracking.
+     * On first transaction, should include viewing_key for compliance registration.
+     */
+    metadataBundle?: {
+        encrypted_user: string;
+        encrypted_compliance: string;
+        user_pubkey: string;
+        commitment: string;
+        timestamp: number;
+        tx_type?: string;
+        viewing_key?: string;
+    };
+    /**
+     * Optional encrypted output notes to embed on-chain for chain-native scanning.
+     * Each entry must be base64-encoded note bytes.
+     */
+    encryptedNotes?: string[];
+    /**
+     * Optional nk (32 bytes, hex or bytes) for diversified chain note encryption (Phase 3).
+     * When provided, 2 per-output encrypted notes are embedded on-chain.
+     */
+    chainNoteViewingKeyNk?: string | Uint8Array;
+    /**
+     * Optional async getter for chain note viewing key. When provided (and chainNoteViewingKeyNk
+     * is not set), the SDK calls this when building chain notes. Use this to avoid deriving and
+     * passing nk at every call site — e.g. pass a getter from your key manager.
+     */
+    getChainNoteViewingKeyNk?: () => Promise<string | Uint8Array | null>;
+    /**
+     * Cached Merkle tree from a previous transaction.
+     * When provided, the SDK skips fetching commitments from the relay and uses this
+     * tree directly for Merkle proof generation. The tree should already contain the
+     * output commitments from the previous transaction (returned in TransactResult.merkleTree).
+     * This eliminates the need for `waitForCommitmentIndex` between sequential transactions.
+     */
+    cachedMerkleTree?: MerkleTree;
+    /**
+     * Use chain indexing for Merkle tree instead of relay.
+     * When true, commitments are fetched from chain via getSignaturesForAddress (slower).
+     * Use when relay is unavailable or for no-relay mode. In browser, chain indexing is disabled.
+     */
+    useChainForMerkle?: boolean;
+    /**
+     * Use unique nullifiers per run (timestamp-based salts for zero UTXOs).
+     * Set when using surfpool or validators that don't support reset - avoids 0x1020 DoubleSpend
+     * across runs. May trigger line 146 in some environments; if so, omit this option.
+     */
+    useUniqueNullifiers?: boolean;
+    /**
+     * Optional DEX allow-list for swaps (Jupiter `dexes`).
+     * Example: ["Orca V2", "Raydium CLMM"]
+     */
+    swapDexes?: string[];
+    /**
+     * Optional DEX block-list for swaps (Jupiter `excludeDexes`).
+     */
+    swapExcludeDexes?: string[];
+    /**
+     * Extra route retries inside the relay swap handler (0-5).
+     * Default relay behavior is 2 extra retries when not provided.
+     */
+    swapRouteRetryAttempts?: number;
+    /**
+     * Optional worker retry budget override for swap TX2 execution (1-10).
+     * Higher values allow more background retries before final failure.
+     */
+    swapMaxRetries?: number;
+    /**
+     * Slippage tolerance in basis points for swaps (passed to relay for Jupiter quotes).
+     * Defaults to 500 bps (5%) if not provided.
+     */
+    swapSlippageBps?: number;
+    /**
+     * Max polling attempts when waiting for swap TX2 completion.
+     * Defaults to 60 attempts.
+     */
+    swapStatusMaxAttempts?: number;
+    /**
+     * Poll interval (ms) when waiting for swap TX2 completion.
+     * Defaults to 2000ms.
+     */
+    swapStatusDelayMs?: number;
+    /** Enforce viewing-key registration before any protocol transaction (default: true). */
+    enforceViewingKeyRegistration?: boolean;
+    /**
+     * Use chain root instead of relay root for proof generation.
+     * When true, readMerkleTreeState skips the relay /merkle-root and uses the on-chain root.
+     * Use when relay may be behind the chain (e.g. commitment_sync lag) to avoid ProofInvalid.
+     */
+    useChainRootForProof?: boolean;
+}
+/** Switchboard-style response: pre-built instruction. */
+interface RiskQuoteInstructionResponse {
+    instruction: {
+        programId: string;
+        keys: Array<{
+            pubkey: string;
+            isSigner: boolean;
+            isWritable: boolean;
+        }>;
+        data: string;
+    };
+}
+/**
+ * Fetch the risk quote instruction from a backend (e.g. relay /risk-quote).
+ * The backend should call Switchboard's fetchQuoteIx for the given wallet
+ * (Range Risk API) and return the serialized instruction.
+ * See: https://www.range.org/blog/integrate-range-onchain-risk-verifier-into-your-solana-program
+ */
+declare function fetchRiskQuoteInstruction(riskQuoteUrl: string, wallet: PublicKey, options?: {
+    recipient?: PublicKey;
+    amount?: bigint;
+    token?: PublicKey;
+}): Promise<TransactionInstruction>;
+declare function transact(params: TransactParams, options: TransactOptions): Promise<TransactResult>;
+/**
+ * Execute a shield-to-shield transfer
+ *
+ * Transfers funds from your UTXOs to another recipient's public key,
+ * keeping everything within the shielded pool.
+ *
+ * @param inputUtxos Your UTXOs to spend
+ * @param recipientPubkey Recipient's UTXO public key
+ * @param amount Amount to transfer
+ * @param options Transaction options
+ */
+declare function transfer(inputUtxos: Utxo[], recipientPubkey: bigint, amount: bigint, options: TransactOptions): Promise<TransactResult>;
+/**
+ * Execute a partial withdrawal
+ *
+ * Withdraws a portion of funds to an external Solana address,
+ * keeping the remainder shielded.
+ *
+ * @param inputUtxos Your UTXOs to spend
+ * @param recipient External Solana address
+ * @param withdrawAmount Amount to withdraw
+ * @param options Transaction options
+ */
+declare function partialWithdraw(inputUtxos: Utxo[], recipient: PublicKey, withdrawAmount: bigint, options: TransactOptions): Promise<TransactResult>;
+/**
+ * Execute a full withdrawal
+ *
+ * Withdraws all funds from UTXOs to an external address.
+ *
+ * @param inputUtxos Your UTXOs to spend
+ * @param recipient External Solana address
+ * @param options Transaction options
+ */
+declare function fullWithdraw(inputUtxos: Utxo[], recipient: PublicKey, options: TransactOptions): Promise<TransactResult>;
+/**
+ * Parameters for UTXO swap operation
+ */
+interface UtxoSwapParams {
+    /** UTXOs to spend */
+    inputUtxos: Utxo[];
+    /** Optional change UTXO to create (remaining shielded funds) */
+    changeUtxo?: Utxo;
+    /** Amount to swap (lamports) */
+    swapAmount: bigint;
+    /** Output token mint address */
+    outputMint: PublicKey;
+    /** Recipient's Associated Token Account for output tokens */
+    recipientAta: PublicKey;
+    /** Optional recipient wallet (used by relay to create ATA if missing) */
+    recipientWallet?: PublicKey;
+    /** Minimum output amount (slippage protection) */
+    minOutputAmount: bigint;
+}
+/**
+ * Result of a UTXO swap operation
+ */
+interface UtxoSwapResult extends TransactResult {
+    /** SwapState PDA address (used for executing the actual swap) */
+    swapStatePda: string;
+    /** Nullifier used for SwapState derivation (hex) */
+    nullifier: string;
+    /** Relay request ID for swap execution status */
+    requestId?: string;
+}
+/**
+ * Execute a UTXO swap withdrawal
+ *
+ * This spends input UTXOs and creates a SwapState PDA for swapping SOL to SPL tokens.
+ * After this transaction, the relay can execute:
+ * 1. PrepareSwapSol - Wrap SOL to wSOL
+ * 2. ExecuteSwapViaOrca - Execute the swap on Orca
+ *
+ * @param params Swap parameters
+ * @param options Transaction options
+ * @returns UtxoSwapResult with SwapState PDA for executing the swap
+ */
+declare function swapUtxo(params: UtxoSwapParams, options: TransactOptions): Promise<UtxoSwapResult>;
+/**
+ * Execute a swap with change
+ *
+ * Convenience function that creates a change UTXO automatically.
+ *
+ * @param inputUtxos UTXOs to spend
+ * @param swapAmount Amount to swap
+ * @param outputMint Output token mint
+ * @param recipientAta Recipient's ATA
+ * @param minOutputAmount Minimum output (slippage protection)
+ * @param options Transaction options
+ */
+declare function swapWithChange(inputUtxos: Utxo[], swapAmount: bigint, outputMint: PublicKey, recipientAta: PublicKey, minOutputAmount: bigint, options: TransactOptions, recipientWallet?: PublicKey): Promise<UtxoSwapResult>;
+
+/**
+ * Compact deterministic chain note format (current format only).
+ *
+ * Envelope: [version 1][ciphertext (timestamp + tag)]
+ */
+type ChainNoteTxType = "deposit" | "withdraw" | "transfer" | "swap" | "unknown";
+interface CompactChainNote {
+    timestamp: bigint;
+    commitment: string;
+}
+/**
+ * Encrypt a compact deterministic chain note.
+ * Payload is minimal to keep relay withdrawals under Solana packet size limits.
+ * Envelope: [version 1][ciphertext (timestamp + tag)]
+ */
+declare function encryptCompactChainNote(timestamp: bigint, nk: Uint8Array, commitmentHex: string): Promise<Uint8Array>;
+/**
+ * Decrypt a compact deterministic chain note with candidate output commitments.
+ * Tries each commitment-derived key until AES-GCM authentication succeeds.
+ */
+declare function decryptCompactChainNote(noteBytes: Uint8Array, nk: Uint8Array, candidateCommitments: string[]): Promise<CompactChainNote>;
+declare function chainNoteToBase64(noteBytes: Uint8Array): string;
+declare function chainNoteFromBase64(base64: string): Uint8Array;
+
+/**
+ * Transaction Scanner
+ *
+ * Scans on-chain transactions for the Cloak shield pool program,
+ * extracts chain note envelopes from instruction data, and
+ * trial-decrypts them with the caller's viewing key.
+ *
+ * This module is fully autonomous — it talks directly to a Solana
+ * RPC node and does not depend on the relay.
+ */
+
+/** A single decoded & verified transaction record. */
+interface ScannedTransaction {
+    /** Transaction type (deposit / withdraw / transfer / swap) */
+    txType: ChainNoteTxType;
+    /** Absolute amount in lamports (gross — the full amount leaving the pool) */
+    amount: bigint;
+    /** Protocol fee in lamports (non-zero only for withdrawals/swaps) */
+    fee: bigint;
+    /** Net amount received by the recipient (amount - fee). For deposits this equals amount. */
+    netAmount: bigint;
+    /** Millisecond timestamp embedded in the chain note */
+    timestamp: bigint;
+    /** Recipient Solana address (base58) */
+    recipient: string;
+    /** Output commitment hex */
+    commitment: string;
+    /** Solana transaction signature */
+    signature: string;
+    /** Running balance in lamports (computed after sorting) */
+    runningBalance: bigint;
+    /** Input asset mint for this transaction (pool mint) */
+    mint: string;
+    /** Input asset decimals */
+    decimals: number;
+    /** Input asset symbol (best effort) */
+    symbol: string;
+    /** Swap output mint (when txType=swap) */
+    outputMint?: string;
+    /** Swap output symbol (best effort) */
+    outputSymbol?: string;
+}
+/** Summary statistics for a scan result. */
+interface ScanSummary {
+    totalDeposits: bigint;
+    totalWithdrawals: bigint;
+    /** Total protocol fees paid across all withdrawals/swaps */
+    totalFees: bigint;
+    netChange: bigint;
+    transactionCount: number;
+    finalBalance: bigint;
+}
+/** Full result of a scan operation. */
+interface ScanResult {
+    transactions: ScannedTransaction[];
+    summary: ScanSummary;
+    /**
+     * The most recent (newest) signature that was scanned.
+     * Pass this as `untilSignature` in the next scan to only fetch new transactions.
+     */
+    lastSignature?: string;
+    /** Number of RPC getTransaction calls actually made (for diagnostics). */
+    rpcCallsMade: number;
+}
+/** Options for `scanTransactions`. */
+interface ScanOptions {
+    /** Solana RPC connection */
+    connection: Connection;
+    /** Cloak shield pool program ID */
+    programId: PublicKey;
+    /** nk (32 bytes) for diversified chain note decryption (Phase 3) */
+    viewingKeyNk: Uint8Array;
+    /** Maximum number of signatures to scan. Omit or set to 0 for no limit (scan everything). */
+    limit?: number;
+    /** Only include transactions after this timestamp (ms) */
+    afterTimestamp?: number;
+    /** Only include transactions before this timestamp (ms) */
+    beforeTimestamp?: number;
+    /**
+     * Resume scanning from after this signature (exclusive).
+     * Pass the `lastSignature` from a previous scan result to only fetch new transactions.
+     * This is the most impactful optimization — avoids re-scanning the entire history.
+     */
+    untilSignature?: string;
+    /** Progress callback — called once per processed transaction */
+    onProgress?: (processed: number, total: number) => void;
+    /** Batch size for getTransaction calls (default 50) */
+    batchSize?: number;
+    /** Optional status callback for phase updates (signature fetch / tx fetch / done). */
+    onStatus?: (status: string) => void;
+    /** When true, log why each transaction is skipped (for debugging) */
+    debug?: boolean;
+    /**
+     * Wallet public key (base58) for fallback detection of note-less transactions.
+     * When provided, the scanner can detect withdrawals that lack chain notes by
+     * matching the wallet's associated token account against the on-chain recipient ATA.
+     */
+    walletPublicKey?: string;
+}
+/**
+ * Scan on-chain transactions for the Cloak program, extract chain
+ * notes, trial-decrypt with the provided viewing key, verify integrity,
+ * and return a sorted list of the caller's transactions.
+ *
+ * This is fully self-contained — it only needs a Solana RPC connection
+ * and the user's viewing key (private).
+ */
+declare function scanTransactions(opts: ScanOptions): Promise<ScanResult>;
+/** JSON-serializable compliance report (numbers instead of bigint). Used for cache and display. */
+interface ComplianceReport {
+    transactions: Array<{
+        txType: string;
+        amount: number;
+        fee: number;
+        netAmount: number;
+        runningBalance: number;
+        timestamp: number;
+        recipient: string;
+        commitment: string;
+        signature?: string;
+        mint?: string;
+        decimals?: number;
+        symbol?: string;
+        outputMint?: string;
+        outputSymbol?: string;
+    }>;
+    summary: {
+        totalDeposits: number;
+        totalWithdrawals: number;
+        totalFees: number;
+        netChange: number;
+        transactionCount: number;
+        finalBalance: number;
+    };
+    lastSignature?: string;
+    rpcCallsMade: number;
+}
+/** Convert ScanResult to JSON-serializable ComplianceReport. Use for cache and display. */
+declare function toComplianceReport(result: ScanResult): ComplianceReport;
+/** Format compliance report as CSV for export. */
+declare function formatComplianceCsv(report: ComplianceReport): string;
+
+/**
+ * Automatic UTXO Wallet Manager
+ *
+ * Provides ZCash-like automatic UTXO management:
+ * - Tracks all UTXOs locally
+ * - Auto-selects optimal inputs for transactions
+ * - Handles change automatically
+ * - User just sees a simple balance
+ */
+
+/**
+ * Stored UTXO with metadata for wallet management
+ */
+interface WalletUtxo extends Utxo {
+    /** When this UTXO was discovered */
+    discoveredAt: number;
+    /** Merkle tree index (if known) */
+    index?: number;
+    /** Whether this UTXO has been spent */
+    isSpent: boolean;
+    /** When it was spent (if applicable) */
+    spentAt?: number;
+    /** Optional: human-readable label */
+    label?: string;
+}
+/**
+ * Automatic UTXO Wallet
+ *
+ * Manages UTXOs automatically like ZCash:
+ * - You don't pick UTXOs, you just specify amount
+ * - Wallet picks optimal inputs
+ * - Change is handled automatically
+ */
+declare class UtxoWallet {
+    private wallets;
+    private viewingKey?;
+    constructor(viewingKey?: Uint8Array);
+    /**
+     * Add a UTXO to the wallet (discovered from chain or created)
+     */
+    addUtxo(utxo: Utxo, mint?: PublicKey): void;
+    /**
+     * Mark a UTXO as spent
+     */
+    markSpent(utxo: Utxo, mint?: PublicKey): void;
+    /**
+     * Get total balance (unspent only)
+     */
+    getBalance(mint?: PublicKey): bigint;
+    /**
+     * Get all unspent UTXOs
+     */
+    getUnspentUtxos(mint?: PublicKey): WalletUtxo[];
+    /**
+     * Automatically select UTXOs for a transaction
+     *
+     * Strategy:
+     * 1. Try to find exact match (avoid change)
+     * 2. Use largest UTXO first (reduce UTXO count)
+     * 3. Combine smallest UTXOs (consolidation)
+     *
+     * Returns selected inputs and change amount
+     */
+    selectInputs(amount: bigint, mint?: PublicKey, strategy?: "exact" | "largest" | "smallest"): {
+        inputs: Utxo[];
+        change: bigint;
+        total: bigint;
+    };
+    /**
+     * Create a simple "send" transaction
+     *
+     * Just like ZCash: specify amount and recipient, wallet handles the rest
+     */
+    prepareSend(amount: bigint, recipient: PublicKey, mint?: PublicKey, options?: {
+        strategy?: "exact" | "largest" | "smallest";
+    }): Promise<{
+        inputs: Utxo[];
+        outputs: Utxo[];
+        changeAmount: bigint;
+    }>;
+    /**
+     * Create a UTXO for a recipient
+     */
+    private createOutputUtxo;
+    /**
+     * Create change output for self
+     */
+    private createChangeUtxo;
+    /**
+     * Serialize wallet to JSON for storage
+     */
+    serialize(): string;
+    /**
+     * Deserialize wallet from JSON
+     */
+    static deserialize(json: string): UtxoWallet;
+    /**
+     * Get wallet statistics
+     */
+    getStats(mint?: PublicKey): {
+        totalUtxos: number;
+        unspentUtxos: number;
+        spentUtxos: number;
+        totalBalance: bigint;
+    };
+}
+/**
+ * Simple balance-only interface for apps
+ *
+ * Apps can use this instead of dealing with UTXOs directly
+ */
+declare class SimpleWallet {
+    private utxoWallet;
+    constructor(viewingKey?: Uint8Array);
+    /**
+     * Get balance
+     */
+    getBalance(): bigint;
+    /**
+     * Send amount to recipient
+     * Returns transaction parameters ready for transact()
+     */
+    send(amount: bigint, recipient: PublicKey): Promise<{
+        inputs: Utxo[];
+        outputs: Utxo[];
+        change: bigint;
+    }>;
+    /**
+     * Scan and sync UTXOs from chain
+     * (Would be implemented with chain scanning logic)
+     */
+    sync(): Promise<void>;
+}
+
+/**
+ * Cloak SDK - TypeScript SDK for Private Transactions on Solana
+ *
+ * @packageDocumentation
+ */
+
+declare const VERSION = "1.0.0";
+/** True when scanner supports TransactSwap (tag 1). Check this to verify the correct SDK bundle is loaded. */
+declare const SCANNER_SUPPORTS_TRANSACT_SWAP = true;
+
+export { CLOAK_PROGRAM_ID, type ChainNoteTxType, type CircuitVerificationResult, type CloakConfig, CloakError, type CloakKeyPair, type CloakNote, CloakSDK, type CommitmentEntry, type CommitmentsResponse, type CompactChainNote, type ComplianceReport, type ComplianceTxType, DEFAULT_CIRCUITS_URL, DEFAULT_TRANSACTION_CIRCUITS_URL, type DepositInstructionParams, type DepositOptions, type DepositResult, type DepositStatus, EXPECTED_CIRCUIT_HASHES, type EncryptedMetadataBundle, type EncryptedNote$1 as EncryptedNote, type ErrorCategory, type ExpandedSpendKey, FIXED_FEE_LAMPORTS, type Groth16Proof, LAMPORTS_PER_SOL, LocalStorageAdapter, type LogLevel, type Logger, MERKLE_TREE_HEIGHT, MIN_DEPOSIT_LAMPORTS, type MasterKey, type MaxLengthArray, MemoryStorageAdapter, type MerkleProof, type MerkleRootResponse, MerkleTree, NATIVE_SOL_MINT, type Network, type NoteData, type OnchainMerkleProof, type PendingDeposit, type PendingWithdrawal, type ProofResult, RelayService, type RiskQuoteInstructionResponse, RootNotFoundError, SCANNER_SUPPORTS_TRANSACT_SWAP, SIGN_IN_MESSAGE, type ScanOptions, type ScanResult, type ScanSummary, type ScannedTransaction, ShieldPoolErrors, type ShieldPoolPDAs, SimpleWallet, type SpendKey, type StorageAdapter, type SwapOptions, type SwapParams, type SwapResult, type TransactOptions, type TransactParams, type TransactResult, type TransactionMetadata, type Transfer, type TransferOptions, type TransferResult, type TxStatus, type UserFriendlyError, type Utxo, type EncryptedNote as UtxoEncryptedNote, type UtxoKeypair, type UtxoSwapParams, type UtxoSwapResult, UtxoWallet, VARIABLE_FEE_DENOMINATOR, VARIABLE_FEE_NUMERATOR, VARIABLE_FEE_RATE, VERSION, type ViewKey, type ViewingKeyPair, type WalletAdapter, type WalletUtxo, type WithdrawOptions, type WithdrawRegularInputs, type WithdrawSubmissionResult, type WithdrawSwapInputs, areCircuitsAvailable, bigintToBytes32$1 as bigintToBytes32, bigintToHex, buildMerkleTree, buildMerkleTreeFromChain, buildMerkleTreeFromRelay, buildPublicInputsBytes, bytesToHex, calculateFee, calculateFeeBigint, calculateRelayFee, chainNoteFromBase64, chainNoteToBase64, cleanupStalePendingOperations, clearPendingDeposits, clearPendingWithdrawals, computeChainNoteHash, computeCommitment$1 as computeCommitment, computeExtDataHash, computeMerkleRoot, computeNullifier$1 as computeNullifier, computeNullifierAsync, computeNullifierSync, computeOutputsHash, computeOutputsHashAsync, computeOutputsHashSync, computeProofForLatestDeposit, computeProofFromChain, computeSignature, computeSwapOutputsHash, computeSwapOutputsHashAsync, computeSwapOutputsHashSync, computeCommitment as computeUtxoCommitment, computeNullifier as computeUtxoNullifier, copyNoteToClipboard, createCloakError, createDepositInstruction, createLogger, createUtxo, createZeroUtxo, decryptCompactChainNote, decryptComplianceMetadataWithMasterKey, decryptTransactionMetadata, deriveDiversifiedViewingKey, deriveDiversifier, derivePublicKey, deriveSpendKey, deriveUserCompliancePublicKey, deriveUserComplianceScalar, deriveUtxoKeypairFromSpendKey, deriveViewKey, deriveViewingKeyFromNk, deriveViewingKeyFromSpendKey, deriveViewingKeyFromUtxoPrivateKey, deserializeUtxo, detectNetworkFromRpcUrl, downloadNote, encodeNoteSimple, encryptCompactChainNote, encryptNoteForRecipient, encryptTransactionMetadata, encryptTransactionMetadataBundle, expandSpendKey, exportKeys, exportNote, exportWalletKeys, fetchCommitments, fetchRiskQuoteInstruction, fetchRiskQuoteIx, filterNotesByNetwork, filterWithdrawableNotes, findNoteByCommitment, formatAmount, formatComplianceCsv, formatErrorForLogging, formatSol, fullWithdraw, generateCloakKeys, generateCommitment, generateCommitmentAsync, generateMasterSeed, generateNote, generateNoteFromWallet, generateUtxoKeypair, generateViewingKeyPair, generateWithdrawRegularProof, generateWithdrawSwapProof, getAddressExplorerUrl, getCircuitsPath, getDefaultCircuitsPath, getDistributableAmount, getExplorerUrl, getNkFromUtxoPrivateKey, getNullifierPDA, getPendingOperationsSummary, getPublicKey, getPublicViewKey, getRecipientAmount, getRpcUrlForNetwork, getShieldPoolPDAs, getSwapStatePDA, getViewKey, hasPendingOperations, hexToBigint$1 as hexToBigint, hexToBytes, importKeys, importWalletKeys, isDebugEnabled, isRootNotFoundError, isValidHex, isValidRpcUrl, isValidSolanaAddress, isWithdrawAmountSufficient, isWithdrawable, keypairToAdapter, loadPendingDeposits, loadPendingWithdrawals, parseAmount, parseError, parseNote, parseRelayErrorResponse, parseTransactionError, partialWithdraw, poseidonHash, preflightCheck, prepareEncryptedOutput, prepareEncryptedOutputForRecipient, proofToBytes, pubkeyToFieldElement, pubkeyToLimbs, randomBytes, randomFieldElement, readMerkleTreeState, registerViewingKey, removePendingDeposit, removePendingWithdrawal, savePendingDeposit, savePendingWithdrawal, scanNotesForWallet, scanTransactions, sdkLogger, selectUtxos, sendTransaction, serializeNote, serializeUtxo, setCircuitsPath, setDebugMode, signTransaction, splitTo2Limbs, sumUtxoAmounts, swapUtxo, swapWithChange, toComplianceReport, transact, transfer, truncate, tryDecryptNote, updateNoteWithDeposit, updatePendingDeposit, updatePendingWithdrawal, bigintToBytes32 as utxoBigintToBytes32, utxoEquals, hexToBigint as utxoHexToBigint, validateDepositParams, validateNote, validateOutputsSum, validateRoot, validateTransfers, validateWalletConnected, validateWithdrawableNote, verifyAllCircuits, verifyCircuitIntegrity, waitForRoot, withTiming };