@cloak.dev/sdk 0.1.6 → 0.1.8

package/dist/index.d.cts

@@ -1,5 +1,376 @@
 import { PublicKey, Transaction, Connection, AddressLookupTableAccount, TransactionInstruction, Keypair, SendOptions, 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)
  *
@@ -51,343 +422,674 @@ declare function deriveSpendKey(masterSeed: Uint8Array): SpendKey;
 /**
  * Derive view key from spend key
  */
-declare function deriveViewKey(sk_spend: Uint8Array): ViewKey;
+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;
 /**
- * Generate complete key hierarchy from master seed
+ * 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 generateCloakKeys(masterSeed?: Uint8Array): CloakKeyPair;
+declare function parseAmount(sol: string): number;
 /**
- * Encrypt note data for a recipient using their public view key
+ * Validate that outputs sum equals expected amount
  *
- * Uses X25519 ECDH + XSalsa20-Poly1305 authenticated encryption
+ * @param outputs - Array of output amounts
+ * @param expectedTotal - Expected total amount
+ * @returns True if amounts match
  */
-declare function encryptNoteForRecipient(noteData: NoteData, recipientPvk: Uint8Array): EncryptedNote$1;
+declare function validateOutputsSum(outputs: Array<{
+    amount: number;
+}>, expectedTotal: number): boolean;
 /**
- * Attempt to decrypt an encrypted note using view key
+ * Calculate relay fee from basis points
  *
- * Returns null if decryption fails (note doesn't belong to this wallet)
- * Returns NoteData if successful
+ * @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 tryDecryptNote(encryptedNote: EncryptedNote$1, viewKey: ViewKey): NoteData | null;
+declare function calculateRelayFee(amountLamports: number, feeBps: number): number;
+
 /**
- * Scan a batch of encrypted outputs and return notes belonging to this wallet
+ * 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)
  */
-declare function scanNotesForWallet(encryptedOutputs: string[], // Base64 encoded encrypted note JSON
-viewKey: ViewKey): NoteData[];
+
 /**
- * Export keys for backup (WARNING: contains secrets!)
+ * 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 exportKeys(keys: CloakKeyPair): string;
+declare function generateNote(amountLamports: number, network?: Network): Promise<CloakNote>;
 /**
- * Import keys from backup
+ * Generate a note using wallet's spend key (v2.0 recommended)
+ * Uses Poseidon hashing to match circuit implementation
  */
-declare function importKeys(exported: string): CloakKeyPair;
-
+declare function generateNoteFromWallet(amountLamports: number, keys: CloakKeyPair, network?: Network): Promise<CloakNote>;
 /**
- * Supported Solana networks.
+ * Parse and validate a note from JSON string
  */
-type Network = "localnet" | "devnet" | "mainnet" | "testnet";
+declare function parseNote(jsonString: string): CloakNote;
 /**
- * Minimal wallet adapter interface — compatible with `@solana/wallet-adapter-base`.
+ * Export note to JSON string
  */
-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>;
-}
+declare function exportNote(note: CloakNote, pretty?: boolean): string;
 /**
- * Cloak-specific error with categorization.
+ * Check if a note is withdrawable (has been deposited)
+ * Note: merkleProof is optional - it may be fetched lazily at withdrawal time
  */
-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);
-}
+declare function isWithdrawable(note: CloakNote): boolean;
 /**
- * Merkle proof for a leaf in the commitment tree.
+ * Update note with deposit information
+ * Returns a new note object with deposit info added
  */
-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;
-}
+declare function updateNoteWithDeposit(note: CloakNote, depositInfo: {
+    signature: string;
+    slot: number;
+    leafIndex: number;
+    root: string;
+    merkleProof?: {
+        pathElements: string[];
+        pathIndices: number[];
+    };
+}): CloakNote;
 /**
- * Snapshot of the active SDK configuration, returned by `CloakSDK.getConfig()`.
- *
- * This type is intentionally narrower than the constructor input
- * (`CloakSDKOptions` in `core/CloakSDK.ts`): it omits `keypairBytes`,
- * `wallet`, and `storage` because those are consumed into private SDK
- * state (`this.keypair`, `this.wallet`, `this.storage`) at construction
- * time and are never persisted on the config object. The type system
- * therefore enforces the same invariant exercised at runtime by
- * `cloak-sdk.test.ts`.
- *
- * If you're configuring the SDK at construction, use `CloakSDKOptions`.
+ * Find note by commitment from an array
  */
-interface CloakConfig {
-    /** Network the SDK was constructed for. Defaults to `"mainnet"`. */
-    network?: Network;
-    /** Cloak key pair for note scanning / encryption (when provided). */
-    cloakKeys?: CloakKeyPair;
-    /** Resolved program ID (defaults to the mainnet shield-pool). */
-    programId?: PublicKey;
-    /** Pool PDA derived from `programId` + native SOL mint. */
-    poolAddress?: PublicKey;
-    /** Merkle-tree PDA. */
-    merkleTreeAddress?: PublicKey;
-    /** Treasury PDA. */
-    treasuryAddress?: PublicKey;
-    /**
-     * Whether structured debug logging was enabled at construction.
-     *
-     * Can also be enabled via env: `CLOAK_DEBUG=1` or `DEBUG=cloak:*`.
-     */
-    debug?: boolean;
-}
+declare function findNoteByCommitment(notes: CloakNote[], commitment: string): CloakNote | undefined;
 /**
- * Merkle root response from the relay/indexer.
+ * Filter notes by network
  */
-interface MerkleRootResponse {
-    root: string;
-    next_index: number;
-}
+declare function filterNotesByNetwork(notes: CloakNote[], network: Network): CloakNote[];
 /**
- * Transaction status returned by the relay.
+ * Filter notes that can be withdrawn
  */
-interface TxStatus {
-    status: "pending" | "processing" | "completed" | "failed";
-    txId?: string;
-    error?: string;
-}
-
+declare function filterWithdrawableNotes(notes: CloakNote[]): CloakNote[];
 /**
- * Storage Interface
- *
- * Pluggable storage for Cloak wallet keys (master seed / spend / view keys).
- *
- * As of `0.1.6`, note persistence is the consumer's responsibility: the OLD
- * `CloakNote` model was retired (see `CloakSDK` jsdoc), and UTXO persistence
- * in the new flow is owned by callers.
+ * Export keys to JSON string
+ * WARNING: This exports secret keys! Store securely.
  */
-
-interface StorageAdapter {
-    /** Save wallet keys. */
-    saveKeys(keys: CloakKeyPair): Promise<void> | void;
-    /** Load wallet keys (`null` when none stored). */
-    loadKeys(): Promise<CloakKeyPair | null> | CloakKeyPair | null;
-    /** Delete wallet keys. */
-    deleteKeys(): Promise<void> | void;
-}
+declare function exportWalletKeys(keys: CloakKeyPair): string;
 /**
- * In-memory storage adapter (default; no persistence). Useful for tests or
- * when storage is handled externally.
+ * Import keys from JSON string
  */
-declare class MemoryStorageAdapter implements StorageAdapter {
-    private keys;
-    saveKeys(keys: CloakKeyPair): void;
-    loadKeys(): CloakKeyPair | null;
-    deleteKeys(): void;
-}
+declare function importWalletKeys(keysJson: string): CloakKeyPair;
 /**
- * Browser `localStorage` adapter — only safe in browser environments.
- *
- * **Auto-purge on construction:** the first time any `LocalStorageAdapter`
- * is constructed in a given browser, it removes the legacy `cloak_notes`
- * localStorage entry (pre-0.1.6 plaintext `r` + `sk_spend` blob) and writes
- * a sentinel under {@link LEGACY_PURGE_SENTINEL_KEY} so subsequent
- * constructions skip the work. This closes the upgrade-time security gap
- * without requiring every consumer to explicitly call
- * {@link LocalStorageAdapter.purgeLegacyNoteStorage}. Consumers using a
- * non-default legacy key can still call the static helper with their own
- * key name.
+ * Get public view key from keys
  */
-declare class LocalStorageAdapter implements StorageAdapter {
-    private keysKey;
-    constructor(keysKey?: string);
-    private getStorage;
-    saveKeys(keys: CloakKeyPair): void;
-    loadKeys(): CloakKeyPair | null;
-    deleteKeys(): void;
-    /**
-     * Sentinel key set after the auto-purge runs. Persists across browser
-     * sessions so the purge never re-runs on the same origin.
-     */
-    static readonly LEGACY_PURGE_SENTINEL_KEY = "cloak_purged_v0_1_5";
-    /**
-     * Default localStorage key the legacy `<= 0.1.5` SDK used for the
-     * plaintext `CloakNote[]` blob.
-     */
-    static readonly LEGACY_NOTES_KEY = "cloak_notes";
-    /**
-     * Runs the legacy-purge exactly once per browser origin. Invoked
-     * automatically by the constructor; exposed as a static for tests and
-     * for callers who want to force the check before the first adapter
-     * instantiation.
-     */
-    static runLegacyPurgeOnce(): void;
-    /**
-     * Manual cleanup helper for callers that stored notes under a non-default
-     * key. The auto-purge in the constructor only handles the canonical
-     * `cloak_notes` slot; pass the custom key here.
-     *
-     * Pre-0.1.6 versions stored the user's `CloakNote[]` (including
-     * `r` randomness and `sk_spend` secret-key hex) as JSON plaintext.
-     * Those notes are no longer usable (the OLD `withdraw_regular.circom`
-     * flow is incompatible with the deployed UTXO program) but the plaintext
-     * would otherwise linger indefinitely.
-     *
-     * Idempotent; safe to call when the key doesn't exist or when running
-     * outside a browser (no-op). Does NOT update the auto-purge sentinel.
-     *
-     * @param notesKey - localStorage key to remove (default `"cloak_notes"`,
-     *   matching the pre-0.1.6 default).
-     */
-    static purgeLegacyNoteStorage(notesKey?: string): void;
-}
-
-/** Default Cloak Program ID on Solana mainnet. */
-declare const CLOAK_PROGRAM_ID: PublicKey;
+declare function getPublicViewKey(keys: CloakKeyPair): string;
 /**
- * Constructor options for {@link CloakSDK}.
- *
- * Contains *all* the settings a caller can supply at construction time —
- * including the secret-bearing fields (`keypairBytes`, `wallet`, `cloakKeys`).
- * Those secrets are consumed into private SDK state and are NOT persisted on
- * the snapshot returned by {@link CloakSDK.getConfig}; see
- * {@link CloakConfig} for the (narrower) snapshot shape.
+ * Get view key from keys
  */
-interface CloakSDKOptions {
-    /** Keypair bytes for signing (Node.js mode). Consumed into a `Keypair`; not retained. */
-    keypairBytes?: Uint8Array;
-    /** Wallet adapter for signing (browser mode). */
-    wallet?: WalletAdapter;
-    /** Network the SDK targets. Defaults to `"mainnet"`. */
-    network?: Network;
-    /** Cloak key pair for note scanning / encryption. */
-    cloakKeys?: CloakKeyPair;
-    /** Storage adapter for wallet keys (defaults to in-memory). */
-    storage?: StorageAdapter;
-    /** Program ID override (defaults to the mainnet shield-pool). */
-    programId?: PublicKey;
-    /** Relay URL override (defaults to `https://api.cloak.ag`). */
-    relayUrl?: string;
-    /** Enable structured debug logging. Also via env `CLOAK_DEBUG=1` / `DEBUG=cloak:*`. */
-    debug?: boolean;
-}
+declare function getViewKey(keys: CloakKeyPair): ViewKey;
 /**
- * Lightweight Cloak client.
- *
- * Holds program/relay/storage configuration and exposes a small set of
- * read-only chain helpers. **All transaction-emitting methods (deposit,
- * privateTransfer, withdraw, send, swap) were removed in 0.1.6** — they
- * shipped a legacy `[discriminator: 1, amount: u64, commitment: 32]` deposit
- * instruction (`createDepositInstruction`) that the on-chain program no
- * longer understands. Tag `1` is now `TransactSwap`, not `Deposit`, so every
- * call hit `0x1063 MissingAccounts`. The OLD note model
- * (3-input `Poseidon(amount, r0, r1, pk_spend)` for `withdraw_regular.circom`)
- * is also incompatible with the deployed `transaction.circom` UTXO circuit.
- *
- * The supported flow is the functional UTXO API:
- *
- * ```ts
- * import {
- *   transact,
- *   createUtxo,
- *   createZeroUtxo,
- *   generateUtxoKeypair,
- *   CLOAK_PROGRAM_ID,
- *   NATIVE_SOL_MINT,
- * } from "@cloak.dev/sdk";
- *
- * const outputKeypair = await generateUtxoKeypair();
- * const outputUtxo = await createUtxo(amountLamports, outputKeypair);
- * const result = await transact(
- *   {
- *     inputUtxos: [await createZeroUtxo(), await createZeroUtxo()],
- *     outputUtxos: [outputUtxo, await createZeroUtxo()],
- *     externalAmount: amountLamports, // positive = deposit
- *     depositor: payer.publicKey,
- *   },
- *   {
- *     connection,
- *     programId: CLOAK_PROGRAM_ID,
- *     relayUrl: "https://api.cloak.ag",
- *     depositorKeypair: payer,
- *   },
- * );
- * ```
- *
- * See `transfer`, `partialWithdraw`, `fullWithdraw`, `swapUtxo` for the
- * non-deposit flows.
+ * Get recipient amount after fees
  */
-declare class CloakSDK {
-    private config;
-    private keypair?;
-    private wallet?;
-    private cloakKeys?;
-    private relay;
-    private storage;
-    constructor(config: CloakSDKOptions);
-    /** Public key of the configured signer (keypair or wallet). */
-    getPublicKey(): PublicKey;
-    /** True when the SDK was constructed with a wallet adapter (browser). */
-    isWalletMode(): boolean;
-    /**
-     * Compute a Merkle proof for `leafIndex` from on-chain state. No relay /
-     * indexer round-trip required.
-     */
-    getMerkleProof(connection: Connection, leafIndex: number): Promise<MerkleProof>;
-    /** Read the current SOL-pool Merkle root from on-chain state. */
-    getCurrentRoot(connection: Connection): Promise<string>;
-    /** Poll relay for the status of a previously-submitted request. */
-    getTransactionStatus(requestId: string): Promise<TxStatus>;
-    /** Import wallet keys from JSON; persists to the configured storage adapter. */
-    importWalletKeys(keysJson: string): Promise<void>;
-    /**
-     * Export wallet keys to JSON.
-     *
-     * WARNING: this exports secret keys. Store securely.
-     */
-    exportWalletKeys(): string;
-    /**
-     * Snapshot of the active SDK configuration.
-     *
-     * The return type ({@link CloakConfig}) is structurally narrower than the
-     * constructor input ({@link CloakSDKOptions}): `keypairBytes`, `wallet`,
-     * and `storage` are intentionally absent from the snapshot. The secrets
-     * are consumed into private SDK state at construction time and are not
-     * re-exposable through this method — the type system enforces it. To
-     * sign, pass a `Keypair` / `WalletAdapter` directly to the standalone
-     * `transact` / `partialWithdraw` / `fullWithdraw` / `swapUtxo` helpers.
-     */
-    getConfig(): CloakConfig;
-}
-
-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;
-}
+declare function getRecipientAmount(amountLamports: number): number;
 
 interface ViewingKeyPair {
     privateKey: Uint8Array;
@@ -527,20 +1229,151 @@ declare function pubkeyToLimbs(pubkey: Uint8Array | PublicKey | {
     toBytes: () => Uint8Array;
 }): [bigint, bigint];
 /**
- * Compute Merkle root from leaf and path
+ * 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
  *
- * This matches the test implementation
+ * 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)
  *
- * @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
+ * 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 computeMerkleRoot(leaf: bigint, pathElements: bigint[], pathIndices: number[]): Promise<bigint>;
+declare function computeSwapOutputsHashAsync(inputMint: PublicKey, outputMint: PublicKey, recipientAta: PublicKey, minOutputAmount: number, amount: number): Promise<bigint>;
 /**
- * Convert hex string to bigint
+ * Compute swap outputs hash (sync wrapper for backward compatibility)
+ * @deprecated Use computeSwapOutputsHashAsync instead
  */
-declare function hexToBigint$1(hex: string): bigint;
+declare function computeSwapOutputsHashSync(_outputMint: PublicKey, _recipientAta: PublicKey, _minOutputAmount: number, _amount: number): Uint8Array;
 /**
  * Convert bigint to 32-byte big-endian Uint8Array
  */
@@ -603,125 +1436,37 @@ declare function proofToBytes(proof: Groth16Proof): Uint8Array;
 declare function buildPublicInputsBytes(root: bigint, nullifier: bigint, outputsHash: bigint, publicAmount: bigint): Uint8Array;
 
 /**
- * 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
+ * Validate a Solana public key
  *
- * 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
- * ```
+ * @param address - Address string to validate
+ * @returns True if valid Solana address
  */
-declare function getDistributableAmount(amountLamports: number): number;
+declare function isValidSolanaAddress(address: string): boolean;
 /**
- * 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")
+ * Validate a Cloak note structure
  *
- * @example
- * ```typescript
- * formatAmount(1_000_000_000); // "1.000000000"
- * formatAmount(1_500_000_000); // "1.500000000"
- * formatAmount(123_456_789, 4); // "0.1235"
- * ```
+ * @param note - Note object to validate
+ * @throws Error if invalid
  */
-declare function formatAmount(lamports: number, decimals?: number): string;
+declare function validateNote(note: any): asserts note is CloakNote;
 /**
- * Parse SOL string to lamports
- *
- * @param sol - SOL amount as string (e.g., "1.5")
- * @returns Amount in lamports
- * @throws Error if invalid format
+ * Validate that a note is ready for withdrawal
  *
- * @example
- * ```typescript
- * parseAmount("1.5"); // 1_500_000_000
- * parseAmount("0.001"); // 1_000_000
- * ```
+ * @param note - Note to validate
+ * @throws Error if note cannot be used for withdrawal
  */
-declare function parseAmount(sol: string): number;
+declare function validateWithdrawableNote(note: CloakNote): void;
 /**
- * Validate that outputs sum equals expected amount
+ * Validate transfer recipients
  *
- * @param outputs - Array of output amounts
- * @param expectedTotal - Expected total amount
- * @returns True if amounts match
+ * @param recipients - Array of transfers to validate
+ * @param totalAmount - Total amount available
+ * @throws Error if invalid
  */
-declare function validateOutputsSum(outputs: Array<{
+declare function validateTransfers(recipients: Array<{
+    recipient: PublicKey;
     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;
-
-/**
- * Validate that a string is a valid Solana public key.
- *
- * @param address - Address string to validate
- * @returns True if valid Solana address
- */
-declare function isValidSolanaAddress(address: string): boolean;
+}>, totalAmount: number): void;
 
 /**
  * Network Utilities
@@ -1604,6 +2349,36 @@ declare function fetchRiskQuoteIx(connection: Connection, wallet: PublicKey, ran
     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
  *
@@ -1631,6 +2406,58 @@ declare function signTransaction<T extends Transaction>(transaction: T, wallet:
  */
 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
  *
@@ -1851,6 +2678,263 @@ declare function preflightCheck(relayUrl: string, rootHex: string): Promise<{
     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://storage.googleapis.com/cloak-circuits/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://storage.googleapis.com/cloak-circuits/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 Transaction Methods
  *
@@ -1860,7 +2944,7 @@ declare function preflightCheck(relayUrl: string, rootHex: string): Promise<{
  * - partialWithdraw(): Withdraw with change
  */
 
-declare const DEFAULT_TRANSACTION_CIRCUITS_URL = "https://cloak-circuits.s3.us-east-1.amazonaws.com/circuits/0.1.0";
+declare const DEFAULT_TRANSACTION_CIRCUITS_URL = "https://storage.googleapis.com/cloak-circuits/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).
@@ -2474,25 +3558,10 @@ declare class SimpleWallet {
  * Cloak SDK - TypeScript SDK for Private Transactions on Solana
  *
  * @packageDocumentation
- *
- * # 0.1.6 — breaking changes
- *
- * The legacy `CloakNote` API (`CloakSDK.deposit/privateTransfer/withdraw/
- * send/swap`, `createDepositInstruction`, `generateNote`, `withdraw_regular`
- * proofs, etc.) was removed because every code path eventually emitted a
- * legacy `[discriminator: 1, amount: u64, commitment: 32]` instruction that
- * the deployed shield-pool program no longer accepts (tag `1` is now
- * `TransactSwap`, not `Deposit`). The OLD 3-input commitment scheme is
- * also incompatible with the deployed `transaction.circom` UTXO circuit.
- *
- * Use the functional UTXO API instead — `transact`, `transfer`,
- * `partialWithdraw`, `fullWithdraw`, `swapUtxo`, `createUtxo`,
- * `createZeroUtxo`, `generateUtxoKeypair`. The `CloakSDK` class is kept as
- * a thin config + read-only chain helper.
  */
 
-declare const VERSION = "0.1.6";
-/** True when scanner supports TransactSwap (tag 1). */
+declare const VERSION = "0.1.5";
+/** 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 CloakConfig, CloakError, type CloakKeyPair, CloakSDK, type CloakSDKOptions, type CommitmentEntry, type CommitmentsResponse, type CompactChainNote, type ComplianceReport, type ComplianceTxType, DEFAULT_TRANSACTION_CIRCUITS_URL, 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, MemoryStorageAdapter, type MerkleProof, type MerkleRootResponse, MerkleTree, NATIVE_SOL_MINT, type Network, type NoteData, type OnchainMerkleProof, RelayInternalError, RelayService, type RiskQuoteInstructionResponse, RootNotFoundError, SCANNER_SUPPORTS_TRANSACT_SWAP, SIGN_IN_MESSAGE, SanctionsQuoteError, type ScanOptions, type ScanResult, type ScanSummary, type ScannedTransaction, ShieldPoolErrors, type ShieldPoolPDAs, SimpleWallet, type SpendKey, type StorageAdapter, type TransactOptions, type TransactParams, type TransactResult, type TransactionMetadata, type TxStatus, type UserFriendlyError, type Utxo, UtxoAlreadySpentError, type EncryptedNote as UtxoEncryptedNote, type UtxoKeypair, type UtxoSwapParams, type UtxoSwapResult, UtxoWallet, VARIABLE_FEE_DENOMINATOR, VARIABLE_FEE_NUMERATOR, VARIABLE_FEE_RATE, VERSION, type VerifyUtxosResult, type ViewKey, type ViewingKeyPair, type WalletAdapter, type WalletUtxo, type WithdrawSubmissionResult, bigintToBytes32$1 as bigintToBytes32, bigintToHex, buildMerkleTree, buildMerkleTreeFromChain, buildMerkleTreeFromRelay, buildPublicInputsBytes, bytesToHex, calculateFee, calculateFeeBigint, calculateRelayFee, chainNoteFromBase64, chainNoteToBase64, classifyRelayError, computeChainNoteHash, computeExtDataHash, computeMerkleRoot, computeProofForLatestDeposit, computeProofFromChain, computeSignature, computeCommitment as computeUtxoCommitment, computeNullifier as computeUtxoNullifier, createCloakError, createLogger, createUtxo, createZeroUtxo, decryptCompactChainNote, decryptComplianceMetadataWithMasterKey, decryptTransactionMetadata, deriveDiversifiedViewingKey, deriveDiversifier, derivePublicKey, deriveSpendKey, deriveUserCompliancePublicKey, deriveUserComplianceScalar, deriveUtxoKeypairFromSpendKey, deriveViewKey, deriveViewingKeyFromNk, deriveViewingKeyFromSpendKey, deriveViewingKeyFromUtxoPrivateKey, deserializeUtxo, detectNetworkFromRpcUrl, encryptCompactChainNote, encryptNoteForRecipient, encryptTransactionMetadata, encryptTransactionMetadataBundle, expandSpendKey, exportKeys, fetchCommitments, fetchRiskQuoteInstruction, fetchRiskQuoteIx, formatAmount, formatComplianceCsv, formatErrorForLogging, formatSol, fullWithdraw, generateCloakKeys, generateMasterSeed, generateUtxoKeypair, generateViewingKeyPair, getAddressExplorerUrl, getCircuitsPath, getDistributableAmount, getExplorerUrl, getNkFromUtxoPrivateKey, getNullifierPDA, getPublicKey, getRpcUrlForNetwork, getShieldPoolPDAs, getSwapStatePDA, hexToBigint$1 as hexToBigint, hexToBytes, importKeys, isDebugEnabled, isRootNotFoundError, isValidHex, isValidRpcUrl, isValidSolanaAddress, isWithdrawAmountSufficient, keypairToAdapter, parseAmount, parseError, parseRelayErrorResponse, parseTransactionError, partialWithdraw, poseidonHash, preflightCheck, preflightNullifiers, proofToBytes, pubkeyToFieldElement, pubkeyToLimbs, randomBytes, randomFieldElement, readMerkleTreeState, registerViewingKey, scanNotesForWallet, scanTransactions, sdkLogger, selectUtxos, sendTransaction, serializeUtxo, setCircuitsPath, setDebugMode, signTransaction, splitTo2Limbs, sumUtxoAmounts, swapUtxo, swapWithChange, toComplianceReport, transact, transfer, truncate, tryDecryptNote, bigintToBytes32 as utxoBigintToBytes32, utxoEquals, hexToBigint as utxoHexToBigint, validateOutputsSum, validateRoot, validateWalletConnected, verifyUtxos, waitForRoot, withTiming };
+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, RelayInternalError, RelayService, type RiskQuoteInstructionResponse, RootNotFoundError, SCANNER_SUPPORTS_TRANSACT_SWAP, SIGN_IN_MESSAGE, SanctionsQuoteError, 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, UtxoAlreadySpentError, type EncryptedNote as UtxoEncryptedNote, type UtxoKeypair, type UtxoSwapParams, type UtxoSwapResult, UtxoWallet, VARIABLE_FEE_DENOMINATOR, VARIABLE_FEE_NUMERATOR, VARIABLE_FEE_RATE, VERSION, type VerifyUtxosResult, 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, classifyRelayError, 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, preflightNullifiers, 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, verifyUtxos, waitForRoot, withTiming };