@cloak.dev/sdk 0.1.7 → 0.2.0

package/dist/index.d.ts

@@ -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)
  *
@@ -84,310 +455,641 @@ declare function exportKeys(keys: CloakKeyPair): string;
 declare function importKeys(exported: string): CloakKeyPair;
 
 /**
- * Supported Solana networks.
+ * Storage Interface
+ *
+ * Defines a pluggable storage interface for notes and keys.
+ * Applications can implement their own storage (localStorage, IndexedDB, file system, etc.)
  */
-type Network = "localnet" | "devnet" | "mainnet" | "testnet";
+
 /**
- * Minimal wallet adapter interface — compatible with `@solana/wallet-adapter-base`.
+ * 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 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>;
+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;
 /**
- * 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;
@@ -542,186 +1244,246 @@ declare function computeMerkleRoot(leaf: bigint, pathElements: bigint[], pathInd
  */
 declare function hexToBigint$1(hex: string): bigint;
 /**
- * Convert bigint to 32-byte big-endian Uint8Array
+ * 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 bigintToBytes32$1(n: bigint): Uint8Array;
+declare function computeCommitment$1(amount: bigint, r: bigint, sk_spend: bigint): Promise<bigint>;
 /**
- * Convert hex string to Uint8Array
+ * Generate a Poseidon commitment for a note
  *
- * @param hex - Hex string (with or without 0x prefix)
- * @returns Decoded bytes
+ * 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 hexToBytes(hex: string): Uint8Array;
+declare function generateCommitmentAsync(amountLamports: number, r: Uint8Array, skSpend: Uint8Array): Promise<bigint>;
 /**
- * Convert Uint8Array to hex string
+ * Generate a Poseidon commitment for a note (sync wrapper)
+ * Returns bytes instead of bigint for backward compatibility
  *
- * @param bytes - Bytes to encode
- * @param prefix - Whether to include 0x prefix (default: false)
- * @returns Hex-encoded string
+ * @deprecated Use generateCommitmentAsync instead
  */
-declare function bytesToHex(bytes: Uint8Array, prefix?: boolean): string;
+declare function generateCommitment(_amountLamports: number, _r: Uint8Array, _skSpend: Uint8Array): Uint8Array;
 /**
- * Generate random bytes using Web Crypto API
+ * Compute nullifier = Poseidon(sk0, sk1, leaf_index)
+ * (matching withdraw_regular.circom)
  *
- * @param length - Number of bytes to generate
- * @returns Random bytes
+ * 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 randomBytes(length: number): Uint8Array;
+declare function computeNullifier$1(sk_spend: bigint, leafIndex: bigint): Promise<bigint>;
 /**
- * Validate a hex string format
+ * Compute nullifier from spending key and leaf index
  *
- * @param hex - Hex string to validate
- * @param expectedLength - Expected length in bytes (optional)
- * @returns True if valid hex string
+ * 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 isValidHex(hex: string, expectedLength?: number): boolean;
+declare function computeNullifierAsync(skSpend: Uint8Array | string, leafIndex: number): Promise<bigint>;
 /**
- * Groth16 proof structure from snarkjs
+ * Compute nullifier (sync wrapper for backward compatibility)
+ * @deprecated Use computeNullifierAsync instead
  */
-interface Groth16Proof {
-    pi_a: string[];
-    pi_b: string[][];
-    pi_c: string[];
-    protocol: string;
-    curve: string;
-}
+declare function computeNullifierSync(_skSpend: Uint8Array, _leafIndex: number): Uint8Array;
 /**
- * Convert snarkjs Groth16 proof to 256-byte format for Solana (pinocchio-groth16 format)
+ * Compute outputs hash from recipients and amounts
  *
- * 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)
+ * Formula: Chain of Poseidon(prev_hash, addr_lo, addr_hi, amount) for each active output
  *
- * Format: pi_a (64) + pi_b (128) + pi_c (64) = 256 bytes
+ * 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 proofToBytes(proof: Groth16Proof): Uint8Array;
+declare function computeOutputsHashAsync(outputs: Array<{
+    recipient: PublicKey;
+    amount: number;
+}>): Promise<bigint>;
 /**
- * Build public inputs bytes for on-chain verification
- * Format: root (32) + nullifier (32) + outputs_hash (32) + public_amount (8) = 104 bytes
+ * 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 buildPublicInputsBytes(root: bigint, nullifier: bigint, outputsHash: bigint, publicAmount: bigint): Uint8Array;
-
+declare function computeOutputsHash(outAddr: bigint[][], outAmount: bigint[], outFlags: number[]): Promise<bigint>;
 /**
- * Fee calculation utilities for Cloak Protocol
+ * 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)
  *
- * The protocol charges a fixed fee plus a variable percentage fee
- * to prevent sybil attacks and cover operational costs.
+ * This is the test-style function that takes raw limbs
  *
- * 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.
+ * @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
  */
-/** 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;
+declare function computeSwapOutputsHash(inputMintLimbs: [bigint, bigint], outputMintLimbs: [bigint, bigint], recipientAtaLimbs: [bigint, bigint], minOutputAmount: bigint, publicAmount: bigint): Promise<bigint>;
 /**
- * Calculate the total protocol fee for a given amount
+ * Compute outputs hash for swap transactions
  *
- * Formula: FIXED_FEE + floor((amount * VARIABLE_FEE_NUMERATOR) / VARIABLE_FEE_DENOMINATOR)
+ * 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 amountLamports - Amount in lamports
- * @returns Total fee in lamports
+ * This matches the withdraw_swap.circom circuit
  *
- * @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
- * ```
+ * @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 calculateFee(amountLamports: number): number;
+declare function computeSwapOutputsHashAsync(inputMint: PublicKey, outputMint: PublicKey, recipientAta: PublicKey, minOutputAmount: number, amount: number): Promise<bigint>;
 /**
- * Bigint version of calculateFee (for UTXO flows that use bigint lamports).
+ * Compute swap outputs hash (sync wrapper for backward compatibility)
+ * @deprecated Use computeSwapOutputsHashAsync instead
  */
-declare function calculateFeeBigint(amountLamports: bigint): bigint;
+declare function computeSwapOutputsHashSync(_outputMint: PublicKey, _recipientAta: PublicKey, _minOutputAmount: number, _amount: number): Uint8Array;
 /**
- * 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.)
+ * Convert bigint to 32-byte big-endian Uint8Array
  */
-declare function isWithdrawAmountSufficient(amountLamports: bigint): boolean;
+declare function bigintToBytes32$1(n: bigint): Uint8Array;
 /**
- * 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
+ * Convert hex string to Uint8Array
  *
- * @example
- * ```typescript
- * const distributable = getDistributableAmount(1_000_000_000);
- * // Returns: 1_000_000_000 - 7_500_000 = 992_500_000 lamports
- * ```
+ * @param hex - Hex string (with or without 0x prefix)
+ * @returns Decoded bytes
  */
-declare function getDistributableAmount(amountLamports: number): number;
+declare function hexToBytes(hex: string): Uint8Array;
 /**
- * Format lamports as SOL string
+ * Convert Uint8Array to hex string
  *
- * @param lamports - Amount in lamports
- * @param decimals - Number of decimal places (default: 9)
- * @returns Formatted string (e.g., "1.000000000")
+ * @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;
+/**
+ * Thrown when no cryptographically secure randomness source is reachable.
  *
- * @example
- * ```typescript
- * formatAmount(1_000_000_000); // "1.000000000"
- * formatAmount(1_500_000_000); // "1.500000000"
- * formatAmount(123_456_789, 4); // "0.1235"
- * ```
+ * `randomBytes` backs note spend keys, blindings, salts and nonces. A predictable
+ * value there is unrecoverable — it deanonymizes and can drain the note — so the
+ * SDK fails closed instead of degrading to a non-cryptographic generator.
  */
-declare function formatAmount(lamports: number, decimals?: number): string;
+declare class InsecureRandomnessError extends CloakError {
+    constructor(message: string, originalError?: Error);
+}
 /**
- * Parse SOL string to lamports
+ * Generate cryptographically secure random bytes.
  *
- * @param sol - SOL amount as string (e.g., "1.5")
- * @returns Amount in lamports
- * @throws Error if invalid format
+ * Source order: `globalThis.crypto.getRandomValues` first (works in every runtime
+ * this SDK supports, under both ESM and CJS), then `node:crypto.randomFillSync`.
+ * There is deliberately **no** insecure fallback: if neither source is usable this
+ * throws {@link InsecureRandomnessError} naming every source that was tried and why
+ * it failed.
  *
- * @example
- * ```typescript
- * parseAmount("1.5"); // 1_500_000_000
- * parseAmount("0.001"); // 1_000_000
- * ```
+ * @param length - Number of bytes to generate
+ * @returns Random bytes
+ * @throws {InsecureRandomnessError} If no cryptographically secure source is available
  */
-declare function parseAmount(sol: string): number;
+declare function randomBytes(length: number): Uint8Array;
 /**
- * Validate that outputs sum equals expected amount
+ * Validate a hex string format
  *
- * @param outputs - Array of output amounts
- * @param expectedTotal - Expected total amount
- * @returns True if amounts match
+ * @param hex - Hex string to validate
+ * @param expectedLength - Expected length in bytes (optional)
+ * @returns True if valid hex string
  */
-declare function validateOutputsSum(outputs: Array<{
-    amount: number;
-}>, expectedTotal: number): boolean;
+declare function isValidHex(hex: string, expectedLength?: number): boolean;
 /**
- * Calculate relay fee from basis points
+ * 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)
  *
- * @param amountLamports - Amount in lamports
- * @param feeBps - Fee in basis points (100 bps = 1%)
- * @returns Relay fee in lamports
+ * 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)
  *
- * @example
- * ```typescript
- * calculateRelayFee(1_000_000_000, 50); // 0.5% = 5_000_000 lamports
- * ```
+ * Format: pi_a (64) + pi_b (128) + pi_c (64) = 256 bytes
  */
-declare function calculateRelayFee(amountLamports: number, feeBps: number): number;
+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 that a string is a valid Solana public key.
+ * 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
@@ -927,6 +1689,67 @@ declare class RelayInternalError extends Error {
      */
     cachedTreeFromChain?: MerkleTree | undefined);
 }
+/**
+ * Raised when a submission's outcome could NOT be established as "landed" from chain state.
+ *
+ * This is the failure side of settlement verification (see `core/settlement.ts`). It exists
+ * because the campaign's worst outcome was not a failed transaction — it was an AMBIGUOUS one
+ * whose error text carried no signature (REL-A-10: seven POSTs, the transaction landed, the SDK
+ * threw `RelayInternalError`, and the user had nothing to look up). Losing the signature is what
+ * turns a landed transaction into a support ticket.
+ *
+ * `outcome` is deliberately unambiguous for the caller:
+ *
+ *   "landed"      the transaction DID land — the input nullifier PDAs exist — but the relay never
+ *                 returned a usable response, so the SDK cannot hand back commitment indices.
+ *                 DO NOT RETRY: a retry spends nothing and fails 0x1020. Rescan to recover notes.
+ *   "not-landed"  provably nothing landed. The inputs are unspent; retrying is safe.
+ *   "unknown"     the evidence is contradictory or unavailable. Check `signature` on an
+ *                 independent RPC before doing anything else.
+ *   "failed"      the transaction is on chain and failed during execution. Inputs are unspent.
+ */
+declare class SettlementVerificationError extends Error {
+    /** What the chain evidence supports. See the class doc — each value implies a different action. */
+    readonly outcome: "landed" | "not-landed" | "unknown" | "failed";
+    /**
+     * The signature to look up, when one is known. `null` means no counterparty ever gave the SDK
+     * one — which is itself part of the report, not something to paper over.
+     */
+    readonly signature: string | null;
+    /** The verifier's own statement of what was and was not proven. */
+    readonly reason: string;
+    /** True when the input nullifier PDAs were observed on chain. */
+    readonly nullifiersSpent: boolean;
+    /** The underlying relay/RPC error, when the failure started as one. */
+    readonly cause?: unknown | undefined;
+    constructor(message: string, 
+    /** What the chain evidence supports. See the class doc — each value implies a different action. */
+    outcome: "landed" | "not-landed" | "unknown" | "failed", 
+    /**
+     * The signature to look up, when one is known. `null` means no counterparty ever gave the SDK
+     * one — which is itself part of the report, not something to paper over.
+     */
+    signature: string | null, 
+    /** The verifier's own statement of what was and was not proven. */
+    reason: string, 
+    /** True when the input nullifier PDAs were observed on chain. */
+    nullifiersSpent?: boolean, 
+    /** The underlying relay/RPC error, when the failure started as one. */
+    cause?: unknown | undefined);
+    /** True when retrying this exact spend is safe (nothing was consumed on chain). */
+    get safeToRetry(): boolean;
+}
+/**
+ * Pull the signature out of a relay error body.
+ *
+ * The relay's `SubmissionOutcomeUnknown` response is a 503 whose JSON carries
+ * `{"code":"submission_outcome_unknown","retryable":true,"signature":"<sig>"}` (relay
+ * `src/error.rs`). The SDK used to funnel that body into a generic retry and then throw an error
+ * built from a LATER attempt's message, dropping the one field the user needs.
+ */
+declare function parseRelayErrorSignature(responseText: string): string | null;
+/** True when a relay error body is the relay's own "I do not know if this landed" report. */
+declare function isSubmissionOutcomeUnknownResponse(responseText: string): boolean;
 /**
  * Classify a relay error (response body text + HTTP status) into one of the
  * structured error types above, or fall back to RelayInternalError.
@@ -1307,6 +2130,141 @@ declare function verifyUtxos(utxos: Utxo[], connection: Connection, programId: P
  */
 declare function preflightNullifiers(utxos: Utxo[], connection: Connection, programId: PublicKey, commitment?: "processed" | "confirmed" | "finalized"): Promise<void>;
 
+/**
+ * Settlement verification — decide from CHAIN STATE whether a submission landed.
+ *
+ * Why this module exists (adversarial campaign, tier 2):
+ *
+ *   X-S-01B  A hostile relay answered `/transact` with a well-formed success body carrying a
+ *            phantom signature and commitment indices [4242, 4243]. The SDK returned SUCCESS.
+ *            Real-RPC `getSignatureStatuses(searchTransactionHistory)` -> null, and BOTH input
+ *            nullifier PDAs read `exists=false`. Nothing had landed.
+ *   X-S-03a  A hostile RPC swallowed `sendTransaction` and fabricated
+ *            `{err: null, confirmationStatus: "finalized"}`. `confirmTransaction` was satisfied and
+ *            the SDK returned a signature for a transaction that was never forwarded. (A control
+ *            deposit landed honestly through the same proxy, so account reads were NOT tampered
+ *            with — only the submission and its status were.)
+ *
+ * Both defects have the same shape: the SDK reported success on the strength of what its
+ * counterparty SAID, never on the strength of what the chain SHOWS.
+ *
+ * The ground truth used here is the one the campaign itself used to prove nothing landed: the
+ * input NULLIFIER PDAs. Their addresses are derived locally from the proof's own public inputs
+ * (`["nullifier", pool, nullifier]`), and the program creates one per non-zero input nullifier on
+ * every landed transact — including deposits, whose padding slots still emit real nullifiers
+ * (transaction.circom: "the slot still emits a real nullifier ... and consumed on-chain";
+ * shield-pool/src/instructions/transact.rs skips only all-zero nullifiers).
+ *
+ * Nullifier presence is strictly stronger evidence than a signature status:
+ *
+ *   - it is ACCOUNT STATE, so it survives an RPC that has no signature history for the slot
+ *     (Surfpool forks, pruned nodes, a load-balanced endpoint that missed the write); and
+ *   - the nullifier and the output commitments are fields of the SAME proof's public inputs, so
+ *     the only transaction that can create these PDAs is one that also appended exactly our
+ *     output commitments. "Nullifiers exist" therefore means "our outputs are in the tree".
+ *
+ * The signature status is still checked, because it is the only signal that can prove a
+ * DEFINITIVE FAILURE (`err != null`) and because a signature the RPC has never heard of is the
+ * fingerprint of a phantom. It is corroboration, never the sole basis for success.
+ *
+ * LIMIT, stated plainly: a single RPC endpoint that lies about ACCOUNT READS as well cannot be
+ * caught by any single-endpoint client, and this module does not pretend to. It closes the two
+ * observed attacks — a lying relay, and an RPC that lies only about submission/status — and it
+ * downgrades every unproven outcome to an explicit, signature-carrying "unknown" instead of
+ * silently reporting success.
+ */
+
+/**
+ * The RPC surface settlement verification needs, as a structural type rather than a hard
+ * dependency on `Connection`. A real `web3.js` Connection satisfies it; so does a test stub, which
+ * is what lets the phantom-relay / lying-RPC regressions be reproduced without a validator.
+ */
+interface SettlementConnection {
+    getSignatureStatuses(signatures: string[], config?: {
+        searchTransactionHistory?: boolean;
+    }): Promise<{
+        value: Array<{
+            err: unknown | null;
+            confirmationStatus?: string | null;
+        } | null>;
+    }>;
+    getMultipleAccountsInfo(publicKeys: PublicKey[], commitmentOrConfig?: any): Promise<Array<unknown | null>>;
+}
+/**
+ * What the chain says about a submission.
+ *
+ *  - `landed`      the input nullifier PDAs exist: the proof was consumed, so its output
+ *                  commitments are in the tree. This is the ONLY status that may be reported as
+ *                  success.
+ *  - `failed`      the signature is on chain and carries an execution error. Nothing was applied;
+ *                  the inputs are still spendable.
+ *  - `not-landed`  no nullifier PDA exists and the signature (if any) is unknown to the RPC even
+ *                  with `searchTransactionHistory`. The phantom-signature fingerprint.
+ *  - `unknown`     the evidence is contradictory or incomplete — most importantly the case where
+ *                  a status claims confirmation while no nullifier PDA exists. NEVER report this
+ *                  as success and NEVER silently retry it: the caller must surface the signature.
+ */
+type SettlementStatus = "landed" | "failed" | "not-landed" | "unknown";
+interface SettlementVerdict {
+    status: SettlementStatus;
+    /** The signature that was checked, when one was supplied and syntactically usable. */
+    signature: string | null;
+    /** Human-readable statement of what was and was not proven. Safe to put in an error message. */
+    reason: string;
+    /** True when every checkable input nullifier PDA was present on chain. */
+    nullifiersSpent: boolean;
+    /** What `getSignatureStatuses` reported for `signature`. */
+    signatureStatus: "finalized" | "confirmed" | "processed" | "absent" | "error" | "unchecked";
+}
+interface ConfirmSettlementParams {
+    connection: SettlementConnection;
+    programId: PublicKey;
+    mint: PublicKey;
+    /** The proof's public input nullifiers. All-zero entries are padding and are skipped. */
+    inputNullifiers: bigint[];
+    /** The signature the counterparty reported, if it reported one. */
+    signature?: string | null;
+    /** Total time to wait for evidence to appear before giving a verdict. */
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    onProgress?: (status: string) => void;
+}
+declare function isPlausibleSignature(value: string | null | undefined): value is string;
+/**
+ * Derive the nullifier PDA for each non-zero input nullifier. Zero entries are the program's own
+ * padding sentinel (`transact.rs`: "Skip zero nullifiers (padding inputs)") and create no account.
+ */
+declare function deriveInputNullifierPdas(programId: PublicKey, mint: PublicKey, inputNullifiers: bigint[]): PublicKey[];
+/**
+ * Establish, from chain state, whether a submission landed.
+ *
+ * Polls until either side of the question is answered or `timeoutMs` elapses. Every RPC error is
+ * absorbed into the verdict rather than thrown: "I could not check" is `unknown`, which the caller
+ * must surface — it is never success.
+ */
+declare function confirmTransactSettlement(params: ConfirmSettlementParams): Promise<SettlementVerdict>;
+/**
+ * Gate a DIRECT (self-signed) submission on chain state — X-S-03a.
+ *
+ * `connection.confirmTransaction` is not proof of anything: the campaign's proxy swallowed
+ * `sendTransaction` and answered the follow-up status poll with a fabricated
+ * `{err: null, confirmationStatus: "finalized"}`, and the SDK handed the caller a signature for a
+ * transaction that was never forwarded. A control deposit landed honestly through the same proxy,
+ * so this was not broken plumbing — it was the client believing a status field.
+ *
+ * Throws `SettlementVerificationError` unless the input nullifier PDAs prove the transaction was
+ * applied. The signature is always carried on the error so the caller can look it up.
+ */
+declare function assertDirectSubmissionLanded(params: {
+    connection: SettlementConnection;
+    programId: PublicKey;
+    mint: PublicKey;
+    nullifiers: Array<Uint8Array | bigint>;
+    signature: string;
+    timeoutMs?: number;
+    onProgress?: (status: string) => void;
+}): Promise<SettlementVerdict>;
+
 /**
  * Structured Logger for Cloak SDK
  *
@@ -1604,6 +2562,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 +2619,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
  *
@@ -1683,6 +2723,111 @@ declare function getNullifierPDA(poolPubkey: PublicKey, nullifier: Uint8Array |
  * @returns [PublicKey, bump] - The swap state PDA and its bump seed
  */
 declare function getSwapStatePDA(poolPubkey: PublicKey, nullifier: Uint8Array | Buffer, programId?: PublicKey): [PublicKey, number];
+/**
+ * H-04: derive the per-pool RefundLedger PDA (conservation counter).
+ *
+ * Seeds: ["refund_ledger", pool_mint]
+ */
+declare function getRefundLedgerPDA(mint?: PublicKey, programId?: PublicKey): [PublicKey, number];
+/**
+ * H-04: derive the one-time RefundClaim PDA (replay guard for a voucher).
+ *
+ * Seeds: ["refund_claim", claim_id]
+ */
+declare function getRefundClaimPDA(claimId: Uint8Array | Buffer, programId?: PublicKey): [PublicKey, number];
+/**
+ * M-07/H-04: derive the per-pool PoolAuthorityConfig PDA (holds the
+ * withdraw-authorizer the refund voucher must be signed by).
+ *
+ * Seeds: ["pool_authority", pool_mint]
+ */
+declare function getPoolAuthorityConfigPDA(mint?: PublicKey, programId?: PublicKey): [PublicKey, number];
+/**
+ * Registry PDA the relay's recipient-delivery carrier (CLKD1) touches so the carrier transaction is
+ * enumerable via `getSignaturesForAddress`.
+ *
+ * Seed: ["cloak_delivery_registry"] — `DELIVERY_REGISTRY_SEED` in
+ * `services/relay/src/solana/mod.rs::emit_recipient_delivery_carrier`. Mint-independent, exactly
+ * like the chain-note registry: one registry per program, not per pool.
+ */
+declare function getDeliveryRegistryPDA(programId?: PublicKey): PublicKey;
+/**
+ * Registry PDA the relay's compliance chain-note carrier (CLK1) touches.
+ *
+ * Seed: ["cloak_chain_note_registry"] — `CHAIN_NOTE_REGISTRY_SEED` in
+ * `services/relay/src/solana/mod.rs::emit_chain_note_carrier`.
+ */
+declare function getChainNoteRegistryPDA(programId?: PublicKey): PublicKey;
+
+/**
+ * H-04 — claim-based timeout refund (SDK).
+ *
+ * When a private swap times out, `CloseSwapState` returns the parked principal
+ * to the pool and credits the on-chain `RefundLedger`. The user later reclaims
+ * that principal as a FRESH shielded note via `ClaimRefund`, gated by a
+ * withdraw-authorizer voucher (signed by the relay) and a deposit-shape Groth16
+ * proof — with no on-chain link back to the original swap.
+ *
+ * This module:
+ *   1. asks the relay to sign the 81-byte refund voucher for `claim_id`,
+ *   2. generates a deposit-shape proof (publicAmount = +refund_amount, zero
+ *      inputs, one fresh output note `C_r`) bound to the live merkle root,
+ *   3. builds and submits the `[ed25519 voucher][CU][ClaimRefund]` transaction,
+ *   4. returns the fresh refund UTXO for the caller to store/spend later.
+ *
+ * The proof construction is byte-for-byte the same as the standalone
+ * `audit-tests/h-04/gen-claim-proof.cjs` generator that the program-side soak
+ * verified, so the proof verifies against the deployed transaction vkey.
+ */
+
+/** A relay-signed refund voucher, as returned by `POST /refund-voucher`. */
+interface RefundVoucher {
+    /** base64 Ed25519 signature over the 81-byte message. */
+    signature: string;
+    /** hex 81-byte voucher message. */
+    message: string;
+    /** base58 signer (pool withdraw-authorizer). */
+    signer_pubkey: string;
+    /** expiry slot bound into the voucher. */
+    expiry_slot?: number;
+}
+interface ClaimTimeoutRefundParams {
+    /** Refund principal in lamports (must equal the closed swap's parked amount). */
+    refundAmount: bigint;
+    /** Pool mint; ClaimRefund is SOL-pool only (defaults to WSOL sentinel). */
+    poolMint?: PublicKey;
+    /** 32-byte claim id = H(user secret). Random if omitted. */
+    claimId?: Uint8Array;
+    /** Supply a pre-fetched voucher to skip the relay round-trip. */
+    voucher?: RefundVoucher;
+}
+interface ClaimTimeoutRefundOptions {
+    connection: Connection;
+    programId: PublicKey;
+    /** Relay base URL (used to fetch the voucher when not supplied). */
+    relayUrl?: string;
+    /** Pays fees + signs the claim tx (relay-submitted is a documented follow-up). */
+    payerKeypair: Keypair;
+    onProgress?: (message: string) => void;
+}
+interface ClaimTimeoutRefundResult {
+    /** Submitted ClaimRefund transaction signature. */
+    signature: string;
+    /** The fresh refund note created by the claim — store this to spend later. */
+    refundUtxo: Utxo;
+    /** The claim id consumed (hex). */
+    claimId: string;
+    /** The merkle leaf index where the refund note `C_r` landed. */
+    leafIndex: number;
+}
+/**
+ * Reclaim a timed-out swap's principal as a fresh shielded note via ClaimRefund.
+ *
+ * Front-running note: this self-submits the claim. The production default is
+ * relay submission (decision #3) to avoid mempool exposure of the voucher; a
+ * relay `/claim-refund` endpoint is the documented follow-up.
+ */
+declare function claimTimeoutRefund(params: ClaimTimeoutRefundParams, options: ClaimTimeoutRefundOptions): Promise<ClaimTimeoutRefundResult>;
 
 /**
  * On-chain Merkle proof computation
@@ -1798,7 +2943,12 @@ declare function buildMerkleTreeFromRelay(relayUrl: string, options?: {
     maxRetries?: number;
     waitForIndex?: number;
 }): Promise<MerkleTree>;
-declare function buildMerkleTreeFromChain(connection: Connection, programId: PublicKey, merkleTree: PublicKey, onProgress?: (message: string) => void): Promise<MerkleTree>;
+declare function buildMerkleTreeFromChain(connection: Connection, programId: PublicKey, merkleTree: PublicKey, onProgress?: (message: string) => void, 
+/**
+ * The pool mint this tree belongs to. Required in practice: without it a `CloseSwapState` refund
+ * leaf cannot be attributed to a tree, and reconstruction fails closed rather than guess.
+ */
+mint?: PublicKey): Promise<MerkleTree>;
 /**
  * Pre-flight root validation
  *
@@ -1851,6 +3001,111 @@ declare function preflightCheck(relayUrl: string, rootHex: string): Promise<{
     estimatedWaitMs?: number;
 }>;
 
+/**
+ * The SDK's host-environment predicates, in one place (X-S-02C).
+ *
+ * ── The defect this closes ────────────────────────────────────────────────────────────────────
+ * The merkle-from-chain rebuild was guarded by TWO independently written predicates that disagreed
+ * about React Native:
+ *
+ *   - the GATE in `core/transact.ts` — `!IS_BROWSER && isMerkleClass && relayUrl`, where
+ *     `IS_BROWSER` was `typeof window !== "undefined" || typeof globalThis.document !== "undefined"`,
+ *     with NO React-Native carve-out. React Native defines `window`, so RN read as a browser and the
+ *     last-resort chain replay was silently skipped there.
+ *   - the BUILDER it guards — `utils/relay-client.ts::buildMerkleTreeFromChain`, whose own
+ *     `isBrowser()` short-circuits on `navigator.product === "ReactNative"` and therefore explicitly
+ *     PERMITS React Native to rebuild from chain.
+ *
+ * So one half of the same mechanism classified RN as a browser and the other half classified it as
+ * not-a-browser.
+ *
+ * ── The decision: the BUILDER is right, and the gate was wrong ────────────────────────────────
+ * The browser fails closed for a stated reason — a full signature-history scan is too slow and too
+ * unreliable on a browser main thread, and a browser always has a reachable relay whose tree it can
+ * use instead. Neither half of that reasoning holds for React Native: it is not a browser, it has no
+ * DOM, it is not running on a page's main thread, and on a local node it has no relay-tree fallback
+ * at all. Closing the gate against RN removed its ONLY recovery path from a drifted relay tree —
+ * precisely the class of failure the fallback exists for — while leaving the builder it calls happy
+ * to serve it.
+ *
+ * The alternative reading (make the builder refuse RN too, so the two agree by failing closed
+ * everywhere) was rejected: it agrees by breaking the Cloak mobile wallet, whose merkle path depends
+ * on the carve-out, and it discards a documented, deliberate decision in favour of an undocumented
+ * accident. The gate's own comment never mentions React Native — it argues about SSR — which is what
+ * an accident looks like.
+ *
+ * ── Two predicates, deliberately, and the difference is not RN ────────────────────────────────
+ * `isBrowser()` is a HARD REFUSAL — "this host cannot do it at all" — so it demands a real DOM
+ * (`window` AND `document`).
+ * `isBrowserLike()` is a CONSERVATIVE OPT-OUT — "don't start something slow here" — so `window` OR
+ * `document` is enough, which keeps an SSR host that polyfills only `document` from being mistaken
+ * for Node and made to attempt a chain replay.
+ *
+ * They differ on SSR on purpose. They must NEVER differ on React Native again, which is why both are
+ * built from the single `isReactNative()` below.
+ *
+ * All three are functions, not module-scope constants: a constant is frozen at import time, so any
+ * host that installs its globals after the bundle loads — and any test that wants to pin the three
+ * environments — reads a stale answer.
+ */
+/**
+ * True on React Native. `navigator.product === "ReactNative"` is the canonical flag and is what
+ * `utils/proof-generation.ts` has always used.
+ */
+declare function isReactNative(): boolean;
+/**
+ * True only on a real browser: a DOM host with both `window` and `document`, and not React Native.
+ *
+ * Use for HARD refusals — work this host genuinely cannot perform.
+ */
+declare function isBrowser(): boolean;
+/**
+ * True on a browser OR on a DOM-ish host such as SSR that defines only one of `window`/`document`,
+ * and false on React Native and on Node.
+ *
+ * Use for CONSERVATIVE opt-outs — expensive work that should not be started speculatively.
+ */
+declare function isBrowserLike(): boolean;
+
+/**
+ * Circuit artifact releases — the single source of truth for
+ * "which bundle version" and "which bytes are that bundle".
+ *
+ * Why this file exists
+ * -------------------
+ * The version segment of the artifact base URL and the pinned SHA-256 digests
+ * used to be written out by hand in two unrelated places
+ * (`utils/proof-generation.ts` held `.../circuits/0.1.0` plus a digest table,
+ * `core/transact.ts` held its own copy of the same URL literal). They drifted:
+ * the default base pointed at the `0.1.0` bundle while the pinned `transaction`
+ * digests were the `0.2.0` trusted-setup ceremony output, so every default-config
+ * proof died on a digest mismatch several megabytes into proof generation.
+ *
+ * Here a bundle is declared once, as a version plus the digests of the artifacts
+ * that version contains, and the base URL is *derived* from that version by
+ * {@link defineCircuitBundle}. There is no way to write a URL whose version
+ * segment disagrees with the digests next to it:
+ *
+ *  - **compile time** — `baseUrl` is typed `` `${string}/circuits/${V}` ``, where
+ *    `V` is the bundle's own `version` literal, and {@link BUNDLE_BY_CIRCUIT} is
+ *    an exhaustive `Record<CircuitName, …>`, so a new circuit with no bundle, or
+ *    an assertion about a version the bundle does not carry, fails `tsc`.
+ *  - **startup** — {@link assertCircuitReleaseConsistency} runs at module load
+ *    and throws if a bundle's digests are malformed, if a bundle does not pin the
+ *    circuit that maps to it, or if a hand-edited base URL stops ending in its own
+ *    version. That is an import-time failure, not a failure deep inside
+ *    `groth16.fullProve`.
+ *
+ * Publication is deliberately *not* assumed. A bundle whose bytes this SDK has
+ * not verified at a public location carries `baseUrl: null`; callers must point
+ * the SDK at a location themselves (`setCircuitsPath`). Nothing here silently
+ * defaults to a URL that has not been checked against the digests below.
+ */
+/** Circuits whose artifacts carry a pinned SHA-256 digest in this SDK. */
+type CircuitName = 'withdraw_regular' | 'withdraw_swap' | 'transaction';
+/** Version of the trusted-setup ceremony bundle that froze the `transaction` circuit. */
+declare const TRANSACTION_CIRCUITS_VERSION = "0.2.0";
+
 /**
  * UTXO Transaction Methods
  *
@@ -1860,23 +3115,73 @@ declare function preflightCheck(relayUrl: string, rootHex: string): Promise<{
  * - partialWithdraw(): Withdraw with change
  */
 
-declare const DEFAULT_TRANSACTION_CIRCUITS_URL = "https://storage.googleapis.com/cloak-circuits/circuits/0.1.0";
+/**
+ * Can this host attempt the last-resort "rebuild the merkle tree from chain" recovery?
+ *
+ * X-S-02C: this gate and the builder it guards (`buildMerkleTreeFromChain`, which refuses only on a
+ * real browser and EXPLICITLY permits React Native) used to be written separately and disagreed —
+ * RN defines `window`, so the old inline `typeof window !== "undefined" || typeof document !==
+ * "undefined"` classified RN as a browser and skipped the rebuild, removing RN's only recovery path
+ * from a drifted relay tree while the builder was perfectly willing to serve it. Both now come from
+ * `utils/environment`, so they cannot disagree about React Native again.
+ *
+ * The SSR conservatism is kept: `isBrowserLike()` is true when EITHER `window` or `document` exists,
+ * because an SSR host that polyfills only `document` must not be mistaken for Node and made to run a
+ * full signature-history scan.
+ *
+ * A function, not a module-scope constant: the constant was frozen at import time, so a host that
+ * installs its globals after the bundle loads read a stale answer.
+ */
+declare function canRebuildMerkleTreeFromChain(): boolean;
+
+/**
+ * Base the ceremony-frozen `transaction` artifacts are fetched from by default.
+ *
+ * Derived from {@link TRANSACTION_CIRCUIT_BUNDLE} — the same record that pins the
+ * digests — so the version in the URL and the digests checked against it cannot
+ * drift apart. It is `null` while this SDK build pins no location whose bytes
+ * were verified to hash to those digests; that makes an unconfigured SDK a
+ * `tsc` error at the call site (`setCircuitsPath(DEFAULT_TRANSACTION_CIRCUITS_URL)`
+ * does not type-check against `string`) and an immediate, explanatory throw at
+ * runtime, instead of a digest mismatch ~22 MB into proof generation.
+ */
+declare const DEFAULT_TRANSACTION_CIRCUITS_URL: string | null;
+
 /**
  * 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).
+ * or an `http(s)` base URL to those artifacts (loaded into memory once per process).
+ *
+ * No cache invalidation is needed here: verified artifact buffers are memoised
+ * per base inside `proof-generation.ts`, so a new base loads and re-verifies its
+ * own bytes.
  */
 declare function setCircuitsPath(next: string): void;
 /**
- * Get the current circuits path
+ * Get the current circuits path, or `null` when none is configured and this SDK
+ * build pins no verified default (see `DEFAULT_TRANSACTION_CIRCUITS_URL`).
+ */
+declare function getCircuitsPath(): string | null;
+/**
+ * Resolve a base to prove from: an explicit argument, else `CLOAK_CIRCUITS_PATH`
+ * / `CLOAK_CIRCUITS` from the environment, else this build's pinned default.
+ *
+ * Use this instead of writing an artifact URL out by hand — a hand-written URL
+ * is exactly how the base's version segment came to disagree with the digests
+ * this SDK checks against. Throws an explanatory error (naming the expected
+ * bundle version and both expected digests) when nothing resolves.
  */
-declare function getCircuitsPath(): string;
-declare function computeChainNoteHash(publicAmount: bigint, extDataHash: bigint, noteTimestamp: bigint, noteCommitment: bigint): Promise<bigint>;
+declare function resolveCircuitsBase(explicit?: string): string;
 /**
- * Compute extDataHash for binding proof to external parameters
+ * Chain note v4.
+ *
+ * v4 binds noteSemantics = Poseidon(outAmount[0], outPubkey[0], noteIsSendToSelfKey0) into the note
+ * tail, matching the ceremony circuit. The tail is therefore a 4-input hash, not 3.
  *
- * extDataHash = Poseidon(recipient, relayerFee, relayer)
+ * noteIsSendToSelfKey0 is 1 only when publicAmount == 0 AND output 0 went to the spender's own key,
+ * exactly as the circuit computes it.
  */
-declare function computeExtDataHash(recipient: PublicKey | null, relayerFee: bigint, relayer: PublicKey | null): Promise<bigint>;
+declare function computeChainNoteHash(publicAmount: bigint, extDataHash: bigint, noteTimestamp: bigint, noteCommitment: bigint, noteSalt: bigint, outAmount0: bigint, outPubkey0: bigint, noteIsSendToSelfKey0: bigint): Promise<bigint>;
+declare function computeExtDataHash(recipient: PublicKey | null, relayerFee: bigint, relayer: PublicKey | null, maxFee?: bigint): Promise<bigint>;
 /**
  * Options for transact operation
  */
@@ -1894,8 +3199,8 @@ interface TransactOptions {
     /** Relayer address for fee payment */
     relayer?: PublicKey;
     /**
-     * Relay URL override.
-     * Defaults to `https://api.cloak.ag` when omitted.
+     * Relay URL. Never defaulted: resolved from this option, then from `CLOAK_RELAY_URL`.
+     * Name production explicitly (`https://api.cloak.ag`).
      */
     relayUrl?: string;
     /** Keypair of the depositor (signs the deposit transaction) - for programmatic use */
@@ -1981,6 +3286,13 @@ interface TransactOptions {
      * Each entry must be base64-encoded note bytes.
      */
     encryptedNotes?: string[];
+    /**
+     * Omit the on-chain encrypted chain-note envelope entirely. The chainNoteHash public input
+     * is unaffected (proof still binds it); only the optional ciphertext blob the program emits
+     * for wallet auto-scan is dropped. Use when the caller tracks UTXOs out-of-band and needs the
+     * smaller packet — e.g. V3 + SPL deposits that would otherwise overflow the 1232-byte limit.
+     */
+    disableChainNotes?: boolean;
     /**
      * 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.
@@ -1992,6 +3304,32 @@ interface TransactOptions {
      * passing nk at every call site — e.g. pass a getter from your key manager.
      */
     getChainNoteViewingKeyNk?: () => Promise<string | Uint8Array | null>;
+    /**
+     * Pin the chain note's 96-bit `noteSalt` instead of drawing a fresh one (VK-01).
+     *
+     * Pass the `noteSalt` returned by {@link createRecoverableDepositUtxo}. That helper derives the
+     * deposit note's keypair and blinding as `PRF(nk, noteSalt)`, and the chain note is the ONLY place
+     * the salt is published — so a cold `(rpc, programId, nk)` scan can only rebuild the note if the
+     * salt that anchored it is the salt that reaches the note. Leaving this unset draws a random salt,
+     * which is correct for every non-derived flow.
+     *
+     * Requires an explicit `chainNoteViewingKeyNk` / `getChainNoteViewingKeyNk`; `transact` refuses
+     * otherwise rather than pairing the salt with an nk inferred from the note's own key.
+     */
+    chainNoteSalt?: bigint;
+    /**
+     * The RECIPIENT's 32-byte X25519 public viewing key, for a shield-to-shield send.
+     *
+     * Supply `deriveViewingKeyFromNk(recipientNk).publicKey` (hex or bytes). When present, the SDK
+     * seals `{amount, blinding}` of output 0 to this key and ships it as `recipient_delivery_notes`,
+     * which the relay publishes as a CLKD1 carrier the recipient can find with their `nk` alone.
+     *
+     * When absent, the send still succeeds but the recipient CANNOT discover the note from chain —
+     * it must be handed over out of band. That was the shipped behaviour and is what campaign rows
+     * S2S-08 / VK-01 measured. Ignored on deposits and withdrawals: the relay rejects the field
+     * outright on anything that is not a send.
+     */
+    recipientViewingPublicKey?: Uint8Array | string;
     /**
      * Cached Merkle tree from a previous transaction.
      * When provided, the SDK skips fetching commitments from the relay and uses this
@@ -2067,17 +3405,119 @@ interface RiskQuoteInstructionResponse {
         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?: {
+declare function fetchRiskQuoteInstruction(riskQuoteUrl: string, wallet: PublicKey, options: {
+    poolMint: PublicKey;
     recipient?: PublicKey;
     amount?: bigint;
     token?: PublicKey;
+    commitment?: string | Uint8Array;
+    context?: "deposit" | "send" | "withdraw";
+    nullifier0?: string;
+    nullifier1?: string;
 }): Promise<TransactionInstruction>;
+/** Everything the `/transact` relay body is built from. */
+interface TransactRequestBodyParams {
+    proofB64: string;
+    publicInputsB64: string;
+    mint: PublicKey;
+    recipient?: PublicKey | null;
+    relayer?: PublicKey | null;
+    relayerFee: bigint;
+    maxFee: bigint;
+    encryptedNotes?: string[];
+    riskQuote?: {
+        signature: string;
+        message: string;
+        signer_pubkey: string;
+    };
+    /** Present only on shield-to-shield sends, where the relay enforces sanctions on the sender. */
+    sender?: PublicKey | null;
+    /** Signed public amount; zero is a shield-to-shield send. */
+    externalAmount: bigint;
+    /** Base64 CLKD1 envelopes, from `buildRecipientDeliveryNotes`. Omitted when the rail is off. */
+    recipientDeliveryNotes?: string[];
+}
+/**
+ * Assemble the `/transact` body.
+ *
+ * Extracted so the wire shape is testable without a proof. The field set is a contract with
+ * `services/relay/src/api/transact.rs`, and `recipient_delivery_notes` in particular is part of the
+ * relay's signed field view (`TRANSACT_AUTH_FIELDS`) — so a body that carries it must be signed
+ * with it present, and a body that omits it must be signed with an explicit null. `buildAuthRequest`
+ * handles that, but only if the field is genuinely absent rather than set to `undefined`-ish values.
+ */
+declare function buildTransactRequestBody(params: TransactRequestBodyParams): Record<string, unknown>;
+/** Everything settlement verification needs to check THIS proof against chain state. */
+interface SettlementContext {
+    connection: SettlementConnection;
+    programId: PublicKey;
+    mint: PublicKey;
+    /** The proof's public input nullifiers — the ground truth for "did this land". */
+    inputNullifiers: bigint[];
+}
+type RelaySubmissionResult = {
+    kind: "submitted";
+    signature: string;
+    commitmentIndices?: [number, number];
+    viewingKeyRegistered?: boolean;
+    settlement: SettlementVerdict;
+}
+/** The relay rejected the proof's root; the caller must rebuild the tree and re-prove. */
+ | {
+    kind: "stale-root";
+    error: Error;
+} | {
+    kind: "failed";
+    error: Error;
+};
+interface SubmitTransactToRelayArgs {
+    relayUrl: string;
+    /** The exact body to POST. Auth fields are added ONCE, in place, and then never changed. */
+    requestBody: Record<string, unknown>;
+    programId: PublicKey;
+    depositorKeypair?: Keypair;
+    settlement: SettlementContext;
+    /** True while the caller still has a re-prove budget for a stale root. */
+    canRetryStaleRoot: boolean;
+    maxNetworkRetries?: number;
+    requestTimeoutMs?: number;
+    /** Injection seam for tests; defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    onProgress?: (status: string) => void;
+    /** Total window allowed for the on-chain settlement check after a reported success. */
+    settlementTimeoutMs?: number;
+    /** Shorter window used to ask "did it land anyway?" after a terminal relay failure. */
+    failureProbeTimeoutMs?: number;
+}
+/**
+ * POST one logical `/transact` request and REPORT ONLY WHAT THE CHAIN CONFIRMS.
+ *
+ * Extracted from `transact()` so the two campaign defects it fixes are reproducible without a
+ * validator: a stub `fetchImpl` plays the hostile relay, a stub `SettlementConnection` plays the
+ * RPC. Its control flow is the caller's old inline network-retry loop, unchanged except where
+ * noted below.
+ *
+ * THREE fixes live here, all of them the same root cause — trusting the counterparty:
+ *
+ * 1. REL-A-1 (root cause of REL-A-10): the request is signed ONCE, before the retry loop, and
+ *    every retry re-POSTs the byte-identical body. The relay's recovery contract is keyed on
+ *    `(auth_nonce, endpoint, sender, request_digest)` — `request_auth.rs::authenticate_relay_request`
+ *    — and `handle_transact` answers an exact replay from its durable row: `Completed` replays the
+ *    stored response, `Prepared` reconciles the stored signature against chain, `Processing`
+ *    returns a retryable 503. The shipped client re-signed with a FRESH `randomUUID()` nonce inside
+ *    the loop, so every retry was a NEW request that could only collide with its own predecessor's
+ *    nullifier reservation (503) — measured: 7 POSTs, 7 nonces, byte-identical business fields, and
+ *    the recovery path unreachable. Re-signing here is not a fallback: a nonce that has aged past
+ *    the relay's 300s freshness window is still accepted for an EXACT replay whose row exists, and
+ *    when no row exists nothing was mutated, so the 401 is both correct and safe.
+ * 2. X-S-01B: a reported success is verified against chain before it is returned. The relay's word
+ *    plus its commitment indices are not evidence; the input nullifier PDAs are.
+ * 3. REL-A-10 / (b): the signature the relay puts in a `submission_outcome_unknown` body is
+ *    captured across attempts, and every terminal failure that could plausibly have been submitted
+ *    is resolved against chain into a `SettlementVerificationError` that states the outcome and
+ *    carries the signature.
+ */
+declare function submitTransactToRelay(args: SubmitTransactToRelayArgs): Promise<RelaySubmissionResult>;
 declare function transact(params: TransactParams, options: TransactOptions): Promise<TransactResult>;
 /**
  * Execute a shield-to-shield transfer
@@ -2142,6 +3582,25 @@ interface UtxoSwapResult extends TransactResult {
     nullifier: string;
     /** Relay request ID for swap execution status */
     requestId?: string;
+    /**
+     * V3-04 refund-fallback secret. **Persist this** to recover the swap principal if the swap times
+     * out before TX2. On a timeout close the program builds the amount-bound note
+     *   R_fb = Poseidon(amountAfterFee, publicKey, blinding, WSOL)
+     * where `amountAfterFee` is the principal it locked (read authoritatively from the on-chain
+     * `SwapState.sol_amount`, = gross swap amount minus the on-chain swap fee). `ClaimRefund` then spends
+     * `R_fb` with `privateKey` (a plain ZK membership proof of the refund tree). All values are hex.
+     *
+     * VK-02: when `derivedFromNk` is true this secret is ALSO recoverable from the wallet's `nk` plus
+     * the swap's public first input nullifier — see `matchSwapRefundLeaf`. Persisting it is still the
+     * fast path; losing it is no longer terminal. When false (no `nk` was supplied to the swap) this
+     * object is the only copy that will ever exist.
+     */
+    refund: {
+        privateKey: string;
+        publicKey: string;
+        blinding: string;
+        derivedFromNk: boolean;
+    };
 }
 /**
  * Execute a UTXO swap withdrawal
@@ -2171,24 +3630,755 @@ declare function swapUtxo(params: UtxoSwapParams, options: TransactOptions): Pro
 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).
+ * 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
+ *
+ * Artifacts come from the pinned per-bundle hosts in `config/circuit-release`,
+ * verified by digest; no backend prover service is required.
+ */
+
+/**
+ * Default base URL for the legacy `withdraw_regular` / `withdraw_swap` artifacts.
+ *
+ * Derived from {@link LEGACY_WITHDRAW_CIRCUIT_BUNDLE}, so the version segment is
+ * the same one the pinned digests were declared under. Do not write this URL out
+ * by hand anywhere — change the bundle instead.
+ *
+ * This is NOT the base for the ceremony-frozen `transaction` circuit: that
+ * circuit lives in a different bundle ({@link TRANSACTION_CIRCUIT_BUNDLE}) with
+ * different digests, and is configured through `setCircuitsPath()`.
+ *
+ * `string | null` — null when the bundle has no published host, which is the
+ * case for the legacy withdraw artifacts.
+ *
+ * RESOLVED LAZILY ON PURPOSE. This was previously
+ * `requirePinnedBaseUrl('withdraw_regular')` evaluated at module scope, so an
+ * unpinned bundle made merely IMPORTING the SDK throw — breaking every consumer,
+ * including those that never touch a legacy withdraw path. The diagnostic is
+ * still raised, by `resolveCircuitsUrl` and `getDefaultCircuitsPath` at the
+ * point of use, where a caller can actually act on it.
+ */
+declare const DEFAULT_CIRCUITS_URL: string | null;
+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), flattened from the release table in
+ * `config/circuit-release.ts`.
+ *
+ * This is a *view*, not the source of truth: edit the bundle, not this object.
+ * It stays writable because the artifact TOCTOU tests re-pin it to synthetic
+ * fixtures; production code must not mutate it.
+ */
+declare const EXPECTED_CIRCUIT_HASHES: {
+    withdraw_regular_wasm: string;
+    withdraw_regular_zkey: string;
+    withdraw_swap_wasm: string;
+    withdraw_swap_zkey: string;
+    transaction_wasm: string;
+    transaction_zkey: string;
+};
+/**
+ * Circuit verification result
+ */
+interface CircuitVerificationResult {
+    /** Whether verification passed */
+    valid: boolean;
+    /** Which circuit was checked */
+    circuit: CircuitName;
+    /** Error message if verification failed */
+    error?: string;
+    computed?: {
+        wasm: string;
+        zkey: string;
+    };
+    expected?: {
+        wasm: string;
+        zkey: string;
+    };
+}
+/** Circuit artifact bytes together with the digests computed over those bytes. */
+interface VerifiedCircuitArtifacts {
+    /** `<circuit>_js/<circuit>.wasm` bytes. */
+    wasm: Uint8Array;
+    /** `<circuit>_final.zkey` bytes. */
+    zkey: Uint8Array;
+    /** SHA-256 (lowercase hex) of the buffers in this object. */
+    digests: {
+        wasm: string;
+        zkey: string;
+    };
+}
+/**
+ * Load circuit artifacts and return the very bytes whose digest was checked.
+ *
+ * This is the only supported way to obtain proving artifacts: the caller passes
+ * the returned buffers straight to `snarkjs.groth16.fullProve`, which accepts a
+ * `Uint8Array` for both the wasm and the zkey. Passing snarkjs a URL or a file
+ * path instead would re-read the artifact independently of the digest check, so
+ * a CDN (or a concurrent writer on disk) could serve good bytes to the check and
+ * different bytes to the prover.
+ *
+ * Fails closed: any digest mismatch, unreachable artifact, or environment that
+ * cannot produce bytes (a browser pointed at a local directory) throws rather
+ * than falling back to an unverified source.
+ */
+declare function loadVerifiedCircuitArtifacts(circuitsPath: string | null, circuit: CircuitName): Promise<VerifiedCircuitArtifacts>;
+/**
+ * Report whether a circuit's artifacts match the digests pinned in this SDK.
+ *
+ * This is a *reporting* helper (used by `verifyAllCircuits` for start-up checks
+ * and diagnostics). It is NOT what gates proving: a check that only inspects the
+ * source cannot say anything about the bytes a later, independent read returns.
+ * Proof paths must call {@link loadVerifiedCircuitArtifacts} and hand the bytes
+ * it returns to snarkjs.
+ *
+ * IMPORTANT: If the hashes don't match, the circuit may produce proofs
+ * that will be rejected by the on-chain verifier!
+ *
+ * @param circuitsPath - Ignored for the legacy withdraw circuits (they always use
+ *                       their own pinned bundle); honoured for `transaction`.
+ * @param circuit - Which circuit to verify
+ * @returns Verification result
+ *
+ * @example
+ * ```typescript
+ * const result = await verifyCircuitIntegrity(DEFAULT_CIRCUITS_URL, 'withdraw_regular');
+ * if (!result.valid) {
+ *   console.error('Circuit verification failed:', result.error);
+ *   // Don't proceed with proof generation!
+ * }
+ * ```
+ */
+declare function verifyCircuitIntegrity(circuitsPath: string | null, circuit: CircuitName, prefetched?: {
+    wasm: Uint8Array;
+    zkey: Uint8Array;
+}): Promise<CircuitVerificationResult>;
+/**
+ * Assert the ceremony-frozen `transaction` circuit artifacts are the pinned ones.
+ *
+ * Throws (fail-closed) when the digests do not match, mirroring how
+ * `generateWithdrawRegularProof` / `generateWithdrawSwapProof` gate the legacy
+ * circuits. Proving against an unpinned zkey silently produces proofs the
+ * on-chain verifying key rejects, so failing here is strictly better than
+ * failing on-chain.
+ *
+ * @param circuitsPath - Base directory or URL holding `transaction_js/transaction.wasm`
+ *                       and `transaction_final.zkey`.
+ * @param prefetched - Already-downloaded artifact bytes, to avoid a second fetch.
+ */
+declare function assertTransactionCircuitIntegrity(circuitsPath: string | null, prefetched?: {
+    wasm: Uint8Array;
+    zkey: Uint8Array;
+}): Promise<void>;
+/**
+ * Verify all circuits before use
+ *
+ * Call this at SDK initialization to ensure circuits are valid.
+ *
+ * @param circuitsPath - For the legacy withdraw circuits this is ignored; verification
+ *                       always uses their own pinned bundle.
+ * @param transactionCircuitsPath - Base for the ceremony-frozen `transaction` circuit.
+ *                       Pass `getCircuitsPath()` when the caller has reconfigured it;
+ *                       `null` reports the "no base configured" state rather than throwing.
+ * @returns Array of verification results (one per circuit)
+ */
+declare function verifyAllCircuits(circuitsPath: string, transactionCircuitsPath?: string | null): 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;
+};
+
+/**
+ * Recipient-addressed delivery envelope (CLKD1).
+ *
+ * ── The defect this closes ────────────────────────────────────────────────────────────────────
+ * A shield-to-shield send creates an output note OWNED BY THE RECIPIENT. The only discovery
+ * artefact the SDK used to publish for it was the CLK1 compliance chain note, which is encrypted
+ * under the SENDER's `nk` and keyed (HKDF salt) by the output commitment. That note is openable by
+ * the sender and by nobody else — so the recipient's money sat on chain, valid and spendable, with
+ * its owner unable to see it (campaign rows S2S-08 / VK-01).
+ *
+ * This envelope is the recipient's half. It is encrypted to the RECIPIENT's X25519 public viewing
+ * key — the one derived by `deriveViewingKeyFromNk(nk)` — so a cold scan holding nothing but
+ * `(rpc, programId, nk)` can open it. That triple is exactly the cold-scan contract VK-01 tested.
+ *
+ * ── Wire format — dictated by the relay, not by us ────────────────────────────────────────────
+ * `services/relay/src/api/transact.rs:176-205` accepts EXACTLY ONE base64 envelope of EXACTLY
+ * 112 bytes and only on a shield-to-shield send (`public_amount == 0`); anything else is a 400 and
+ * no carrier is written. `services/relay/src/solana/mod.rs:2338` then publishes
+ *
+ *     "CLKD1" || hex(output_commitment[0]) || hex(envelope)
+ *
+ * as an SPL Memo in a transaction that touches the PDA at seed `b"cloak_delivery_registry"`, which
+ * is what makes it enumerable via `getSignaturesForAddress`.
+ *
+ * The 112 bytes are:
+ *
+ *     [0  ..32)  ephemeral X25519 public key
+ *     [32 ..56)  24-byte XSalsa20-Poly1305 nonce
+ *     [56..112)  56-byte ciphertext = 40-byte plaintext + 16-byte Poly1305 tag
+ *
+ * and the 40-byte plaintext is `amount(u64 LE) || blinding(u256 BE)` — precisely what a recipient
+ * needs, alongside their own keypair and the pool mint, to recompute the commitment and spend it.
+ * Amount is LE to match every other u64 the SDK writes (`chain-note.ts`, public inputs); blinding
+ * is BE to match `bigintToBytes32` and the on-chain field-element convention.
+ *
+ * ── Crypto ────────────────────────────────────────────────────────────────────────────────────
+ * X25519 ECDH + XSalsa20-Poly1305, i.e. `nacl.box`, reusing the exact construction already in
+ * `core/keys.ts` (`nacl.box.before` + `nacl.secretbox`). No new primitive is introduced here.
+ */
+
+/** Ephemeral X25519 public key, at offset 0. */
+declare const RECIPIENT_DELIVERY_EPHEMERAL_PK_LEN = 32;
+/** XSalsa20-Poly1305 nonce, immediately after the ephemeral key. */
+declare const RECIPIENT_DELIVERY_NONCE_LEN = 24;
+/** amount(8) + blinding(32) — everything the owner needs to rebuild and spend the note. */
+declare const RECIPIENT_DELIVERY_PLAINTEXT_LEN = 40;
+/** Poly1305 authentication tag. */
+declare const RECIPIENT_DELIVERY_TAG_LEN = 16;
+/** Sealed payload = plaintext + tag. */
+declare const RECIPIENT_DELIVERY_CIPHERTEXT_LEN: number;
+/**
+ * Total envelope size. The relay rejects any other length outright
+ * (`RECIPIENT_DELIVERY_NOTE_BYTES` in `services/relay/src/api/transact.rs`), so this constant is a
+ * contract with a shipped binary, not a preference.
+ */
+declare const RECIPIENT_DELIVERY_NOTE_BYTES: number;
+/** PDA seed the relay derives the carrier's registry account from. */
+declare const DELIVERY_REGISTRY_SEED = "cloak_delivery_registry";
+/** ASCII tag prefixing the carrier memo payload. */
+declare const DELIVERY_MEMO_TAG = "CLKD1";
+/** The spendable contents of a delivery envelope. */
+interface RecipientDeliveryNote {
+    /** Note amount in the pool mint's smallest unit. */
+    amount: bigint;
+    /** Note blinding factor (BN254 field element). */
+    blinding: bigint;
+}
+/**
+ * Seal `{amount, blinding}` to a recipient's X25519 public viewing key.
+ *
+ * Every input is length-checked here rather than at the relay: a malformed envelope costs a
+ * confirmed transaction's worth of latency before the 400 comes back, and the send has already
+ * generated its proof by then.
+ */
+declare function encodeRecipientDeliveryNote(note: RecipientDeliveryNote, recipientViewingPublicKey: Uint8Array): Uint8Array;
+/**
+ * Trial-open an envelope with a viewing secret. Returns `null` — never throws — when the envelope
+ * is not ours, because a scanner runs this against every carrier in the registry.
+ */
+declare function openRecipientDeliveryNote(envelope: Uint8Array, viewingSecretKey: Uint8Array): RecipientDeliveryNote | null;
+declare function recipientDeliveryNoteToBase64(envelope: Uint8Array): string;
+/** Parameters the send path already has in hand when it assembles the relay body. */
+interface BuildRecipientDeliveryNotesParams {
+    /** Signed public amount. Zero — and only zero — is a shield-to-shield send. */
+    externalAmount: bigint;
+    /** External withdrawal recipient, if any. A send has none. */
+    recipient?: PublicKey | null;
+    /** The recipient's 32-byte X25519 public viewing key (`deriveViewingKeyFromNk(nk).publicKey`). */
+    recipientViewingPublicKey?: Uint8Array | string | null;
+    /**
+     * The output note being delivered. MUST be output 0: the relay binds the carrier to
+     * `public_inputs.output_commitments[0]` (`services/relay/src/api/transact.rs:1015`).
+     */
+    note?: Pick<Utxo, "amount" | "blinding"> | null;
+    /** UTXO public key that owns `note` (i.e. `paddedOutputs[0].keypair.publicKey`). */
+    noteOwnerPublicKey?: bigint;
+    /** UTXO public key doing the spending (i.e. `paddedInputs[0].keypair.publicKey`). */
+    spenderPublicKey?: bigint;
+}
+/**
+ * Build the `recipient_delivery_notes` field for `/transact`, or `undefined` when the rail does not
+ * apply. Returning `undefined` (rather than an empty array) matters: the relay's signed field view
+ * treats omitted and null identically, and an empty array on a withdrawal would still be a 400.
+ */
+declare function buildRecipientDeliveryNotes(params: BuildRecipientDeliveryNotesParams): string[] | undefined;
+/** Render the carrier memo byte-for-byte as `emit_recipient_delivery_carrier` does. */
+declare function encodeDeliveryCarrierMemo(outputCommitment: bigint | Uint8Array, envelope: Uint8Array): Uint8Array;
+interface ParsedDeliveryCarrier {
+    /** Lowercase 64-char hex of the output commitment the carrier declares. */
+    commitment: string;
+    /** The raw 112-byte envelope. */
+    note: Uint8Array;
+}
+/**
+ * Parse one SPL Memo payload. Returns `null` for anything that is not a well-formed CLKD1 carrier —
+ * the memo program accepts arbitrary UTF-8 from anyone, so this must fail closed on exact lengths
+ * (I-12: exact `!==` gates, never `<`).
+ */
+declare function parseDeliveryCarrierMemo(data: Uint8Array): ParsedDeliveryCarrier | null;
+
+/**
+ * Recoverable deposit notes (VK-01, deposit shape).
+ *
+ * ── The defect this closes ────────────────────────────────────────────────────────────────────
+ * A cold scan holding exactly `(rpc, programId, nk)` — the contract the SDK advertises for viewing
+ * keys — found the WITHDRAWAL change note and did NOT find the DEPOSIT. The control that makes the
+ * miss attributable is the withdrawal: the same scanner, the same 300-signature window, the same
+ * key, one shape found and one not.
+ *
+ * Two things were missing, and only one of them was visible from the failing arm:
+ *
+ *  1. `outPubkey0`. The deposit's chain note is v3 (timestamp + noteSalt), and `chainNoteHash` binds
+ *     `noteSemantics = Poseidon(outAmount0, outPubkey0, isSendToSelfKey0)`. `outPubkey0` is the
+ *     output note's OWNER key, which is not derivable from `nk` — the key hierarchy runs
+ *     `skSpend → nk` through BLAKE3 and does not run backwards. So the scanner could decrypt the
+ *     note and then had to drop it, because the hash it recomputed could never match. That is why
+ *     the widened arm needed an undocumented `ownUtxoPublicKey`: it was feeding the scanner the one
+ *     value the advertised contract does not carry.
+ *  2. The BLINDING. Even with `ownUtxoPublicKey` the deposit is only VISIBLE, not RECOVERABLE — the
+ *     blinding came from `randomFieldElement()` inside `createUtxo` and is written nowhere. A note
+ *     you can see and cannot spend is not a recovered note.
+ *
+ * ── Why derivation, and not another envelope ──────────────────────────────────────────────────
+ * The shielded-send shape was fixed with a CLKD1 delivery envelope because a send's output is owned
+ * by SOMEONE ELSE: the only way to reach them is to encrypt to their key. A deposit's output is
+ * SELF-owned. There is nobody to deliver to, and an envelope would cost 112 bytes on the one
+ * transaction in the protocol that is wallet-signed and already tight against the 1232-byte packet
+ * limit (a v4 chain note's extra 41 bytes is measured at 1282 and is exactly why deposits stay v3).
+ *
+ * So make the existing chain-note path recoverable instead. Both missing values become a PRF of the
+ * wallet's own `nk` and the note salt the chain note ALREADY carries:
+ *
+ *     seed        = BLAKE3("cloak_deposit_note_v1" || nk || noteSalt(32B BE) || info)
+ *     privateKey  = seed("sk")       reduced into the field
+ *     blinding    = seed("blinding") reduced into the field
+ *     publicKey   = PoseidonEx(privateKey, KEYPAIR_)      [L-02, matches keypair.circom]
+ *
+ * A cold scanner decrypts the chain note with `nk` (AES-GCM, HKDF-salted by the output commitment),
+ * reads `noteSalt` out of the plaintext, replays those three lines, recomputes
+ * `Poseidon(amount, publicKey, blinding, mint)` and requires it to equal a commitment the
+ * transaction actually published. That equality is the authentication: it is not a heuristic, and a
+ * wrong `nk` cannot produce it. Zero extra bytes on chain, no new envelope, no relay change.
+ *
+ * This is the same shape already blessed for swap timeout refunds in `core/swap-refund.ts`
+ * (PRF(nk, nullifier0)), for the same reason: unrecoverable randomness becomes recoverable
+ * randomness without changing anything an observer can see.
+ *
+ * ── The consequence to be explicit about ──────────────────────────────────────────────────────
+ * The deposit note is owned by a PER-DEPOSIT key rather than by the wallet's single long-lived UTXO
+ * keypair. It is still fully spendable — the wallet re-derives `privateKey` from `nk` whenever it
+ * needs it — and it is strictly better for privacy, because `outPubkey0` no longer links a wallet's
+ * deposits to each other. But it means the caller MUST persist (or be able to re-derive) `nk`, which
+ * a Cloak wallet already does, and it means `transact` must be given an explicit `nk` rather than
+ * inferring one from the output note's own key. `transact` enforces that rather than trusting it.
+ *
+ * ── Guardrails preserved ──────────────────────────────────────────────────────────────────────
+ * [L-02] the public key comes from the capacity-tagged `derivePublicKey`. [H-04-shaped] a zero
+ * public key or blinding would be an unspendable note, so the reduction forces non-zero and the
+ * derivation refuses to return a degenerate pair. [M-04] `noteSalt` stays a private input to
+ * `chainNoteHash`; it is only ever published inside the note's own authenticated ciphertext.
+ */
+
+/**
+ * The chain note salt is 96 bits — the circuit constrains it with `Num2Bits(96)` and `transact`
+ * generates exactly 12 bytes. A salt outside that range would produce a proof the circuit rejects,
+ * so it is refused here rather than at proof time.
+ */
+declare const CHAIN_NOTE_SALT_BITS = 96;
+/** The secrets a deposit note is built from — and the ones a cold scan re-derives. */
+interface DepositNoteSecrets {
+    keypair: UtxoKeypair;
+    blinding: bigint;
+}
+/** A deposit note recovered from `nk` alone, in spendable form. */
+interface RecoveredDepositNote extends DepositNoteSecrets {
+    amount: bigint;
+    mintAddress: PublicKey;
+    /** The commitment the transaction published, reproduced from the derived secrets. */
+    commitment: bigint;
+    /** The salt the chain note carried, which anchored the derivation. */
+    noteSalt: bigint;
+}
+/** A fresh 96-bit chain-note salt, from the same fail-closed source `transact` uses. */
+declare function randomDepositNoteSalt(): bigint;
+/**
+ * Derive a deposit note's keypair and blinding from `(nk, noteSalt)`.
+ *
+ * Deterministic by design: this is the whole reason a cold scan can rebuild the note. Both the
+ * builder and the scanner call it, so there is exactly one definition of what a deposit note is.
+ */
+declare function deriveDepositNoteSecrets(viewingKeyNk: Uint8Array, noteSalt: bigint): Promise<DepositNoteSecrets>;
+/**
+ * Build a deposit output note that a cold `(rpc, programId, nk)` scan can recover.
+ *
+ * Returns the UTXO to pass as `outputUtxos[0]` AND the salt that anchored it. The SAME salt must be
+ * handed to `transact` as `options.chainNoteSalt`, because the chain note is what publishes it — a
+ * salt that does not reach the note leaves the deposit exactly as undiscoverable as before.
+ *
+ * ```ts
+ * const { utxo, noteSalt } = await createRecoverableDepositUtxo(amount, nk, mint);
+ * await transact({ ..., outputUtxos: [utxo], externalAmount: amount },
+ *                { chainNoteViewingKeyNk: nk, chainNoteSalt: noteSalt, ... });
+ * ```
+ */
+declare function createRecoverableDepositUtxo(amount: bigint, viewingKeyNk: Uint8Array, mintAddress?: PublicKey, noteSalt?: bigint): Promise<{
+    utxo: Utxo;
+    noteSalt: bigint;
+}>;
+interface MatchDepositNoteParams {
+    /** The scanning wallet's incoming viewing base. */
+    viewingKeyNk: Uint8Array;
+    /** `noteSalt`, read out of the decrypted chain note. */
+    noteSalt: bigint;
+    /** Candidate note amount — for a shield with no inputs this is the public deposit amount. */
+    amount: bigint;
+    /** Pool mint the commitment was computed under. */
+    mintAddress: PublicKey;
+    /** Output commitments the transaction actually published, hex or field elements. */
+    outputCommitments: Array<string | bigint>;
+}
+/**
+ * Decide whether a deposit's published commitment is one this `nk` can rebuild, and if so return
+ * the note in spendable form. Returns `null` for everything that is not ours.
+ *
+ * The commitment equality is the authentication. Nothing here trusts the chain note's own claim
+ * about what it describes; the note only supplies `noteSalt`, and the derived secrets have to
+ * reproduce a value the transaction published or the candidate is discarded.
+ */
+declare function matchDepositNote(params: MatchDepositNoteParams): Promise<RecoveredDepositNote | null>;
+
+/**
+ * Swap timeout-refund discovery (VK-02).
+ *
+ * ── The defect this closes ────────────────────────────────────────────────────────────────────
+ * When a private swap exhausts its retry budget, `CloseSwapState` appends
+ *
+ *     R_fb = Poseidon(amount_after_fee, refund_pubkey, refund_blinding, field(WSOL))
+ *
+ * to the main pool tree. `swapUtxo` generated `refund_pubkey` / `refund_blinding` from raw
+ * randomness and returned them only in the in-memory `UtxoSwapResult.refund`. Lose that object —
+ * a crashed tab, a different device, a scan from cold key material — and the leaf is real, funded,
+ * and permanently unrecoverable: campaign row VK-02 observed R_fb under BOTH the refund note's own
+ * viewing key and the swap creator's, and found nothing under either.
+ *
+ * ── The fix, and why it is SDK-only ───────────────────────────────────────────────────────────
+ * Derive the refund authorization as a PRF of the owner's `nk` and the swap's own first input
+ * nullifier:
+ *
+ *     seed = BLAKE3("cloak_swap_refund_v1" || nk || nullifier0)
+ *
+ * `nullifier0` is published in the TransactSwap public inputs, so a cold scanner enumerating
+ * program transactions can replay this derivation for every swap it sees, recompute R_fb, and
+ * match it against the commitment `CloseSwapState` declared. `nk` is secret, so no third party can
+ * predict, front-run or link the refund key — the on-chain artefacts are unchanged in shape and
+ * every existing binding still holds.
+ *
+ * This changes NOTHING on chain or in the relay. `refund_pubkey` / `refund_blinding` remain
+ * caller-supplied values bound into `computeSwapExtDataHash`; only their provenance changes, from
+ * "unrecoverable randomness" to "recoverable randomness".
+ *
+ * ── Guardrails preserved ──────────────────────────────────────────────────────────────────────
+ * [H-04 / DD-01] the derivation is rejected unless publicKey and blinding are both non-zero, and
+ * it is unique per swap because `nullifier0` is unique per spend. [L-02] the public key comes from
+ * the capacity-tagged `derivePublicKey`, matching `keypair.circom`.
+ *
+ * ── FORWARD-LOOKING ONLY ──────────────────────────────────────────────────────────────────────
+ * Everything here — including `discoverSwapRefunds`, the RPC walker at the bottom of this file —
+ * recovers only refunds whose authorization was DERIVED. Swaps already on chain whose refund keypair
+ * and blinding came from raw randomness stay unrecoverable, permanently, by any key-only scan. There
+ * is nothing to replay: those secrets existed only in the caller's in-memory `UtxoSwapResult.refund`.
+ * Do not let this note get softened — a wallet that reports "no stranded refunds" on the strength of
+ * an empty scan would be making a claim this code cannot support.
+ */
+
+/** A refund authorization: what `swapUtxo` binds into the swap ext-data hash. */
+interface SwapRefundAuthorization {
+    privateKey: bigint;
+    publicKey: bigint;
+    blinding: bigint;
+}
+/** A refund leaf matched back to its owner, ready to spend. */
+interface RecoveredSwapRefund {
+    keypair: UtxoKeypair;
+    blinding: bigint;
+    amount: bigint;
+    /** R_fb as a field element, identical to the commitment `CloseSwapState` appended. */
+    commitment: bigint;
+}
+/**
+ * Derive a swap's refund authorization from the owner's `nk` and the swap's first input nullifier.
+ *
+ * Deterministic by design: this is what makes the refund leaf recoverable from key material alone.
+ */
+declare function deriveSwapRefundAuthorization(viewingKeyNk: Uint8Array, inputNullifier: Uint8Array | bigint): Promise<SwapRefundAuthorization>;
+/**
+ * R_fb, exactly as `CloseSwapState` computes it. The swap principal is always WSOL-locked, so the
+ * mint term is the native-SOL sentinel.
+ */
+declare function computeSwapRefundCommitment(amountAfterFee: bigint, refundPublicKey: bigint, refundBlinding: bigint): Promise<bigint>;
+interface MatchSwapRefundLeafParams {
+    /** The scanning wallet's incoming viewing base. */
+    viewingKeyNk: Uint8Array;
+    /** First input nullifier of the candidate swap, read from its TransactSwap public inputs. */
+    inputNullifier: Uint8Array | bigint;
+    /** Principal returned to the pool, from the `cloak/refund_leaf/v1` event. */
+    amountAfterFee: bigint;
+    /** R_fb as appended on chain. */
+    commitment: bigint | Uint8Array;
+}
+/**
+ * Decide whether a public refund leaf belongs to the holder of `viewingKeyNk`, and if so return it
+ * in spendable form. Returns `null` for every leaf that is not ours — a scanner runs this against
+ * every close it can see.
+ */
+declare function matchSwapRefundLeaf(params: MatchSwapRefundLeafParams): Promise<RecoveredSwapRefund | null>;
+/** One recovered refund leaf, with the chain coordinates that produced it. */
+interface DiscoveredSwapRefund extends RecoveredSwapRefund {
+    /** Signature of the `CloseSwapState` transaction that appended the leaf. */
+    signature: string;
+    /** Leaf index, straight from the `cloak/refund_leaf/v1` event. */
+    leafIndex: bigint;
+    /** First input nullifier of the swap this refund belongs to (the PRF's second input). */
+    inputNullifier: Uint8Array;
+    /** Signature of the `TransactSwap` that opened the swap, when it was inside the scanned window. */
+    swapSignature?: string;
+}
+interface DiscoverSwapRefundsOptions {
+    /** Maximum program signatures to walk. Omit or 0 to walk the whole history. */
+    limit?: number;
+    /** Stop when this signature is reached (exclusive) — the cursor from a previous run. */
+    untilSignature?: string;
+    /** `getTransaction` concurrency (default 50). */
+    batchSize?: number;
+    /** Progress/status callback. */
+    onStatus?: (status: string) => void;
+    /**
+     * Pool mint whose `swap_state` PDAs to derive. Swap input is wSOL-locked, so the default is the
+     * native-SOL sentinel and there is no reason to change it outside a test.
+     */
+    poolMint?: PublicKey;
+}
+/**
+ * Find every swap timeout-refund leaf on chain that belongs to the holder of `viewingKeyNk`, and
+ * return each in spendable form (`keypair`, `blinding`, `amount`, `commitment`).
+ *
+ * Key material only — no relay, no local note store, no prior knowledge of the swap. This is the
+ * recovery path for the exact situation VK-02 described: `CloseSwapState` appended a funded leaf and
+ * its owner could not see it under any key they held.
+ *
+ * FORWARD-LOOKING ONLY. This finds refunds whose authorization was DERIVED as PRF(nk, nullifier0).
+ * A swap whose refund keypair and blinding were drawn from raw randomness — every swap submitted
+ * before that derivation shipped, and any swap built without an `nk` — has no derivation to replay,
+ * and no key-only scan can ever recover it. Those secrets existed solely in the caller's in-memory
+ * `UtxoSwapResult.refund`. An empty result is therefore NOT proof that a wallet has no stranded
+ * refund; it means none of the leaves in the scanned window were derivable from this `nk`.
+ *
+ * @param connection    Solana RPC connection.
+ * @param programId     Shield-pool program id.
+ * @param viewingKeyNk  32-byte `nk` — the same value chain notes are decrypted with.
+ */
+declare function discoverSwapRefunds(connection: Connection, programId: PublicKey, viewingKeyNk: Uint8Array, options?: DiscoverSwapRefundsOptions): Promise<DiscoveredSwapRefund[]>;
+
+/**
+ * Compact deterministic chain note format.
+ *
+ * Envelope: [version 1][ciphertext (plaintext + AES-GCM tag)]
  *
- * Envelope: [version 1][ciphertext (timestamp + tag)]
+ * Plaintext layout by version:
+ * - v3: [timestamp: u64 LE (8)][noteSalt: u256 BE (32)]
+ * - v2: [timestamp: u64 LE (8)]
  */
 type ChainNoteTxType = "deposit" | "withdraw" | "transfer" | "swap" | "unknown";
 interface CompactChainNote {
     timestamp: bigint;
     commitment: string;
+    noteSalt?: bigint;
+    /** v4 only: the three terms that make up `noteSemantics`. */
+    outAmount0?: bigint;
+    outPubkey0?: bigint;
+    isSendToSelfKey0?: bigint;
 }
 /**
  * Encrypt a compact deterministic chain note.
- * Payload is minimal to keep relay withdrawals under Solana packet size limits.
- * Envelope: [version 1][ciphertext (timestamp + tag)]
+ *
+ * v3 carries noteSalt so the recipient can recompute and verify the public
+ * chainNoteHash without making the output commitment linkable by observers.
  */
-declare function encryptCompactChainNote(timestamp: bigint, nk: Uint8Array, commitmentHex: string): Promise<Uint8Array>;
+declare function encryptCompactChainNote(timestamp: bigint, nk: Uint8Array, commitmentHex: string, noteSalt: bigint, semantics?: {
+    outAmount0: bigint;
+    outPubkey0: bigint;
+    isSendToSelfKey0: bigint;
+}): Promise<Uint8Array>;
 /**
  * Decrypt a compact deterministic chain note with candidate output commitments.
  * Tries each commitment-derived key until AES-GCM authentication succeeds.
+ * Accepts current v3 notes and legacy v2 notes.
  */
 declare function decryptCompactChainNote(noteBytes: Uint8Array, nk: Uint8Array, candidateCommitments: string[]): Promise<CompactChainNote>;
 declare function chainNoteToBase64(noteBytes: Uint8Array): string;
@@ -2257,6 +4447,30 @@ interface ScanResult {
     lastSignature?: string;
     /** Number of RPC getTransaction calls actually made (for diagnostics). */
     rpcCallsMade: number;
+    /**
+     * Notes delivered TO this wallet by other people's shield-to-shield sends, recovered from the
+     * CLKD1 registry. These are SPENDABLE note secrets, not history records — they are intentionally
+     * kept out of `transactions`/`summary` so the compliance report shape is unchanged.
+     */
+    deliveredNotes: DeliveredNote[];
+    /**
+     * This wallet's OWN deposits, rebuilt in SPENDABLE form from `nk` alone (VK-01).
+     *
+     * `transactions` records that a deposit happened and for how much. These carry the keypair and
+     * blinding as well, which is the difference between seeing a note and being able to spend it.
+     * Only deposits built with {@link createRecoverableDepositUtxo} appear here; a deposit whose
+     * blinding came from raw randomness has nothing to rebuild and shows up as a history row only.
+     *
+     * Additive, for the same reason as `deliveredNotes`: note secrets are not compliance rows.
+     */
+    recoveredDepositNotes: RecoveredDepositNoteRecord[];
+}
+/** A recovered deposit note plus the chain coordinates it was recovered from. */
+interface RecoveredDepositNoteRecord extends RecoveredDepositNote {
+    /** Signature of the deposit transaction. */
+    signature: string;
+    /** Millisecond timestamp from the chain note. */
+    timestamp: bigint;
 }
 /** Options for `scanTransactions`. */
 interface ScanOptions {
@@ -2292,15 +4506,74 @@ interface ScanOptions {
      * matching the wallet's associated token account against the on-chain recipient ATA.
      */
     walletPublicKey?: string;
+    /**
+     * Sweep the CLKD1 recipient-delivery registry for notes sent TO this wallet (default: true).
+     * Costs one extra `getSignaturesForAddress` page plus one `getTransaction` per carrier.
+     */
+    includeRecipientDeliveries?: boolean;
+    /**
+     * This wallet's UTXO public key. Supply it to authenticate each delivery carrier's declared
+     * commitment (see `ScanRecipientDeliveryOptions.ownerUtxoPublicKey`). Without it the commitment
+     * is reported unverified.
+     */
+    ownerUtxoPublicKey?: bigint;
+    /** Candidate pool mints for delivery-carrier commitment verification. Defaults to native SOL. */
+    deliveryMints?: PublicKey[];
+}
+/** A note delivered TO the scanning wallet by someone else's shield-to-shield send. */
+interface DeliveredNote {
+    /** Output commitment (lowercase hex) the carrier declares. */
+    commitment: string;
+    /** Note amount, decrypted from the envelope. */
+    amount: bigint;
+    /** Note blinding, decrypted from the envelope. */
+    blinding: bigint;
+    /** Carrier transaction signature (the discovery record, NOT the source transaction). */
+    carrierSignature: string;
+    /** Carrier block time in seconds, when the RPC supplied one. */
+    blockTime?: number;
+    /**
+     * Pool mint the note lives in, resolved by recomputing the commitment. Present only when
+     * `ownerUtxoPublicKey` was supplied — without it the declared commitment cannot be checked.
+     */
+    mint?: string;
+    /**
+     * True when the declared commitment was recomputed from the decrypted note and matched. The
+     * memo's commitment field is unauthenticated; only this recomputation binds it.
+     */
+    commitmentVerified: boolean;
+}
+interface ScanRecipientDeliveryOptions {
+    connection: Connection;
+    programId: PublicKey;
+    /** nk (32 bytes). The X25519 opening key is `deriveViewingKeyFromNk(nk).privateKey`. */
+    viewingKeyNk: Uint8Array;
+    /**
+     * The scanning wallet's UTXO public key. Supply it to authenticate the carrier's declared
+     * commitment: the memo's commitment field is written by the relay and is not covered by the
+     * envelope's Poly1305 tag, so a carrier can claim any commitment it likes. With this set, a
+     * carrier survives only if `Poseidon(amount, ownerPubkey, blinding, mint)` reproduces it.
+     */
+    ownerUtxoPublicKey?: bigint;
+    /** Candidate pool mints to try when verifying. Defaults to the native-SOL sentinel. */
+    mints?: PublicKey[];
+    onStatus?: (status: string) => void;
+    debug?: boolean;
 }
 /**
- * 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.
+ * Sweep the recipient-delivery registry (CLKD1) and trial-open every carrier with the caller's
+ * viewing key.
  *
- * This is fully self-contained — it only needs a Solana RPC connection
- * and the user's viewing key (private).
+ * This is the READ half of the fix for S2S-08 / VK-01. The pre-existing sweep
+ * (`scanSwapNoteCarriers`) reads the CLK1 registry, which carries the SENDER-encrypted compliance
+ * note — which is why a cold scan found the withdrawal change note and nothing that was sent TO the
+ * scanning wallet. This registry carries the recipient-encrypted envelope, and is the only place a
+ * recipient's own note is discoverable from `(rpc, programId, nk)` alone.
  */
+declare function scanRecipientDeliveryNotes(opts: ScanRecipientDeliveryOptions): Promise<{
+    notes: DeliveredNote[];
+    rpcCalls: number;
+}>;
 declare function scanTransactions(opts: ScanOptions): Promise<ScanResult>;
 /** JSON-serializable compliance report (numbers instead of bigint). Used for cache and display. */
 interface ComplianceReport {
@@ -2474,25 +4747,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.2.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 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 { type BuildRecipientDeliveryNotesParams, CHAIN_NOTE_SALT_BITS, CLOAK_PROGRAM_ID, type ChainNoteTxType, type CircuitName, type CircuitVerificationResult, type ClaimTimeoutRefundOptions, type ClaimTimeoutRefundParams, type ClaimTimeoutRefundResult, type CloakConfig, CloakError, type CloakKeyPair, type CloakNote, CloakSDK, type CommitmentEntry, type CommitmentsResponse, type CompactChainNote, type ComplianceReport, type ComplianceTxType, type ConfirmSettlementParams, DEFAULT_CIRCUITS_URL, DEFAULT_TRANSACTION_CIRCUITS_URL, DELIVERY_MEMO_TAG, DELIVERY_REGISTRY_SEED, type DeliveredNote, type DepositInstructionParams, type DepositNoteSecrets, type DepositOptions, type DepositResult, type DepositStatus, type DiscoverSwapRefundsOptions, type DiscoveredSwapRefund, EXPECTED_CIRCUIT_HASHES, type EncryptedMetadataBundle, type EncryptedNote$1 as EncryptedNote, type ErrorCategory, type ExpandedSpendKey, FIXED_FEE_LAMPORTS, type Groth16Proof, InsecureRandomnessError, LAMPORTS_PER_SOL, LocalStorageAdapter, type LogLevel, type Logger, MERKLE_TREE_HEIGHT, MIN_DEPOSIT_LAMPORTS, type MasterKey, type MatchDepositNoteParams, type MatchSwapRefundLeafParams, type MaxLengthArray, MemoryStorageAdapter, type MerkleProof, type MerkleRootResponse, MerkleTree, NATIVE_SOL_MINT, type Network, type NoteData, type OnchainMerkleProof, type ParsedDeliveryCarrier, type PendingDeposit, type PendingWithdrawal, type ProofResult, RECIPIENT_DELIVERY_CIPHERTEXT_LEN, RECIPIENT_DELIVERY_EPHEMERAL_PK_LEN, RECIPIENT_DELIVERY_NONCE_LEN, RECIPIENT_DELIVERY_NOTE_BYTES, RECIPIENT_DELIVERY_PLAINTEXT_LEN, RECIPIENT_DELIVERY_TAG_LEN, type RecipientDeliveryNote, type RecoveredDepositNote, type RecoveredDepositNoteRecord, type RecoveredSwapRefund, type RefundVoucher, RelayInternalError, RelayService, type RelaySubmissionResult, type RiskQuoteInstructionResponse, RootNotFoundError, SCANNER_SUPPORTS_TRANSACT_SWAP, SIGN_IN_MESSAGE, SanctionsQuoteError, type ScanOptions, type ScanRecipientDeliveryOptions, type ScanResult, type ScanSummary, type ScannedTransaction, type SettlementConnection, type SettlementContext, type SettlementStatus, type SettlementVerdict, SettlementVerificationError, ShieldPoolErrors, type ShieldPoolPDAs, SimpleWallet, type SpendKey, type StorageAdapter, type SubmitTransactToRelayArgs, type SwapOptions, type SwapParams, type SwapRefundAuthorization, type SwapResult, TRANSACTION_CIRCUITS_VERSION, type TransactOptions, type TransactParams, type TransactRequestBodyParams, 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, assertDirectSubmissionLanded, assertTransactionCircuitIntegrity, bigintToBytes32$1 as bigintToBytes32, bigintToHex, buildMerkleTree, buildMerkleTreeFromChain, buildMerkleTreeFromRelay, buildPublicInputsBytes, buildRecipientDeliveryNotes, buildTransactRequestBody, bytesToHex, calculateFee, calculateFeeBigint, calculateRelayFee, canRebuildMerkleTreeFromChain, chainNoteFromBase64, chainNoteToBase64, claimTimeoutRefund, 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, computeSwapRefundCommitment, computeCommitment as computeUtxoCommitment, computeNullifier as computeUtxoNullifier, confirmTransactSettlement, copyNoteToClipboard, createCloakError, createDepositInstruction, createLogger, createRecoverableDepositUtxo, createUtxo, createZeroUtxo, decryptCompactChainNote, decryptComplianceMetadataWithMasterKey, decryptTransactionMetadata, deriveDepositNoteSecrets, deriveDiversifiedViewingKey, deriveDiversifier, deriveInputNullifierPdas, derivePublicKey, deriveSpendKey, deriveSwapRefundAuthorization, deriveUserCompliancePublicKey, deriveUserComplianceScalar, deriveUtxoKeypairFromSpendKey, deriveViewKey, deriveViewingKeyFromNk, deriveViewingKeyFromSpendKey, deriveViewingKeyFromUtxoPrivateKey, deserializeUtxo, detectNetworkFromRpcUrl, discoverSwapRefunds, downloadNote, encodeDeliveryCarrierMemo, encodeNoteSimple, encodeRecipientDeliveryNote, 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, getChainNoteRegistryPDA, getCircuitsPath, getDefaultCircuitsPath, getDeliveryRegistryPDA, getDistributableAmount, getExplorerUrl, getNkFromUtxoPrivateKey, getNullifierPDA, getPendingOperationsSummary, getPoolAuthorityConfigPDA, getPublicKey, getPublicViewKey, getRecipientAmount, getRefundClaimPDA, getRefundLedgerPDA, getRpcUrlForNetwork, getShieldPoolPDAs, getSwapStatePDA, getViewKey, hasPendingOperations, hexToBigint$1 as hexToBigint, hexToBytes, importKeys, importWalletKeys, isBrowser, isBrowserLike, isDebugEnabled, isPlausibleSignature, isReactNative, isRootNotFoundError, isSubmissionOutcomeUnknownResponse, isValidHex, isValidRpcUrl, isValidSolanaAddress, isWithdrawAmountSufficient, isWithdrawable, keypairToAdapter, loadPendingDeposits, loadPendingWithdrawals, loadVerifiedCircuitArtifacts, matchDepositNote, matchSwapRefundLeaf, openRecipientDeliveryNote, parseAmount, parseDeliveryCarrierMemo, parseError, parseNote, parseRelayErrorResponse, parseRelayErrorSignature, parseTransactionError, partialWithdraw, poseidonHash, preflightCheck, preflightNullifiers, prepareEncryptedOutput, prepareEncryptedOutputForRecipient, proofToBytes, pubkeyToFieldElement, pubkeyToLimbs, randomBytes, randomDepositNoteSalt, randomFieldElement, readMerkleTreeState, recipientDeliveryNoteToBase64, registerViewingKey, removePendingDeposit, removePendingWithdrawal, resolveCircuitsBase, savePendingDeposit, savePendingWithdrawal, scanNotesForWallet, scanRecipientDeliveryNotes, scanTransactions, sdkLogger, selectUtxos, sendTransaction, serializeNote, serializeUtxo, setCircuitsPath, setDebugMode, signTransaction, splitTo2Limbs, submitTransactToRelay, 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 };