@cloak.dev/sdk 0.1.3 → 0.1.5

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { PublicKey, Transaction, Connection, TransactionInstruction, Keypair, SendOptions, AddressLookupTableAccount, VersionedTransaction } from '@solana/web3.js';
+import { PublicKey, Transaction, Connection, AddressLookupTableAccount, TransactionInstruction, Keypair, SendOptions, VersionedTransaction } from '@solana/web3.js';
 
 type ComplianceTxType = "deposit" | "withdraw" | "send" | "swap";
 interface TransactionMetadata {
@@ -1498,6 +1498,85 @@ declare function getExplorerUrl(signature: string, network?: Network): string;
  */
 declare function getAddressExplorerUrl(address: string, network?: Network): string;
 
+/**
+ * Merkle Tree implementation for computing proofs
+ *
+ * This tree stores all leaves and can compute the correct Merkle path
+ * for any leaf index.
+ */
+declare const MERKLE_TREE_HEIGHT = 32;
+/**
+ * Merkle Tree class that stores all leaves and computes proofs
+ */
+declare class MerkleTree {
+    private levels;
+    private capacity;
+    private layers;
+    private zeros;
+    private poseidon;
+    /**
+     * Create a new Merkle tree
+     * @param levels Number of levels in the tree (height)
+     * @param leaves Initial leaves to insert
+     * @param zeros Precomputed zero values for each level
+     * @param poseidon Pre-initialized Poseidon instance (avoids async in constructor)
+     */
+    constructor(levels: number, leaves: bigint[], zeros: bigint[], poseidon: any);
+    /**
+     * Create a new MerkleTree with async initialization
+     */
+    static create(levels?: number, leaves?: bigint[]): Promise<MerkleTree>;
+    /**
+     * Rebuild the tree from the leaves (synchronous — poseidon must be initialized)
+     */
+    private _rebuildSync;
+    /**
+     * Get the tree root
+     */
+    root(): bigint;
+    /**
+     * Get the number of leaves in the tree
+     */
+    get length(): number;
+    /**
+     * Insert a new leaf into the tree
+     */
+    insert(leaf: bigint): void;
+    /**
+     * Insert multiple leaves
+     */
+    bulkInsert(leaves: bigint[]): void;
+    /**
+     * Update the path from a leaf to the root
+     */
+    private _updatePath;
+    /**
+     * Get the Merkle path for a leaf at the given index
+     * @param index Leaf index
+     * @returns pathElements and pathIndices for the proof
+     */
+    path(index: number): {
+        pathElements: bigint[];
+        pathIndices: number;
+    };
+    /**
+     * Find the index of a leaf in the tree
+     * @param leaf Leaf value to find
+     * @returns Index if found, -1 otherwise
+     */
+    indexOf(leaf: bigint): number;
+    /**
+     * Get all leaves
+     */
+    leaves(): bigint[];
+}
+/**
+ * Build a MerkleTree from commitment values
+ * @param commitments Array of commitment bigints
+ * @param height Tree height (default: 32)
+ */
+declare function buildMerkleTree(commitments: bigint[], height?: number): Promise<MerkleTree>;
+
 /**
  * Error Utilities
  *
@@ -1529,6 +1608,79 @@ declare function parseRelayErrorResponse(responseText: string): {
     isRootNotFound: boolean;
     currentRoot?: string;
 };
+/**
+ * Raised when a spend attempt hits 0x1020 DoubleSpend on-chain — the input
+ * UTXO's nullifier PDA already exists, meaning the UTXO was spent earlier
+ * (often via another device / session the user forgot about).
+ *
+ * Recovery path: the SDK's pre-flight nullifier check catches this BEFORE
+ * proof generation via `verifyUtxos()`. If thrown after submission (unlikely
+ * once pre-flight is wired in), the caller should call `verifyUtxos()` to
+ * reconcile local state with chain.
+ */
+declare class UtxoAlreadySpentError extends Error {
+    readonly spentUtxoCommitments: string[];
+    constructor(message: string, spentUtxoCommitments?: string[]);
+}
+/**
+ * Base class for Range / sanctions-quote mismatches from the on-chain
+ * program. The relay signs quotes; the program verifies them. When they
+ * don't line up we hit one of three errors:
+ *
+ *   0x10B0 = QuoteExpired  — quote's expiry_ts < on-chain clock
+ *   0x10B2 = WalletMismatch — quote wallet != expected_wallet
+ *   0x10B3 = MissingEd25519 — no withdraw-auth / range-quote ix at all
+ *
+ * These are structural mismatches the caller can't fix on their own —
+ * they indicate a relay / program version skew or a config drift
+ * (e.g. pool not initialized with the expected range_signer).
+ */
+declare class SanctionsQuoteError extends Error {
+    readonly onChainCode: number;
+    readonly subKind: "expired" | "wallet_mismatch" | "missing_ix";
+    constructor(message: string, onChainCode: number, subKind: "expired" | "wallet_mismatch" | "missing_ix");
+}
+/**
+ * Generic catch-all for relay 500s that don't map to any structured class.
+ * Preserves the raw relay error text in `relayMessage` so the caller can
+ * log it without having to string-match.
+ */
+declare class RelayInternalError extends Error {
+    readonly relayMessage?: string | undefined;
+    readonly httpStatus?: number | undefined;
+    /**
+     * Optional pre-built merkle tree rebuilt from chain (Node only).
+     * Populated by the chain-replay fallback in `transact()` when the
+     * relay-tree path fails after all retries. Callers can retry the
+     * spend with `options.cachedMerkleTree = err.cachedTreeFromChain`
+     * without paying the chain-replay cost a second time.
+     *
+     * Typed via `import type` so there's no runtime coupling between
+     * this module and the MerkleTree implementation.
+     */
+    readonly cachedTreeFromChain?: MerkleTree | undefined;
+    constructor(message: string, relayMessage?: string | undefined, httpStatus?: number | undefined, 
+    /**
+     * Optional pre-built merkle tree rebuilt from chain (Node only).
+     * Populated by the chain-replay fallback in `transact()` when the
+     * relay-tree path fails after all retries. Callers can retry the
+     * spend with `options.cachedMerkleTree = err.cachedTreeFromChain`
+     * without paying the chain-replay cost a second time.
+     *
+     * Typed via `import type` so there's no runtime coupling between
+     * this module and the MerkleTree implementation.
+     */
+    cachedTreeFromChain?: MerkleTree | undefined);
+}
+/**
+ * Classify a relay error (response body text + HTTP status) into one of the
+ * structured error types above, or fall back to RelayInternalError.
+ *
+ * Order matters — more specific first. RootNotFoundError is handled by the
+ * caller separately (existing code path) since it carries `current_root` in
+ * the response body.
+ */
+declare function classifyRelayError(responseText: string, httpStatus?: number): Error;
 /**
  * Shield Pool Program Error Codes
  *
@@ -1578,609 +1730,853 @@ declare function createCloakError(error: unknown, _context: string): CloakError;
 declare function formatErrorForLogging(error: unknown): string;
 
 /**
- * Structured Logger for Cloak SDK
- *
- * Provides structured logging similar to Rust tracing format:
- * 2026-01-23T00:51:46.489317Z  INFO cloak::module: 📥 Message key=value
+ * UTXO (Unspent Transaction Output) Model
  *
- * Enable via:
- * - SDK config: new CloakSDK({ debug: true })
- * - Environment: CLOAK_DEBUG=1 or DEBUG=cloak:*
- */
-type LogLevel = "DEBUG" | "INFO" | "WARN" | "ERROR";
-/**
- * Enable or disable debug logging globally
- */
-declare function setDebugMode(enabled: boolean): void;
-/**
- * Check if debug mode is enabled
+ * This module implements the UTXO model for the Cloak privacy protocol.
+ * UTXOs allow for:
+ * - Shield-to-shield transfers (privacy preserved)
+ * - Partial withdrawals (change stays shielded)
+ * - Combining multiple small deposits
+ * - Multi-token support (SOL + any SPL token)
  */
-declare function isDebugEnabled(): boolean;
+
+declare const NATIVE_SOL_MINT: PublicKey;
 /**
- * Logger interface
+ * UTXO Keypair for ownership verification
+ *
+ * Uses Poseidon hash for key derivation:
+ * - privateKey: random field element (kept secret)
+ * - publicKey: Poseidon(privateKey, 0) - can be shared
  */
-interface Logger {
-    debug: (message: string, kvPairs?: Record<string, unknown>) => void;
-    info: (message: string, kvPairs?: Record<string, unknown>) => void;
-    warn: (message: string, kvPairs?: Record<string, unknown>) => void;
-    error: (message: string, kvPairs?: Record<string, unknown>) => void;
+interface UtxoKeypair {
+    /** Private key (random 252-bit field element) */
+    privateKey: bigint;
+    /** Public key derived as Poseidon(privateKey, 0) */
+    publicKey: bigint;
 }
 /**
- * Create a logger for a specific module
- *
- * @param module - Module name (e.g., "cloak::sdk", "cloak::indexer")
- * @returns Logger instance with debug, info, warn, error methods
+ * UTXO represents an unspent transaction output
  *
- * @example
- * ```typescript
- * const log = createLogger("cloak::deposit");
- * log.info("Depositing", { amount: 100000000 });
- * // Output: 2026-01-23T00:51:46.489000Z  INFO cloak::deposit: Depositing amount=100000000
- * ```
+ * Contains all information needed to spend the UTXO:
+ * - amount: Value in the smallest unit (lamports for SOL)
+ * - keypair: Ownership keys
+ * - blinding: Randomness for hiding
+ * - mintAddress: Token type (SOL or SPL token)
+ * - index: Leaf index in Merkle tree (set after deposit/creation)
  */
-declare function createLogger(module: string): Logger;
+interface Utxo {
+    /** Amount in the smallest unit (lamports for SOL, token units for SPL) */
+    amount: bigint;
+    /** Keypair for ownership */
+    keypair: UtxoKeypair;
+    /** Random blinding factor */
+    blinding: bigint;
+    /** Token mint address (NATIVE_SOL_MINT for SOL) */
+    mintAddress: PublicKey;
+    /** Leaf index in Merkle tree (set after the UTXO is in the tree) */
+    index?: number;
+    /** Commitment hash (computed from amount, pubkey, blinding, mint) */
+    commitment?: bigint;
+    /** Nullifier hash (computed when spending) */
+    nullifier?: bigint;
+    /**
+     * Sibling commitment at level 0 of the Merkle tree.
+     * Required for Merkle proofs since siblings aren't stored on-chain.
+     * This is the commitment of the other output in the same transaction.
+     */
+    siblingCommitment?: bigint;
+}
 /**
- * Measure and return duration of an async operation
+ * Encrypted UTXO note for recipient discovery
  *
- * @param _logger - Logger instance (reserved for future debug logging)
- * @param _operation - Operation name (reserved for future debug logging)
- * @param fn - Async function to measure
- * @returns Result and duration in milliseconds
- */
-declare function withTiming<T>(_logger: Logger, _operation: string, fn: () => Promise<T>): Promise<{
-    result: T;
-    durationMs: number;
-}>;
-/**
- * Format lamports as SOL with proper decimals
- */
-declare function formatSol(lamports: number | bigint): string;
-/**
- * Truncate a string (useful for signatures, hashes)
- */
-declare function truncate(str: string, len?: number): string;
-/**
- * Default SDK logger instance
+ * When creating an output UTXO for someone else, the data is encrypted
+ * so only the recipient can discover and spend it.
  */
-declare const sdkLogger: Logger;
-
+interface EncryptedNote {
+    /** Encrypted UTXO data (ECIES/ChaCha20 encrypted) */
+    ciphertext: Uint8Array;
+    /** Ephemeral public key for ECDH */
+    ephemeralPubkey: Uint8Array;
+    /** MAC for integrity verification */
+    mac: Uint8Array;
+}
 /**
- * Result from submitting a withdrawal that includes the request ID
- * for potential recovery/resume scenarios
+ * Transaction parameters for a UTXO transaction
  */
-interface WithdrawSubmissionResult {
-    /** The relay request ID - persist this for recovery */
-    requestId: string;
-    /** The final transaction signature */
-    signature: string;
+interface TransactParams {
+    /** Input UTXOs to spend (max 2) */
+    inputUtxos: Utxo[];
+    /** Output UTXOs to create (max 2) */
+    outputUtxos: Utxo[];
+    /** External recipient for withdrawal (optional) */
+    recipient?: PublicKey;
+    /** Net external amount: positive = deposit, negative = withdraw */
+    externalAmount?: bigint;
+    /** Depositor address (for deposits, the source of funds) */
+    depositor?: PublicKey;
 }
 /**
- * Relay Service Client
- *
- * Handles submission of withdrawal transactions through a relay service
- * that pays for transaction fees and submits the transaction on-chain.
+ * Result from a UTXO transaction
  */
-declare class RelayService {
-    private baseUrl;
+interface TransactResult {
+    /** Transaction signature */
+    signature: string;
+    /** Nullifiers of spent inputs */
+    inputNullifiers: bigint[];
+    /** Commitments of created outputs */
+    outputCommitments: bigint[];
+    /** New Merkle root after the transaction */
+    newRoot: string;
+    /** Merkle tree indices where output commitments were inserted */
+    commitmentIndices: [number, number];
     /**
-     * Create a new Relay Service client
-     *
-     * @param baseUrl - Relay service base URL
-     */
-    constructor(baseUrl: string);
-    /**
-     * Submit a withdrawal transaction via relay
-     *
-     * The relay service will validate the proof, pay for transaction fees,
-     * and submit the transaction on-chain.
-     *
-     * @param params - Withdrawal parameters
-     * @param onStatusUpdate - Optional callback for status updates
-     * @param onRequestId - CRITICAL: Callback when request_id is received.
-     *                      Persist this ID to recover if browser crashes during polling.
-     * @returns Transaction signature when completed
-     *
-     * @example
-     * ```typescript
-     * const signature = await relay.submitWithdraw({
-     *   proof: proofHex,
-     *   publicInputs: { root, nf, outputs_hash, amount },
-     *   outputs: [{ recipient: addr, amount: lamports }],
-     *   feeBps: 50
-     * }, (status) => console.log(`Status: ${status}`),
-     *    (requestId) => localStorage.setItem('pending_withdraw', requestId));
-     * console.log(`Transaction: ${signature}`);
-     * ```
-     */
-    submitWithdraw(params: {
-        proof: string;
-        publicInputs: {
-            root: string;
-            nf: string;
-            outputs_hash: string;
-            amount: number;
-        };
-        outputs: Array<{
-            recipient: string;
-            amount: number;
-        }>;
-        feeBps: number;
-        metadataBundle?: EncryptedMetadataBundle;
-    }, onStatusUpdate?: (status: string) => void, onRequestId?: (requestId: string) => void): Promise<string>;
-    /**
-     * Resume polling for a withdrawal that was previously started
-     *
-     * Use this after page reload to check status of a pending withdrawal.
-     * The requestId should have been persisted via the onRequestId callback.
-     *
-     * @param requestId - Request ID from a previous submitWithdraw call
-     * @param onStatusUpdate - Optional callback for status updates
-     * @returns Transaction signature if completed, null if still pending/failed
-     *
-     * @example
-     * ```typescript
-     * // On page load, check for pending withdrawal
-     * const pendingId = localStorage.getItem('pending_withdraw');
-     * if (pendingId) {
-     *   const result = await relay.resumeWithdraw(pendingId);
-     *   if (result.status === 'completed') {
-     *     console.log('Withdrawal completed:', result.signature);
-     *     localStorage.removeItem('pending_withdraw');
-     *   }
-     * }
-     * ```
-     */
-    resumeWithdraw(requestId: string, onStatusUpdate?: (status: string) => void): Promise<{
-        status: 'completed' | 'failed' | 'pending';
-        signature?: string;
-        error?: string;
-    }>;
-    /**
-     * Poll for withdrawal completion
-     *
-     * @param requestId - Request ID from relay service
-     * @param onStatusUpdate - Optional callback for status updates
-     * @returns Transaction signature when completed
-     */
-    private pollForCompletion;
-    /**
-     * Submit a swap transaction via relay
-     *
-     * Similar to submitWithdraw but includes swap parameters for token swaps.
-     * The relay service will validate the proof, execute the swap, pay for fees,
-     * and submit the transaction on-chain.
-     *
-     * @param params - Swap parameters
-     * @param onStatusUpdate - Optional callback for status updates
-     * @returns Transaction signature when completed
-     *
-     * @example
-     * ```typescript
-     * const signature = await relay.submitSwap({
-     *   proof: proofHex,
-     *   publicInputs: { root, nf, outputs_hash, amount },
-     *   outputs: [{ recipient: addr, amount: lamports }],
-     *   feeBps: 50,
-     *   swap: {
-     *     output_mint: tokenMint.toBase58(),
-     *     slippage_bps: 100,
-     *     min_output_amount: minAmount
-     *   }
-     * }, (status) => console.log(`Status: ${status}`));
-     * console.log(`Transaction: ${signature}`);
-     * ```
+     * Sibling commitments for each output.
+     * For output[0], sibling is output[1] and vice versa.
+     * These are needed for Merkle proofs since siblings aren't stored on-chain.
      */
-    submitSwap(params: {
-        proof: string;
-        publicInputs: {
-            root: string;
-            nf: string;
-            outputs_hash: string;
-            amount: number;
-        };
-        outputs: Array<{
-            recipient: string;
-            amount: number;
-        }>;
-        feeBps: number;
-        swap: {
-            output_mint: string;
-            slippage_bps: number;
-            min_output_amount: number;
-        };
-        metadataBundle?: EncryptedMetadataBundle;
-    }, onStatusUpdate?: (status: string) => void, onRequestId?: (requestId: string) => void): Promise<string>;
+    siblingCommitments: [bigint, bigint];
     /**
-     * Get transaction status
-     *
-     * @param requestId - Request ID from previous submission
-     * @returns Current status
-     *
-     * @example
-     * ```typescript
-     * const status = await relay.getStatus(requestId);
-     * console.log(`Status: ${status.status}`);
-     * if (status.status === 'completed') {
-     *   console.log(`TX: ${status.txId}`);
-     * }
-     * ```
+     * Left sibling from before the transaction (for odd-index handling).
+     * When the first output ends up at an odd index due to concurrent access,
+     * its sibling at index-1 comes from a previous transaction.
+     * This value captures subtrees[0] before our transaction to enable
+     * correct Merkle proof computation for odd indices.
      */
-    getStatus(requestId: string): Promise<TxStatus>;
+    preTransactionLeftSibling?: bigint;
     /**
-     * Register viewing key with relay for compliance decryption.
-     * This is a one-time operation - the viewing key is stored by the relay.
-     *
-     * The user must sign a one-time relay challenge proving wallet ownership.
-     *
-     * @param userPubkey - User's wallet public key (base58)
-     * @param viewingKey - Viewing key private key (32 bytes, hex encoded)
-     * @param signMessage - Function to sign challenge message bytes
-     *
-     * @example
-     * ```typescript
-     * await relay.registerViewingKey(
-     *   userPublicKey.toBase58(),
-     *   viewingKeyHex,
-     *   signatureBase64
-     * );
-     * ```
+     * The actual output UTXOs created by this transaction.
+     * These have all the data needed to spend them later (keypair, blinding, etc).
+     * The UTXOs are already updated with their indices and sibling commitments.
      */
-    registerViewingKey(userPubkey: string, viewingKey: string, signMessage: (message: Uint8Array) => Promise<Uint8Array>): Promise<boolean>;
+    outputUtxos: Utxo[];
     /**
-     * Fetch relay compliance master public key.
-     * DEPRECATED: This endpoint is no longer used
+     * Whether the viewing key was registered with the relay for compliance.
+     * True on first transaction when metadataBundle includes viewing_key.
+     * Once registered, subsequent transactions don't need to send metadataBundle.
      */
-    getCompliancePublicKey(): Promise<Uint8Array>;
+    viewingKeyRegistered?: boolean;
     /**
-     * Convert bytes to base64 string
+     * The Merkle tree used/built for this transaction, with output commitments inserted.
+     * Pass this as `cachedMerkleTree` in the next transaction to skip relay fetching
+     * and avoid needing `waitForCommitmentIndex`.
      */
-    private bytesToBase64;
+    merkleTree?: MerkleTree;
     /**
-     * Sleep utility
+     * Address lookup table used for v0 transaction (when chain notes or risk oracle require it).
+     * Pass this as `addressLookupTableAccounts` in the next deposit to avoid creating a new ALT.
      */
-    private sleep;
-    private computeViewingKeyIdentifier;
+    addressLookupTableAccounts?: AddressLookupTableAccount[];
 }
-
 /**
- * Risk Oracle Service
- *
- * Self-contained module for fetching Switchboard risk quote instructions
- * using the Range Risk API. Eliminates the need for an external web endpoint
- * (e.g. `/api/risk-quote`) by calling Switchboard directly from the SDK.
- *
- * Uses dynamic imports for @switchboard-xyz packages so they are only loaded
- * when fetchRiskQuoteIx is actually called — not at SDK import time. This
- * prevents the heavy Node.js-only Switchboard code from being bundled into
- * browser builds (Next.js, etc.).
- *
- * Usage:
- *   const { instruction, queue } = await fetchRiskQuoteIx(connection, wallet, rangeApiKey);
+ * Generate a random field element suitable for BN254
  */
-
+declare function randomFieldElement(): bigint;
 /**
- * Fetch a Switchboard risk quote instruction directly from Range + Switchboard.
- *
- * This removes the need for an external `/api/risk-quote` endpoint. The SDK
- * calls Switchboard's crossbar oracle network directly with the Range API key.
+ * Generate a new UTXO keypair
  *
- * @param connection - Solana RPC connection
- * @param wallet - Depositor's public key (the wallet being risk-scored)
- * @param rangeApiKey - Range.org API key for the risk score lookup
- * @returns The Ed25519 sig-verify instruction to prepend at index 0, plus the queue pubkey
+ * @returns A new keypair with random private key and derived public key
  */
-declare function fetchRiskQuoteIx(connection: Connection, wallet: PublicKey, rangeApiKey: string): Promise<{
-    instruction: TransactionInstruction;
-    queue: PublicKey;
-}>;
-
+declare function generateUtxoKeypair(): Promise<UtxoKeypair>;
 /**
- * Encrypted Output Helpers
+ * Derive a deterministic UTXO keypair from a wallet's spend key.
+ * Use this for deposits and change outputs so all chain notes use the same nk,
+ * enabling the compliance scan (scanTransactions + toComplianceReport) to decrypt them.
  *
- * Functions for creating encrypted outputs that enable note scanning
+ * @param skSpend - 32-byte spend key (from wallet key derivation)
+ * @returns UtxoKeypair with deterministic private/public keys
  */
-
+declare function deriveUtxoKeypairFromSpendKey(skSpend: Uint8Array): Promise<UtxoKeypair>;
 /**
- * Prepare encrypted output for scanning by wallet owner
+ * Derive public key from private key
  *
- * @param note - Note to encrypt
- * @param cloakKeys - Wallet's Cloak keys (for self-encryption)
- * @returns Base64-encoded encrypted output
+ * @param privateKey The private key
+ * @returns The corresponding public key
  */
-declare function prepareEncryptedOutput(note: CloakNote, cloakKeys: CloakKeyPair): string;
+declare function derivePublicKey(privateKey: bigint): Promise<bigint>;
 /**
- * Prepare encrypted output for a specific recipient
+ * Create a new UTXO
  *
- * @param note - Note to encrypt
- * @param recipientPvkHex - Recipient's public view key (hex)
- * @returns Base64-encoded encrypted output
+ * @param amount Amount in smallest unit
+ * @param keypair Owner's keypair
+ * @param mintAddress Token mint (defaults to native SOL)
+ * @returns A new UTXO (commitment will be computed)
  */
-declare function prepareEncryptedOutputForRecipient(note: CloakNote, recipientPvkHex: string): string;
+declare function createUtxo(amount: bigint, keypair: UtxoKeypair, mintAddress?: PublicKey): Promise<Utxo>;
 /**
- * Simple base64 encoding for v1.0 notes (no encryption)
+ * Create a zero/padding UTXO
  *
- * @param note - Note to encode
- * @returns Base64-encoded note data
- */
-declare function encodeNoteSimple(note: CloakNote): string;
-
-/**
- * Wallet Integration Helpers
+ * Zero UTXOs are used as padding when we need fewer than 2 inputs/outputs.
+ * They have zero amount and don't require valid Merkle proofs.
+ * Uses salt-based keypair (privateKey = salt) with blinding=0 to match the circuit
+ * test. By default, salt is random to avoid cross-process collisions under concurrency.
+ * Callers can pass an explicit salt for deterministic behavior.
  *
- * Helper functions for working with Solana Wallet Adapters
+ * @param mintAddress Token mint (defaults to native SOL)
+ * @param salt Optional salt; if omitted, uses timestamp+counter for uniqueness
  */
-
+declare function createZeroUtxo(mintAddress?: PublicKey, salt?: bigint): Promise<Utxo>;
 /**
- * Validate wallet is connected and has public key
+ * Convert PublicKey to field element for circuit
+ *
+ * @param pubkey Solana PublicKey
+ * @returns Field element representation
  */
-declare function validateWalletConnected(wallet: WalletAdapter | Keypair): void;
+declare function pubkeyToFieldElement(pubkey: PublicKey): bigint;
 /**
- * Get public key from wallet or keypair
+ * Compute the commitment for a UTXO
+ *
+ * commitment = Poseidon(amount, pubkey, blinding, mintAddress)
+ *
+ * @param utxo The UTXO to compute commitment for
+ * @returns The commitment as a bigint
  */
-declare function getPublicKey(wallet: WalletAdapter | Keypair): PublicKey;
+declare function computeCommitment(utxo: Utxo): Promise<bigint>;
 /**
- * Send transaction using wallet adapter or keypair
+ * Compute the signature for nullifier derivation
+ *
+ * signature = Poseidon(privateKey, commitment, pathIndex)
+ *
+ * @param privateKey Owner's private key
+ * @param commitment The UTXO commitment
+ * @param pathIndex Merkle tree path index
+ * @returns The signature
  */
-declare function sendTransaction(transaction: Transaction, wallet: WalletAdapter | Keypair, connection: Connection, options?: SendOptions): Promise<string>;
+declare function computeSignature(privateKey: bigint, commitment: bigint, pathIndex: bigint): Promise<bigint>;
 /**
- * Sign transaction using wallet adapter or keypair
+ * Compute the nullifier for a UTXO
+ *
+ * nullifier = Poseidon(commitment, pathIndex, signature)
+ *
+ * The nullifier is a unique identifier that gets recorded on-chain
+ * to prevent double-spending.
+ *
+ * @param utxo The UTXO being spent
+ * @returns The nullifier
  */
-declare function signTransaction<T extends Transaction>(transaction: T, wallet: WalletAdapter | Keypair): Promise<T>;
+declare function computeNullifier(utxo: Utxo): Promise<bigint>;
 /**
- * Create a keypair adapter for testing
+ * Serialize a UTXO to bytes for encryption
  */
-declare function keypairToAdapter(keypair: Keypair): WalletAdapter;
-
+declare function serializeUtxo(utxo: Utxo): Uint8Array;
 /**
- * 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
- * });
- * ```
+ * Deserialize a UTXO from bytes
  */
-declare function createDepositInstruction(params: {
-    programId: PublicKey;
-    payer: PublicKey;
-    pool: PublicKey;
-    merkleTree: PublicKey;
-    amount: number;
-    commitment: Uint8Array;
-}): TransactionInstruction;
+declare function deserializeUtxo(bytes: Uint8Array): Promise<Utxo>;
 /**
- * Deposit instruction parameters for type safety
+ * Convert bigint to hex string (64 chars, padded)
  */
-interface DepositInstructionParams {
-    programId: PublicKey;
-    payer: PublicKey;
-    pool: PublicKey;
-    merkleTree: PublicKey;
-    amount: number;
-    commitment: Uint8Array;
-}
+declare function bigintToHex(value: bigint): string;
 /**
- * Validate deposit instruction parameters
- *
- * @param params - Parameters to validate
- * @throws Error if invalid
+ * Convert hex string to bigint
  */
-declare function validateDepositParams(params: DepositInstructionParams): void;
-
+declare function hexToBigint(hex: string): bigint;
 /**
- * Program Derived Address (PDA) utilities for Shield Pool
+ * Convert bigint to 32-byte array (big-endian for circuits)
+ */
+declare function bigintToBytes32(value: bigint): Uint8Array;
+/**
+ * Check if two UTXOs are equal (same commitment)
+ */
+declare function utxoEquals(a: Utxo, b: Utxo): Promise<boolean>;
+/**
+ * Calculate total amount from an array of UTXOs
+ */
+declare function sumUtxoAmounts(utxos: Utxo[]): bigint;
+/**
+ * Select UTXOs to cover a target amount
  *
- * These functions derive deterministic addresses from the program ID and seeds.
- * This matches the behavior in tooling/test/src/shared.rs::get_pda_addresses()
+ * @param available Available UTXOs (sorted by amount descending)
+ * @param targetAmount Target amount to cover
+ * @returns Selected UTXOs that cover the target, or null if insufficient
  */
+declare function selectUtxos(available: Utxo[], targetAmount: bigint): Utxo[] | null;
 
-interface ShieldPoolPDAs {
-    pool: PublicKey;
-    merkleTree: PublicKey;
-    vaultAuthority: PublicKey;
-    treasury: PublicKey;
-}
 /**
- * Derive all Shield Pool PDAs from program ID + pool mint
+ * UTXO verification — reconcile local UTXO state with on-chain nullifier state.
  *
- * Seeds match the on-chain mint-scoped program:
- * - pool: [b"pool", mint]
- * - merkle_tree: [b"merkle_tree", mint]
- * - treasury: [b"treasury", mint]
- * - vault_authority: [b"vault_authority", mint]
+ * Shipped in 0.1.5 as the structured building block for self-repair flows.
+ * The web app previously composed this out of lower-level SDK primitives
+ * (`computeNullifier` + `getNullifierPDA` + `getMultipleAccountsInfo`); now
+ * it's a first-class SDK export so callers don't re-implement the same
+ * ~40 lines across tools.
  *
- * @param programId - Optional program ID (defaults to CLOAK_PROGRAM_ID)
- * @param mint - Pool mint (defaults to NATIVE_SOL_MINT / WSOL sentinel)
+ * Two entry points:
+ *
+ *   1. `verifyUtxos(utxos, conn, programId)` — pure function. Takes a UTXO
+ *      set, does a single batched on-chain lookup of the derived nullifier
+ *      PDAs, returns `{ spent, unspent }`. Caller decides what to do.
+ *
+ *   2. `preflightNullifiers(utxos, conn, programId)` — thin wrapper that
+ *      throws `UtxoAlreadySpentError` if ANY input is already spent.
+ *      Intended for use at the top of spend entry points (transact,
+ *      fullWithdraw, swap) so the SDK fails fast with a structured error
+ *      instead of burning proof-gen + relay retries on a doomed tx.
+ *
+ * Root-caused from a production incident 2026-04-24: a user's cloak.ag
+ * backup contained a UTXO that had been spent via another session. The
+ * recovery tool generated a valid proof against the correct merkle tree
+ * and submitted it; relay's simulation returned 0x1020 DoubleSpend after
+ * 6 retries over ~60s. Pre-flight catches this class in ~200ms.
  */
-declare function getShieldPoolPDAs(programId?: PublicKey, mint?: PublicKey): ShieldPoolPDAs;
+
+/** Result of a batch verification — disjoint partition of the input set. */
+interface VerifyUtxosResult {
+    /** Inputs whose nullifier PDA exists on-chain (already spent). */
+    spent: Utxo[];
+    /** Inputs whose nullifier PDA is absent on-chain (safe to spend). */
+    unspent: Utxo[];
+    /** Inputs we couldn't check — missing commitment / index / mint. */
+    skipped: Utxo[];
+}
 /**
- * Derive the nullifier PDA for a specific pool + nullifier hash.
+ * Check the on-chain nullifier PDA for each UTXO and partition by state.
  *
- * With the new PDA-per-nullifier design, each nullifier has its own PDA
- * instead of being stored in a shared shard. The PDA is created when
- * the nullifier is used during withdrawal.
+ * Only UTXOs with `commitment`, `mintAddress`, AND a non-null keypair can
+ * be verified — the nullifier derivation needs all three. UTXOs lacking any
+ * of these go into `skipped` and the caller must decide how to treat them.
+ * (In practice a missing `commitment` means the UTXO hasn't landed on-chain
+ * yet — those can't be spent anyway.)
  *
- * Seeds: ["nullifier", pool_pubkey, nullifier_hash]
+ * Uses a single batched `getMultipleAccountsInfo` call for efficiency —
+ * one round-trip regardless of UTXO count (up to Solana's 100-key cap,
+ * beyond which we page).
  *
- * @param poolPubkey - Pool PDA that scopes nullifier domain
- * @param nullifier - 32-byte nullifier hash
- * @param programId - Optional program ID (defaults to CLOAK_PROGRAM_ID)
- * @returns [PublicKey, bump] - The nullifier PDA and its bump seed
+ * Typical latency: ~150-300ms on a healthy RPC.
  */
-declare function getNullifierPDA(poolPubkey: PublicKey, nullifier: Uint8Array | Buffer, programId?: PublicKey): [PublicKey, number];
+declare function verifyUtxos(utxos: Utxo[], connection: Connection, programId: PublicKey, commitment?: "processed" | "confirmed" | "finalized"): Promise<VerifyUtxosResult>;
 /**
- * Derive the swap state PDA for a given pool + nullifier.
- *
- * Seeds: ["swap_state", pool_pubkey, nullifier_hash]
+ * Pre-flight gate: throw `UtxoAlreadySpentError` if any input is already
+ * spent on-chain. Called at the top of spend entry points in core/transact.
  *
- * @param poolPubkey - Pool PDA used for swap state domain separation
- * @param nullifier - 32-byte nullifier hash
- * @param programId - Optional program ID (defaults to CLOAK_PROGRAM_ID)
- * @returns [PublicKey, bump] - The swap state PDA and its bump seed
+ * Browser-safe: uses one batched RPC call.
  */
-declare function getSwapStatePDA(poolPubkey: PublicKey, nullifier: Uint8Array | Buffer, programId?: PublicKey): [PublicKey, number];
+declare function preflightNullifiers(utxos: Utxo[], connection: Connection, programId: PublicKey, commitment?: "processed" | "confirmed" | "finalized"): Promise<void>;
 
 /**
- * On-chain Merkle proof computation
+ * Structured Logger for Cloak SDK
  *
- * Computes Merkle proofs directly from on-chain tree state,
- * eliminating the need for an indexer for proof generation.
+ * Provides structured logging similar to Rust tracing format:
+ * 2026-01-23T00:51:46.489317Z  INFO cloak::module: 📥 Message key=value
+ *
+ * Enable via:
+ * - SDK config: new CloakSDK({ debug: true })
+ * - Environment: CLOAK_DEBUG=1 or DEBUG=cloak:*
  */
-
+type LogLevel = "DEBUG" | "INFO" | "WARN" | "ERROR";
 /**
- * Merkle proof result
+ * Enable or disable debug logging globally
  */
-interface OnchainMerkleProof {
-    pathElements: string[];
-    pathIndices: number[];
-    root: string;
-}
-interface MerkleTreeState {
-    nextIndex: number;
-    root: string;
-    subtrees: string[];
-}
+declare function setDebugMode(enabled: boolean): void;
 /**
- * Read the Merkle tree state from on-chain account
- * @param forceConfirmed - If true, forces "confirmed" commitment level for fresh data
- * @param relayUrl - Optional relay URL to query for current root (bypasses RPC caching)
- * @param mint - Optional pool mint used when querying relay /merkle-root
+ * Check if debug mode is enabled
  */
-declare function readMerkleTreeState(connection: Connection, merkleTreePDA: PublicKey, forceConfirmed?: boolean, relayUrl?: string, 
-/** When true, skip relay root and use chain directly (avoids stale relay root causing ProofInvalid) */
-skipRelayRoot?: boolean, mint?: PublicKey): Promise<MerkleTreeState>;
+declare function isDebugEnabled(): boolean;
 /**
- * Compute Merkle proof for a leaf at a given index using on-chain state
- *
- * This works by:
- * 1. Reading the subtrees (frontier) from the on-chain account
- * 2. For each level, determining the sibling:
- *    - If index is odd: sibling is the stored subtree (left sibling)
- *    - If index is even: sibling is either a subsequent subtree or zero value
+ * Logger interface
+ */
+interface Logger {
+    debug: (message: string, kvPairs?: Record<string, unknown>) => void;
+    info: (message: string, kvPairs?: Record<string, unknown>) => void;
+    warn: (message: string, kvPairs?: Record<string, unknown>) => void;
+    error: (message: string, kvPairs?: Record<string, unknown>) => void;
+}
+/**
+ * Create a logger for a specific module
  *
- * Note: This works best for recent leaves where siblings are zero values.
- * For older leaves with non-zero siblings that aren't stored in subtrees,
- * an indexer may still be needed.
+ * @param module - Module name (e.g., "cloak::sdk", "cloak::indexer")
+ * @returns Logger instance with debug, info, warn, error methods
  *
- * @param connection - Solana connection
- * @param merkleTreePDA - PDA of the merkle tree account
- * @param leafIndex - Index of the leaf to compute proof for
- * @param forceConfirmed - If true, forces "confirmed" commitment level for fresh data
- * @returns Merkle proof with path elements and indices
+ * @example
+ * ```typescript
+ * const log = createLogger("cloak::deposit");
+ * log.info("Depositing", { amount: 100000000 });
+ * // Output: 2026-01-23T00:51:46.489000Z  INFO cloak::deposit: Depositing amount=100000000
+ * ```
  */
-declare function computeProofFromChain(connection: Connection, merkleTreePDA: PublicKey, leafIndex: number, forceConfirmed?: boolean): Promise<OnchainMerkleProof>;
+declare function createLogger(module: string): Logger;
 /**
- * Compute proof for the most recently inserted leaf
+ * Measure and return duration of an async operation
  *
- * This is the most reliable case - immediately after your deposit,
- * all siblings to the right are zero values, and siblings to the left
- * are stored in the subtrees.
+ * @param _logger - Logger instance (reserved for future debug logging)
+ * @param _operation - Operation name (reserved for future debug logging)
+ * @param fn - Async function to measure
+ * @returns Result and duration in milliseconds
  */
-declare function computeProofForLatestDeposit(connection: Connection, merkleTreePDA: PublicKey): Promise<OnchainMerkleProof & {
-    leafIndex: number;
+declare function withTiming<T>(_logger: Logger, _operation: string, fn: () => Promise<T>): Promise<{
+    result: T;
+    durationMs: number;
 }>;
-
 /**
- * Merkle Tree implementation for computing proofs
- *
- * This tree stores all leaves and can compute the correct Merkle path
- * for any leaf index.
+ * Format lamports as SOL with proper decimals
  */
-declare const MERKLE_TREE_HEIGHT = 32;
+declare function formatSol(lamports: number | bigint): string;
 /**
- * Merkle Tree class that stores all leaves and computes proofs
+ * Truncate a string (useful for signatures, hashes)
  */
-declare class MerkleTree {
-    private levels;
-    private capacity;
-    private layers;
-    private zeros;
-    private poseidon;
-    /**
-     * Create a new Merkle tree
-     * @param levels Number of levels in the tree (height)
-     * @param leaves Initial leaves to insert
-     * @param zeros Precomputed zero values for each level
-     * @param poseidon Pre-initialized Poseidon instance (avoids async in constructor)
-     */
-    constructor(levels: number, leaves: bigint[], zeros: bigint[], poseidon: any);
+declare function truncate(str: string, len?: number): string;
+/**
+ * Default SDK logger instance
+ */
+declare const sdkLogger: Logger;
+
+/**
+ * Result from submitting a withdrawal that includes the request ID
+ * for potential recovery/resume scenarios
+ */
+interface WithdrawSubmissionResult {
+    /** The relay request ID - persist this for recovery */
+    requestId: string;
+    /** The final transaction signature */
+    signature: string;
+}
+/**
+ * Relay Service Client
+ *
+ * Handles submission of withdrawal transactions through a relay service
+ * that pays for transaction fees and submits the transaction on-chain.
+ */
+declare class RelayService {
+    private baseUrl;
     /**
-     * Create a new MerkleTree with async initialization
+     * Create a new Relay Service client
+     *
+     * @param baseUrl - Relay service base URL
      */
-    static create(levels?: number, leaves?: bigint[]): Promise<MerkleTree>;
+    constructor(baseUrl: string);
     /**
-     * Rebuild the tree from the leaves (synchronous — poseidon must be initialized)
+     * Submit a withdrawal transaction via relay
+     *
+     * The relay service will validate the proof, pay for transaction fees,
+     * and submit the transaction on-chain.
+     *
+     * @param params - Withdrawal parameters
+     * @param onStatusUpdate - Optional callback for status updates
+     * @param onRequestId - CRITICAL: Callback when request_id is received.
+     *                      Persist this ID to recover if browser crashes during polling.
+     * @returns Transaction signature when completed
+     *
+     * @example
+     * ```typescript
+     * const signature = await relay.submitWithdraw({
+     *   proof: proofHex,
+     *   publicInputs: { root, nf, outputs_hash, amount },
+     *   outputs: [{ recipient: addr, amount: lamports }],
+     *   feeBps: 50
+     * }, (status) => console.log(`Status: ${status}`),
+     *    (requestId) => localStorage.setItem('pending_withdraw', requestId));
+     * console.log(`Transaction: ${signature}`);
+     * ```
      */
-    private _rebuildSync;
+    submitWithdraw(params: {
+        proof: string;
+        publicInputs: {
+            root: string;
+            nf: string;
+            outputs_hash: string;
+            amount: number;
+        };
+        outputs: Array<{
+            recipient: string;
+            amount: number;
+        }>;
+        feeBps: number;
+        metadataBundle?: EncryptedMetadataBundle;
+    }, onStatusUpdate?: (status: string) => void, onRequestId?: (requestId: string) => void): Promise<string>;
     /**
-     * Get the tree root
+     * Resume polling for a withdrawal that was previously started
+     *
+     * Use this after page reload to check status of a pending withdrawal.
+     * The requestId should have been persisted via the onRequestId callback.
+     *
+     * @param requestId - Request ID from a previous submitWithdraw call
+     * @param onStatusUpdate - Optional callback for status updates
+     * @returns Transaction signature if completed, null if still pending/failed
+     *
+     * @example
+     * ```typescript
+     * // On page load, check for pending withdrawal
+     * const pendingId = localStorage.getItem('pending_withdraw');
+     * if (pendingId) {
+     *   const result = await relay.resumeWithdraw(pendingId);
+     *   if (result.status === 'completed') {
+     *     console.log('Withdrawal completed:', result.signature);
+     *     localStorage.removeItem('pending_withdraw');
+     *   }
+     * }
+     * ```
      */
-    root(): bigint;
+    resumeWithdraw(requestId: string, onStatusUpdate?: (status: string) => void): Promise<{
+        status: 'completed' | 'failed' | 'pending';
+        signature?: string;
+        error?: string;
+    }>;
     /**
-     * Get the number of leaves in the tree
+     * Poll for withdrawal completion
+     *
+     * @param requestId - Request ID from relay service
+     * @param onStatusUpdate - Optional callback for status updates
+     * @returns Transaction signature when completed
      */
-    get length(): number;
+    private pollForCompletion;
     /**
-     * Insert a new leaf into the tree
+     * Submit a swap transaction via relay
+     *
+     * Similar to submitWithdraw but includes swap parameters for token swaps.
+     * The relay service will validate the proof, execute the swap, pay for fees,
+     * and submit the transaction on-chain.
+     *
+     * @param params - Swap parameters
+     * @param onStatusUpdate - Optional callback for status updates
+     * @returns Transaction signature when completed
+     *
+     * @example
+     * ```typescript
+     * const signature = await relay.submitSwap({
+     *   proof: proofHex,
+     *   publicInputs: { root, nf, outputs_hash, amount },
+     *   outputs: [{ recipient: addr, amount: lamports }],
+     *   feeBps: 50,
+     *   swap: {
+     *     output_mint: tokenMint.toBase58(),
+     *     slippage_bps: 100,
+     *     min_output_amount: minAmount
+     *   }
+     * }, (status) => console.log(`Status: ${status}`));
+     * console.log(`Transaction: ${signature}`);
+     * ```
      */
-    insert(leaf: bigint): void;
+    submitSwap(params: {
+        proof: string;
+        publicInputs: {
+            root: string;
+            nf: string;
+            outputs_hash: string;
+            amount: number;
+        };
+        outputs: Array<{
+            recipient: string;
+            amount: number;
+        }>;
+        feeBps: number;
+        swap: {
+            output_mint: string;
+            slippage_bps: number;
+            min_output_amount: number;
+        };
+        metadataBundle?: EncryptedMetadataBundle;
+    }, onStatusUpdate?: (status: string) => void, onRequestId?: (requestId: string) => void): Promise<string>;
     /**
-     * Insert multiple leaves
+     * Get transaction status
+     *
+     * @param requestId - Request ID from previous submission
+     * @returns Current status
+     *
+     * @example
+     * ```typescript
+     * const status = await relay.getStatus(requestId);
+     * console.log(`Status: ${status.status}`);
+     * if (status.status === 'completed') {
+     *   console.log(`TX: ${status.txId}`);
+     * }
+     * ```
      */
-    bulkInsert(leaves: bigint[]): void;
+    getStatus(requestId: string): Promise<TxStatus>;
     /**
-     * Update the path from a leaf to the root
+     * Register viewing key with relay for compliance decryption.
+     * This is a one-time operation - the viewing key is stored by the relay.
+     *
+     * The user must sign a one-time relay challenge proving wallet ownership.
+     *
+     * @param userPubkey - User's wallet public key (base58)
+     * @param viewingKey - Viewing key private key (32 bytes, hex encoded)
+     * @param signMessage - Function to sign challenge message bytes
+     *
+     * @example
+     * ```typescript
+     * await relay.registerViewingKey(
+     *   userPublicKey.toBase58(),
+     *   viewingKeyHex,
+     *   signatureBase64
+     * );
+     * ```
      */
-    private _updatePath;
+    registerViewingKey(userPubkey: string, viewingKey: string, signMessage: (message: Uint8Array) => Promise<Uint8Array>): Promise<boolean>;
     /**
-     * Get the Merkle path for a leaf at the given index
-     * @param index Leaf index
-     * @returns pathElements and pathIndices for the proof
+     * Fetch relay compliance master public key.
+     * DEPRECATED: This endpoint is no longer used
      */
-    path(index: number): {
-        pathElements: bigint[];
-        pathIndices: number;
-    };
+    getCompliancePublicKey(): Promise<Uint8Array>;
     /**
-     * Find the index of a leaf in the tree
-     * @param leaf Leaf value to find
-     * @returns Index if found, -1 otherwise
+     * Convert bytes to base64 string
      */
-    indexOf(leaf: bigint): number;
+    private bytesToBase64;
     /**
-     * Get all leaves
+     * Sleep utility
      */
-    leaves(): bigint[];
+    private sleep;
+    private computeViewingKeyIdentifier;
 }
+
 /**
- * Build a MerkleTree from commitment values
- * @param commitments Array of commitment bigints
- * @param height Tree height (default: 32)
+ * Risk Oracle Service
+ *
+ * Self-contained module for fetching Switchboard risk quote instructions
+ * using the Range Risk API. Eliminates the need for an external web endpoint
+ * (e.g. `/api/risk-quote`) by calling Switchboard directly from the SDK.
+ *
+ * Uses dynamic imports for @switchboard-xyz packages so they are only loaded
+ * when fetchRiskQuoteIx is actually called — not at SDK import time. This
+ * prevents the heavy Node.js-only Switchboard code from being bundled into
+ * browser builds (Next.js, etc.).
+ *
+ * Usage:
+ *   const { instruction, queue } = await fetchRiskQuoteIx(connection, wallet, rangeApiKey);
  */
-declare function buildMerkleTree(commitments: bigint[], height?: number): Promise<MerkleTree>;
 
 /**
- * Relay client utilities for fetching data from the relay service
+ * Fetch a Switchboard risk quote instruction directly from Range + Switchboard.
+ *
+ * This removes the need for an external `/api/risk-quote` endpoint. The SDK
+ * calls Switchboard's crossbar oracle network directly with the Range API key.
+ *
+ * @param connection - Solana RPC connection
+ * @param wallet - Depositor's public key (the wallet being risk-scored)
+ * @param rangeApiKey - Range.org API key for the risk score lookup
+ * @returns The Ed25519 sig-verify instruction to prepend at index 0, plus the queue pubkey
  */
-
-interface CommitmentEntry {
-    index: number;
+declare function fetchRiskQuoteIx(connection: Connection, wallet: PublicKey, rangeApiKey: string): Promise<{
+    instruction: TransactionInstruction;
+    queue: PublicKey;
+}>;
+
+/**
+ * Encrypted Output Helpers
+ *
+ * Functions for creating encrypted outputs that enable note scanning
+ */
+
+/**
+ * Prepare encrypted output for scanning by wallet owner
+ *
+ * @param note - Note to encrypt
+ * @param cloakKeys - Wallet's Cloak keys (for self-encryption)
+ * @returns Base64-encoded encrypted output
+ */
+declare function prepareEncryptedOutput(note: CloakNote, cloakKeys: CloakKeyPair): string;
+/**
+ * Prepare encrypted output for a specific recipient
+ *
+ * @param note - Note to encrypt
+ * @param recipientPvkHex - Recipient's public view key (hex)
+ * @returns Base64-encoded encrypted output
+ */
+declare function prepareEncryptedOutputForRecipient(note: CloakNote, recipientPvkHex: string): string;
+/**
+ * Simple base64 encoding for v1.0 notes (no encryption)
+ *
+ * @param note - Note to encode
+ * @returns Base64-encoded note data
+ */
+declare function encodeNoteSimple(note: CloakNote): string;
+
+/**
+ * Wallet Integration Helpers
+ *
+ * Helper functions for working with Solana Wallet Adapters
+ */
+
+/**
+ * Validate wallet is connected and has public key
+ */
+declare function validateWalletConnected(wallet: WalletAdapter | Keypair): void;
+/**
+ * Get public key from wallet or keypair
+ */
+declare function getPublicKey(wallet: WalletAdapter | Keypair): PublicKey;
+/**
+ * Send transaction using wallet adapter or keypair
+ */
+declare function sendTransaction(transaction: Transaction, wallet: WalletAdapter | Keypair, connection: Connection, options?: SendOptions): Promise<string>;
+/**
+ * Sign transaction using wallet adapter or keypair
+ */
+declare function signTransaction<T extends Transaction>(transaction: T, wallet: WalletAdapter | Keypair): Promise<T>;
+/**
+ * Create a keypair adapter for testing
+ */
+declare function keypairToAdapter(keypair: Keypair): WalletAdapter;
+
+/**
+ * Create a deposit instruction
+ *
+ * Deposits SOL into the Cloak protocol by creating a commitment.
+ *
+ * Instruction format:
+ * - Byte 0: Discriminant (0x01 for Deposit, per ShieldPoolInstruction enum)
+ * - Bytes 1-8: Amount (u64, little-endian)
+ * - Bytes 9-40: Commitment (32 bytes)
+ *
+ * @param params - Deposit parameters
+ * @returns Transaction instruction
+ *
+ * @example
+ * ```typescript
+ * const instruction = createDepositInstruction({
+ *   programId: CLOAK_PROGRAM_ID,
+ *   payer: wallet.publicKey,
+ *   pool: POOL_ADDRESS,
+ *   commitments: COMMITMENTS_ADDRESS,
+ *   amount: 1_000_000_000, // 1 SOL
+ *   commitment: commitmentBytes
+ * });
+ * ```
+ */
+declare function createDepositInstruction(params: {
+    programId: PublicKey;
+    payer: PublicKey;
+    pool: PublicKey;
+    merkleTree: PublicKey;
+    amount: number;
+    commitment: Uint8Array;
+}): TransactionInstruction;
+/**
+ * Deposit instruction parameters for type safety
+ */
+interface DepositInstructionParams {
+    programId: PublicKey;
+    payer: PublicKey;
+    pool: PublicKey;
+    merkleTree: PublicKey;
+    amount: number;
+    commitment: Uint8Array;
+}
+/**
+ * Validate deposit instruction parameters
+ *
+ * @param params - Parameters to validate
+ * @throws Error if invalid
+ */
+declare function validateDepositParams(params: DepositInstructionParams): void;
+
+/**
+ * Program Derived Address (PDA) utilities for Shield Pool
+ *
+ * These functions derive deterministic addresses from the program ID and seeds.
+ * This matches the behavior in tooling/test/src/shared.rs::get_pda_addresses()
+ */
+
+interface ShieldPoolPDAs {
+    pool: PublicKey;
+    merkleTree: PublicKey;
+    vaultAuthority: PublicKey;
+    treasury: PublicKey;
+}
+/**
+ * Derive all Shield Pool PDAs from program ID + pool mint
+ *
+ * Seeds match the on-chain mint-scoped program:
+ * - pool: [b"pool", mint]
+ * - merkle_tree: [b"merkle_tree", mint]
+ * - treasury: [b"treasury", mint]
+ * - vault_authority: [b"vault_authority", mint]
+ *
+ * @param programId - Optional program ID (defaults to CLOAK_PROGRAM_ID)
+ * @param mint - Pool mint (defaults to NATIVE_SOL_MINT / WSOL sentinel)
+ */
+declare function getShieldPoolPDAs(programId?: PublicKey, mint?: PublicKey): ShieldPoolPDAs;
+/**
+ * Derive the nullifier PDA for a specific pool + nullifier hash.
+ *
+ * With the new PDA-per-nullifier design, each nullifier has its own PDA
+ * instead of being stored in a shared shard. The PDA is created when
+ * the nullifier is used during withdrawal.
+ *
+ * Seeds: ["nullifier", pool_pubkey, nullifier_hash]
+ *
+ * @param poolPubkey - Pool PDA that scopes nullifier domain
+ * @param nullifier - 32-byte nullifier hash
+ * @param programId - Optional program ID (defaults to CLOAK_PROGRAM_ID)
+ * @returns [PublicKey, bump] - The nullifier PDA and its bump seed
+ */
+declare function getNullifierPDA(poolPubkey: PublicKey, nullifier: Uint8Array | Buffer, programId?: PublicKey): [PublicKey, number];
+/**
+ * Derive the swap state PDA for a given pool + nullifier.
+ *
+ * Seeds: ["swap_state", pool_pubkey, nullifier_hash]
+ *
+ * @param poolPubkey - Pool PDA used for swap state domain separation
+ * @param nullifier - 32-byte nullifier hash
+ * @param programId - Optional program ID (defaults to CLOAK_PROGRAM_ID)
+ * @returns [PublicKey, bump] - The swap state PDA and its bump seed
+ */
+declare function getSwapStatePDA(poolPubkey: PublicKey, nullifier: Uint8Array | Buffer, programId?: PublicKey): [PublicKey, number];
+
+/**
+ * On-chain Merkle proof computation
+ *
+ * Computes Merkle proofs directly from on-chain tree state,
+ * eliminating the need for an indexer for proof generation.
+ */
+
+/**
+ * Merkle proof result
+ */
+interface OnchainMerkleProof {
+    pathElements: string[];
+    pathIndices: number[];
+    root: string;
+}
+interface MerkleTreeState {
+    nextIndex: number;
+    root: string;
+    subtrees: string[];
+}
+/**
+ * Read the Merkle tree state from on-chain account
+ * @param forceConfirmed - If true, forces "confirmed" commitment level for fresh data
+ * @param relayUrl - Optional relay URL to query for current root (bypasses RPC caching)
+ * @param mint - Optional pool mint used when querying relay /merkle-root
+ */
+declare function readMerkleTreeState(connection: Connection, merkleTreePDA: PublicKey, forceConfirmed?: boolean, relayUrl?: string, 
+/** When true, skip relay root and use chain directly (avoids stale relay root causing ProofInvalid) */
+skipRelayRoot?: boolean, mint?: PublicKey): Promise<MerkleTreeState>;
+/**
+ * Compute Merkle proof for a leaf at a given index using on-chain state
+ *
+ * This works by:
+ * 1. Reading the subtrees (frontier) from the on-chain account
+ * 2. For each level, determining the sibling:
+ *    - If index is odd: sibling is the stored subtree (left sibling)
+ *    - If index is even: sibling is either a subsequent subtree or zero value
+ *
+ * Note: This works best for recent leaves where siblings are zero values.
+ * For older leaves with non-zero siblings that aren't stored in subtrees,
+ * an indexer may still be needed.
+ *
+ * @param connection - Solana connection
+ * @param merkleTreePDA - PDA of the merkle tree account
+ * @param leafIndex - Index of the leaf to compute proof for
+ * @param forceConfirmed - If true, forces "confirmed" commitment level for fresh data
+ * @returns Merkle proof with path elements and indices
+ */
+declare function computeProofFromChain(connection: Connection, merkleTreePDA: PublicKey, leafIndex: number, forceConfirmed?: boolean): Promise<OnchainMerkleProof>;
+/**
+ * Compute proof for the most recently inserted leaf
+ *
+ * This is the most reliable case - immediately after your deposit,
+ * all siblings to the right are zero values, and siblings to the left
+ * are stored in the subtrees.
+ */
+declare function computeProofForLatestDeposit(connection: Connection, merkleTreePDA: PublicKey): Promise<OnchainMerkleProof & {
+    leafIndex: number;
+}>;
+
+/**
+ * Relay client utilities for fetching data from the relay service
+ */
+
+interface CommitmentEntry {
+    index: number;
     commitment: string;
 }
 interface CommitmentsResponse {
@@ -2316,490 +2712,228 @@ interface WithdrawRegularInputs {
     rem: bigint;
 }
 interface WithdrawSwapInputs {
-    sk_spend: bigint;
-    r: bigint;
-    amount: bigint;
-    leaf_index: bigint;
-    path_elements: bigint[];
-    path_indices: number[];
-    root: bigint;
-    nullifier: bigint;
-    outputs_hash: bigint;
-    public_amount: bigint;
-    input_mint: bigint[];
-    output_mint: bigint[];
-    recipient_ata: bigint[];
-    min_output_amount: bigint;
-    var_fee: bigint;
-    rem: bigint;
-}
-interface ProofResult {
-    proof: Groth16Proof;
-    publicSignals: string[];
-    proofBytes: Uint8Array;
-    publicInputsBytes: Uint8Array;
-}
-/**
- * Generate Groth16 proof for regular withdrawal using Circom WASM
- *
- * This matches the approach in services-new/tests/src/proof.ts
- *
- * @param inputs - Circuit inputs
- * @param circuitsPath - Ignored. Proof generation always uses pinned S3 circuits.
- */
-declare function generateWithdrawRegularProof(inputs: WithdrawRegularInputs, circuitsPath: string): Promise<ProofResult>;
-/**
- * Generate Groth16 proof for swap withdrawal using Circom WASM
- *
- * This matches the approach in services-new/tests/src/proof.ts
- *
- * @param inputs - Circuit inputs
- * @param circuitsPath - Ignored. Proof generation always uses pinned S3 circuits.
- */
-declare function generateWithdrawSwapProof(inputs: WithdrawSwapInputs, circuitsPath: string): Promise<ProofResult>;
-/**
- * Check if circuits are available from the pinned S3 source.
- */
-declare function areCircuitsAvailable(circuitsPath: string): Promise<boolean>;
-/**
- * Get default circuits URL.
- */
-declare function getDefaultCircuitsPath(): Promise<string>;
-/**
- * Pinned circuit artifact hashes (SHA-256).
- *
- * These hashes must be updated whenever the trusted circuit artifacts change.
- */
-declare const EXPECTED_CIRCUIT_HASHES: {
-    withdraw_regular_wasm: string;
-    withdraw_regular_zkey: string;
-    withdraw_swap_wasm: string;
-    withdraw_swap_zkey: string;
-};
-/**
- * Circuit verification result
- */
-interface CircuitVerificationResult {
-    /** Whether verification passed */
-    valid: boolean;
-    /** Which circuit was checked */
-    circuit: 'withdraw_regular' | 'withdraw_swap';
-    /** Error message if verification failed */
-    error?: string;
-    computed?: {
-        wasm: string;
-        zkey: string;
-    };
-    expected?: {
-        wasm: string;
-        zkey: string;
-    };
-}
-/**
- * Verify circuit integrity by checking verification key hashes
- *
- * This function fetches the verification key and computes its hash,
- * then compares against the expected hash embedded in the SDK.
- *
- * IMPORTANT: If the hashes don't match, the circuit may produce proofs
- * that will be rejected by the on-chain verifier!
- *
- * @param circuitsPath - Ignored. Verification always uses pinned S3 circuits.
- * @param circuit - Which circuit to verify ('withdraw_regular' or 'withdraw_swap')
- * @returns Verification result
- *
- * @example
- * ```typescript
- * const result = await verifyCircuitIntegrity('https://cloak-circuits.s3.us-east-1.amazonaws.com/circuits/0.1.0', 'withdraw_regular');
- * if (!result.valid) {
- *   console.error('Circuit verification failed:', result.error);
- *   // Don't proceed with proof generation!
- * }
- * ```
- */
-declare function verifyCircuitIntegrity(circuitsPath: string, circuit: 'withdraw_regular' | 'withdraw_swap'): Promise<CircuitVerificationResult>;
-/**
- * Verify all circuits before use
- *
- * Call this at SDK initialization to ensure circuits are valid.
- *
- * @param circuitsPath - Ignored. Verification always uses pinned S3 circuits.
- * @returns Array of verification results (one per circuit)
- */
-declare function verifyAllCircuits(circuitsPath: string): Promise<CircuitVerificationResult[]>;
-
-/**
- * Pending Operations Manager
- *
- * Utility for persisting pending deposit/withdrawal operations in browser storage.
- * This enables recovery if the browser crashes or user navigates away mid-operation.
- *
- * IMPORTANT: This uses localStorage by default which has security implications.
- * Notes contain sensitive spending keys - consider using more secure storage
- * in production (e.g., encrypted IndexedDB, secure enclave).
- */
-
-/**
- * Pending deposit record
- */
-interface PendingDeposit {
-    /** The note (contains spending secrets!) */
-    note: CloakNote;
-    /** When the deposit was initiated */
-    startedAt: number;
-    /** Transaction signature if available */
-    txSignature?: string;
-    /** Status of the deposit */
-    status: "pending" | "tx_sent" | "confirmed" | "failed";
-    /** Error message if failed */
-    error?: string;
-}
-/**
- * Pending withdrawal record
- */
-interface PendingWithdrawal {
-    /** The relay request ID (for resumption) */
-    requestId: string;
-    /** The note commitment being withdrawn */
-    commitment: string;
-    /** The nullifier being used */
-    nullifier: string;
-    /** When the withdrawal was initiated */
-    startedAt: number;
-    /** Status of the withdrawal */
-    status: "pending" | "processing" | "completed" | "failed";
-    /** Transaction signature if completed */
-    txSignature?: string;
-    /** Error message if failed */
-    error?: string;
-}
-/**
- * Save a pending deposit
- * Call this BEFORE sending the on-chain transaction to ensure note is persisted
- */
-declare function savePendingDeposit(deposit: PendingDeposit): void;
-/**
- * Load all pending deposits
- */
-declare function loadPendingDeposits(): PendingDeposit[];
-/**
- * Update a pending deposit status
- */
-declare function updatePendingDeposit(commitment: string, updates: Partial<PendingDeposit>): void;
-/**
- * Remove a pending deposit (e.g., after successful confirmation)
- */
-declare function removePendingDeposit(commitment: string): void;
-/**
- * Clear all pending deposits
- */
-declare function clearPendingDeposits(): void;
-/**
- * Save a pending withdrawal
- * Call this when you receive the request_id from the relay
- */
-declare function savePendingWithdrawal(withdrawal: PendingWithdrawal): void;
-/**
- * Load all pending withdrawals
- */
-declare function loadPendingWithdrawals(): PendingWithdrawal[];
-/**
- * Update a pending withdrawal status
- */
-declare function updatePendingWithdrawal(requestId: string, updates: Partial<PendingWithdrawal>): void;
-/**
- * Remove a pending withdrawal (e.g., after successful completion)
- */
-declare function removePendingWithdrawal(requestId: string): void;
-/**
- * Clear all pending withdrawals
- */
-declare function clearPendingWithdrawals(): void;
-/**
- * Check if there are any pending operations that need recovery
- * Call this on page load to determine if recovery UI should be shown
- */
-declare function hasPendingOperations(): boolean;
-/**
- * Get summary of pending operations for recovery UI
- */
-declare function getPendingOperationsSummary(): {
-    deposits: PendingDeposit[];
-    withdrawals: PendingWithdrawal[];
-    totalPending: number;
-};
-/**
- * Clean up stale pending operations
- * Call this periodically to remove old failed/completed operations
- *
- * @param maxAgeMs Maximum age in milliseconds before an operation is removed (default: 24 hours)
- */
-declare function cleanupStalePendingOperations(maxAgeMs?: number): {
-    removedDeposits: number;
-    removedWithdrawals: number;
-};
-
-/**
- * UTXO (Unspent Transaction Output) Model
- *
- * This module implements the UTXO model for the Cloak privacy protocol.
- * UTXOs allow for:
- * - Shield-to-shield transfers (privacy preserved)
- * - Partial withdrawals (change stays shielded)
- * - Combining multiple small deposits
- * - Multi-token support (SOL + any SPL token)
- */
-
-declare const NATIVE_SOL_MINT: PublicKey;
-/**
- * UTXO Keypair for ownership verification
- *
- * Uses Poseidon hash for key derivation:
- * - privateKey: random field element (kept secret)
- * - publicKey: Poseidon(privateKey, 0) - can be shared
- */
-interface UtxoKeypair {
-    /** Private key (random 252-bit field element) */
-    privateKey: bigint;
-    /** Public key derived as Poseidon(privateKey, 0) */
-    publicKey: bigint;
-}
-/**
- * UTXO represents an unspent transaction output
- *
- * Contains all information needed to spend the UTXO:
- * - amount: Value in the smallest unit (lamports for SOL)
- * - keypair: Ownership keys
- * - blinding: Randomness for hiding
- * - mintAddress: Token type (SOL or SPL token)
- * - index: Leaf index in Merkle tree (set after deposit/creation)
- */
-interface Utxo {
-    /** Amount in the smallest unit (lamports for SOL, token units for SPL) */
-    amount: bigint;
-    /** Keypair for ownership */
-    keypair: UtxoKeypair;
-    /** Random blinding factor */
-    blinding: bigint;
-    /** Token mint address (NATIVE_SOL_MINT for SOL) */
-    mintAddress: PublicKey;
-    /** Leaf index in Merkle tree (set after the UTXO is in the tree) */
-    index?: number;
-    /** Commitment hash (computed from amount, pubkey, blinding, mint) */
-    commitment?: bigint;
-    /** Nullifier hash (computed when spending) */
-    nullifier?: bigint;
-    /**
-     * Sibling commitment at level 0 of the Merkle tree.
-     * Required for Merkle proofs since siblings aren't stored on-chain.
-     * This is the commitment of the other output in the same transaction.
-     */
-    siblingCommitment?: bigint;
-}
-/**
- * Encrypted UTXO note for recipient discovery
- *
- * When creating an output UTXO for someone else, the data is encrypted
- * so only the recipient can discover and spend it.
- */
-interface EncryptedNote {
-    /** Encrypted UTXO data (ECIES/ChaCha20 encrypted) */
-    ciphertext: Uint8Array;
-    /** Ephemeral public key for ECDH */
-    ephemeralPubkey: Uint8Array;
-    /** MAC for integrity verification */
-    mac: Uint8Array;
-}
-/**
- * Transaction parameters for a UTXO transaction
- */
-interface TransactParams {
-    /** Input UTXOs to spend (max 2) */
-    inputUtxos: Utxo[];
-    /** Output UTXOs to create (max 2) */
-    outputUtxos: Utxo[];
-    /** External recipient for withdrawal (optional) */
-    recipient?: PublicKey;
-    /** Net external amount: positive = deposit, negative = withdraw */
-    externalAmount?: bigint;
-    /** Depositor address (for deposits, the source of funds) */
-    depositor?: PublicKey;
-}
-/**
- * Result from a UTXO transaction
- */
-interface TransactResult {
-    /** Transaction signature */
-    signature: string;
-    /** Nullifiers of spent inputs */
-    inputNullifiers: bigint[];
-    /** Commitments of created outputs */
-    outputCommitments: bigint[];
-    /** New Merkle root after the transaction */
-    newRoot: string;
-    /** Merkle tree indices where output commitments were inserted */
-    commitmentIndices: [number, number];
-    /**
-     * Sibling commitments for each output.
-     * For output[0], sibling is output[1] and vice versa.
-     * These are needed for Merkle proofs since siblings aren't stored on-chain.
-     */
-    siblingCommitments: [bigint, bigint];
-    /**
-     * Left sibling from before the transaction (for odd-index handling).
-     * When the first output ends up at an odd index due to concurrent access,
-     * its sibling at index-1 comes from a previous transaction.
-     * This value captures subtrees[0] before our transaction to enable
-     * correct Merkle proof computation for odd indices.
-     */
-    preTransactionLeftSibling?: bigint;
-    /**
-     * The actual output UTXOs created by this transaction.
-     * These have all the data needed to spend them later (keypair, blinding, etc).
-     * The UTXOs are already updated with their indices and sibling commitments.
-     */
-    outputUtxos: Utxo[];
-    /**
-     * Whether the viewing key was registered with the relay for compliance.
-     * True on first transaction when metadataBundle includes viewing_key.
-     * Once registered, subsequent transactions don't need to send metadataBundle.
-     */
-    viewingKeyRegistered?: boolean;
-    /**
-     * The Merkle tree used/built for this transaction, with output commitments inserted.
-     * Pass this as `cachedMerkleTree` in the next transaction to skip relay fetching
-     * and avoid needing `waitForCommitmentIndex`.
-     */
-    merkleTree?: MerkleTree;
-    /**
-     * Address lookup table used for v0 transaction (when chain notes or risk oracle require it).
-     * Pass this as `addressLookupTableAccounts` in the next deposit to avoid creating a new ALT.
-     */
-    addressLookupTableAccounts?: AddressLookupTableAccount[];
+    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 a random field element suitable for BN254
- */
-declare function randomFieldElement(): bigint;
-/**
- * Generate a new UTXO keypair
+ * Generate Groth16 proof for regular withdrawal using Circom WASM
  *
- * @returns A new keypair with random private key and derived public key
+ * 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 generateUtxoKeypair(): Promise<UtxoKeypair>;
+declare function generateWithdrawRegularProof(inputs: WithdrawRegularInputs, circuitsPath: string): Promise<ProofResult>;
 /**
- * Derive a deterministic UTXO keypair from a wallet's spend key.
- * Use this for deposits and change outputs so all chain notes use the same nk,
- * enabling the compliance scan (scanTransactions + toComplianceReport) to decrypt them.
+ * Generate Groth16 proof for swap withdrawal using Circom WASM
  *
- * @param skSpend - 32-byte spend key (from wallet key derivation)
- * @returns UtxoKeypair with deterministic private/public keys
+ * 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 deriveUtxoKeypairFromSpendKey(skSpend: Uint8Array): Promise<UtxoKeypair>;
+declare function generateWithdrawSwapProof(inputs: WithdrawSwapInputs, circuitsPath: string): Promise<ProofResult>;
 /**
- * Derive public key from private key
- *
- * @param privateKey The private key
- * @returns The corresponding public key
+ * Check if circuits are available from the pinned S3 source.
  */
-declare function derivePublicKey(privateKey: bigint): Promise<bigint>;
+declare function areCircuitsAvailable(circuitsPath: string): Promise<boolean>;
 /**
- * Create a new UTXO
- *
- * @param amount Amount in smallest unit
- * @param keypair Owner's keypair
- * @param mintAddress Token mint (defaults to native SOL)
- * @returns A new UTXO (commitment will be computed)
+ * Get default circuits URL.
  */
-declare function createUtxo(amount: bigint, keypair: UtxoKeypair, mintAddress?: PublicKey): Promise<Utxo>;
+declare function getDefaultCircuitsPath(): Promise<string>;
 /**
- * Create a zero/padding UTXO
- *
- * Zero UTXOs are used as padding when we need fewer than 2 inputs/outputs.
- * They have zero amount and don't require valid Merkle proofs.
- * Uses salt-based keypair (privateKey = salt) with blinding=0 to match the circuit
- * test. By default, salt is random to avoid cross-process collisions under concurrency.
- * Callers can pass an explicit salt for deterministic behavior.
+ * Pinned circuit artifact hashes (SHA-256).
  *
- * @param mintAddress Token mint (defaults to native SOL)
- * @param salt Optional salt; if omitted, uses timestamp+counter for uniqueness
+ * These hashes must be updated whenever the trusted circuit artifacts change.
  */
-declare function createZeroUtxo(mintAddress?: PublicKey, salt?: bigint): Promise<Utxo>;
+declare const EXPECTED_CIRCUIT_HASHES: {
+    withdraw_regular_wasm: string;
+    withdraw_regular_zkey: string;
+    withdraw_swap_wasm: string;
+    withdraw_swap_zkey: string;
+};
 /**
- * Convert PublicKey to field element for circuit
- *
- * @param pubkey Solana PublicKey
- * @returns Field element representation
+ * Circuit verification result
  */
-declare function pubkeyToFieldElement(pubkey: PublicKey): bigint;
+interface CircuitVerificationResult {
+    /** Whether verification passed */
+    valid: boolean;
+    /** Which circuit was checked */
+    circuit: 'withdraw_regular' | 'withdraw_swap';
+    /** Error message if verification failed */
+    error?: string;
+    computed?: {
+        wasm: string;
+        zkey: string;
+    };
+    expected?: {
+        wasm: string;
+        zkey: string;
+    };
+}
 /**
- * Compute the commitment for a UTXO
+ * Verify circuit integrity by checking verification key hashes
  *
- * commitment = Poseidon(amount, pubkey, blinding, mintAddress)
+ * This function fetches the verification key and computes its hash,
+ * then compares against the expected hash embedded in the SDK.
  *
- * @param utxo The UTXO to compute commitment for
- * @returns The commitment as a bigint
+ * IMPORTANT: If the hashes don't match, the circuit may produce proofs
+ * that will be rejected by the on-chain verifier!
+ *
+ * @param circuitsPath - Ignored. Verification always uses pinned S3 circuits.
+ * @param circuit - Which circuit to verify ('withdraw_regular' or 'withdraw_swap')
+ * @returns Verification result
+ *
+ * @example
+ * ```typescript
+ * const result = await verifyCircuitIntegrity('https://cloak-circuits.s3.us-east-1.amazonaws.com/circuits/0.1.0', 'withdraw_regular');
+ * if (!result.valid) {
+ *   console.error('Circuit verification failed:', result.error);
+ *   // Don't proceed with proof generation!
+ * }
+ * ```
  */
-declare function computeCommitment(utxo: Utxo): Promise<bigint>;
+declare function verifyCircuitIntegrity(circuitsPath: string, circuit: 'withdraw_regular' | 'withdraw_swap'): Promise<CircuitVerificationResult>;
 /**
- * Compute the signature for nullifier derivation
+ * Verify all circuits before use
  *
- * signature = Poseidon(privateKey, commitment, pathIndex)
+ * Call this at SDK initialization to ensure circuits are valid.
  *
- * @param privateKey Owner's private key
- * @param commitment The UTXO commitment
- * @param pathIndex Merkle tree path index
- * @returns The signature
+ * @param circuitsPath - Ignored. Verification always uses pinned S3 circuits.
+ * @returns Array of verification results (one per circuit)
  */
-declare function computeSignature(privateKey: bigint, commitment: bigint, pathIndex: bigint): Promise<bigint>;
+declare function verifyAllCircuits(circuitsPath: string): Promise<CircuitVerificationResult[]>;
+
 /**
- * Compute the nullifier for a UTXO
- *
- * nullifier = Poseidon(commitment, pathIndex, signature)
+ * Pending Operations Manager
  *
- * The nullifier is a unique identifier that gets recorded on-chain
- * to prevent double-spending.
+ * Utility for persisting pending deposit/withdrawal operations in browser storage.
+ * This enables recovery if the browser crashes or user navigates away mid-operation.
  *
- * @param utxo The UTXO being spent
- * @returns The nullifier
+ * 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).
  */
-declare function computeNullifier(utxo: Utxo): Promise<bigint>;
+
 /**
- * Serialize a UTXO to bytes for encryption
+ * Pending deposit record
  */
-declare function serializeUtxo(utxo: Utxo): Uint8Array;
+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;
+}
 /**
- * Deserialize a UTXO from bytes
+ * Pending withdrawal record
  */
-declare function deserializeUtxo(bytes: Uint8Array): Promise<Utxo>;
+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;
+}
 /**
- * Convert bigint to hex string (64 chars, padded)
+ * Save a pending deposit
+ * Call this BEFORE sending the on-chain transaction to ensure note is persisted
  */
-declare function bigintToHex(value: bigint): string;
+declare function savePendingDeposit(deposit: PendingDeposit): void;
 /**
- * Convert hex string to bigint
+ * Load all pending deposits
  */
-declare function hexToBigint(hex: string): bigint;
+declare function loadPendingDeposits(): PendingDeposit[];
 /**
- * Convert bigint to 32-byte array (big-endian for circuits)
+ * Update a pending deposit status
  */
-declare function bigintToBytes32(value: bigint): Uint8Array;
+declare function updatePendingDeposit(commitment: string, updates: Partial<PendingDeposit>): void;
 /**
- * Check if two UTXOs are equal (same commitment)
+ * Remove a pending deposit (e.g., after successful confirmation)
  */
-declare function utxoEquals(a: Utxo, b: Utxo): Promise<boolean>;
+declare function removePendingDeposit(commitment: string): void;
 /**
- * Calculate total amount from an array of UTXOs
+ * Clear all pending deposits
  */
-declare function sumUtxoAmounts(utxos: Utxo[]): bigint;
+declare function clearPendingDeposits(): void;
 /**
- * Select UTXOs to cover a target amount
+ * 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 available Available UTXOs (sorted by amount descending)
- * @param targetAmount Target amount to cover
- * @returns Selected UTXOs that cover the target, or null if insufficient
+ * @param maxAgeMs Maximum age in milliseconds before an operation is removed (default: 24 hours)
  */
-declare function selectUtxos(available: Utxo[], targetAmount: bigint): Utxo[] | null;
+declare function cleanupStalePendingOperations(maxAgeMs?: number): {
+    removedDeposits: number;
+    removedWithdrawals: number;
+};
 
 /**
  * UTXO Transaction Methods
@@ -3426,8 +3560,8 @@ declare class SimpleWallet {
  * @packageDocumentation
  */
 
-declare const VERSION = "1.0.0";
+declare const VERSION = "0.1.5";
 /** True when scanner supports TransactSwap (tag 1). Check this to verify the correct SDK bundle is loaded. */
 declare const SCANNER_SUPPORTS_TRANSACT_SWAP = true;
 
-export { CLOAK_PROGRAM_ID, type ChainNoteTxType, type CircuitVerificationResult, type CloakConfig, CloakError, type CloakKeyPair, type CloakNote, CloakSDK, type CommitmentEntry, type CommitmentsResponse, type CompactChainNote, type ComplianceReport, type ComplianceTxType, DEFAULT_CIRCUITS_URL, DEFAULT_TRANSACTION_CIRCUITS_URL, type DepositInstructionParams, type DepositOptions, type DepositResult, type DepositStatus, EXPECTED_CIRCUIT_HASHES, type EncryptedMetadataBundle, type EncryptedNote$1 as EncryptedNote, type ErrorCategory, type ExpandedSpendKey, FIXED_FEE_LAMPORTS, type Groth16Proof, LAMPORTS_PER_SOL, LocalStorageAdapter, type LogLevel, type Logger, MERKLE_TREE_HEIGHT, MIN_DEPOSIT_LAMPORTS, type MasterKey, type MaxLengthArray, MemoryStorageAdapter, type MerkleProof, type MerkleRootResponse, MerkleTree, NATIVE_SOL_MINT, type Network, type NoteData, type OnchainMerkleProof, type PendingDeposit, type PendingWithdrawal, type ProofResult, RelayService, type RiskQuoteInstructionResponse, RootNotFoundError, SCANNER_SUPPORTS_TRANSACT_SWAP, SIGN_IN_MESSAGE, type ScanOptions, type ScanResult, type ScanSummary, type ScannedTransaction, ShieldPoolErrors, type ShieldPoolPDAs, SimpleWallet, type SpendKey, type StorageAdapter, type SwapOptions, type SwapParams, type SwapResult, type TransactOptions, type TransactParams, type TransactResult, type TransactionMetadata, type Transfer, type TransferOptions, type TransferResult, type TxStatus, type UserFriendlyError, type Utxo, type EncryptedNote as UtxoEncryptedNote, type UtxoKeypair, type UtxoSwapParams, type UtxoSwapResult, UtxoWallet, VARIABLE_FEE_DENOMINATOR, VARIABLE_FEE_NUMERATOR, VARIABLE_FEE_RATE, VERSION, type ViewKey, type ViewingKeyPair, type WalletAdapter, type WalletUtxo, type WithdrawOptions, type WithdrawRegularInputs, type WithdrawSubmissionResult, type WithdrawSwapInputs, areCircuitsAvailable, bigintToBytes32$1 as bigintToBytes32, bigintToHex, buildMerkleTree, buildMerkleTreeFromChain, buildMerkleTreeFromRelay, buildPublicInputsBytes, bytesToHex, calculateFee, calculateFeeBigint, calculateRelayFee, chainNoteFromBase64, chainNoteToBase64, cleanupStalePendingOperations, clearPendingDeposits, clearPendingWithdrawals, computeChainNoteHash, computeCommitment$1 as computeCommitment, computeExtDataHash, computeMerkleRoot, computeNullifier$1 as computeNullifier, computeNullifierAsync, computeNullifierSync, computeOutputsHash, computeOutputsHashAsync, computeOutputsHashSync, computeProofForLatestDeposit, computeProofFromChain, computeSignature, computeSwapOutputsHash, computeSwapOutputsHashAsync, computeSwapOutputsHashSync, computeCommitment as computeUtxoCommitment, computeNullifier as computeUtxoNullifier, copyNoteToClipboard, createCloakError, createDepositInstruction, createLogger, createUtxo, createZeroUtxo, decryptCompactChainNote, decryptComplianceMetadataWithMasterKey, decryptTransactionMetadata, deriveDiversifiedViewingKey, deriveDiversifier, derivePublicKey, deriveSpendKey, deriveUserCompliancePublicKey, deriveUserComplianceScalar, deriveUtxoKeypairFromSpendKey, deriveViewKey, deriveViewingKeyFromNk, deriveViewingKeyFromSpendKey, deriveViewingKeyFromUtxoPrivateKey, deserializeUtxo, detectNetworkFromRpcUrl, downloadNote, encodeNoteSimple, encryptCompactChainNote, encryptNoteForRecipient, encryptTransactionMetadata, encryptTransactionMetadataBundle, expandSpendKey, exportKeys, exportNote, exportWalletKeys, fetchCommitments, fetchRiskQuoteInstruction, fetchRiskQuoteIx, filterNotesByNetwork, filterWithdrawableNotes, findNoteByCommitment, formatAmount, formatComplianceCsv, formatErrorForLogging, formatSol, fullWithdraw, generateCloakKeys, generateCommitment, generateCommitmentAsync, generateMasterSeed, generateNote, generateNoteFromWallet, generateUtxoKeypair, generateViewingKeyPair, generateWithdrawRegularProof, generateWithdrawSwapProof, getAddressExplorerUrl, getCircuitsPath, getDefaultCircuitsPath, getDistributableAmount, getExplorerUrl, getNkFromUtxoPrivateKey, getNullifierPDA, getPendingOperationsSummary, getPublicKey, getPublicViewKey, getRecipientAmount, getRpcUrlForNetwork, getShieldPoolPDAs, getSwapStatePDA, getViewKey, hasPendingOperations, hexToBigint$1 as hexToBigint, hexToBytes, importKeys, importWalletKeys, isDebugEnabled, isRootNotFoundError, isValidHex, isValidRpcUrl, isValidSolanaAddress, isWithdrawAmountSufficient, isWithdrawable, keypairToAdapter, loadPendingDeposits, loadPendingWithdrawals, parseAmount, parseError, parseNote, parseRelayErrorResponse, parseTransactionError, partialWithdraw, poseidonHash, preflightCheck, prepareEncryptedOutput, prepareEncryptedOutputForRecipient, proofToBytes, pubkeyToFieldElement, pubkeyToLimbs, randomBytes, randomFieldElement, readMerkleTreeState, registerViewingKey, removePendingDeposit, removePendingWithdrawal, savePendingDeposit, savePendingWithdrawal, scanNotesForWallet, scanTransactions, sdkLogger, selectUtxos, sendTransaction, serializeNote, serializeUtxo, setCircuitsPath, setDebugMode, signTransaction, splitTo2Limbs, sumUtxoAmounts, swapUtxo, swapWithChange, toComplianceReport, transact, transfer, truncate, tryDecryptNote, updateNoteWithDeposit, updatePendingDeposit, updatePendingWithdrawal, bigintToBytes32 as utxoBigintToBytes32, utxoEquals, hexToBigint as utxoHexToBigint, validateDepositParams, validateNote, validateOutputsSum, validateRoot, validateTransfers, validateWalletConnected, validateWithdrawableNote, verifyAllCircuits, verifyCircuitIntegrity, waitForRoot, withTiming };
+export { CLOAK_PROGRAM_ID, type ChainNoteTxType, type CircuitVerificationResult, type CloakConfig, CloakError, type CloakKeyPair, type CloakNote, CloakSDK, type CommitmentEntry, type CommitmentsResponse, type CompactChainNote, type ComplianceReport, type ComplianceTxType, DEFAULT_CIRCUITS_URL, DEFAULT_TRANSACTION_CIRCUITS_URL, type DepositInstructionParams, type DepositOptions, type DepositResult, type DepositStatus, EXPECTED_CIRCUIT_HASHES, type EncryptedMetadataBundle, type EncryptedNote$1 as EncryptedNote, type ErrorCategory, type ExpandedSpendKey, FIXED_FEE_LAMPORTS, type Groth16Proof, LAMPORTS_PER_SOL, LocalStorageAdapter, type LogLevel, type Logger, MERKLE_TREE_HEIGHT, MIN_DEPOSIT_LAMPORTS, type MasterKey, type MaxLengthArray, MemoryStorageAdapter, type MerkleProof, type MerkleRootResponse, MerkleTree, NATIVE_SOL_MINT, type Network, type NoteData, type OnchainMerkleProof, type PendingDeposit, type PendingWithdrawal, type ProofResult, RelayInternalError, RelayService, type RiskQuoteInstructionResponse, RootNotFoundError, SCANNER_SUPPORTS_TRANSACT_SWAP, SIGN_IN_MESSAGE, SanctionsQuoteError, type ScanOptions, type ScanResult, type ScanSummary, type ScannedTransaction, ShieldPoolErrors, type ShieldPoolPDAs, SimpleWallet, type SpendKey, type StorageAdapter, type SwapOptions, type SwapParams, type SwapResult, type TransactOptions, type TransactParams, type TransactResult, type TransactionMetadata, type Transfer, type TransferOptions, type TransferResult, type TxStatus, type UserFriendlyError, type Utxo, UtxoAlreadySpentError, type EncryptedNote as UtxoEncryptedNote, type UtxoKeypair, type UtxoSwapParams, type UtxoSwapResult, UtxoWallet, VARIABLE_FEE_DENOMINATOR, VARIABLE_FEE_NUMERATOR, VARIABLE_FEE_RATE, VERSION, type VerifyUtxosResult, type ViewKey, type ViewingKeyPair, type WalletAdapter, type WalletUtxo, type WithdrawOptions, type WithdrawRegularInputs, type WithdrawSubmissionResult, type WithdrawSwapInputs, areCircuitsAvailable, bigintToBytes32$1 as bigintToBytes32, bigintToHex, buildMerkleTree, buildMerkleTreeFromChain, buildMerkleTreeFromRelay, buildPublicInputsBytes, bytesToHex, calculateFee, calculateFeeBigint, calculateRelayFee, chainNoteFromBase64, chainNoteToBase64, classifyRelayError, cleanupStalePendingOperations, clearPendingDeposits, clearPendingWithdrawals, computeChainNoteHash, computeCommitment$1 as computeCommitment, computeExtDataHash, computeMerkleRoot, computeNullifier$1 as computeNullifier, computeNullifierAsync, computeNullifierSync, computeOutputsHash, computeOutputsHashAsync, computeOutputsHashSync, computeProofForLatestDeposit, computeProofFromChain, computeSignature, computeSwapOutputsHash, computeSwapOutputsHashAsync, computeSwapOutputsHashSync, computeCommitment as computeUtxoCommitment, computeNullifier as computeUtxoNullifier, copyNoteToClipboard, createCloakError, createDepositInstruction, createLogger, createUtxo, createZeroUtxo, decryptCompactChainNote, decryptComplianceMetadataWithMasterKey, decryptTransactionMetadata, deriveDiversifiedViewingKey, deriveDiversifier, derivePublicKey, deriveSpendKey, deriveUserCompliancePublicKey, deriveUserComplianceScalar, deriveUtxoKeypairFromSpendKey, deriveViewKey, deriveViewingKeyFromNk, deriveViewingKeyFromSpendKey, deriveViewingKeyFromUtxoPrivateKey, deserializeUtxo, detectNetworkFromRpcUrl, downloadNote, encodeNoteSimple, encryptCompactChainNote, encryptNoteForRecipient, encryptTransactionMetadata, encryptTransactionMetadataBundle, expandSpendKey, exportKeys, exportNote, exportWalletKeys, fetchCommitments, fetchRiskQuoteInstruction, fetchRiskQuoteIx, filterNotesByNetwork, filterWithdrawableNotes, findNoteByCommitment, formatAmount, formatComplianceCsv, formatErrorForLogging, formatSol, fullWithdraw, generateCloakKeys, generateCommitment, generateCommitmentAsync, generateMasterSeed, generateNote, generateNoteFromWallet, generateUtxoKeypair, generateViewingKeyPair, generateWithdrawRegularProof, generateWithdrawSwapProof, getAddressExplorerUrl, getCircuitsPath, getDefaultCircuitsPath, getDistributableAmount, getExplorerUrl, getNkFromUtxoPrivateKey, getNullifierPDA, getPendingOperationsSummary, getPublicKey, getPublicViewKey, getRecipientAmount, getRpcUrlForNetwork, getShieldPoolPDAs, getSwapStatePDA, getViewKey, hasPendingOperations, hexToBigint$1 as hexToBigint, hexToBytes, importKeys, importWalletKeys, isDebugEnabled, isRootNotFoundError, isValidHex, isValidRpcUrl, isValidSolanaAddress, isWithdrawAmountSufficient, isWithdrawable, keypairToAdapter, loadPendingDeposits, loadPendingWithdrawals, parseAmount, parseError, parseNote, parseRelayErrorResponse, parseTransactionError, partialWithdraw, poseidonHash, preflightCheck, preflightNullifiers, prepareEncryptedOutput, prepareEncryptedOutputForRecipient, proofToBytes, pubkeyToFieldElement, pubkeyToLimbs, randomBytes, randomFieldElement, readMerkleTreeState, registerViewingKey, removePendingDeposit, removePendingWithdrawal, savePendingDeposit, savePendingWithdrawal, scanNotesForWallet, scanTransactions, sdkLogger, selectUtxos, sendTransaction, serializeNote, serializeUtxo, setCircuitsPath, setDebugMode, signTransaction, splitTo2Limbs, sumUtxoAmounts, swapUtxo, swapWithChange, toComplianceReport, transact, transfer, truncate, tryDecryptNote, updateNoteWithDeposit, updatePendingDeposit, updatePendingWithdrawal, bigintToBytes32 as utxoBigintToBytes32, utxoEquals, hexToBigint as utxoHexToBigint, validateDepositParams, validateNote, validateOutputsSum, validateRoot, validateTransfers, validateWalletConnected, validateWithdrawableNote, verifyAllCircuits, verifyCircuitIntegrity, verifyUtxos, waitForRoot, withTiming };