@cloak.ag/sdk 1.0.4 → 1.0.5

package/dist/index.js

@@ -172,14 +172,14 @@ function randomBytes(length) {
   } catch {
   }
   try {
-    const nodeCrypto = __require("crypto");
-    if (nodeCrypto?.randomBytes) {
-      const buffer = nodeCrypto.randomBytes(length);
+    const nodeCrypto2 = __require("crypto");
+    if (nodeCrypto2?.randomBytes) {
+      const buffer = nodeCrypto2.randomBytes(length);
       bytes.set(buffer);
       return bytes;
     }
-    if (nodeCrypto?.webcrypto?.getRandomValues) {
-      nodeCrypto.webcrypto.getRandomValues(bytes);
+    if (nodeCrypto2?.webcrypto?.getRandomValues) {
+      nodeCrypto2.webcrypto.getRandomValues(bytes);
       return bytes;
     }
   } catch {
@@ -301,8 +301,8 @@ function generateMasterSeed() {
     cryptoObj.getRandomValues(seed);
   } else {
     try {
-      const nodeCrypto = __require("crypto");
-      const buffer = nodeCrypto.randomBytes(32);
+      const nodeCrypto2 = __require("crypto");
+      const buffer = nodeCrypto2.randomBytes(32);
       seed.set(buffer);
     } catch {
       throw new Error("No secure random number generator available");
@@ -1043,6 +1043,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 +1054,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 +1100,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 +1221,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 +1263,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 +1502,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 +1749,15 @@ 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";
 function joinPath(...parts) {
-  const isBrowser = typeof window !== "undefined" || typeof globalThis !== "undefined" && globalThis.window;
-  if (!isBrowser && path) {
-    return path.join(...parts);
+  if (IS_BROWSER) {
+    return parts.join("/").replace(/\/+/g, "/");
   }
   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,18 +1765,26 @@ async function fileExists(filePath) {
       return false;
     }
   }
-  return false;
+  try {
+    const nodeFs2 = globalThis.require?.("fs") || (typeof __require !== "undefined" ? __require("fs") : null);
+    if (nodeFs2) {
+      return nodeFs2.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;
+async function generateWithdrawRegularProof(inputs, circuitsPath2) {
   let wasmPath;
   let zkeyPath;
-  if (isBrowser) {
-    wasmPath = `${circuitsPath}/withdraw_regular_js/withdraw_regular.wasm`;
-    zkeyPath = `${circuitsPath}/withdraw_regular_final.zkey`;
+  if (IS_BROWSER) {
+    wasmPath = `${circuitsPath2}/withdraw_regular_js/withdraw_regular.wasm`;
+    zkeyPath = `${circuitsPath2}/withdraw_regular_final.zkey`;
   } else {
-    wasmPath = joinPath(circuitsPath, "build", "withdraw_regular_js", "withdraw_regular.wasm");
-    zkeyPath = joinPath(circuitsPath, "build", "withdraw_regular_final.zkey");
+    wasmPath = joinPath(circuitsPath2, "build", "withdraw_regular_js", "withdraw_regular.wasm");
+    zkeyPath = joinPath(circuitsPath2, "build", "withdraw_regular_final.zkey");
     const wasmExists = await fileExists(wasmPath);
     const zkeyExists = await fileExists(zkeyPath);
     if (!wasmExists) {
@@ -1724,16 +1826,15 @@ async function generateWithdrawRegularProof(inputs, circuitsPath) {
     // Not used, kept for compatibility
   };
 }
-async function generateWithdrawSwapProof(inputs, circuitsPath) {
-  const isBrowser = typeof window !== "undefined" || typeof globalThis !== "undefined" && globalThis.window;
+async function generateWithdrawSwapProof(inputs, circuitsPath2) {
   let wasmPath;
   let zkeyPath;
-  if (isBrowser) {
-    wasmPath = `${circuitsPath}/withdraw_swap_js/withdraw_swap.wasm`;
-    zkeyPath = `${circuitsPath}/withdraw_swap_final.zkey`;
+  if (IS_BROWSER) {
+    wasmPath = `${circuitsPath2}/withdraw_swap_js/withdraw_swap.wasm`;
+    zkeyPath = `${circuitsPath2}/withdraw_swap_final.zkey`;
   } else {
-    wasmPath = joinPath(circuitsPath, "build", "withdraw_swap_js", "withdraw_swap.wasm");
-    zkeyPath = joinPath(circuitsPath, "build", "withdraw_swap_final.zkey");
+    wasmPath = joinPath(circuitsPath2, "build", "withdraw_swap_js", "withdraw_swap.wasm");
+    zkeyPath = joinPath(circuitsPath2, "build", "withdraw_swap_final.zkey");
     const wasmExists = await fileExists(wasmPath);
     const zkeyExists = await fileExists(zkeyPath);
     if (!wasmExists) {
@@ -1782,32 +1883,35 @@ async function generateWithdrawSwapProof(inputs, circuitsPath) {
     // Not used, kept for compatibility
   };
 }
-async function areCircuitsAvailable(circuitsPath) {
-  const isBrowser = typeof window !== "undefined" || typeof globalThis !== "undefined" && globalThis.window;
-  if (isBrowser) {
-    return Boolean(circuitsPath && circuitsPath !== "");
+async function areCircuitsAvailable(circuitsPath2) {
+  if (IS_BROWSER) {
+    return Boolean(circuitsPath2 && circuitsPath2 !== "");
   }
-  const wasmPath = joinPath(circuitsPath, "build", "withdraw_regular_js", "withdraw_regular.wasm");
-  const zkeyPath = joinPath(circuitsPath, "build", "withdraw_regular_final.zkey");
+  const wasmPath = joinPath(circuitsPath2, "build", "withdraw_regular_js", "withdraw_regular.wasm");
+  const zkeyPath = joinPath(circuitsPath2, "build", "withdraw_regular_final.zkey");
   const wasmExists = await fileExists(wasmPath);
   const zkeyExists = await fileExists(zkeyPath);
   return wasmExists && zkeyExists;
 }
 async function getDefaultCircuitsPath() {
-  const isBrowser = typeof window !== "undefined" || typeof globalThis !== "undefined" && globalThis.window;
-  if (isBrowser) {
+  if (IS_BROWSER) {
     return "/circuits";
   }
-  const { path: path2 } = await loadNodeModules();
-  if (!path2 || typeof process === "undefined" || !process.cwd) {
+  if (typeof process === "undefined" || !process.cwd) {
+    return "/circuits";
+  }
+  let nodePath;
+  try {
+    nodePath = eval("require")("path");
+  } 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,6 +1920,90 @@ 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 = eval("require")("fs");
+        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 = eval("require")("crypto");
+      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(circuitsPath2) {
+  const results = await Promise.all([
+    verifyCircuitIntegrity(circuitsPath2, "withdraw_regular"),
+    verifyCircuitIntegrity(circuitsPath2, "withdraw_swap")
+  ]);
+  return results;
+}
 
 // src/core/CloakSDK.ts
 var CLOAK_PROGRAM_ID = new PublicKey4("c1oak6tetxYnNfvXKFkpn1d98FxtK7B68vBQLYQpWKp");
@@ -1930,14 +2118,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;
@@ -2129,6 +2338,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,
@@ -2230,8 +2449,8 @@ var CloakSDK = class {
       }
     }
     const isBrowser = typeof window !== "undefined" || typeof globalThis !== "undefined" && globalThis.window;
-    const circuitsPath = isBrowser ? "/circuits" : typeof process !== "undefined" && process.env?.CIRCUITS_PATH || await getDefaultCircuitsPath();
-    const useDirectProof = await areCircuitsAvailable(circuitsPath);
+    const circuitsPath2 = isBrowser ? "/circuits" : typeof process !== "undefined" && process.env?.CIRCUITS_PATH || await getDefaultCircuitsPath();
+    const useDirectProof = await areCircuitsAvailable(circuitsPath2);
     let proofHex;
     let finalPublicInputs;
     if (useDirectProof) {
@@ -2293,7 +2512,7 @@ var CloakSDK = class {
         rem
       };
       options?.onProgress?.("proof_generating");
-      const proofResult = await generateWithdrawRegularProof(proofInputs, circuitsPath);
+      const proofResult = await generateWithdrawRegularProof(proofInputs, circuitsPath2);
       options?.onProgress?.("proof_complete");
       proofHex = Buffer.from(proofResult.proofBytes).toString("hex");
       finalPublicInputs = {
@@ -2304,7 +2523,7 @@ var CloakSDK = class {
       };
     } else {
       throw new Error(
-        `Circuits not available at ${circuitsPath}. Make sure circuits are built and accessible. In browser, circuits should be served from /circuits. In Node.js, set CIRCUITS_PATH environment variable or ensure circuits are in the expected location.`
+        `Circuits not available at ${circuitsPath2}. Make sure circuits are built and accessible. In browser, circuits should be served from /circuits. In Node.js, set CIRCUITS_PATH environment variable or ensure circuits are in the expected location.`
       );
     }
     const signature = await this.relay.submitWithdraw(
@@ -2501,8 +2720,8 @@ var CloakSDK = class {
         throw new Error("Merkle proof is invalid: missing path elements");
       }
       const envCircuitsPath = typeof window !== "undefined" ? typeof process !== "undefined" && process.env?.NEXT_PUBLIC_CIRCUITS_PATH || void 0 : typeof process !== "undefined" && process.env?.CIRCUITS_PATH || void 0;
-      const circuitsPath = envCircuitsPath || await getDefaultCircuitsPath();
-      const useDirectProof = await areCircuitsAvailable(circuitsPath);
+      const circuitsPath2 = envCircuitsPath || await getDefaultCircuitsPath();
+      const useDirectProof = await areCircuitsAvailable(circuitsPath2);
       let proofHex;
       let finalPublicInputs;
       if (useDirectProof) {
@@ -2545,7 +2764,7 @@ var CloakSDK = class {
           rem
         };
         options?.onProgress?.("proof_generating");
-        const proofResult = await generateWithdrawSwapProof(proofInputs, circuitsPath);
+        const proofResult = await generateWithdrawSwapProof(proofInputs, circuitsPath2);
         options?.onProgress?.("proof_complete");
         proofHex = Buffer.from(proofResult.proofBytes).toString("hex");
         finalPublicInputs = {
@@ -2556,7 +2775,7 @@ var CloakSDK = class {
         };
       } else {
         throw new Error(
-          `Circuits not available at ${circuitsPath}. Make sure circuits are built and accessible. In browser, circuits should be served from /circuits. In Node.js, set CIRCUITS_PATH environment variable or ensure circuits are in the expected location.`
+          `Circuits not available at ${circuitsPath2}. Make sure circuits are built and accessible. In browser, circuits should be served from /circuits. In Node.js, set CIRCUITS_PATH environment variable or ensure circuits are in the expected location.`
         );
       }
       const signature = await this.relay.submitSwap(
@@ -2931,6 +3150,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 +3235,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 +3848,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 +4022,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 +4037,9 @@ export {
   bytesToHex,
   calculateFee2 as calculateFee,
   calculateRelayFee,
+  cleanupStalePendingOperations,
+  clearPendingDeposits,
+  clearPendingWithdrawals,
   computeCommitment,
   computeMerkleRoot,
   computeNullifier,
@@ -3199,12 +4079,14 @@ export {
   getAddressExplorerUrl,
   getDistributableAmount2 as getDistributableAmount,
   getExplorerUrl,
+  getPendingOperationsSummary,
   getPublicKey,
   getPublicViewKey,
   getRecipientAmount,
   getRpcUrlForNetwork,
   getShieldPoolPDAs,
   getViewKey,
+  hasPendingOperations,
   hexToBigint,
   hexToBytes,
   importKeys,
@@ -3214,7 +4096,10 @@ export {
   isValidSolanaAddress,
   isWithdrawable,
   keypairToAdapter,
+  loadPendingDeposits,
+  loadPendingWithdrawals,
   parseAmount,
+  parseError,
   parseNote,
   parseTransactionError,
   poseidonHash,
@@ -3223,6 +4108,10 @@ export {
   proofToBytes,
   pubkeyToLimbs,
   randomBytes,
+  removePendingDeposit,
+  removePendingWithdrawal,
+  savePendingDeposit,
+  savePendingWithdrawal,
   scanNotesForWallet,
   sendTransaction,
   serializeNote,
@@ -3230,10 +4119,14 @@ export {
   splitTo2Limbs,
   tryDecryptNote,
   updateNoteWithDeposit,
+  updatePendingDeposit,
+  updatePendingWithdrawal,
   validateDepositParams,
   validateNote,
   validateOutputsSum,
   validateTransfers,
   validateWalletConnected,
-  validateWithdrawableNote
+  validateWithdrawableNote,
+  verifyAllCircuits,
+  verifyCircuitIntegrity
 };