@cloak.ag/sdk 1.0.4 → 1.0.6

package/dist/index.js

@@ -9,7 +9,9 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
 import {
   Keypair,
   PublicKey as PublicKey4,
-  Transaction
+  Transaction,
+  TransactionInstruction as TransactionInstruction2,
+  ComputeBudgetProgram
 } from "@solana/web3.js";
 
 // src/core/types.ts
@@ -1043,6 +1045,8 @@ var RelayService = class {
    *
    * @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
@@ -1052,11 +1056,12 @@ var RelayService = class {
    *   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}`);
    * ```
    */
-  async submitWithdraw(params, onStatusUpdate) {
+  async submitWithdraw(params, onStatusUpdate, onRequestId) {
     const proofBytes = hexToBytes(params.proof);
     const proofBase64 = this.bytesToBase64(proofBytes);
     const requestBody = {
@@ -1097,8 +1102,55 @@ var RelayService = class {
     if (!requestId) {
       throw new Error("Relay response missing request_id");
     }
+    if (onRequestId) {
+      onRequestId(requestId);
+    }
     return this.pollForCompletion(requestId, onStatusUpdate);
   }
+  /**
+   * 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');
+   *   }
+   * }
+   * ```
+   */
+  async resumeWithdraw(requestId, onStatusUpdate) {
+    try {
+      const status = await this.getStatus(requestId);
+      if (onStatusUpdate) {
+        onStatusUpdate(status.status);
+      }
+      if (status.status === "completed") {
+        return { status: "completed", signature: status.txId };
+      } else if (status.status === "failed") {
+        return { status: "failed", error: status.error };
+      } else {
+        const signature = await this.pollForCompletion(requestId, onStatusUpdate);
+        return { status: "completed", signature };
+      }
+    } catch (error) {
+      return {
+        status: "failed",
+        error: error instanceof Error ? error.message : String(error)
+      };
+    }
+  }
   /**
    * Poll for withdrawal completion
    *
@@ -1171,7 +1223,7 @@ var RelayService = class {
    * console.log(`Transaction: ${signature}`);
    * ```
    */
-  async submitSwap(params, onStatusUpdate) {
+  async submitSwap(params, onStatusUpdate, onRequestId) {
     const proofBytes = hexToBytes(params.proof);
     const proofBase64 = this.bytesToBase64(proofBytes);
     const requestBody = {
@@ -1213,6 +1265,9 @@ var RelayService = class {
     if (!requestId) {
       throw new Error("Relay response missing request_id");
     }
+    if (onRequestId) {
+      onRequestId(requestId);
+    }
     return this.pollForCompletion(requestId, onStatusUpdate);
   }
   /**
@@ -1449,29 +1504,94 @@ var DepositRecoveryService = class {
   }
   /**
    * Check if a deposit already exists in the indexer
+   * Uses the enhanced deposit lookup endpoint with include_proof=true
    * 
    * @private
    */
-  async checkExistingDeposit(_commitment) {
+  async checkExistingDeposit(commitment) {
     try {
-      const { next_index } = await this.indexer.getMerkleRoot();
-      const batchSize = 100;
-      for (let i = 0; i < next_index; i += batchSize) {
-        const end = Math.min(i + batchSize - 1, next_index - 1);
-        const { notes } = await this.indexer.getNotesRange(i, end, batchSize);
-        for (let j = 0; j < notes.length; j++) {
-          try {
-            return null;
-          } catch (e) {
-            continue;
-          }
+      const cleanCommit = commitment.replace(/^0x/, "").toLowerCase();
+      const response = await fetch(
+        `${this.apiUrl}/api/v1/deposit/${cleanCommit}?include_proof=true`
+      );
+      if (!response.ok) {
+        if (response.status === 404) {
+          return null;
         }
+        throw new Error(`Failed to check deposit: ${response.status}`);
       }
-      return null;
+      const data = await response.json();
+      if (!data.merkle_proof) {
+        const merkleProof = await this.indexer.getMerkleProof(data.leaf_index);
+        return {
+          leafIndex: data.leaf_index,
+          root: merkleProof.root || "",
+          slot: data.slot,
+          merkleProof: {
+            pathElements: merkleProof.pathElements,
+            pathIndices: merkleProof.pathIndices
+          }
+        };
+      }
+      return {
+        leafIndex: data.leaf_index,
+        root: data.merkle_proof.root,
+        slot: data.slot,
+        merkleProof: {
+          pathElements: data.merkle_proof.path_elements,
+          pathIndices: data.merkle_proof.path_indices
+        }
+      };
     } catch (error) {
       return null;
     }
   }
+  /**
+   * Recover deposit by transaction signature
+   * Uses the indexer's signature lookup endpoint
+   */
+  async recoverBySignature(signature) {
+    try {
+      const response = await fetch(
+        `${this.apiUrl}/api/v1/deposit/tx/${signature}?include_proof=true`
+      );
+      if (!response.ok) {
+        if (response.status === 404) {
+          return {
+            success: false,
+            error: "Deposit not found for this transaction signature"
+          };
+        }
+        const errorText = await response.text();
+        return {
+          success: false,
+          error: `Failed to recover deposit: ${errorText}`
+        };
+      }
+      const data = await response.json();
+      if (!data.merkle_proof) {
+        return {
+          success: false,
+          error: "Deposit found but merkle proof not available"
+        };
+      }
+      return {
+        success: true,
+        leafIndex: data.leaf_index,
+        root: data.merkle_proof.root,
+        slot: data.slot,
+        merkleProof: {
+          pathElements: data.merkle_proof.path_elements,
+          pathIndices: data.merkle_proof.path_indices
+        }
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : String(error)
+      };
+    }
+  }
   /**
    * Finalize a deposit via server API (alternative recovery method)
    * 
@@ -1631,39 +1751,30 @@ function getShieldPoolPDAs(programId, mint) {
 
 // src/utils/proof-generation.ts
 import * as snarkjs from "snarkjs";
-var path = null;
-var fs = null;
-async function loadNodeModules() {
-  const isBrowser = typeof window !== "undefined" || typeof globalThis !== "undefined" && globalThis.window;
-  if (!isBrowser && typeof process !== "undefined" && process.versions?.node) {
-    if (!path) {
-      path = await import("path");
-    }
-    if (!fs) {
-      fs = await import("fs");
-    }
-    return { path, fs };
-  }
-  return { path: null, fs: null };
+var IS_BROWSER = typeof window !== "undefined" || typeof globalThis !== "undefined" && typeof globalThis.document !== "undefined";
+var _nodePath = null;
+var _nodeFs = null;
+var _nodeCrypto = null;
+async function getNodePath() {
+  if (_nodePath) return _nodePath;
+  _nodePath = await import("path");
+  return _nodePath;
+}
+async function getNodeFs() {
+  if (_nodeFs) return _nodeFs;
+  _nodeFs = await import("fs");
+  return _nodeFs;
+}
+async function getNodeCrypto() {
+  if (_nodeCrypto) return _nodeCrypto;
+  _nodeCrypto = await import("crypto");
+  return _nodeCrypto;
 }
 function joinPath(...parts) {
-  const isBrowser = typeof window !== "undefined" || typeof globalThis !== "undefined" && globalThis.window;
-  if (!isBrowser && path) {
-    return path.join(...parts);
-  }
   return parts.join("/").replace(/\/+/g, "/");
 }
 async function fileExists(filePath) {
-  const { fs: fs2 } = await loadNodeModules();
-  if (fs2) {
-    try {
-      return fs2.existsSync(filePath);
-    } catch {
-      return false;
-    }
-  }
-  const isBrowser = typeof window !== "undefined" || typeof globalThis !== "undefined" && globalThis.window;
-  if (isBrowser) {
+  if (IS_BROWSER) {
     try {
       const response = await fetch(filePath, { method: "HEAD" });
       return response.ok;
@@ -1671,13 +1782,21 @@ async function fileExists(filePath) {
       return false;
     }
   }
-  return false;
+  try {
+    const nodeFs = globalThis.require?.("fs") || (typeof __require !== "undefined" ? __require("fs") : null);
+    if (nodeFs) {
+      return nodeFs.existsSync(filePath);
+    }
+    const fsModule = await import("fs");
+    return fsModule.existsSync(filePath);
+  } catch {
+    return false;
+  }
 }
 async function generateWithdrawRegularProof(inputs, circuitsPath) {
-  const isBrowser = typeof window !== "undefined" || typeof globalThis !== "undefined" && globalThis.window;
   let wasmPath;
   let zkeyPath;
-  if (isBrowser) {
+  if (IS_BROWSER) {
     wasmPath = `${circuitsPath}/withdraw_regular_js/withdraw_regular.wasm`;
     zkeyPath = `${circuitsPath}/withdraw_regular_final.zkey`;
   } else {
@@ -1725,10 +1844,9 @@ async function generateWithdrawRegularProof(inputs, circuitsPath) {
   };
 }
 async function generateWithdrawSwapProof(inputs, circuitsPath) {
-  const isBrowser = typeof window !== "undefined" || typeof globalThis !== "undefined" && globalThis.window;
   let wasmPath;
   let zkeyPath;
-  if (isBrowser) {
+  if (IS_BROWSER) {
     wasmPath = `${circuitsPath}/withdraw_swap_js/withdraw_swap.wasm`;
     zkeyPath = `${circuitsPath}/withdraw_swap_final.zkey`;
   } else {
@@ -1783,8 +1901,7 @@ async function generateWithdrawSwapProof(inputs, circuitsPath) {
   };
 }
 async function areCircuitsAvailable(circuitsPath) {
-  const isBrowser = typeof window !== "undefined" || typeof globalThis !== "undefined" && globalThis.window;
-  if (isBrowser) {
+  if (IS_BROWSER) {
     return Boolean(circuitsPath && circuitsPath !== "");
   }
   const wasmPath = joinPath(circuitsPath, "build", "withdraw_regular_js", "withdraw_regular.wasm");
@@ -1794,20 +1911,24 @@ async function areCircuitsAvailable(circuitsPath) {
   return wasmExists && zkeyExists;
 }
 async function getDefaultCircuitsPath() {
-  const isBrowser = typeof window !== "undefined" || typeof globalThis !== "undefined" && globalThis.window;
-  if (isBrowser) {
+  if (IS_BROWSER) {
+    return "/circuits";
+  }
+  if (typeof process === "undefined" || !process.cwd) {
     return "/circuits";
   }
-  const { path: path2 } = await loadNodeModules();
-  if (!path2 || typeof process === "undefined" || !process.cwd) {
+  let nodePath;
+  try {
+    nodePath = await getNodePath();
+  } catch {
     return "/circuits";
   }
   const possiblePaths = [
-    path2.resolve(process.cwd(), "../../packages-new/circuits"),
-    path2.resolve(process.cwd(), "../packages-new/circuits"),
-    path2.resolve(process.cwd(), "packages-new/circuits"),
-    path2.resolve(process.cwd(), "../../circuits"),
-    path2.resolve(process.cwd(), "../circuits")
+    nodePath.resolve(process.cwd(), "../../packages-new/circuits"),
+    nodePath.resolve(process.cwd(), "../packages-new/circuits"),
+    nodePath.resolve(process.cwd(), "packages-new/circuits"),
+    nodePath.resolve(process.cwd(), "../../circuits"),
+    nodePath.resolve(process.cwd(), "../circuits")
   ];
   for (const p of possiblePaths) {
     if (await areCircuitsAvailable(p)) {
@@ -1816,8 +1937,103 @@ async function getDefaultCircuitsPath() {
   }
   return possiblePaths[0];
 }
+var EXPECTED_CIRCUIT_HASHES = {
+  // SHA-256 of the verification key JSON from withdraw_regular circuit
+  withdraw_regular_vkey: null,
+  // Set to null to skip check during development
+  // SHA-256 of the verification key JSON from withdraw_swap circuit
+  withdraw_swap_vkey: null
+  // Set to null to skip check during development
+};
+async function verifyCircuitIntegrity(circuitsPath, circuit) {
+  const expectedHash = circuit === "withdraw_regular" ? EXPECTED_CIRCUIT_HASHES.withdraw_regular_vkey : EXPECTED_CIRCUIT_HASHES.withdraw_swap_vkey;
+  if (!expectedHash) {
+    return {
+      valid: true,
+      circuit,
+      error: "Verification skipped (no expected hash configured)"
+    };
+  }
+  try {
+    const vkeyPath = IS_BROWSER ? `${circuitsPath}/${circuit}_verification_key.json` : joinPath(circuitsPath, "build", `${circuit}_verification_key.json`);
+    let vkeyData;
+    if (IS_BROWSER) {
+      const response = await fetch(vkeyPath);
+      if (!response.ok) {
+        return {
+          valid: false,
+          circuit,
+          error: `Failed to fetch verification key: ${response.status}`
+        };
+      }
+      vkeyData = await response.text();
+    } else {
+      try {
+        const nodeFs = await getNodeFs();
+        vkeyData = nodeFs.readFileSync(vkeyPath, "utf8");
+      } catch (e) {
+        return {
+          valid: false,
+          circuit,
+          error: `Failed to read verification key: ${e}`
+        };
+      }
+    }
+    let computedHash;
+    if (IS_BROWSER) {
+      const encoder = new TextEncoder();
+      const data = encoder.encode(vkeyData);
+      const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+      const hashArray = Array.from(new Uint8Array(hashBuffer));
+      computedHash = hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+    } else {
+      const nodeCrypto = await getNodeCrypto();
+      computedHash = nodeCrypto.createHash("sha256").update(vkeyData).digest("hex");
+    }
+    if (computedHash === expectedHash) {
+      return {
+        valid: true,
+        circuit,
+        computedHash,
+        expectedHash
+      };
+    } else {
+      return {
+        valid: false,
+        circuit,
+        error: `Verification key hash mismatch! This circuit may produce invalid proofs.`,
+        computedHash,
+        expectedHash
+      };
+    }
+  } catch (error) {
+    return {
+      valid: false,
+      circuit,
+      error: `Circuit verification failed: ${error instanceof Error ? error.message : String(error)}`
+    };
+  }
+}
+async function verifyAllCircuits(circuitsPath) {
+  const results = await Promise.all([
+    verifyCircuitIntegrity(circuitsPath, "withdraw_regular"),
+    verifyCircuitIntegrity(circuitsPath, "withdraw_swap")
+  ]);
+  return results;
+}
 
 // src/core/CloakSDK.ts
+var COMPUTE_BUDGET_PROGRAM_ID = new PublicKey4("ComputeBudget111111111111111111111111111111");
+function createSetLoadedAccountsDataSizeLimitInstruction(bytes) {
+  const data = Buffer.alloc(5);
+  data.writeUInt8(4, 0);
+  data.writeUInt32LE(bytes, 1);
+  return new TransactionInstruction2({
+    keys: [],
+    programId: COMPUTE_BUDGET_PROGRAM_ID,
+    data
+  });
+}
 var CLOAK_PROGRAM_ID = new PublicKey4("c1oak6tetxYnNfvXKFkpn1d98FxtK7B68vBQLYQpWKp");
 var CLOAK_API_URL = "https://api.cloak.ag";
 var CloakSDK = class {
@@ -1930,14 +2146,35 @@ var CloakSDK = class {
   async deposit(connection, amountOrNote, options) {
     try {
       let note;
+      let isNewNote = false;
       if (typeof amountOrNote === "number") {
+        options?.onProgress?.("generating_note", { message: "Generating note with secrets..." });
         note = await generateNote(amountOrNote, this.config.network);
+        isNewNote = true;
       } else {
         note = amountOrNote;
         if (note.depositSignature) {
           throw new Error("Note has already been deposited");
         }
       }
+      if (isNewNote) {
+        await this.storage.saveNote(note);
+        if (options?.onNoteGenerated) {
+          options?.onProgress?.("awaiting_note_acknowledgment", {
+            message: "Waiting for note to be saved before proceeding with deposit..."
+          });
+          try {
+            await options.onNoteGenerated(note);
+          } catch (error) {
+            throw new Error(
+              `Failed to save note before deposit: ${error instanceof Error ? error.message : String(error)}. For your safety, the deposit has been aborted. Your funds are safe.`
+            );
+          }
+        }
+        options?.onProgress?.("note_saved", {
+          message: "Note saved. Proceeding with on-chain deposit..."
+        });
+      }
       const payerPubkey = this.getPublicKey();
       const balance = await connection.getBalance(payerPubkey);
       const requiredAmount = note.amount + 5e3;
@@ -1957,10 +2194,51 @@ var CloakSDK = class {
         commitment: commitmentBytes
       });
       const { blockhash, lastValidBlockHeight } = await connection.getLatestBlockhash();
+      const priorityFee = options?.priorityFee ?? 1e4;
+      const cuPriceIx = ComputeBudgetProgram.setComputeUnitPrice({ microLamports: priorityFee });
+      const dataSizeLimit = options?.loadedAccountsDataSizeLimit ?? 256 * 1024;
+      const dataSizeLimitIx = dataSizeLimit > 0 ? createSetLoadedAccountsDataSizeLimitInstruction(dataSizeLimit) : null;
+      let computeUnits;
+      if (options?.optimizeCU && this.keypair) {
+        options?.onProgress?.("simulating", { message: "Simulating transaction for optimal CU..." });
+        const simCuLimitIx = ComputeBudgetProgram.setComputeUnitLimit({ units: 2e5 });
+        const simTransaction = new Transaction({
+          feePayer: payerPubkey,
+          recentBlockhash: blockhash
+        }).add(simCuLimitIx).add(cuPriceIx);
+        if (dataSizeLimitIx) {
+          simTransaction.add(dataSizeLimitIx);
+        }
+        simTransaction.add(depositIx);
+        try {
+          const simulation = await connection.simulateTransaction(simTransaction, [this.keypair]);
+          if (simulation.value.err) {
+            console.warn("Simulation failed, using default CU:", simulation.value.err);
+            computeUnits = 4e4;
+          } else {
+            const simulatedCU = simulation.value.unitsConsumed ?? 3e4;
+            computeUnits = Math.ceil(simulatedCU * 1.2);
+            console.log(`CU optimization: ${simulatedCU} simulated \u2192 ${computeUnits} limit`);
+          }
+        } catch (simError) {
+          console.warn("Simulation RPC error, using default CU:", simError);
+          computeUnits = 4e4;
+        }
+      } else if (options?.optimizeCU && this.wallet) {
+        console.warn("CU optimization via simulation not available in wallet mode (would require double signing). Using default.");
+        computeUnits = options?.computeUnits ?? 4e4;
+      } else {
+        computeUnits = options?.computeUnits ?? 4e4;
+      }
+      const cuLimitIx = ComputeBudgetProgram.setComputeUnitLimit({ units: computeUnits });
       const transaction = new Transaction({
         feePayer: payerPubkey,
         recentBlockhash: blockhash
-      }).add(depositIx);
+      }).add(cuLimitIx).add(cuPriceIx);
+      if (dataSizeLimitIx) {
+        transaction.add(dataSizeLimitIx);
+      }
+      transaction.add(depositIx);
       if (!transaction.feePayer) {
         throw new Error("Transaction feePayer is not set");
       }
@@ -2129,6 +2407,16 @@ var CloakSDK = class {
           pathIndices: merkleProof.pathIndices
         }
       });
+      await this.storage.updateNote(note.commitment, {
+        depositSignature: signature,
+        depositSlot,
+        leafIndex,
+        root,
+        merkleProof: {
+          pathElements: merkleProof.pathElements,
+          pathIndices: merkleProof.pathIndices
+        }
+      });
       return {
         note: updatedNote,
         signature,
@@ -2931,6 +3219,63 @@ async function copyNoteToClipboard(note) {
 }
 
 // src/utils/errors.ts
+var ShieldPoolErrors = {
+  // Root management errors
+  4096: "Invalid Merkle root",
+  4097: "Root not found in the roots ring",
+  4098: "Roots ring is full",
+  // Proof verification errors
+  4112: "Zero-knowledge proof is invalid",
+  4113: "Invalid proof size (expected 260 bytes)",
+  4114: "Invalid public inputs",
+  4115: "Verification key mismatch",
+  // Nullifier errors
+  4128: "Double spend detected - this note has already been spent",
+  4129: "Nullifier shard is full",
+  4130: "Invalid nullifier",
+  // Transaction validation errors
+  4144: "Output addresses or amounts don't match the proof",
+  4145: "Amount conservation failed - outputs + fee must equal input amount",
+  4146: "Invalid outputs hash",
+  4147: "Invalid amount (must be greater than zero)",
+  4148: "Invalid recipient address",
+  4149: "Commitment already exists in the tree",
+  4150: "Commitment log is full",
+  // Math errors
+  4160: "Math overflow occurred",
+  4161: "Division by zero",
+  // Account errors
+  4176: "Account validation failed - please check your wallet balance and try again",
+  4177: "Pool account owner mismatch",
+  4178: "Treasury account owner mismatch",
+  4179: "Roots ring account owner mismatch",
+  4180: "Nullifier shard account owner mismatch",
+  4181: "Pool account is not writable",
+  4182: "Treasury account is not writable",
+  4183: "Recipient account is not writable",
+  4184: "Insufficient lamports in pool or account",
+  4185: "Invalid account owner",
+  4186: "Invalid account size",
+  4187: "Commitments account is not writable",
+  4188: "Invalid admin authority",
+  // Instruction errors
+  4192: "Invalid instruction data length",
+  4193: "Invalid instruction data format",
+  4194: "Missing required accounts",
+  4195: "Invalid instruction tag",
+  // PoW/Scrambler errors
+  4196: "Invalid miner account",
+  4197: "Invalid claim account",
+  4198: "Failed to consume claim",
+  // Groth16 verifier errors
+  4208: "Invalid G1 point length",
+  4209: "Invalid G2 point length",
+  4210: "Invalid public inputs length",
+  4211: "Public input exceeds field size",
+  4212: "G1 multiplication failed during proof preparation",
+  4213: "G1 addition failed during proof preparation",
+  4214: "Proof verification failed"
+};
 var PROGRAM_ERRORS = {
   // Nullifier errors
   "NullifierAlreadyUsed": "This note has already been withdrawn. Each note can only be spent once.",
@@ -2959,6 +3304,438 @@ var PROGRAM_ERRORS = {
   "AccountNotFound": "Required account not found.",
   "InvalidInstruction": "Invalid instruction data."
 };
+var ErrorPatterns = [
+  // Wallet/User action errors
+  {
+    patterns: [
+      "User rejected",
+      "user rejected",
+      "User denied",
+      "user denied",
+      "Transaction cancelled",
+      "Transaction rejected",
+      /code.*4001/i
+    ],
+    result: {
+      title: "Transaction Cancelled",
+      message: "You cancelled the transaction.",
+      category: "wallet",
+      recoverable: true
+    }
+  },
+  {
+    patterns: [
+      "Wallet not connected",
+      "wallet not connected",
+      "Please connect wallet",
+      "No wallet connected"
+    ],
+    result: {
+      title: "Wallet Not Connected",
+      message: "Please connect your wallet to continue.",
+      category: "wallet",
+      suggestion: "Click the wallet button to connect.",
+      recoverable: true
+    }
+  },
+  {
+    patterns: [
+      "SDK not initialized",
+      "sdk not initialized"
+    ],
+    result: {
+      title: "Wallet Connection Required",
+      message: "Your wallet connection was interrupted.",
+      category: "wallet",
+      suggestion: "Please reconnect your wallet and try again.",
+      recoverable: true
+    }
+  },
+  {
+    patterns: [
+      "Wallet does not support signing",
+      "signTransaction"
+    ],
+    result: {
+      title: "Wallet Feature Not Supported",
+      message: "Your wallet doesn't support the required signing method.",
+      category: "wallet",
+      suggestion: "Try using a different wallet like Phantom or Solflare.",
+      recoverable: true
+    }
+  },
+  // Balance errors
+  {
+    patterns: [
+      "insufficient lamports",
+      "Insufficient lamports",
+      "insufficient balance",
+      "Insufficient balance",
+      "Insufficient SOL",
+      "not enough SOL",
+      "Attempt to debit an account but found no record",
+      /0x1$/
+    ],
+    result: {
+      title: "Insufficient Balance",
+      message: "You don't have enough SOL for this transaction.",
+      category: "validation",
+      suggestion: "Add more SOL to your wallet or reduce the amount.",
+      recoverable: true
+    }
+  },
+  {
+    patterns: [
+      "Insufficient funds",
+      "insufficient funds"
+    ],
+    result: {
+      title: "Insufficient Funds",
+      message: "Your wallet doesn't have enough funds for this transaction.",
+      category: "validation",
+      suggestion: "Add more funds to your wallet and try again.",
+      recoverable: true
+    }
+  },
+  // Network errors
+  {
+    patterns: [
+      "fetch failed",
+      "Failed to fetch",
+      "Network error",
+      "network error",
+      "ECONNREFUSED",
+      "ETIMEDOUT",
+      "ENOTFOUND",
+      "NetworkError",
+      "net::ERR",
+      "Failed to load"
+    ],
+    result: {
+      title: "Connection Error",
+      message: "Unable to connect to the network.",
+      category: "network",
+      suggestion: "Check your internet connection and try again.",
+      recoverable: true
+    }
+  },
+  {
+    patterns: [
+      "timeout",
+      "Timeout",
+      "TIMEOUT",
+      "timed out",
+      "Timed out"
+    ],
+    result: {
+      title: "Request Timed Out",
+      message: "The request took too long to complete.",
+      category: "network",
+      suggestion: "The network may be congested. Please try again in a moment.",
+      recoverable: true
+    }
+  },
+  {
+    patterns: [
+      "blockhash not found",
+      "Blockhash not found",
+      "block height exceeded"
+    ],
+    result: {
+      title: "Transaction Expired",
+      message: "The transaction took too long and expired.",
+      category: "network",
+      suggestion: "Please try again. If this persists, the network may be congested.",
+      recoverable: true
+    }
+  },
+  // Service errors (Indexer/Relay)
+  {
+    patterns: [
+      "Indexer",
+      "indexer",
+      /indexer.*unavailable/i,
+      /failed.*indexer/i
+    ],
+    result: {
+      title: "Service Temporarily Unavailable",
+      message: "The privacy service is temporarily unavailable.",
+      category: "service",
+      suggestion: "Please wait a moment and try again.",
+      recoverable: true
+    }
+  },
+  {
+    patterns: [
+      "Relay",
+      "relay",
+      /relay.*unavailable/i,
+      /failed.*relay/i,
+      "failed to submit",
+      "Failed to submit"
+    ],
+    result: {
+      title: "Processing Service Busy",
+      message: "The transaction processing service is busy.",
+      category: "service",
+      suggestion: "Please wait a moment and try again.",
+      recoverable: true
+    }
+  },
+  {
+    patterns: [
+      "429",
+      "Too Many Requests",
+      "rate limit",
+      "Rate limit"
+    ],
+    result: {
+      title: "Too Many Requests",
+      message: "You're making requests too quickly.",
+      category: "service",
+      suggestion: "Please wait a moment before trying again.",
+      recoverable: true
+    }
+  },
+  {
+    patterns: [
+      "503",
+      "Service Unavailable",
+      "502",
+      "Bad Gateway"
+    ],
+    result: {
+      title: "Service Temporarily Unavailable",
+      message: "Our servers are temporarily unavailable.",
+      category: "service",
+      suggestion: "Please try again in a few minutes.",
+      recoverable: true
+    }
+  },
+  // Proof/ZK errors
+  {
+    patterns: [
+      "Circuits not available",
+      "circuits not available",
+      "Failed to load circuit",
+      "WASM",
+      "wasm",
+      /circuit.*not.*found/i
+    ],
+    result: {
+      title: "Loading Error",
+      message: "Failed to load required cryptographic components.",
+      category: "service",
+      suggestion: "Try refreshing the page. If the problem persists, clear your browser cache.",
+      recoverable: true
+    }
+  },
+  {
+    patterns: [
+      "proof generation",
+      "Proof generation",
+      "Failed to generate proof",
+      "proving error"
+    ],
+    result: {
+      title: "Proof Generation Failed",
+      message: "Failed to generate the privacy proof.",
+      category: "service",
+      suggestion: "Try again with a smaller amount or refresh the page.",
+      recoverable: true
+    }
+  },
+  // Validation errors
+  {
+    patterns: [
+      "Invalid amount",
+      "invalid amount",
+      "Amount must be",
+      "amount must be",
+      "Amount too small"
+    ],
+    result: {
+      title: "Invalid Amount",
+      message: "The amount you entered is not valid.",
+      category: "validation",
+      suggestion: "Enter an amount greater than the minimum required.",
+      recoverable: true
+    }
+  },
+  {
+    patterns: [
+      "Invalid recipient",
+      "invalid recipient",
+      "Invalid address",
+      "invalid address",
+      "Invalid Solana address"
+    ],
+    result: {
+      title: "Invalid Address",
+      message: "The recipient address is not valid.",
+      category: "validation",
+      suggestion: "Check the address and make sure it's a valid Solana address.",
+      recoverable: true
+    }
+  },
+  {
+    patterns: [
+      "Invalid token",
+      "invalid token",
+      "Unsupported token"
+    ],
+    result: {
+      title: "Unsupported Token",
+      message: "This token is not supported.",
+      category: "validation",
+      suggestion: "Select a supported token and try again.",
+      recoverable: true
+    }
+  },
+  // Swap errors
+  {
+    patterns: [
+      "Failed to get quote",
+      "failed to get quote",
+      "No route found",
+      "no route found",
+      "Insufficient liquidity",
+      "insufficient liquidity"
+    ],
+    result: {
+      title: "Swap Quote Unavailable",
+      message: "Unable to get a price quote for this swap.",
+      category: "service",
+      suggestion: "Try a different amount or wait for better liquidity.",
+      recoverable: true
+    }
+  },
+  {
+    patterns: [
+      "Slippage",
+      "slippage",
+      "Price impact",
+      "price impact"
+    ],
+    result: {
+      title: "Price Changed",
+      message: "The price changed too much during the transaction.",
+      category: "transaction",
+      suggestion: "Try again or increase your slippage tolerance.",
+      recoverable: true
+    }
+  },
+  // Transaction errors
+  {
+    patterns: [
+      "Double spend",
+      "double spend",
+      "already been spent",
+      "already spent"
+    ],
+    result: {
+      title: "Already Spent",
+      message: "This note has already been used.",
+      category: "transaction",
+      suggestion: "This funds have already been withdrawn.",
+      recoverable: false
+    }
+  },
+  {
+    patterns: [
+      "simulation failed",
+      "Simulation failed",
+      "Transaction simulation"
+    ],
+    result: {
+      title: "Transaction Failed",
+      message: "The transaction could not be completed.",
+      category: "transaction",
+      suggestion: "Please try again. If the problem persists, check your balance.",
+      recoverable: true
+    }
+  },
+  {
+    patterns: [
+      "confirmation timeout",
+      "Confirmation timeout",
+      "not confirmed"
+    ],
+    result: {
+      title: "Confirmation Pending",
+      message: "Transaction confirmation is taking longer than expected.",
+      category: "network",
+      suggestion: "Your transaction may still complete. Check your wallet or try again.",
+      recoverable: true
+    }
+  }
+];
+function parseError(error) {
+  let errorMessage = "";
+  let originalError = "";
+  if (error instanceof Error) {
+    errorMessage = error.message;
+    originalError = error.stack || error.message;
+  } else if (typeof error === "string") {
+    errorMessage = error;
+    originalError = error;
+  } else if (error && typeof error === "object") {
+    const err = error;
+    errorMessage = String(err.message || err.error || err.msg || JSON.stringify(error));
+    originalError = JSON.stringify(error);
+  } else {
+    errorMessage = String(error);
+    originalError = String(error);
+  }
+  for (const { patterns, result } of ErrorPatterns) {
+    for (const pattern of patterns) {
+      if (typeof pattern === "string") {
+        if (errorMessage.includes(pattern)) {
+          return { ...result, originalError };
+        }
+      } else if (pattern instanceof RegExp) {
+        if (pattern.test(errorMessage)) {
+          return { ...result, originalError };
+        }
+      }
+    }
+  }
+  const programError = tryParseProgramError(errorMessage);
+  if (programError) {
+    return { ...programError, originalError };
+  }
+  return {
+    title: "Something Went Wrong",
+    message: "An unexpected error occurred.",
+    category: "unknown",
+    suggestion: "Please try again. If the problem persists, refresh the page.",
+    recoverable: true,
+    originalError
+  };
+}
+function tryParseProgramError(message) {
+  const match = message.match(/\{"InstructionError":\[(\d+),\{"Custom":(\d+)\}\]\}/);
+  if (match) {
+    const errorCode = parseInt(match[2]);
+    const friendlyMessage = ShieldPoolErrors[errorCode];
+    if (friendlyMessage) {
+      return {
+        title: "Transaction Failed",
+        message: friendlyMessage,
+        category: "transaction",
+        recoverable: !friendlyMessage.toLowerCase().includes("double spend")
+      };
+    }
+    return {
+      title: "Transaction Failed",
+      message: `Transaction failed with error code ${errorCode}.`,
+      category: "transaction",
+      suggestion: "Please try again or contact support if this persists.",
+      recoverable: true
+    };
+  }
+  return null;
+}
 function parseTransactionError(error) {
   if (!error) return "An unknown error occurred";
   const errorStr = typeof error === "string" ? error : error.message || error.toString();
@@ -3140,6 +3917,173 @@ function keypairToAdapter(keypair) {
   };
 }
 
+// src/utils/pending-operations.ts
+var PENDING_DEPOSITS_KEY = "cloak_pending_deposits";
+var PENDING_WITHDRAWALS_KEY = "cloak_pending_withdrawals";
+function getStorage() {
+  if (typeof globalThis !== "undefined" && globalThis.localStorage) {
+    return globalThis.localStorage;
+  }
+  return null;
+}
+function savePendingDeposit(deposit) {
+  const storage = getStorage();
+  if (!storage) {
+    console.warn("localStorage not available - pending deposit not persisted");
+    return;
+  }
+  const deposits = loadPendingDeposits();
+  const index = deposits.findIndex((d) => d.note.commitment === deposit.note.commitment);
+  if (index >= 0) {
+    deposits[index] = deposit;
+  } else {
+    deposits.push(deposit);
+  }
+  storage.setItem(PENDING_DEPOSITS_KEY, JSON.stringify(deposits));
+}
+function loadPendingDeposits() {
+  const storage = getStorage();
+  if (!storage) return [];
+  const stored = storage.getItem(PENDING_DEPOSITS_KEY);
+  if (!stored) return [];
+  try {
+    return JSON.parse(stored);
+  } catch {
+    return [];
+  }
+}
+function updatePendingDeposit(commitment, updates) {
+  const storage = getStorage();
+  if (!storage) return;
+  const deposits = loadPendingDeposits();
+  const index = deposits.findIndex((d) => d.note.commitment === commitment);
+  if (index >= 0) {
+    deposits[index] = { ...deposits[index], ...updates };
+    storage.setItem(PENDING_DEPOSITS_KEY, JSON.stringify(deposits));
+  }
+}
+function removePendingDeposit(commitment) {
+  const storage = getStorage();
+  if (!storage) return;
+  const deposits = loadPendingDeposits();
+  const filtered = deposits.filter((d) => d.note.commitment !== commitment);
+  storage.setItem(PENDING_DEPOSITS_KEY, JSON.stringify(filtered));
+}
+function clearPendingDeposits() {
+  const storage = getStorage();
+  if (storage) {
+    storage.removeItem(PENDING_DEPOSITS_KEY);
+  }
+}
+function savePendingWithdrawal(withdrawal) {
+  const storage = getStorage();
+  if (!storage) {
+    console.warn("localStorage not available - pending withdrawal not persisted");
+    return;
+  }
+  const withdrawals = loadPendingWithdrawals();
+  const index = withdrawals.findIndex((w) => w.requestId === withdrawal.requestId);
+  if (index >= 0) {
+    withdrawals[index] = withdrawal;
+  } else {
+    withdrawals.push(withdrawal);
+  }
+  storage.setItem(PENDING_WITHDRAWALS_KEY, JSON.stringify(withdrawals));
+}
+function loadPendingWithdrawals() {
+  const storage = getStorage();
+  if (!storage) return [];
+  const stored = storage.getItem(PENDING_WITHDRAWALS_KEY);
+  if (!stored) return [];
+  try {
+    return JSON.parse(stored);
+  } catch {
+    return [];
+  }
+}
+function updatePendingWithdrawal(requestId, updates) {
+  const storage = getStorage();
+  if (!storage) return;
+  const withdrawals = loadPendingWithdrawals();
+  const index = withdrawals.findIndex((w) => w.requestId === requestId);
+  if (index >= 0) {
+    withdrawals[index] = { ...withdrawals[index], ...updates };
+    storage.setItem(PENDING_WITHDRAWALS_KEY, JSON.stringify(withdrawals));
+  }
+}
+function removePendingWithdrawal(requestId) {
+  const storage = getStorage();
+  if (!storage) return;
+  const withdrawals = loadPendingWithdrawals();
+  const filtered = withdrawals.filter((w) => w.requestId !== requestId);
+  storage.setItem(PENDING_WITHDRAWALS_KEY, JSON.stringify(filtered));
+}
+function clearPendingWithdrawals() {
+  const storage = getStorage();
+  if (storage) {
+    storage.removeItem(PENDING_WITHDRAWALS_KEY);
+  }
+}
+function hasPendingOperations() {
+  const deposits = loadPendingDeposits();
+  const withdrawals = loadPendingWithdrawals();
+  const pendingDeposits = deposits.filter(
+    (d) => d.status === "pending" || d.status === "tx_sent"
+  );
+  const pendingWithdrawals = withdrawals.filter(
+    (w) => w.status === "pending" || w.status === "processing"
+  );
+  return pendingDeposits.length > 0 || pendingWithdrawals.length > 0;
+}
+function getPendingOperationsSummary() {
+  const deposits = loadPendingDeposits().filter(
+    (d) => d.status === "pending" || d.status === "tx_sent"
+  );
+  const withdrawals = loadPendingWithdrawals().filter(
+    (w) => w.status === "pending" || w.status === "processing"
+  );
+  return {
+    deposits,
+    withdrawals,
+    totalPending: deposits.length + withdrawals.length
+  };
+}
+function cleanupStalePendingOperations(maxAgeMs = 24 * 60 * 60 * 1e3) {
+  const now = Date.now();
+  let removedDeposits = 0;
+  let removedWithdrawals = 0;
+  const deposits = loadPendingDeposits();
+  const activeDeposits = deposits.filter((d) => {
+    const age = now - d.startedAt;
+    const isStale = age > maxAgeMs;
+    const isTerminal = d.status === "confirmed" || d.status === "failed";
+    if (isStale || isTerminal) {
+      removedDeposits++;
+      return false;
+    }
+    return true;
+  });
+  const storage = getStorage();
+  if (storage) {
+    storage.setItem(PENDING_DEPOSITS_KEY, JSON.stringify(activeDeposits));
+  }
+  const withdrawals = loadPendingWithdrawals();
+  const activeWithdrawals = withdrawals.filter((w) => {
+    const age = now - w.startedAt;
+    const isStale = age > maxAgeMs;
+    const isTerminal = w.status === "completed" || w.status === "failed";
+    if (isStale || isTerminal) {
+      removedWithdrawals++;
+      return false;
+    }
+    return true;
+  });
+  if (storage) {
+    storage.setItem(PENDING_WITHDRAWALS_KEY, JSON.stringify(activeWithdrawals));
+  }
+  return { removedDeposits, removedWithdrawals };
+}
+
 // src/index.ts
 var VERSION = "1.0.0";
 export {
@@ -3147,12 +4091,14 @@ export {
   CloakError,
   CloakSDK,
   DepositRecoveryService,
+  EXPECTED_CIRCUIT_HASHES,
   FIXED_FEE_LAMPORTS,
   IndexerService,
   LAMPORTS_PER_SOL,
   LocalStorageAdapter,
   MemoryStorageAdapter,
   RelayService,
+  ShieldPoolErrors,
   VARIABLE_FEE_RATE,
   VERSION,
   bigintToBytes32,
@@ -3160,6 +4106,9 @@ export {
   bytesToHex,
   calculateFee2 as calculateFee,
   calculateRelayFee,
+  cleanupStalePendingOperations,
+  clearPendingDeposits,
+  clearPendingWithdrawals,
   computeCommitment,
   computeMerkleRoot,
   computeNullifier,
@@ -3199,12 +4148,14 @@ export {
   getAddressExplorerUrl,
   getDistributableAmount2 as getDistributableAmount,
   getExplorerUrl,
+  getPendingOperationsSummary,
   getPublicKey,
   getPublicViewKey,
   getRecipientAmount,
   getRpcUrlForNetwork,
   getShieldPoolPDAs,
   getViewKey,
+  hasPendingOperations,
   hexToBigint,
   hexToBytes,
   importKeys,
@@ -3214,7 +4165,10 @@ export {
   isValidSolanaAddress,
   isWithdrawable,
   keypairToAdapter,
+  loadPendingDeposits,
+  loadPendingWithdrawals,
   parseAmount,
+  parseError,
   parseNote,
   parseTransactionError,
   poseidonHash,
@@ -3223,6 +4177,10 @@ export {
   proofToBytes,
   pubkeyToLimbs,
   randomBytes,
+  removePendingDeposit,
+  removePendingWithdrawal,
+  savePendingDeposit,
+  savePendingWithdrawal,
   scanNotesForWallet,
   sendTransaction,
   serializeNote,
@@ -3230,10 +4188,14 @@ export {
   splitTo2Limbs,
   tryDecryptNote,
   updateNoteWithDeposit,
+  updatePendingDeposit,
+  updatePendingWithdrawal,
   validateDepositParams,
   validateNote,
   validateOutputsSum,
   validateTransfers,
   validateWalletConnected,
-  validateWithdrawableNote
+  validateWithdrawableNote,
+  verifyAllCircuits,
+  verifyCircuitIntegrity
 };