@cloak.ag/sdk 1.0.3 → 1.0.5

package/dist/index.d.cts

@@ -34,7 +34,7 @@ interface CloakNote {
     version: string;
     /** Amount in lamports */
     amount: number;
-    /** Blake3 commitment hash (hex) */
+    /** Commitment hash (hex) */
     commitment: string;
     /** Spending secret key (hex, 64 chars) */
     sk_spend: string;
@@ -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,6 +172,31 @@ 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) */
@@ -210,50 +235,6 @@ interface WithdrawOptions extends TransferOptions {
     /** Specific amount to withdraw in lamports (if not withdrawing all) */
     amount?: number;
 }
-/**
- * SP1 proof inputs for zero-knowledge proof generation
- */
-interface SP1ProofInputs {
-    privateInputs: {
-        amount: number;
-        r: string;
-        sk_spend: string;
-        leaf_index: number;
-        merkle_path: {
-            path_elements: string[];
-            path_indices: number[];
-        };
-    };
-    publicInputs: {
-        root: string;
-        nf: string;
-        outputs_hash: string;
-        amount: number;
-    };
-    outputs: Array<{
-        address: string;
-        amount: number;
-    }>;
-    /**
-     * Optional swap parameters for token swaps
-     * When provided, the proof will be for a swap transaction
-     */
-    swapParams?: {
-        output_mint: string;
-        recipient_ata: string;
-        min_output_amount: number;
-    };
-}
-/**
- * Result from proof generation
- */
-interface SP1ProofResult {
-    success: boolean;
-    proof?: string;
-    publicInputs?: string;
-    generationTimeMs: number;
-    error?: string;
-}
 /**
  * Merkle root response from indexer
  */
@@ -317,6 +298,13 @@ interface SwapOptions extends TransferOptions {
         outAmount: number;
         minOutputAmount: number;
     }>;
+    /**
+     * Recipient's associated token account for the output token.
+     * If not provided, will be computed automatically (requires @solana/spl-token).
+     * For browser environments, it's recommended to compute this in the frontend
+     * where @solana/spl-token is properly bundled.
+     */
+    recipientAta?: string;
 }
 /**
  * Result from a swap operation
@@ -1376,9 +1364,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
  *
@@ -1517,87 +1538,15 @@ declare class IndexerService {
 }
 
 /**
- * Options for proof generation
- */
-interface ProofGenerationOptions {
-    /** Progress callback - called with percentage (0-100) */
-    onProgress?: (progress: number) => void;
-    /** Called when proof generation starts */
-    onStart?: () => void;
-    /** Called on successful proof generation */
-    onSuccess?: (result: SP1ProofResult) => void;
-    /** Called on error */
-    onError?: (error: string) => void;
-    /** Custom timeout in milliseconds */
-    timeout?: number;
-}
-/**
- * Prover Service Client (Legacy)
- *
- * Handles zero-knowledge proof generation via the backend prover service.
- *
- * ⚠️ DEPRECATED: This implementation sends private inputs to a backend service.
- *
- * **Use ArtifactProverService instead** for privacy-preserving proof generation
- * where private inputs are uploaded directly to TEE, never passing through backend.
- *
- * This class is kept for backward compatibility but is not used by CloakSDK anymore.
+ * Result from submitting a withdrawal that includes the request ID
+ * for potential recovery/resume scenarios
  */
-declare class ProverService {
-    private indexerUrl;
-    private timeout;
-    /**
-     * Create a new Prover Service client
-     *
-     * @param indexerUrl - Indexer/Prover service base URL
-     * @param timeout - Proof generation timeout in ms (default: 5 minutes)
-     */
-    constructor(indexerUrl: string, timeout?: number);
-    /**
-     * Generate a zero-knowledge proof for withdrawal
-     *
-     * This process typically takes 30-180 seconds depending on the backend.
-     *
-     * @param inputs - Circuit inputs (private + public + outputs)
-     * @param options - Optional progress tracking and callbacks
-     * @returns Proof result with hex-encoded proof and public inputs
-     *
-     * @example
-     * ```typescript
-     * const result = await prover.generateProof(inputs);
-     * if (result.success) {
-     *   console.log(`Proof: ${result.proof}`);
-     * }
-     * ```
-     *
-     * @example
-     * ```typescript
-     * // With progress tracking
-     * const result = await prover.generateProof(inputs, {
-     *   onProgress: (progress) => console.log(`Progress: ${progress}%`),
-     *   onStart: () => console.log("Starting proof generation..."),
-     *   onSuccess: (result) => console.log("Proof generated!"),
-     *   onError: (error) => console.error("Failed:", error)
-     * });
-     * ```
-     */
-    generateProof(inputs: SP1ProofInputs, options?: ProofGenerationOptions): Promise<SP1ProofResult>;
-    /**
-     * Check if the prover service is available
-     *
-     * @returns True if service is healthy
-     */
-    healthCheck(): Promise<boolean>;
-    /**
-     * Get the configured timeout
-     */
-    getTimeout(): number;
-    /**
-     * Set a new timeout
-     */
-    setTimeout(timeout: number): void;
+interface WithdrawSubmissionResult {
+    /** The relay request ID - persist this for recovery */
+    requestId: string;
+    /** The final transaction signature */
+    signature: string;
 }
-
 /**
  * Relay Service Client
  *
@@ -1620,6 +1569,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
@@ -1629,7 +1580,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}`);
      * ```
      */
@@ -1646,7 +1598,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
      *
@@ -1700,7 +1680,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
      *
@@ -1772,10 +1752,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)
      *
@@ -1998,6 +1984,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
@@ -2007,4 +2162,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 ProofGenerationOptions, type ProofResult, ProverService, type RecoveryOptions, type RecoveryResult, RelayService, type SP1ProofInputs, type SP1ProofResult, 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 };