@cloak.ag/sdk 1.0.4 → 1.0.6

package/dist/index.d.ts

@@ -156,7 +156,7 @@ interface CloakConfig {
 /**
  * Deposit progress status
  */
-type DepositStatus = "generating_note" | "creating_transaction" | "simulating" | "sending" | "confirming" | "submitting_to_indexer" | "fetching_proof" | "complete";
+type DepositStatus = "generating_note" | "awaiting_note_acknowledgment" | "note_saved" | "creating_transaction" | "simulating" | "sending" | "confirming" | "submitting_to_indexer" | "fetching_proof" | "complete";
 /**
  * Options for deposit operation
  */
@@ -172,12 +172,73 @@ interface DepositOptions {
     onTransactionSent?: (signature: string) => void;
     /** Callback when transaction is confirmed */
     onConfirmed?: (signature: string, slot: number) => void;
+    /**
+     * CRITICAL: Callback when note is generated, BEFORE any on-chain transaction.
+     *
+     * This is your chance to safely persist the note. If you don't save the note
+     * and the deposit succeeds but the browser crashes, your funds could be lost!
+     *
+     * The callback receives the note with all secrets needed for withdrawal.
+     * The deposit will NOT proceed until this callback completes.
+     *
+     * @example
+     * ```typescript
+     * onNoteGenerated: async (note) => {
+     *   // Save to secure storage BEFORE deposit proceeds
+     *   await localStorage.setItem(`pending_note_${note.commitment}`, JSON.stringify(note));
+     *   // Or show user a modal to copy/download the note
+     * }
+     * ```
+     */
+    onNoteGenerated?: (note: CloakNote) => Promise<void> | void;
+    /**
+     * If true, require user to acknowledge the note before proceeding with deposit.
+     * When enabled with onNoteGenerated, the deposit will wait for the callback to complete.
+     * Default: true when onNoteGenerated is provided
+     */
+    requireNoteAcknowledgment?: boolean;
     /** Skip simulation (default: false) */
     skipPreflight?: boolean;
-    /** Compute units to request (default: auto) */
+    /**
+     * Compute units to request.
+     * - If `optimizeCU` is true, this is ignored and CU is determined via simulation
+     * - Otherwise defaults to 40,000 (suitable for typical deposits)
+     */
     computeUnits?: number;
-    /** Priority fee in micro-lamports (default: 0) */
+    /**
+     * Enable simulation-based CU optimization.
+     * When true, simulates the transaction first to determine actual CU usage,
+     * then sets an optimal limit (simulated + 20% buffer).
+     *
+     * **Note: Only works in keypair mode (Node.js/scripts).**
+     * In wallet/browser mode, this is ignored because simulation would require
+     * the user to sign twice (simulation + actual tx) which is bad UX.
+     *
+     * Trade-offs:
+     * - ✅ Optimal block scheduling priority
+     * - ❌ Adds ~200-500ms latency (extra RPC call)
+     * - ❌ Only available in keypair mode
+     *
+     * Default: false (uses fixed 40K CU which is ~75% efficient for typical deposits)
+     */
+    optimizeCU?: boolean;
+    /** Priority fee in micro-lamports (default: 10,000) */
     priorityFee?: number;
+    /**
+     * Loaded accounts data size limit in bytes.
+     *
+     * Without this, Solana defaults to 64MB which incurs CU overhead
+     * (charged at 8 CU per 32KB). Setting a lower limit improves priority.
+     *
+     * **Note for Cloak deposits:**
+     * The Shield Pool program is ~104KB, so the minimum practical limit is ~128KB.
+     *
+     * Default: 256 * 1024 (256KB) - provides safety margin above program size.
+     * Set to 0 to disable (use Solana 64MB default).
+     *
+     * @see https://www.anza.xyz/blog/cu-optimization-with-setloadedaccountsdatasizelimit
+     */
+    loadedAccountsDataSizeLimit?: number;
     /**
      * Optional: Encrypt output for specific recipient's view key
      * If not provided, encrypts for the wallet's own view key (for self-scanning)
@@ -1339,9 +1400,42 @@ declare function getAddressExplorerUrl(address: string, network?: Network): stri
 /**
  * Error Utilities
  *
- * Helper functions for parsing and presenting user-friendly error messages
+ * Helper functions for parsing and presenting user-friendly error messages.
+ * This is the single source of truth for error codes and messages.
  */
 
+/**
+ * Shield Pool Program Error Codes
+ *
+ * Maps on-chain program error codes to user-friendly error messages.
+ * These codes match the program's error enum.
+ */
+declare const ShieldPoolErrors: Record<number, string>;
+/**
+ * Error categories for UI display
+ */
+type ErrorCategory = "wallet" | "network" | "validation" | "service" | "transaction" | "unknown";
+/**
+ * Structured error result for UI
+ */
+interface UserFriendlyError {
+    /** User-facing title */
+    title: string;
+    /** User-facing description */
+    message: string;
+    /** Error category for styling */
+    category: ErrorCategory;
+    /** Optional suggestion for the user */
+    suggestion?: string;
+    /** Whether the error is recoverable (user can retry) */
+    recoverable: boolean;
+    /** Original error for debugging (not shown to user) */
+    originalError?: string;
+}
+/**
+ * Parse any error and return a user-friendly error object
+ */
+declare function parseError(error: unknown): UserFriendlyError;
 /**
  * Parse transaction error and return user-friendly message
  *
@@ -1479,6 +1573,16 @@ declare class IndexerService {
     }>;
 }
 
+/**
+ * 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
  *
@@ -1501,6 +1605,8 @@ declare class RelayService {
      *
      * @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
@@ -1510,7 +1616,8 @@ declare class RelayService {
      *   publicInputs: { root, nf, outputs_hash, amount },
      *   outputs: [{ recipient: addr, amount: lamports }],
      *   feeBps: 50
-     * }, (status) => console.log(`Status: ${status}`));
+     * }, (status) => console.log(`Status: ${status}`),
+     *    (requestId) => localStorage.setItem('pending_withdraw', requestId));
      * console.log(`Transaction: ${signature}`);
      * ```
      */
@@ -1527,7 +1634,35 @@ declare class RelayService {
             amount: number;
         }>;
         feeBps: number;
-    }, onStatusUpdate?: (status: string) => void): Promise<string>;
+    }, 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
      *
@@ -1581,7 +1716,7 @@ declare class RelayService {
             slippage_bps: number;
             min_output_amount: number;
         };
-    }, onStatusUpdate?: (status: string) => void): Promise<string>;
+    }, onStatusUpdate?: (status: string) => void, onRequestId?: (requestId: string) => void): Promise<string>;
     /**
      * Get transaction status
      *
@@ -1653,10 +1788,16 @@ declare class DepositRecoveryService {
     recoverDeposit(options: RecoveryOptions): Promise<RecoveryResult>;
     /**
      * Check if a deposit already exists in the indexer
+     * Uses the enhanced deposit lookup endpoint with include_proof=true
      *
      * @private
      */
     private checkExistingDeposit;
+    /**
+     * Recover deposit by transaction signature
+     * Uses the indexer's signature lookup endpoint
+     */
+    recoverBySignature(signature: string): Promise<RecoveryResult>;
     /**
      * Finalize a deposit via server API (alternative recovery method)
      *
@@ -1879,6 +2020,175 @@ declare function generateWithdrawRegularProof(inputs: WithdrawRegularInputs, cir
  * @param circuitsPath - Path or URL to circuits directory. In browser, use URL like '/circuits' or full URL.
  */
 declare function generateWithdrawSwapProof(inputs: WithdrawSwapInputs, circuitsPath: string): Promise<ProofResult>;
+/**
+ * Expected circuit hashes for verification
+ * These are computed from the verification key files to ensure circuits match on-chain vkeys
+ *
+ * To regenerate these hashes, run:
+ * node -e "const fs=require('fs'); const data=fs.readFileSync('path/to/vkey.json'); console.log(require('crypto').createHash('sha256').update(data).digest('hex'));"
+ */
+declare const EXPECTED_CIRCUIT_HASHES: {
+    withdraw_regular_vkey: string | null;
+    withdraw_swap_vkey: string | null;
+};
+/**
+ * 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 hash (for debugging) */
+    computedHash?: string;
+    /** Expected hash (for debugging) */
+    expectedHash?: 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 - Path to circuits directory
+ * @param circuit - Which circuit to verify ('withdraw_regular' or 'withdraw_swap')
+ * @returns Verification result
+ *
+ * @example
+ * ```typescript
+ * const result = await verifyCircuitIntegrity('/circuits', '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 - Path to circuits directory
+ * @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;
+};
 
 /**
  * Cloak SDK - TypeScript SDK for Private Transactions on Solana
@@ -1888,4 +2198,4 @@ declare function generateWithdrawSwapProof(inputs: WithdrawSwapInputs, circuitsP
 
 declare const VERSION = "1.0.0";
 
-export { CLOAK_PROGRAM_ID, type CloakConfig, CloakError, type CloakKeyPair, type CloakNote, CloakSDK, type DepositInstructionParams, type DepositOptions, DepositRecoveryService, type DepositResult, type DepositStatus, type EncryptedNote, FIXED_FEE_LAMPORTS, type Groth16Proof, IndexerService, LAMPORTS_PER_SOL, LocalStorageAdapter, type MasterKey, type MaxLengthArray, MemoryStorageAdapter, type MerkleProof, type MerkleRootResponse, type Network, type NoteData, type NotesRangeResponse, type ProofResult, type RecoveryOptions, type RecoveryResult, RelayService, type ScanNotesOptions, type ScannedNote, type ShieldPoolPDAs, type SpendKey, type StorageAdapter, type SwapOptions, type SwapParams, type SwapResult, type Transfer, type TransferOptions, type TransferResult, type TxStatus, VARIABLE_FEE_RATE, VERSION, type ViewKey, type WalletAdapter, type WithdrawOptions, type WithdrawRegularInputs, type WithdrawSwapInputs, bigintToBytes32, buildPublicInputsBytes, bytesToHex, calculateFee, calculateRelayFee, computeCommitment, computeMerkleRoot, computeNullifier, computeNullifierAsync, computeNullifierSync, computeOutputsHash, computeOutputsHashAsync, computeOutputsHashSync, computeSwapOutputsHash, computeSwapOutputsHashAsync, computeSwapOutputsHashSync, copyNoteToClipboard, createCloakError, createDepositInstruction, deriveSpendKey, deriveViewKey, detectNetworkFromRpcUrl, downloadNote, encodeNoteSimple, encryptNoteForRecipient, exportKeys, exportNote, exportWalletKeys, filterNotesByNetwork, filterWithdrawableNotes, findNoteByCommitment, formatAmount, formatErrorForLogging, generateCloakKeys, generateCommitment, generateCommitmentAsync, generateMasterSeed, generateNote, generateNoteFromWallet, generateWithdrawRegularProof, generateWithdrawSwapProof, getAddressExplorerUrl, getDistributableAmount, getExplorerUrl, getPublicKey, getPublicViewKey, getRecipientAmount, getRpcUrlForNetwork, getShieldPoolPDAs, getViewKey, hexToBigint, hexToBytes, importKeys, importWalletKeys, isValidHex, isValidRpcUrl, isValidSolanaAddress, isWithdrawable, keypairToAdapter, parseAmount, parseNote, parseTransactionError, poseidonHash, prepareEncryptedOutput, prepareEncryptedOutputForRecipient, proofToBytes, pubkeyToLimbs, randomBytes, scanNotesForWallet, sendTransaction, serializeNote, signTransaction, splitTo2Limbs, tryDecryptNote, updateNoteWithDeposit, validateDepositParams, validateNote, validateOutputsSum, validateTransfers, validateWalletConnected, validateWithdrawableNote };
+export { CLOAK_PROGRAM_ID, type CircuitVerificationResult, type CloakConfig, CloakError, type CloakKeyPair, type CloakNote, CloakSDK, type DepositInstructionParams, type DepositOptions, DepositRecoveryService, type DepositResult, type DepositStatus, EXPECTED_CIRCUIT_HASHES, type EncryptedNote, type ErrorCategory, FIXED_FEE_LAMPORTS, type Groth16Proof, IndexerService, LAMPORTS_PER_SOL, LocalStorageAdapter, type MasterKey, type MaxLengthArray, MemoryStorageAdapter, type MerkleProof, type MerkleRootResponse, type Network, type NoteData, type NotesRangeResponse, type PendingDeposit, type PendingWithdrawal, type ProofResult, type RecoveryOptions, type RecoveryResult, RelayService, type ScanNotesOptions, type ScannedNote, ShieldPoolErrors, type ShieldPoolPDAs, type SpendKey, type StorageAdapter, type SwapOptions, type SwapParams, type SwapResult, type Transfer, type TransferOptions, type TransferResult, type TxStatus, type UserFriendlyError, VARIABLE_FEE_RATE, VERSION, type ViewKey, type WalletAdapter, type WithdrawOptions, type WithdrawRegularInputs, type WithdrawSubmissionResult, type WithdrawSwapInputs, bigintToBytes32, buildPublicInputsBytes, bytesToHex, calculateFee, calculateRelayFee, cleanupStalePendingOperations, clearPendingDeposits, clearPendingWithdrawals, computeCommitment, computeMerkleRoot, computeNullifier, computeNullifierAsync, computeNullifierSync, computeOutputsHash, computeOutputsHashAsync, computeOutputsHashSync, computeSwapOutputsHash, computeSwapOutputsHashAsync, computeSwapOutputsHashSync, copyNoteToClipboard, createCloakError, createDepositInstruction, deriveSpendKey, deriveViewKey, detectNetworkFromRpcUrl, downloadNote, encodeNoteSimple, encryptNoteForRecipient, exportKeys, exportNote, exportWalletKeys, filterNotesByNetwork, filterWithdrawableNotes, findNoteByCommitment, formatAmount, formatErrorForLogging, generateCloakKeys, generateCommitment, generateCommitmentAsync, generateMasterSeed, generateNote, generateNoteFromWallet, generateWithdrawRegularProof, generateWithdrawSwapProof, getAddressExplorerUrl, getDistributableAmount, getExplorerUrl, getPendingOperationsSummary, getPublicKey, getPublicViewKey, getRecipientAmount, getRpcUrlForNetwork, getShieldPoolPDAs, getViewKey, hasPendingOperations, hexToBigint, hexToBytes, importKeys, importWalletKeys, isValidHex, isValidRpcUrl, isValidSolanaAddress, isWithdrawable, keypairToAdapter, loadPendingDeposits, loadPendingWithdrawals, parseAmount, parseError, parseNote, parseTransactionError, poseidonHash, prepareEncryptedOutput, prepareEncryptedOutputForRecipient, proofToBytes, pubkeyToLimbs, randomBytes, removePendingDeposit, removePendingWithdrawal, savePendingDeposit, savePendingWithdrawal, scanNotesForWallet, sendTransaction, serializeNote, signTransaction, splitTo2Limbs, tryDecryptNote, updateNoteWithDeposit, updatePendingDeposit, updatePendingWithdrawal, validateDepositParams, validateNote, validateOutputsSum, validateTransfers, validateWalletConnected, validateWithdrawableNote, verifyAllCircuits, verifyCircuitIntegrity };