@cloak.dev/sdk 0.1.7 → 0.1.8

package/dist/index.js

@@ -24,7 +24,10 @@ import {
 // src/core/CloakSDK.ts
 import {
   Keypair,
-  PublicKey as PublicKey2
+  PublicKey as PublicKey4,
+  Transaction,
+  TransactionInstruction as TransactionInstruction2,
+  ComputeBudgetProgram
 } from "@solana/web3.js";
 
 // src/core/types.ts
@@ -82,6 +85,79 @@ function hexToBigint2(hex) {
   const cleanHex = hex.startsWith("0x") ? hex.slice(2) : hex;
   return BigInt("0x" + cleanHex);
 }
+async function computeCommitment2(amount, r, sk_spend) {
+  const [sk0, sk1] = splitTo2Limbs(sk_spend);
+  const [r0, r1] = splitTo2Limbs(r);
+  const pk_spend = await poseidonHash([sk0, sk1]);
+  return await poseidonHash([amount, r0, r1, pk_spend]);
+}
+async function generateCommitmentAsync(amountLamports, r, skSpend) {
+  const amount = BigInt(amountLamports);
+  const rValue = hexToBigint2(bytesToHex(r));
+  const skValue = hexToBigint2(bytesToHex(skSpend));
+  return await computeCommitment2(amount, rValue, skValue);
+}
+function generateCommitment(_amountLamports, _r, _skSpend) {
+  throw new Error("generateCommitment is deprecated. Use generateCommitmentAsync instead.");
+}
+async function computeNullifier2(sk_spend, leafIndex) {
+  const [sk0, sk1] = splitTo2Limbs(sk_spend);
+  return await poseidonHash([sk0, sk1, leafIndex]);
+}
+async function computeNullifierAsync(skSpend, leafIndex) {
+  const skValue = typeof skSpend === "string" ? hexToBigint2(skSpend) : hexToBigint2(bytesToHex(skSpend));
+  return await computeNullifier2(skValue, BigInt(leafIndex));
+}
+function computeNullifierSync(_skSpend, _leafIndex) {
+  throw new Error("computeNullifierSync is deprecated. Use computeNullifierAsync instead.");
+}
+async function computeOutputsHashAsync(outputs) {
+  let hash = 0n;
+  for (const output of outputs) {
+    const [lo, hi] = pubkeyToLimbs(output.recipient);
+    hash = await poseidonHash([hash, lo, hi, BigInt(output.amount)]);
+  }
+  return hash;
+}
+async function computeOutputsHash(outAddr, outAmount, outFlags) {
+  let hash = 0n;
+  for (let i = 0; i < 5; i++) {
+    if (outFlags[i] === 1) {
+      hash = await poseidonHash([hash, outAddr[i][0], outAddr[i][1], outAmount[i]]);
+    }
+  }
+  return hash;
+}
+function computeOutputsHashSync(_outputs) {
+  throw new Error("computeOutputsHashSync is deprecated. Use computeOutputsHashAsync instead.");
+}
+async function computeSwapOutputsHash(inputMintLimbs, outputMintLimbs, recipientAtaLimbs, minOutputAmount, publicAmount) {
+  return await poseidonHash([
+    inputMintLimbs[0],
+    inputMintLimbs[1],
+    outputMintLimbs[0],
+    outputMintLimbs[1],
+    recipientAtaLimbs[0],
+    recipientAtaLimbs[1],
+    minOutputAmount,
+    publicAmount
+  ]);
+}
+async function computeSwapOutputsHashAsync(inputMint, outputMint, recipientAta, minOutputAmount, amount) {
+  const inputMintLimbs = pubkeyToLimbs(inputMint);
+  const outputMintLimbs = pubkeyToLimbs(outputMint);
+  const recipientAtaLimbs = pubkeyToLimbs(recipientAta);
+  return await computeSwapOutputsHash(
+    inputMintLimbs,
+    outputMintLimbs,
+    recipientAtaLimbs,
+    BigInt(minOutputAmount),
+    BigInt(amount)
+  );
+}
+function computeSwapOutputsHashSync(_outputMint, _recipientAta, _minOutputAmount, _amount) {
+  throw new Error("computeSwapOutputsHashSync is deprecated. Use computeSwapOutputsHashAsync instead.");
+}
 function bigintToBytes322(n) {
   const hex = n.toString(16).padStart(64, "0");
   const bytes = new Uint8Array(32);
@@ -354,11 +430,223 @@ function importKeys(exported) {
   return generateCloakKeys(masterSeed);
 }
 
+// src/utils/network.ts
+function detectNetworkFromRpcUrl(rpcUrl) {
+  const url = rpcUrl || process.env.NEXT_PUBLIC_SOLANA_RPC_URL || "";
+  const lowerUrl = url.toLowerCase();
+  if (lowerUrl.includes("mainnet") || lowerUrl.includes("api.mainnet-beta") || lowerUrl.includes("mainnet-beta")) {
+    return "mainnet";
+  }
+  if (lowerUrl.includes("testnet") || lowerUrl.includes("api.testnet")) {
+    return "testnet";
+  }
+  if (lowerUrl.includes("devnet") || lowerUrl.includes("api.devnet")) {
+    return "devnet";
+  }
+  if (lowerUrl.includes("localhost") || lowerUrl.includes("127.0.0.1") || lowerUrl.includes("local")) {
+    return "localnet";
+  }
+  return "mainnet";
+}
+function getRpcUrlForNetwork(network) {
+  switch (network) {
+    case "mainnet":
+      return "https://api.mainnet-beta.solana.com";
+    case "devnet":
+      return "https://api.devnet.solana.com";
+    case "localnet":
+      return "http://localhost:8899";
+    default:
+      return "https://api.mainnet-beta.solana.com";
+  }
+}
+function isValidRpcUrl(url) {
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === "http:" || parsed.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+function getExplorerUrl(signature, network = "devnet") {
+  const cluster = network === "mainnet" ? "" : `?cluster=${network}`;
+  return `https://explorer.solana.com/tx/${signature}${cluster}`;
+}
+function getAddressExplorerUrl(address, network = "devnet") {
+  const cluster = network === "mainnet" ? "" : `?cluster=${network}`;
+  return `https://explorer.solana.com/address/${address}${cluster}`;
+}
+
+// src/utils/fees.ts
+var LAMPORTS_PER_SOL = 1e9;
+var FIXED_FEE_LAMPORTS = 5e6;
+var VARIABLE_FEE_NUMERATOR = 3;
+var VARIABLE_FEE_DENOMINATOR = 1e3;
+var VARIABLE_FEE_RATE = VARIABLE_FEE_NUMERATOR / VARIABLE_FEE_DENOMINATOR;
+var MIN_DEPOSIT_LAMPORTS = 1e7;
+function calculateFee(amountLamports) {
+  const variableFee = Math.floor(amountLamports * VARIABLE_FEE_NUMERATOR / VARIABLE_FEE_DENOMINATOR);
+  return FIXED_FEE_LAMPORTS + variableFee;
+}
+function calculateFeeBigint(amountLamports) {
+  const fixed = BigInt(FIXED_FEE_LAMPORTS);
+  const variable = amountLamports * BigInt(VARIABLE_FEE_NUMERATOR) / BigInt(VARIABLE_FEE_DENOMINATOR);
+  return fixed + variable;
+}
+function isWithdrawAmountSufficient(amountLamports) {
+  return amountLamports > calculateFeeBigint(amountLamports);
+}
+function getDistributableAmount(amountLamports) {
+  return amountLamports - calculateFee(amountLamports);
+}
+function formatAmount(lamports, decimals = 9) {
+  return (lamports / LAMPORTS_PER_SOL).toFixed(decimals);
+}
+function parseAmount(sol) {
+  const num = parseFloat(sol);
+  if (isNaN(num) || num < 0) {
+    throw new Error(`Invalid SOL amount: ${sol}`);
+  }
+  return Math.floor(num * LAMPORTS_PER_SOL);
+}
+function validateOutputsSum(outputs, expectedTotal) {
+  const sum = outputs.reduce((acc, out) => acc + out.amount, 0);
+  return sum === expectedTotal;
+}
+function calculateRelayFee(amountLamports, feeBps) {
+  if (feeBps < 0 || feeBps > 1e4) {
+    throw new Error("Fee basis points must be between 0 and 10000");
+  }
+  return Math.floor(amountLamports * feeBps / 1e4);
+}
+
+// src/core/note-manager.ts
+async function generateNote(amountLamports, network) {
+  const actualNetwork = network || detectNetworkFromRpcUrl();
+  const skSpend = randomBytes(32);
+  const rBytes = randomBytes(32);
+  const commitmentBigint = await generateCommitmentAsync(amountLamports, rBytes, skSpend);
+  const commitmentHex = commitmentBigint.toString(16).padStart(64, "0");
+  const skSpendHex = bytesToHex(skSpend);
+  const rHex = bytesToHex(rBytes);
+  return {
+    version: "1.0",
+    amount: amountLamports,
+    commitment: commitmentHex,
+    sk_spend: skSpendHex,
+    r: rHex,
+    timestamp: Date.now(),
+    network: actualNetwork
+  };
+}
+async function generateNoteFromWallet(amountLamports, keys, network) {
+  const actualNetwork = network || detectNetworkFromRpcUrl();
+  const rBytes = randomBytes(32);
+  const sk_spend = hexToBytes(keys.spend.sk_spend_hex);
+  const commitmentBigint = await generateCommitmentAsync(amountLamports, rBytes, sk_spend);
+  const commitmentHex = commitmentBigint.toString(16).padStart(64, "0");
+  return {
+    version: "2.0",
+    amount: amountLamports,
+    commitment: commitmentHex,
+    sk_spend: keys.spend.sk_spend_hex,
+    r: bytesToHex(rBytes),
+    timestamp: Date.now(),
+    network: actualNetwork
+  };
+}
+function parseNote(jsonString) {
+  const note = JSON.parse(jsonString);
+  if (!note.version || !note.amount || !note.commitment || !note.sk_spend || !note.r) {
+    throw new CloakError(
+      "Invalid note format: missing required fields",
+      "validation",
+      false
+    );
+  }
+  if (!/^[0-9a-f]{64}$/i.test(note.commitment)) {
+    throw new CloakError("Invalid commitment format", "validation", false);
+  }
+  if (!/^[0-9a-f]{64}$/i.test(note.sk_spend)) {
+    throw new CloakError("Invalid sk_spend format", "validation", false);
+  }
+  if (!/^[0-9a-f]{64}$/i.test(note.r)) {
+    throw new CloakError("Invalid r format", "validation", false);
+  }
+  return note;
+}
+function exportNote(note, pretty = false) {
+  return pretty ? JSON.stringify(note, null, 2) : JSON.stringify(note);
+}
+function isWithdrawable(note) {
+  return !!(note.depositSignature && note.leafIndex !== void 0 && note.root);
+}
+function updateNoteWithDeposit(note, depositInfo) {
+  const updated = {
+    ...note,
+    depositSignature: depositInfo.signature,
+    depositSlot: depositInfo.slot,
+    leafIndex: depositInfo.leafIndex,
+    root: depositInfo.root
+  };
+  if (depositInfo.merkleProof) {
+    updated.merkleProof = depositInfo.merkleProof;
+  }
+  return updated;
+}
+function findNoteByCommitment(notes, commitment) {
+  return notes.find((n) => n.commitment === commitment);
+}
+function filterNotesByNetwork(notes, network) {
+  return notes.filter((n) => n.network === network);
+}
+function filterWithdrawableNotes(notes) {
+  return notes.filter(isWithdrawable);
+}
+function exportWalletKeys(keys) {
+  return exportKeys(keys);
+}
+function importWalletKeys(keysJson) {
+  return importKeys(keysJson);
+}
+function getPublicViewKey(keys) {
+  return keys.view.pvk_hex;
+}
+function getViewKey(keys) {
+  return keys.view;
+}
+var calculateFee2 = calculateFee;
+function getDistributableAmount2(amountLamports) {
+  return amountLamports - calculateFee2(amountLamports);
+}
+function getRecipientAmount(amountLamports) {
+  return getDistributableAmount2(amountLamports);
+}
+
 // src/core/storage.ts
 var MemoryStorageAdapter = class {
   constructor() {
+    this.notes = /* @__PURE__ */ new Map();
     this.keys = null;
   }
+  saveNote(note) {
+    this.notes.set(note.commitment, note);
+  }
+  loadAllNotes() {
+    return Array.from(this.notes.values());
+  }
+  updateNote(commitment, updates) {
+    const existing = this.notes.get(commitment);
+    if (existing) {
+      this.notes.set(commitment, { ...existing, ...updates });
+    }
+  }
+  deleteNote(commitment) {
+    this.notes.delete(commitment);
+  }
+  clearAllNotes() {
+    this.notes.clear();
+  }
   saveKeys(keys) {
     this.keys = keys;
   }
@@ -369,10 +657,10 @@ var MemoryStorageAdapter = class {
     this.keys = null;
   }
 };
-var _LocalStorageAdapter = class _LocalStorageAdapter {
-  constructor(keysKey = "cloak_wallet_keys") {
+var LocalStorageAdapter = class {
+  constructor(notesKey = "cloak_notes", keysKey = "cloak_wallet_keys") {
+    this.notesKey = notesKey;
     this.keysKey = keysKey;
-    _LocalStorageAdapter.runLegacyPurgeOnce();
   }
   getStorage() {
     if (typeof globalThis !== "undefined" && globalThis.localStorage) {
@@ -380,6 +668,47 @@ var _LocalStorageAdapter = class _LocalStorageAdapter {
     }
     return null;
   }
+  saveNote(note) {
+    const storage = this.getStorage();
+    if (!storage) throw new Error("localStorage not available");
+    const notes = this.loadAllNotes();
+    notes.push(note);
+    storage.setItem(this.notesKey, JSON.stringify(notes));
+  }
+  loadAllNotes() {
+    const storage = this.getStorage();
+    if (!storage) return [];
+    const stored = storage.getItem(this.notesKey);
+    if (!stored) return [];
+    try {
+      return JSON.parse(stored);
+    } catch {
+      return [];
+    }
+  }
+  updateNote(commitment, updates) {
+    const storage = this.getStorage();
+    if (!storage) return;
+    const notes = this.loadAllNotes();
+    const index = notes.findIndex((n) => n.commitment === commitment);
+    if (index !== -1) {
+      notes[index] = { ...notes[index], ...updates };
+      storage.setItem(this.notesKey, JSON.stringify(notes));
+    }
+  }
+  deleteNote(commitment) {
+    const storage = this.getStorage();
+    if (!storage) return;
+    const notes = this.loadAllNotes();
+    const filtered = notes.filter((n) => n.commitment !== commitment);
+    storage.setItem(this.notesKey, JSON.stringify(filtered));
+  }
+  clearAllNotes() {
+    const storage = this.getStorage();
+    if (storage) {
+      storage.removeItem(this.notesKey);
+    }
+  }
   saveKeys(keys) {
     const storage = this.getStorage();
     if (!storage) throw new Error("localStorage not available");
@@ -402,64 +731,126 @@ var _LocalStorageAdapter = class _LocalStorageAdapter {
       storage.removeItem(this.keysKey);
     }
   }
-  /**
-   * Runs the legacy-purge exactly once per browser origin. Invoked
-   * automatically by the constructor; exposed as a static for tests and
-   * for callers who want to force the check before the first adapter
-   * instantiation.
-   */
-  static runLegacyPurgeOnce() {
-    if (typeof globalThis === "undefined" || !globalThis.localStorage) {
-      return;
+};
+
+// src/utils/validation.ts
+import { PublicKey } from "@solana/web3.js";
+function isValidSolanaAddress(address) {
+  try {
+    new PublicKey(address);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function validateNote(note) {
+  if (!note || typeof note !== "object") {
+    throw new Error("Note must be an object");
+  }
+  const requiredFields = ["version", "amount", "commitment", "sk_spend", "r", "timestamp", "network"];
+  for (const field of requiredFields) {
+    if (!(field in note)) {
+      throw new Error(`Missing required field: ${field}`);
     }
-    const storage = globalThis.localStorage;
-    if (storage.getItem(_LocalStorageAdapter.LEGACY_PURGE_SENTINEL_KEY)) {
-      return;
+  }
+  if (typeof note.version !== "string") {
+    throw new Error("Version must be a string");
+  }
+  if (typeof note.amount !== "number" || note.amount <= 0) {
+    throw new Error("Amount must be a positive number");
+  }
+  if (!isValidHex(note.commitment, 32)) {
+    throw new Error("Invalid commitment format (expected 64 hex characters)");
+  }
+  if (!isValidHex(note.sk_spend, 32)) {
+    throw new Error("Invalid sk_spend format (expected 64 hex characters)");
+  }
+  if (!isValidHex(note.r, 32)) {
+    throw new Error("Invalid r format (expected 64 hex characters)");
+  }
+  if (typeof note.timestamp !== "number" || note.timestamp <= 0) {
+    throw new Error("Timestamp must be a positive number");
+  }
+  if (!["localnet", "devnet", "testnet", "mainnet"].includes(note.network)) {
+    throw new Error("Network must be localnet, devnet, testnet, or mainnet");
+  }
+  if (note.depositSignature !== void 0 && typeof note.depositSignature !== "string") {
+    throw new Error("Deposit signature must be a string");
+  }
+  if (note.depositSlot !== void 0 && typeof note.depositSlot !== "number") {
+    throw new Error("Deposit slot must be a number");
+  }
+  if (note.leafIndex !== void 0) {
+    if (typeof note.leafIndex !== "number" || note.leafIndex < 0) {
+      throw new Error("Leaf index must be a non-negative number");
     }
-    storage.removeItem(_LocalStorageAdapter.LEGACY_NOTES_KEY);
-    try {
-      storage.setItem(_LocalStorageAdapter.LEGACY_PURGE_SENTINEL_KEY, "1");
-    } catch {
+  }
+  if (note.root !== void 0 && !isValidHex(note.root, 32)) {
+    throw new Error("Invalid root format (expected 64 hex characters)");
+  }
+  if (note.merkleProof !== void 0) {
+    if (!Array.isArray(note.merkleProof.pathElements)) {
+      throw new Error("Merkle proof pathElements must be an array");
+    }
+    if (!Array.isArray(note.merkleProof.pathIndices)) {
+      throw new Error("Merkle proof pathIndices must be an array");
+    }
+    if (note.merkleProof.pathElements.length !== note.merkleProof.pathIndices.length) {
+      throw new Error("Merkle proof pathElements and pathIndices must have same length");
     }
   }
-  /**
-   * Manual cleanup helper for callers that stored notes under a non-default
-   * key. The auto-purge in the constructor only handles the canonical
-   * `cloak_notes` slot; pass the custom key here.
-   *
-   * Pre-0.1.6 versions stored the user's `CloakNote[]` (including
-   * `r` randomness and `sk_spend` secret-key hex) as JSON plaintext.
-   * Those notes are no longer usable (the OLD `withdraw_regular.circom`
-   * flow is incompatible with the deployed UTXO program) but the plaintext
-   * would otherwise linger indefinitely.
-   *
-   * Idempotent; safe to call when the key doesn't exist or when running
-   * outside a browser (no-op). Does NOT update the auto-purge sentinel.
-   *
-   * @param notesKey - localStorage key to remove (default `"cloak_notes"`,
-   *   matching the pre-0.1.6 default).
-   */
-  static purgeLegacyNoteStorage(notesKey = _LocalStorageAdapter.LEGACY_NOTES_KEY) {
-    if (typeof globalThis === "undefined" || !globalThis.localStorage) {
-      return;
+}
+function parseNote2(jsonString) {
+  let parsed;
+  try {
+    parsed = JSON.parse(jsonString);
+  } catch (error) {
+    throw new Error("Invalid JSON format");
+  }
+  validateNote(parsed);
+  return parsed;
+}
+function validateWithdrawableNote(note) {
+  if (!note.depositSignature) {
+    throw new Error("Note must be deposited before withdrawal (missing depositSignature)");
+  }
+  if (note.leafIndex === void 0) {
+    throw new Error("Note must be deposited before withdrawal (missing leafIndex)");
+  }
+  if (!note.root) {
+    throw new Error("Note must have historical root for withdrawal");
+  }
+  if (!note.merkleProof) {
+    throw new Error("Note must have Merkle proof for withdrawal");
+  }
+  if (note.merkleProof.pathElements.length === 0) {
+    throw new Error("Merkle proof is empty");
+  }
+}
+function validateTransfers(recipients, totalAmount) {
+  if (recipients.length === 0) {
+    throw new Error("At least one recipient is required");
+  }
+  if (recipients.length > 5) {
+    throw new Error("Maximum 5 recipients allowed");
+  }
+  for (let i = 0; i < recipients.length; i++) {
+    const transfer2 = recipients[i];
+    const isPublicKeyLike = transfer2.recipient && typeof transfer2.recipient.toBase58 === "function" && typeof transfer2.recipient.toBuffer === "function";
+    if (!isPublicKeyLike) {
+      throw new Error(`Recipient ${i} must be a PublicKey (got ${typeof transfer2.recipient})`);
+    }
+    if (typeof transfer2.amount !== "number" || transfer2.amount <= 0) {
+      throw new Error(`Recipient ${i} amount must be a positive number`);
     }
-    globalThis.localStorage.removeItem(notesKey);
   }
-};
-/**
- * Sentinel key set after the auto-purge runs. Persists across browser
- * sessions so the purge never re-runs on the same origin.
- */
-_LocalStorageAdapter.LEGACY_PURGE_SENTINEL_KEY = "cloak_purged_v0_1_5";
-/**
- * Default localStorage key the legacy `<= 0.1.5` SDK used for the
- * plaintext `CloakNote[]` blob.
- */
-_LocalStorageAdapter.LEGACY_NOTES_KEY = "cloak_notes";
-var LocalStorageAdapter = _LocalStorageAdapter;
-
-// src/services/RelayService.ts
-import { sha256 } from "@noble/hashes/sha2";
+  const sum = recipients.reduce((acc, t) => acc + t.amount, 0);
+  if (sum !== totalAmount) {
+    throw new Error(
+      `Recipients sum (${sum}) does not match expected total (${totalAmount})`
+    );
+  }
+}
 
 // src/utils/errors.ts
 var RootNotFoundError = class extends Error {
@@ -519,7 +910,8 @@ function classifyRelayError(responseText, httpStatus) {
     inner = responseText;
   }
   const haystack = inner.toLowerCase();
-  if (haystack.includes("0x1020") || haystack.includes("doublespend")) {
+  if (haystack.includes("0x1020") || // 0x1020 as decimal in a JSON-stringified confirmTransaction err (`"Custom":4128`).
+  haystack.includes('"custom":4128') || haystack.includes("doublespend")) {
     return new UtxoAlreadySpentError(
       "This shielded balance was already spent. The UTXO's nullifier is registered on-chain \u2014 typically means you spent it via another session or device. Run verifyUtxos() to reconcile local state."
     );
@@ -1355,6 +1747,7 @@ function formatErrorForLogging(error) {
 }
 
 // src/services/RelayService.ts
+import { sha256 } from "@noble/hashes/sha2";
 var RelayService = class {
   /**
    * Create a new Relay Service client
@@ -1723,23 +2116,91 @@ var RelayService = class {
   }
 };
 
+// src/solana/instructions.ts
+import {
+  PublicKey as PublicKey2,
+  SystemProgram,
+  TransactionInstruction
+} from "@solana/web3.js";
+function createDepositInstruction(params) {
+  if (params.commitment.length !== 32) {
+    throw new Error(
+      `Invalid commitment length: ${params.commitment.length} (expected 32 bytes)`
+    );
+  }
+  if (params.amount <= 0) {
+    throw new Error("Amount must be positive");
+  }
+  const discriminant = new Uint8Array([1]);
+  const amountBytes = new Uint8Array(8);
+  new DataView(amountBytes.buffer).setBigUint64(
+    0,
+    BigInt(params.amount),
+    true
+    // little-endian
+  );
+  const data = new Uint8Array(41);
+  data.set(discriminant, 0);
+  data.set(amountBytes, 1);
+  data.set(params.commitment, 9);
+  return new TransactionInstruction({
+    programId: params.programId,
+    keys: [
+      // Account 0: Payer (signer, writable) - pays for transaction
+      { pubkey: params.payer, isSigner: true, isWritable: true },
+      // Account 1: Pool (writable) - receives SOL
+      { pubkey: params.pool, isSigner: false, isWritable: true },
+      // Account 2: System Program (readonly) - for transfers
+      { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
+      // Account 3: Merkle Tree (writable) - stores on-chain Merkle tree
+      { pubkey: params.merkleTree, isSigner: false, isWritable: true }
+    ],
+    data: Buffer.from(data)
+  });
+}
+function validateDepositParams(params) {
+  if (!(params.programId instanceof PublicKey2)) {
+    throw new Error("programId must be a PublicKey");
+  }
+  if (!(params.payer instanceof PublicKey2)) {
+    throw new Error("payer must be a PublicKey");
+  }
+  if (!(params.pool instanceof PublicKey2)) {
+    throw new Error("pool must be a PublicKey");
+  }
+  if (!(params.merkleTree instanceof PublicKey2)) {
+    throw new Error("merkleTree must be a PublicKey");
+  }
+  if (typeof params.amount !== "number" || params.amount <= 0) {
+    throw new Error("amount must be a positive number");
+  }
+  if (!(params.commitment instanceof Uint8Array)) {
+    throw new Error("commitment must be a Uint8Array");
+  }
+  if (params.commitment.length !== 32) {
+    throw new Error(
+      `commitment must be 32 bytes (got ${params.commitment.length})`
+    );
+  }
+}
+
 // src/utils/pda.ts
-import { PublicKey } from "@solana/web3.js";
+import { PublicKey as PublicKey3 } from "@solana/web3.js";
 function getShieldPoolPDAs(programId, mint = NATIVE_SOL_MINT) {
   const pid = programId || CLOAK_PROGRAM_ID;
-  const [pool] = PublicKey.findProgramAddressSync(
+  const [pool] = PublicKey3.findProgramAddressSync(
     [Buffer.from("pool"), mint.toBuffer()],
     pid
   );
-  const [merkleTree] = PublicKey.findProgramAddressSync(
+  const [merkleTree] = PublicKey3.findProgramAddressSync(
     [Buffer.from("merkle_tree"), mint.toBuffer()],
     pid
   );
-  const [treasury] = PublicKey.findProgramAddressSync(
+  const [treasury] = PublicKey3.findProgramAddressSync(
     [Buffer.from("treasury"), mint.toBuffer()],
     pid
   );
-  const [vaultAuthority] = PublicKey.findProgramAddressSync(
+  const [vaultAuthority] = PublicKey3.findProgramAddressSync(
     [Buffer.from("vault_authority"), mint.toBuffer()],
     pid
   );
@@ -1755,7 +2216,7 @@ function getNullifierPDA(poolPubkey, nullifier, programId) {
   if (nullifier.length !== 32) {
     throw new Error(`Nullifier must be 32 bytes, got ${nullifier.length}`);
   }
-  return PublicKey.findProgramAddressSync(
+  return PublicKey3.findProgramAddressSync(
     [Buffer.from("nullifier"), poolPubkey.toBuffer(), Buffer.from(nullifier)],
     pid
   );
@@ -1765,29 +2226,273 @@ function getSwapStatePDA(poolPubkey, nullifier, programId) {
   if (nullifier.length !== 32) {
     throw new Error(`Nullifier must be 32 bytes, got ${nullifier.length}`);
   }
-  return PublicKey.findProgramAddressSync(
+  return PublicKey3.findProgramAddressSync(
     [Buffer.from("swap_state"), poolPubkey.toBuffer(), Buffer.from(nullifier)],
     pid
   );
 }
 
-// src/utils/logger.ts
-var globalDebugEnabled = false;
-function checkEnvDebug() {
-  if (typeof process !== "undefined" && process.env) {
-    return !!(process.env.CLOAK_DEBUG === "1" || process.env.CLOAK_DEBUG === "true" || process.env.DEBUG?.includes("cloak"));
+// src/utils/proof-generation.ts
+import * as snarkjs from "snarkjs";
+var IS_REACT_NATIVE = typeof navigator !== "undefined" && navigator.product === "ReactNative";
+var IS_BROWSER = IS_REACT_NATIVE || typeof window !== "undefined" || typeof globalThis !== "undefined" && typeof globalThis.document !== "undefined";
+var DEFAULT_CIRCUITS_URL = "https://storage.googleapis.com/cloak-circuits/circuits/0.1.0";
+var SKIP_CIRCUIT_VERIFY_ENV = typeof process !== "undefined" && process.env && process.env.CLOAK_SKIP_CIRCUIT_INTEGRITY_CHECK === "1";
+function isUrl(path) {
+  return path.startsWith("http://") || path.startsWith("https://");
+}
+function resolveCircuitsUrl(circuitsPath2) {
+  if (circuitsPath2.trim() !== "" && circuitsPath2.trim() !== DEFAULT_CIRCUITS_URL) {
+    return DEFAULT_CIRCUITS_URL;
   }
-  return false;
+  return DEFAULT_CIRCUITS_URL;
 }
-globalDebugEnabled = checkEnvDebug();
-function setDebugMode(enabled) {
-  globalDebugEnabled = enabled;
+async function fetchFileAsBuffer(url) {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch ${url}: ${response.status} ${response.statusText}`);
+  }
+  const arrayBuffer = await response.arrayBuffer();
+  return new Uint8Array(arrayBuffer);
 }
-function isDebugEnabled() {
-  return globalDebugEnabled;
+async function sha256Hex(data) {
+  if (IS_BROWSER) {
+    const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
+    const buffer = bytes.buffer.slice(
+      bytes.byteOffset,
+      bytes.byteOffset + bytes.byteLength
+    );
+    const hashBuffer = await crypto.subtle.digest("SHA-256", buffer);
+    return Array.from(new Uint8Array(hashBuffer)).map((b) => b.toString(16).padStart(2, "0")).join("");
+  }
+  const nodeCrypto = await getNodeCrypto();
+  return nodeCrypto.createHash("sha256").update(data).digest("hex");
 }
-var LOG_COLORS = {
-  DEBUG: "\x1B[90m",
+var _nodeCrypto = null;
+function nodeRequire(moduleName) {
+  if (IS_BROWSER) {
+    throw new Error(`Node.js ${moduleName} module not available in browser/React Native`);
+  }
+  try {
+    const requireFunc = new Function("moduleName", "return require(moduleName)");
+    return requireFunc(moduleName);
+  } catch {
+    throw new Error(`Cannot load Node.js module ${moduleName} synchronously in ESM.`);
+  }
+}
+async function getNodeCrypto() {
+  if (_nodeCrypto) return _nodeCrypto;
+  _nodeCrypto = nodeRequire("crypto");
+  return _nodeCrypto;
+}
+async function generateWithdrawRegularProof(inputs, circuitsPath2) {
+  const circuitsUrl = resolveCircuitsUrl(circuitsPath2);
+  let wasmInput;
+  let zkeyInput;
+  if (IS_BROWSER) {
+    wasmInput = `${circuitsUrl}/withdraw_regular_js/withdraw_regular.wasm`;
+    zkeyInput = `${circuitsUrl}/withdraw_regular_final.zkey`;
+  } else {
+    const wasmUrl = `${circuitsUrl}/withdraw_regular_js/withdraw_regular.wasm`;
+    const zkeyUrl = `${circuitsUrl}/withdraw_regular_final.zkey`;
+    const [wasmData, zkeyData] = await Promise.all([
+      fetchFileAsBuffer(wasmUrl),
+      fetchFileAsBuffer(zkeyUrl)
+    ]);
+    wasmInput = wasmData;
+    zkeyInput = zkeyData;
+  }
+  const verification = await verifyCircuitIntegrity(circuitsUrl, "withdraw_regular");
+  if (!verification.valid) {
+    throw new Error(
+      `withdraw_regular circuit integrity verification failed: ${verification.error ?? "hash mismatch"}`
+    );
+  }
+  const circuitInputs = {
+    // Public signals
+    root: inputs.root.toString(),
+    nullifier: inputs.nullifier.toString(),
+    outputs_hash: inputs.outputs_hash.toString(),
+    public_amount: inputs.public_amount.toString(),
+    // Private common inputs
+    amount: inputs.amount.toString(),
+    leaf_index: inputs.leaf_index.toString(),
+    sk: inputs.sk.map((x) => x.toString()),
+    r: inputs.r.map((x) => x.toString()),
+    pathElements: inputs.pathElements.map((x) => x.toString()),
+    pathIndices: inputs.pathIndices,
+    // Outputs
+    num_outputs: inputs.num_outputs,
+    out_addr: inputs.out_addr.map((addr) => addr.map((x) => x.toString())),
+    out_amount: inputs.out_amount.map((x) => x.toString()),
+    out_flags: inputs.out_flags,
+    // Fee calculation
+    var_fee: inputs.var_fee.toString(),
+    rem: inputs.rem.toString()
+  };
+  const { proof, publicSignals } = await snarkjs.groth16.fullProve(circuitInputs, wasmInput, zkeyInput);
+  const proofBytes = proofToBytes(proof);
+  return {
+    proof,
+    publicSignals,
+    proofBytes,
+    publicInputsBytes: new Uint8Array(0)
+    // Not used, kept for compatibility
+  };
+}
+async function generateWithdrawSwapProof(inputs, circuitsPath2) {
+  const circuitsUrl = resolveCircuitsUrl(circuitsPath2);
+  let wasmInput;
+  let zkeyInput;
+  if (IS_BROWSER) {
+    wasmInput = `${circuitsUrl}/withdraw_swap_js/withdraw_swap.wasm`;
+    zkeyInput = `${circuitsUrl}/withdraw_swap_final.zkey`;
+  } else {
+    const wasmUrl = `${circuitsUrl}/withdraw_swap_js/withdraw_swap.wasm`;
+    const zkeyUrl = `${circuitsUrl}/withdraw_swap_final.zkey`;
+    const [wasmData, zkeyData] = await Promise.all([
+      fetchFileAsBuffer(wasmUrl),
+      fetchFileAsBuffer(zkeyUrl)
+    ]);
+    wasmInput = wasmData;
+    zkeyInput = zkeyData;
+  }
+  const verification = await verifyCircuitIntegrity(circuitsUrl, "withdraw_swap");
+  if (!verification.valid) {
+    throw new Error(
+      `withdraw_swap circuit integrity verification failed: ${verification.error ?? "hash mismatch"}`
+    );
+  }
+  const sk = splitTo2Limbs(inputs.sk_spend);
+  const r = splitTo2Limbs(inputs.r);
+  const circuitInputs = {
+    // Public signals (must be provided for witness generation)
+    root: inputs.root.toString(),
+    nullifier: inputs.nullifier.toString(),
+    outputs_hash: inputs.outputs_hash.toString(),
+    public_amount: inputs.public_amount.toString(),
+    // Private inputs
+    sk: sk.map((x) => x.toString()),
+    r: r.map((x) => x.toString()),
+    amount: inputs.amount.toString(),
+    leaf_index: inputs.leaf_index.toString(),
+    pathElements: inputs.path_elements.map((x) => x.toString()),
+    pathIndices: inputs.path_indices,
+    input_mint: inputs.input_mint.map((x) => x.toString()),
+    output_mint: inputs.output_mint.map((x) => x.toString()),
+    recipient_ata: inputs.recipient_ata.map((x) => x.toString()),
+    min_output_amount: inputs.min_output_amount.toString(),
+    // Note: fee is computed off-chain and validated on-chain:
+    // - fixed_fee is 5000000 (0.005 SOL)
+    // - var_fee and rem are computed from amount * 3 / 1000 (0.3%)
+    var_fee: inputs.var_fee.toString(),
+    rem: inputs.rem.toString()
+  };
+  const { proof, publicSignals } = await snarkjs.groth16.fullProve(
+    circuitInputs,
+    wasmInput,
+    zkeyInput
+  );
+  const proofBytes = proofToBytes(proof);
+  return {
+    proof,
+    publicSignals,
+    proofBytes,
+    publicInputsBytes: new Uint8Array(0)
+    // Not used, kept for compatibility
+  };
+}
+async function areCircuitsAvailable(circuitsPath2) {
+  if (!circuitsPath2 || circuitsPath2 === "") {
+    return false;
+  }
+  return isUrl(resolveCircuitsUrl(circuitsPath2));
+}
+async function getDefaultCircuitsPath() {
+  return DEFAULT_CIRCUITS_URL;
+}
+var EXPECTED_CIRCUIT_HASHES = {
+  withdraw_regular_wasm: "b80c364c926332111945ef437b07a71720fae774e08206cb11b6171f2a2420a3",
+  withdraw_regular_zkey: "6dbca2612f7cc257b897d93384ae9dd09c1617fd1668f8287efb1b124488d144",
+  withdraw_swap_wasm: "a296badc0047c211a4724c96a4e64a77cd75fbde7cfa4cf23af3640a723e5686",
+  withdraw_swap_zkey: "95251954feaac80396651d12a0df3288630fa75db9410aebecb8aaee17a4f6ea"
+};
+async function verifyCircuitIntegrity(circuitsPath2, circuit) {
+  const circuitsUrl = resolveCircuitsUrl(circuitsPath2);
+  if (SKIP_CIRCUIT_VERIFY_ENV) {
+    return {
+      valid: true,
+      circuit,
+      error: "Verification skipped (CLOAK_SKIP_CIRCUIT_INTEGRITY_CHECK=1)"
+    };
+  }
+  const expected = circuit === "withdraw_regular" ? {
+    wasm: EXPECTED_CIRCUIT_HASHES.withdraw_regular_wasm,
+    zkey: EXPECTED_CIRCUIT_HASHES.withdraw_regular_zkey
+  } : {
+    wasm: EXPECTED_CIRCUIT_HASHES.withdraw_swap_wasm,
+    zkey: EXPECTED_CIRCUIT_HASHES.withdraw_swap_zkey
+  };
+  const wasmPath = `${circuitsUrl}/${circuit}_js/${circuit}.wasm`;
+  const zkeyPath = `${circuitsUrl}/${circuit}_final.zkey`;
+  try {
+    const [wasmBytes, zkeyBytes] = await Promise.all([
+      fetchFileAsBuffer(wasmPath),
+      fetchFileAsBuffer(zkeyPath)
+    ]);
+    const computed = {
+      wasm: await sha256Hex(wasmBytes),
+      zkey: await sha256Hex(zkeyBytes)
+    };
+    if (computed.wasm === expected.wasm && computed.zkey === expected.zkey) {
+      return {
+        valid: true,
+        circuit,
+        computed,
+        expected
+      };
+    }
+    return {
+      valid: false,
+      circuit,
+      error: `Circuit artifact hash mismatch for ${circuit}`,
+      computed,
+      expected
+    };
+  } catch (error) {
+    return {
+      valid: false,
+      circuit,
+      error: `Circuit verification failed: ${error instanceof Error ? error.message : String(error)}`
+    };
+  }
+}
+async function verifyAllCircuits(circuitsPath2) {
+  const circuitsUrl = resolveCircuitsUrl(circuitsPath2);
+  const results = await Promise.all([
+    verifyCircuitIntegrity(circuitsUrl, "withdraw_regular"),
+    verifyCircuitIntegrity(circuitsUrl, "withdraw_swap")
+  ]);
+  return results;
+}
+
+// src/utils/logger.ts
+var globalDebugEnabled = false;
+function checkEnvDebug() {
+  if (typeof process !== "undefined" && process.env) {
+    return !!(process.env.CLOAK_DEBUG === "1" || process.env.CLOAK_DEBUG === "true" || process.env.DEBUG?.includes("cloak"));
+  }
+  return false;
+}
+globalDebugEnabled = checkEnvDebug();
+function setDebugMode(enabled) {
+  globalDebugEnabled = enabled;
+}
+function isDebugEnabled() {
+  return globalDebugEnabled;
+}
+var LOG_COLORS = {
+  DEBUG: "\x1B[90m",
   // gray
   INFO: "\x1B[32m",
   // green
@@ -1987,16 +2692,44 @@ async function computeProofInternal(leafIndex, _nextIndex, subtrees) {
 }
 
 // src/core/CloakSDK.ts
-var CLOAK_PROGRAM_ID = new PublicKey2("zh1eLd6rSphLejbFfJEneUwzHRfMKxgzrgkfwA6qRkW");
+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("zh1eLd6rSphLejbFfJEneUwzHRfMKxgzrgkfwA6qRkW");
 var CLOAK_API_URL = "https://api.cloak.ag";
 var CloakSDK = class {
+  /**
+  * Create a new Cloak SDK client
+   *
+   * @param config - Client configuration
+   * 
+   * @example Node.js mode (with keypair)
+   * ```typescript
+   * const sdk = new CloakSDK({
+   *   keypairBytes: keypair.secretKey,
+   *   network: "devnet"
+   * });
+   * ```
+   * 
+   * @example Browser mode (with wallet adapter)
+   * ```typescript
+   * const sdk = new CloakSDK({
+   *   wallet: walletAdapter,
+   *   network: "devnet"
+   * });
+   * ```
+   */
   constructor(config) {
     if (!config.keypairBytes && !config.wallet) {
-      throw new CloakError(
-        "Must provide either keypairBytes (Node.js) or wallet (Browser)",
-        "validation",
-        false
-      );
+      throw new Error("Must provide either keypairBytes (Node.js) or wallet (Browser)");
     }
     if (config.debug) {
       setDebugMode(true);
@@ -2016,9 +2749,13 @@ var CloakSDK = class {
       }
     }
     const programId = config.programId || CLOAK_PROGRAM_ID;
-    const { pool, merkleTree, treasury } = getShieldPoolPDAs(programId, NATIVE_SOL_MINT);
+    const { pool, merkleTree, treasury } = getShieldPoolPDAs(
+      programId,
+      NATIVE_SOL_MINT
+    );
     this.config = {
       network: config.network || "mainnet",
+      keypairBytes: config.keypairBytes,
       cloakKeys: config.cloakKeys,
       programId,
       poolAddress: pool,
@@ -2027,7 +2764,9 @@ var CloakSDK = class {
       debug: config.debug
     };
   }
-  /** Public key of the configured signer (keypair or wallet). */
+  /**
+   * Get the public key for deposits (from keypair or wallet)
+   */
   getPublicKey() {
     if (this.keypair) {
       return this.keypair.publicKey;
@@ -2035,23 +2774,877 @@ var CloakSDK = class {
     if (this.wallet?.publicKey) {
       return this.wallet.publicKey;
     }
-    throw new CloakError(
-      "No public key available - wallet not connected and no keypair provided",
-      "wallet",
-      false
+    throw new Error("No public key available - wallet not connected or keypair not provided");
+  }
+  /**
+   * Check if the SDK is using a wallet adapter
+   */
+  isWalletMode() {
+    return !!this.wallet && !this.keypair;
+  }
+  /**
+   * Deposit SOL into the Cloak protocol
+   *
+   * Creates a new note (or uses a provided one), submits a deposit transaction,
+   * and registers with the indexer.
+   *
+   * @param connection - Solana connection
+   * @param payer - Payer wallet with sendTransaction method
+   * @param amountOrNote - Amount in lamports OR an existing note to deposit
+   * @param options - Optional configuration
+   * @returns Deposit result with note and transaction info
+   *
+   * @example
+   * ```typescript
+   * // Generate and deposit in one step
+   * const result = await client.deposit(
+   *   connection,
+   *   wallet,
+   *   1_000_000_000,
+   *   {
+   *     onProgress: (status) => console.log(status)
+   *   }
+   * );
+   *
+   * // Or deposit a pre-generated note
+   * const note = client.generateNote(1_000_000_000);
+   * const result = await client.deposit(connection, wallet, note);
+   * ```
+   */
+  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;
+      if (balance < requiredAmount) {
+        throw new Error(
+          `Insufficient balance. Required: ${requiredAmount} lamports (${note.amount} + fees), Available: ${balance} lamports`
+        );
+      }
+      const commitmentBytes = hexToBytes(note.commitment);
+      const programId = this.config.programId || CLOAK_PROGRAM_ID;
+      const depositIx = createDepositInstruction({
+        programId,
+        payer: payerPubkey,
+        pool: this.config.poolAddress,
+        merkleTree: this.config.merkleTreeAddress,
+        amount: note.amount,
+        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(cuLimitIx).add(cuPriceIx);
+      if (dataSizeLimitIx) {
+        transaction.add(dataSizeLimitIx);
+      }
+      transaction.add(depositIx);
+      if (!transaction.feePayer) {
+        throw new Error("Transaction feePayer is not set");
+      }
+      if (!transaction.recentBlockhash) {
+        throw new Error("Transaction recentBlockhash is not set");
+      }
+      let signature;
+      if (this.wallet) {
+        if (!this.wallet.publicKey) {
+          throw new Error("Wallet not connected - publicKey is null");
+        }
+        if (this.wallet.signTransaction) {
+          try {
+            const signedTransaction = await this.wallet.signTransaction(transaction);
+            const rawTransaction = signedTransaction.serialize();
+            signature = await connection.sendRawTransaction(rawTransaction, {
+              skipPreflight: options?.skipPreflight || false,
+              preflightCommitment: "confirmed",
+              maxRetries: 3
+            });
+          } catch (signError) {
+            if (this.wallet.sendTransaction) {
+              signature = await this.wallet.sendTransaction(transaction, connection, {
+                skipPreflight: options?.skipPreflight || false,
+                preflightCommitment: "confirmed",
+                maxRetries: 3
+              });
+            } else {
+              throw signError;
+            }
+          }
+        } else if (this.wallet.sendTransaction) {
+          signature = await this.wallet.sendTransaction(transaction, connection, {
+            skipPreflight: options?.skipPreflight || false,
+            preflightCommitment: "confirmed",
+            maxRetries: 3
+          });
+        } else {
+          throw new Error("Wallet adapter must provide either sendTransaction or signTransaction");
+        }
+      } else if (this.keypair) {
+        signature = await connection.sendTransaction(transaction, [this.keypair], {
+          skipPreflight: options?.skipPreflight || false,
+          preflightCommitment: "confirmed",
+          maxRetries: 3
+        });
+      } else {
+        throw new Error("No signing method available - provide keypair or wallet");
+      }
+      const confirmation = await connection.confirmTransaction({
+        signature,
+        blockhash,
+        lastValidBlockHeight
+      });
+      if (confirmation.value.err) {
+        throw new Error(
+          `Transaction failed: ${JSON.stringify(confirmation.value.err)}`
+        );
+      }
+      const txDetails = await connection.getTransaction(signature, {
+        commitment: "confirmed",
+        maxSupportedTransactionVersion: 0
+      });
+      const depositSlot = txDetails?.slot ?? 0;
+      let leafIndex = null;
+      let root = null;
+      try {
+        if (txDetails?.meta?.logMessages) {
+          for (const log of txDetails.meta.logMessages) {
+            if (log.includes("Program data:")) {
+              try {
+                const parts = log.split("Program data:");
+                if (parts.length > 1) {
+                  const base64Data = parts[1].trim();
+                  const eventData = Buffer.from(base64Data, "base64");
+                  if (eventData.length >= 81 && eventData[0] === 1) {
+                    const parsedLeafIndex = Number(eventData.readBigUInt64LE(1));
+                    const loggedCommitment = eventData.slice(9, 41);
+                    if (Buffer.compare(loggedCommitment, Buffer.from(commitmentBytes)) === 0) {
+                      leafIndex = parsedLeafIndex;
+                      const loggedRoot = eventData.slice(49, 81);
+                      root = Buffer.from(loggedRoot).toString("hex");
+                      break;
+                    }
+                  }
+                }
+              } catch (e) {
+                continue;
+              }
+            }
+          }
+        }
+      } catch (e) {
+      }
+      if (leafIndex === null) {
+        const programId2 = this.config.programId || CLOAK_PROGRAM_ID;
+        const mintForSOL = NATIVE_SOL_MINT;
+        const { merkleTree } = getShieldPoolPDAs(programId2, mintForSOL);
+        const merkleTreeAccount = await connection.getAccountInfo(merkleTree);
+        if (!merkleTreeAccount) {
+          throw new Error("Failed to fetch merkle tree account");
+        }
+        const nextIndex = Number(merkleTreeAccount.data.readBigUInt64LE(32));
+        leafIndex = nextIndex - 1;
+        const rootBytes = merkleTreeAccount.data.slice(1064, 1096);
+        root = Buffer.from(rootBytes).toString("hex");
+      }
+      if (leafIndex === null || root === null) {
+        throw new Error("Failed to get leaf index and root from transaction logs or on-chain state");
+      }
+      let merkleProof;
+      try {
+        const programId2 = this.config.programId || CLOAK_PROGRAM_ID;
+        const mintForSOL = NATIVE_SOL_MINT;
+        const { merkleTree: merkleTreePDA } = getShieldPoolPDAs(programId2, mintForSOL);
+        const chainProof = await computeProofFromChain(connection, merkleTreePDA, leafIndex);
+        merkleProof = {
+          pathElements: chainProof.pathElements,
+          pathIndices: chainProof.pathIndices
+        };
+        root = chainProof.root;
+      } catch (proofError) {
+        console.warn("[SDK] Could not compute proof from chain, will fetch at withdrawal:", proofError);
+      }
+      const updatedNote = updateNoteWithDeposit(note, {
+        signature,
+        slot: depositSlot,
+        leafIndex,
+        root,
+        merkleProof
+      });
+      await this.storage.updateNote(note.commitment, {
+        depositSignature: signature,
+        depositSlot,
+        leafIndex,
+        root,
+        merkleProof
+      });
+      return {
+        note: updatedNote,
+        signature,
+        leafIndex,
+        root
+      };
+    } catch (error) {
+      throw this.wrapError(error, "Deposit failed");
+    }
+  }
+  /**
+   * Private transfer with up to 5 recipients
+   *
+   * Handles the complete private transfer flow:
+   * 1. If note is not deposited, deposits it first and waits for confirmation
+   * 2. Generates a zero-knowledge proof
+   * 3. Submits the withdrawal via relay service to recipients
+   *
+   * This is the main method for performing private transfers - it handles everything!
+   *
+   * @param connection - Solana connection (required for deposit if not already deposited)
+   * @param payer - Payer wallet (required for deposit if not already deposited)
+   * @param note - Note to spend (can be deposited or not)
+   * @param recipients - Array of 1-5 recipients with amounts
+   * @param options - Optional configuration
+   * @returns Transfer result with signature and outputs
+   *
+   * @example
+   * ```typescript
+   * // Create a note (not deposited yet)
+   * const note = client.generateNote(1_000_000_000);
+   *
+   * // privateTransfer handles the full flow: deposit + withdraw
+   * const result = await client.privateTransfer(
+   *   connection,
+   *   wallet,
+   *   note,
+   *   [
+   *     { recipient: new PublicKey("..."), amount: 500_000_000 },
+   *     { recipient: new PublicKey("..."), amount: 492_500_000 }
+   *   ],
+   *   {
+   *     relayFeeBps: 50, // 0.5%
+   *     onProgress: (status) => console.log(status),
+   *     onProofProgress: (pct) => console.log(`Proof: ${pct}%`)
+   *   }
+   * );
+   * console.log(`Success! TX: ${result.signature}`);
+   * ```
+   */
+  async privateTransfer(connection, note, recipients, options) {
+    if (!isWithdrawable(note)) {
+      const depositResult = await this.deposit(connection, note, {
+        skipPreflight: false
+      });
+      note = depositResult.note;
+    }
+    const protocolFee = note.amount - getDistributableAmount(note.amount);
+    const feeBps = Math.ceil(protocolFee * 1e4 / note.amount);
+    const distributableAmount = getDistributableAmount(note.amount);
+    validateTransfers(recipients, distributableAmount);
+    if (!note.leafIndex && note.leafIndex !== 0) {
+      throw new Error("Note must have a leaf index (note must be deposited)");
+    }
+    if (!isValidHex(note.r, 32)) {
+      throw new Error("Note r must be 64 hex characters (32 bytes)");
+    }
+    if (!isValidHex(note.sk_spend, 32)) {
+      throw new Error("Note sk_spend must be 64 hex characters (32 bytes)");
+    }
+    const nullifier = await computeNullifierAsync(note.sk_spend, note.leafIndex);
+    const nullifierHex = nullifier.toString(16).padStart(64, "0");
+    const outputsHash = await computeOutputsHashAsync(recipients);
+    const outputsHashHex = outputsHash.toString(16).padStart(64, "0");
+    const circuitsPath2 = await getDefaultCircuitsPath();
+    const useDirectProof = await areCircuitsAvailable(circuitsPath2);
+    if (!useDirectProof) {
+      throw new Error(
+        `Circuits not available at ${circuitsPath2}. Make sure circuits are built and accessible. Circuit artifacts are pinned to S3 and must be reachable from this environment.`
+      );
+    }
+    const MAX_PROOF_RETRIES = 3;
+    let lastError = null;
+    for (let attempt = 0; attempt < MAX_PROOF_RETRIES; attempt++) {
+      try {
+        if (attempt > 0) {
+          options?.onProgress?.(`proof_refresh_${attempt + 1}`);
+          await new Promise((resolve) => setTimeout(resolve, 1e3));
+        }
+        let merkleProof;
+        let merkleRoot;
+        const hasStoredProof = note.merkleProof && note.root && note.merkleProof.pathElements && note.merkleProof.pathElements.length > 0;
+        if (attempt === 0 && hasStoredProof) {
+          merkleProof = note.merkleProof;
+          merkleRoot = note.root;
+        } else {
+          const programId = this.config.programId || CLOAK_PROGRAM_ID;
+          const mintForSOL = NATIVE_SOL_MINT;
+          const { merkleTree: merkleTreePDA } = getShieldPoolPDAs(programId, mintForSOL);
+          const chainProof = await computeProofFromChain(
+            connection,
+            merkleTreePDA,
+            note.leafIndex
+          );
+          merkleProof = {
+            pathElements: chainProof.pathElements,
+            pathIndices: chainProof.pathIndices,
+            root: chainProof.root
+          };
+          merkleRoot = chainProof.root;
+          note.merkleProof = merkleProof;
+          note.root = merkleRoot;
+        }
+        if (!merkleProof || !merkleRoot) {
+          throw new Error("Failed to get Merkle proof from chain");
+        }
+        if (!merkleProof.pathElements || merkleProof.pathElements.length === 0) {
+          throw new Error("Merkle proof is invalid: missing path elements");
+        }
+        if (merkleProof.pathElements.length !== merkleProof.pathIndices.length) {
+          throw new Error("Merkle proof is invalid: path elements and indices length mismatch");
+        }
+        for (let i = 0; i < merkleProof.pathIndices.length; i++) {
+          const idx = merkleProof.pathIndices[i];
+          if (idx !== 0 && idx !== 1) {
+            throw new Error(`Merkle proof path index at position ${i} must be 0 or 1, got ${idx}`);
+          }
+        }
+        if (!isValidHex(merkleRoot, 32)) {
+          throw new Error("Merkle root must be 64 hex characters (32 bytes)");
+        }
+        for (let i = 0; i < merkleProof.pathElements.length; i++) {
+          const element = merkleProof.pathElements[i];
+          if (typeof element !== "string" || !isValidHex(element, 32)) {
+            throw new Error(`Merkle proof path element at position ${i} must be 64 hex characters (32 bytes)`);
+          }
+        }
+        const sk_spend_bigint = BigInt("0x" + note.sk_spend);
+        const r_bigint = BigInt("0x" + note.r);
+        const root_bigint = BigInt("0x" + merkleRoot);
+        const nullifier_bigint = BigInt("0x" + nullifierHex);
+        const outputs_hash_bigint = BigInt("0x" + outputsHashHex);
+        const amount_bigint = BigInt(note.amount);
+        const pathElements = merkleProof.pathElements.map((p) => BigInt("0x" + p));
+        const outAddr = [];
+        for (let i = 0; i < 5; i++) {
+          if (i < recipients.length) {
+            const [lo, hi] = pubkeyToLimbs(recipients[i].recipient.toBytes());
+            outAddr.push([lo, hi]);
+          } else {
+            outAddr.push([0n, 0n]);
+          }
+        }
+        const t = amount_bigint * 3n;
+        const varFee = t / 1000n;
+        const rem = t % 1000n;
+        const outAmount = [];
+        const outFlags = [];
+        for (let i = 0; i < 5; i++) {
+          if (i < recipients.length) {
+            outAmount.push(BigInt(recipients[i].amount));
+            outFlags.push(1);
+          } else {
+            outAmount.push(0n);
+            outFlags.push(0);
+          }
+        }
+        const sk = splitTo2Limbs(sk_spend_bigint);
+        const r = splitTo2Limbs(r_bigint);
+        if (attempt === 0) {
+          const computedCommitment = await computeCommitment2(amount_bigint, r_bigint, sk_spend_bigint);
+          const noteCommitment = BigInt("0x" + note.commitment);
+          if (computedCommitment !== noteCommitment) {
+            throw new Error(
+              `Commitment mismatch! Computed: ${computedCommitment.toString(16)}, Note: ${note.commitment}. This means the note's sk_spend, r, or amount doesn't match what was deposited.`
+            );
+          }
+        }
+        const proofInputs = {
+          root: root_bigint,
+          nullifier: nullifier_bigint,
+          outputs_hash: outputs_hash_bigint,
+          public_amount: amount_bigint,
+          amount: amount_bigint,
+          leaf_index: BigInt(note.leafIndex),
+          sk,
+          r,
+          pathElements,
+          pathIndices: merkleProof.pathIndices,
+          num_outputs: recipients.length,
+          out_addr: outAddr,
+          out_amount: outAmount,
+          out_flags: outFlags,
+          var_fee: varFee,
+          rem
+        };
+        options?.onProgress?.("proof_generating");
+        const proofResult = await generateWithdrawRegularProof(proofInputs, circuitsPath2);
+        options?.onProgress?.("proof_complete");
+        const proofHex = Buffer.from(proofResult.proofBytes).toString("hex");
+        const finalPublicInputs = {
+          root: merkleRoot,
+          nf: nullifierHex,
+          outputs_hash: outputsHashHex,
+          amount: note.amount
+        };
+        const metadataBundle = options?.metadataBundle;
+        const signature = await this.relay.submitWithdraw(
+          {
+            proof: proofHex,
+            publicInputs: finalPublicInputs,
+            outputs: recipients.map((r2) => ({
+              recipient: r2.recipient.toBase58(),
+              amount: r2.amount
+            })),
+            feeBps,
+            // Use calculated protocol fee BPS
+            metadataBundle
+          },
+          options?.onProgress
+        );
+        return {
+          signature,
+          outputs: recipients.map((r2) => ({
+            recipient: r2.recipient.toBase58(),
+            amount: r2.amount
+          })),
+          nullifier: nullifierHex,
+          root: merkleRoot
+        };
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        if (error instanceof RootNotFoundError) {
+          console.warn(
+            `[Cloak SDK] Merkle root expired (attempt ${attempt + 1}/${MAX_PROOF_RETRIES}). Regenerating proof with fresh root...`
+          );
+          continue;
+        }
+        throw error;
+      }
+    }
+    throw new Error(
+      `Withdrawal failed after ${MAX_PROOF_RETRIES} proof refresh attempts. The Merkle tree is updating too rapidly. Last error: ${lastError?.message}`
     );
   }
-  /** True when the SDK was constructed with a wallet adapter (browser). */
-  isWalletMode() {
-    return !!this.wallet && !this.keypair;
+  /**
+   * Withdraw to a single recipient
+   *
+   * Convenience method for withdrawing to one address.
+   * Handles the complete flow: deposits if needed, then withdraws.
+   *
+   * @param connection - Solana connection
+   * @param payer - Payer wallet
+   * @param note - Note to spend
+   * @param recipient - Recipient address
+   * @param options - Optional configuration
+   * @returns Transfer result
+   *
+   * @example
+   * ```typescript
+   * const note = client.generateNote(1_000_000_000);
+   * const result = await client.withdraw(
+   *   connection,
+   *   wallet,
+   *   note,
+   *   new PublicKey("..."),
+   *   { withdrawAll: true }
+   * );
+   * ```
+   */
+  async withdraw(connection, note, recipient, options) {
+    const withdrawAll = options?.withdrawAll ?? true;
+    const amount = withdrawAll ? getDistributableAmount(note.amount) : options?.amount || note.amount;
+    if (!withdrawAll && !options?.amount) {
+      throw new Error("Must specify amount or set withdrawAll: true");
+    }
+    return this.privateTransfer(
+      connection,
+      note,
+      [{ recipient, amount }],
+      options
+    );
+  }
+  /**
+   * Send SOL privately to multiple recipients
+   *
+   * Convenience method that wraps privateTransfer with a simpler API.
+   * Handles the complete flow: deposits if needed, then sends to recipients.
+   *
+   * @param connection - Solana connection
+   * @param note - Note to spend
+   * @param recipients - Array of 1-5 recipients with amounts
+   * @param options - Optional configuration
+   * @returns Transfer result
+   *
+   * @example
+   * ```typescript
+   * const note = client.generateNote(1_000_000_000);
+   * const result = await client.send(
+   *   connection,
+   *   note,
+   *   [
+   *     { recipient: new PublicKey("..."), amount: 500_000_000 },
+   *     { recipient: new PublicKey("..."), amount: 492_500_000 }
+   *   ]
+   * );
+   * ```
+   */
+  async send(connection, note, recipients, options) {
+    return this.privateTransfer(connection, note, recipients, options);
+  }
+  /**
+   * Swap SOL for tokens privately
+   *
+   * Withdraws SOL from a note and swaps it for tokens via the relay service.
+   * Handles the complete flow: deposits if needed, generates proof, and submits swap.
+   *
+   * @param connection - Solana connection
+   * @param note - Note to spend
+   * @param recipient - Recipient address (will receive tokens)
+   * @param options - Swap configuration
+   * @returns Swap result with transaction signature
+   *
+   * @example
+   * ```typescript
+   * const note = client.generateNote(1_000_000_000);
+   * const result = await client.swap(
+   *   connection,
+   *   note,
+   *   new PublicKey("..."), // recipient
+   *   {
+   *     outputMint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // USDC
+   *     slippageBps: 100, // 1%
+   *     getQuote: async (amount, mint, slippage) => {
+   *       // Fetch quote from your swap API
+   *       const quote = await fetchSwapQuote(amount, mint, slippage);
+   *       return {
+   *         outAmount: quote.outAmount,
+   *         minOutputAmount: quote.minOutputAmount
+   *       };
+   *     }
+   *   }
+   * );
+   * ```
+   */
+  async swap(connection, note, recipient, options) {
+    try {
+      if (!isWithdrawable(note)) {
+        const depositResult = await this.deposit(connection, note, {
+          skipPreflight: false
+        });
+        note = depositResult.note;
+      }
+      const variableFee = Math.floor(note.amount * 3 / 1e3);
+      const feeBps = note.amount === 0 ? 0 : Math.min(Math.floor((variableFee * 1e4 + note.amount - 1) / note.amount), 65535);
+      const withdrawAmountLamports = getDistributableAmount(note.amount);
+      if (withdrawAmountLamports <= 0) {
+        throw new Error("Amount too small after fees");
+      }
+      let minOutputAmount;
+      if (options.minOutputAmount !== void 0) {
+        minOutputAmount = options.minOutputAmount;
+      } else if (options.getQuote) {
+        const quote = await options.getQuote(
+          withdrawAmountLamports,
+          options.outputMint,
+          options.slippageBps || 100
+        );
+        minOutputAmount = quote.minOutputAmount;
+      } else {
+        throw new Error(
+          "Must provide either minOutputAmount or getQuote function"
+        );
+      }
+      let recipientAta;
+      if (options.recipientAta) {
+        recipientAta = new PublicKey4(options.recipientAta);
+      } else {
+        try {
+          const splTokenModule = await import("@solana/spl-token");
+          const getAssociatedTokenAddress = splTokenModule.getAssociatedTokenAddress;
+          if (!getAssociatedTokenAddress) {
+            throw new Error("getAssociatedTokenAddress not found");
+          }
+          const outputMint2 = new PublicKey4(options.outputMint);
+          recipientAta = await getAssociatedTokenAddress(outputMint2, recipient);
+        } catch (error) {
+          throw new Error(
+            `Failed to get associated token account: ${error instanceof Error ? error.message : String(error)}. Please install @solana/spl-token or provide recipientAta in options.`
+          );
+        }
+      }
+      if (!note.leafIndex && note.leafIndex !== 0) {
+        throw new Error("Note must have a leaf index (note must be deposited)");
+      }
+      const nullifier = await computeNullifierAsync(note.sk_spend, note.leafIndex);
+      const nullifierHex = nullifier.toString(16).padStart(64, "0");
+      const inputMint = new PublicKey4("11111111111111111111111111111111");
+      const outputMint = new PublicKey4(options.outputMint);
+      const outputsHash = await computeSwapOutputsHashAsync(
+        inputMint,
+        outputMint,
+        recipientAta,
+        minOutputAmount,
+        note.amount
+      );
+      const outputsHashHex = outputsHash.toString(16).padStart(64, "0");
+      const circuitsPath2 = await getDefaultCircuitsPath();
+      const useDirectProof = await areCircuitsAvailable(circuitsPath2);
+      if (!useDirectProof) {
+        throw new Error(
+          `Circuits not available at ${circuitsPath2}. Make sure circuits are built and accessible. Circuit artifacts are pinned to S3 and must be reachable from this environment.`
+        );
+      }
+      const MAX_PROOF_RETRIES = 3;
+      let lastError = null;
+      for (let attempt = 0; attempt < MAX_PROOF_RETRIES; attempt++) {
+        try {
+          if (attempt > 0) {
+            options?.onProgress?.(`proof_refresh_${attempt + 1}`);
+            await new Promise((resolve) => setTimeout(resolve, 1e3));
+          }
+          const programId = this.config.programId || CLOAK_PROGRAM_ID;
+          const mintForSOL = NATIVE_SOL_MINT;
+          const { merkleTree: merkleTreePDA } = getShieldPoolPDAs(programId, mintForSOL);
+          const chainProof = await computeProofFromChain(connection, merkleTreePDA, note.leafIndex);
+          const merkleProof = {
+            pathElements: chainProof.pathElements,
+            pathIndices: chainProof.pathIndices
+          };
+          const merkleRoot = chainProof.root;
+          if (!merkleRoot) {
+            throw new Error("Failed to get Merkle root from chain");
+          }
+          if (!merkleProof.pathElements || merkleProof.pathElements.length === 0) {
+            throw new Error("Merkle proof is invalid: missing path elements");
+          }
+          const sk_spend_bigint = BigInt("0x" + note.sk_spend);
+          const r_bigint = BigInt("0x" + note.r);
+          const root_bigint = BigInt("0x" + merkleRoot);
+          const nullifier_bigint = BigInt("0x" + nullifierHex);
+          const outputs_hash_bigint = BigInt("0x" + outputsHashHex);
+          const amount_bigint = BigInt(note.amount);
+          const pathElements = merkleProof.pathElements.map((p) => BigInt("0x" + p));
+          const inputMintLimbs = pubkeyToLimbs(inputMint.toBytes());
+          const outputMintLimbs = pubkeyToLimbs(outputMint.toBytes());
+          const recipientAtaLimbs = pubkeyToLimbs(recipientAta.toBytes());
+          if (attempt === 0) {
+            const computedCommitment = await computeCommitment2(amount_bigint, r_bigint, sk_spend_bigint);
+            const noteCommitment = BigInt("0x" + note.commitment);
+            if (computedCommitment !== noteCommitment) {
+              throw new Error(
+                `Commitment mismatch! Computed: ${computedCommitment.toString(16)}, Note: ${note.commitment}. This means the note's sk_spend, r, or amount doesn't match what was deposited.`
+              );
+            }
+          }
+          const t = amount_bigint * 3n;
+          const varFee = t / 1000n;
+          const rem = t % 1000n;
+          const proofInputs = {
+            sk_spend: sk_spend_bigint,
+            r: r_bigint,
+            amount: amount_bigint,
+            leaf_index: BigInt(note.leafIndex),
+            path_elements: pathElements,
+            path_indices: merkleProof.pathIndices,
+            root: root_bigint,
+            nullifier: nullifier_bigint,
+            outputs_hash: outputs_hash_bigint,
+            public_amount: amount_bigint,
+            input_mint: inputMintLimbs,
+            output_mint: outputMintLimbs,
+            recipient_ata: recipientAtaLimbs,
+            min_output_amount: BigInt(minOutputAmount),
+            var_fee: varFee,
+            rem
+          };
+          options?.onProgress?.("proof_generating");
+          const proofResult = await generateWithdrawSwapProof(proofInputs, circuitsPath2);
+          options?.onProgress?.("proof_complete");
+          const proofHex = Buffer.from(proofResult.proofBytes).toString("hex");
+          const finalPublicInputs = {
+            root: merkleRoot,
+            nf: nullifierHex,
+            outputs_hash: outputsHashHex,
+            amount: note.amount
+          };
+          const metadataBundle = options?.metadataBundle;
+          const signature = await this.relay.submitSwap(
+            {
+              proof: proofHex,
+              publicInputs: finalPublicInputs,
+              outputs: [
+                {
+                  recipient: recipient.toBase58(),
+                  amount: withdrawAmountLamports
+                }
+              ],
+              feeBps,
+              swap: {
+                output_mint: options.outputMint,
+                slippage_bps: options.slippageBps || 100,
+                min_output_amount: minOutputAmount
+              },
+              metadataBundle
+            },
+            options.onProgress
+          );
+          return {
+            signature,
+            outputs: [
+              {
+                recipient: recipient.toBase58(),
+                amount: withdrawAmountLamports
+              }
+            ],
+            nullifier: nullifierHex,
+            root: merkleRoot,
+            outputMint: options.outputMint,
+            minOutputAmount
+          };
+        } catch (error) {
+          lastError = error instanceof Error ? error : new Error(String(error));
+          if (error instanceof RootNotFoundError) {
+            console.warn(
+              `[Cloak SDK] Merkle root expired (attempt ${attempt + 1}/${MAX_PROOF_RETRIES}). Regenerating swap proof with fresh root...`
+            );
+            continue;
+          }
+          throw error;
+        }
+      }
+      throw new Error(
+        `Swap failed after ${MAX_PROOF_RETRIES} proof refresh attempts. The Merkle tree is updating too rapidly. Last error: ${lastError?.message}`
+      );
+    } catch (error) {
+      throw this.wrapError(error, "Swap failed");
+    }
+  }
+  /**
+   * Generate a new note without depositing
+   *
+   * @param amountLamports - Amount for the note
+   * @param useWalletKeys - Whether to use wallet keys (v2.0 recommended)
+   * @returns New note (not yet deposited)
+   */
+  async generateNote(amountLamports, useWalletKeys = false) {
+    if (useWalletKeys && this.cloakKeys) {
+      return await generateNoteFromWallet(amountLamports, this.cloakKeys, this.config.network);
+    } else if (useWalletKeys) {
+      const keys = generateCloakKeys();
+      this.cloakKeys = keys;
+      const result = this.storage.saveKeys(keys);
+      if (result instanceof Promise) {
+        result.catch(() => {
+        });
+      }
+      return await generateNoteFromWallet(amountLamports, keys, this.config.network);
+    }
+    return await generateNote(amountLamports, this.config.network);
+  }
+  /**
+   * Parse a note from JSON string
+   *
+   * @param jsonString - JSON representation
+   * @returns Parsed note
+   */
+  parseNote(jsonString) {
+    return parseNote2(jsonString);
+  }
+  /**
+   * Export a note to JSON string
+   *
+   * @param note - Note to export
+   * @param pretty - Format with indentation
+   * @returns JSON string
+   */
+  exportNote(note, pretty = false) {
+    return pretty ? JSON.stringify(note, null, 2) : JSON.stringify(note);
+  }
+  /**
+   * Check if a note is ready for withdrawal
+   *
+   * @param note - Note to check
+   * @returns True if withdrawable
+   */
+  isWithdrawable(note) {
+    return isWithdrawable(note);
   }
   /**
-   * Compute a Merkle proof for `leafIndex` from on-chain state. No relay /
-   * indexer round-trip required.
+   * Get Merkle proof for a leaf index directly from on-chain state
+   *
+   * @param connection - Solana connection
+   * @param leafIndex - Leaf index in tree
+   * @returns Merkle proof computed from on-chain data
    */
   async getMerkleProof(connection, leafIndex) {
     const programId = this.config.programId || CLOAK_PROGRAM_ID;
-    const { merkleTree: merkleTreePDA } = getShieldPoolPDAs(programId, NATIVE_SOL_MINT);
+    const mintForSOL = NATIVE_SOL_MINT;
+    const { merkleTree: merkleTreePDA } = getShieldPoolPDAs(programId, mintForSOL);
     const chainProof = await computeProofFromChain(connection, merkleTreePDA, leafIndex);
     return {
       pathElements: chainProof.pathElements,
@@ -2059,20 +3652,72 @@ var CloakSDK = class {
       root: chainProof.root
     };
   }
-  /** Read the current SOL-pool Merkle root from on-chain state. */
+  /**
+   * Get current Merkle root directly from on-chain state
+   *
+   * @param connection - Solana connection
+   * @returns Current root hash from on-chain tree
+   */
   async getCurrentRoot(connection) {
     const programId = this.config.programId || CLOAK_PROGRAM_ID;
-    const { merkleTree: merkleTreePDA } = getShieldPoolPDAs(programId, NATIVE_SOL_MINT);
+    const mintForSOL = NATIVE_SOL_MINT;
+    const { merkleTree: merkleTreePDA } = getShieldPoolPDAs(programId, mintForSOL);
     const state = await readMerkleTreeState(connection, merkleTreePDA);
     return state.root;
   }
-  /** Poll relay for the status of a previously-submitted request. */
+  /**
+   * Get transaction status from relay service
+   *
+   * @param requestId - Request ID from previous submission
+   * @returns Current status
+   */
   async getTransactionStatus(requestId) {
     return this.relay.getStatus(requestId);
   }
-  /** Import wallet keys from JSON; persists to the configured storage adapter. */
+  /**
+   * Fetch and decrypt this user's transaction metadata history.
+   * DEPRECATED: This functionality is no longer supported
+   */
+  async getTransactionMetadata(_options) {
+    throw new Error("getTransactionMetadata is deprecated - use compliance export API instead");
+  }
+  /**
+   * Load all notes from storage
+   * 
+   * @returns Array of saved notes
+   */
+  async loadNotes() {
+    const notes = this.storage.loadAllNotes();
+    return Array.isArray(notes) ? notes : await notes;
+  }
+  /**
+   * Save a note to storage
+   * 
+   * @param note - Note to save
+   */
+  async saveNote(note) {
+    const result = this.storage.saveNote(note);
+    if (result instanceof Promise) {
+      await result;
+    }
+  }
+  /**
+   * Find a note by its commitment
+   * 
+   * @param commitment - Commitment hash
+   * @returns Note if found
+   */
+  async findNote(commitment) {
+    const notes = await this.loadNotes();
+    return findNoteByCommitment(notes, commitment);
+  }
+  /**
+   * Import wallet keys from JSON
+   * 
+   * @param keysJson - JSON string containing keys
+   */
   async importWalletKeys(keysJson) {
-    const keys = importKeys(keysJson);
+    const keys = importWalletKeys(keysJson);
     this.cloakKeys = keys;
     const result = this.storage.saveKeys(keys);
     if (result instanceof Promise) {
@@ -2080,32 +3725,134 @@ var CloakSDK = class {
     }
   }
   /**
-   * Export wallet keys to JSON.
-   *
-   * WARNING: this exports secret keys. Store securely.
+   * Export wallet keys to JSON
+   * 
+   * WARNING: This exports secret keys! Store securely.
+   * 
+   * @returns JSON string with keys
    */
   exportWalletKeys() {
     if (!this.cloakKeys) {
       throw new CloakError("No wallet keys available", "wallet", false);
     }
-    return exportKeys(this.cloakKeys);
+    return exportWalletKeys(this.cloakKeys);
   }
   /**
-   * Snapshot of the active SDK configuration.
-   *
-   * The return type ({@link CloakConfig}) is structurally narrower than the
-   * constructor input ({@link CloakSDKOptions}): `keypairBytes`, `wallet`,
-   * and `storage` are intentionally absent from the snapshot. The secrets
-   * are consumed into private SDK state at construction time and are not
-   * re-exposable through this method — the type system enforces it. To
-   * sign, pass a `Keypair` / `WalletAdapter` directly to the standalone
-   * `transact` / `partialWithdraw` / `fullWithdraw` / `swapUtxo` helpers.
+   * Get the configuration
    */
   getConfig() {
     return { ...this.config };
   }
+  // Note: scanNotes was removed - it required the indexer to store encrypted outputs.
+  // Users should maintain their own note storage. This is more privacy-preserving.
+  /**
+   * Wrap errors with better categorization and user-friendly messages
+   * 
+   * @private
+   */
+  wrapError(error, context) {
+    if (error instanceof CloakError) {
+      return error;
+    }
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    if (errorMessage.includes("duplicate key") || errorMessage.includes("already deposited")) {
+      return new CloakError(
+        "This note was already deposited. Generate a new note to continue.",
+        "validation",
+        false,
+        error instanceof Error ? error : void 0
+      );
+    }
+    if (errorMessage.includes("insufficient funds") || errorMessage.includes("insufficient lamports")) {
+      return new CloakError(
+        "Insufficient funds for this transaction. Please check your wallet balance.",
+        "wallet",
+        false,
+        error instanceof Error ? error : void 0
+      );
+    }
+    if (errorMessage.includes("Merkle tree") || errorMessage.includes("merkle")) {
+      return new CloakError(
+        "Failed to read on-chain Merkle tree state. Please try again.",
+        "network",
+        true,
+        error instanceof Error ? error : void 0
+      );
+    }
+    if (errorMessage.includes("timeout") || errorMessage.includes("timed out")) {
+      return new CloakError(
+        "Network timeout. Please check your connection and try again.",
+        "network",
+        true,
+        error instanceof Error ? error : void 0
+      );
+    }
+    if (errorMessage.includes("not connected") || errorMessage.includes("wallet")) {
+      return new CloakError(
+        "Wallet not connected. Please connect your wallet first.",
+        "wallet",
+        false,
+        error instanceof Error ? error : void 0
+      );
+    }
+    if (errorMessage.includes("proof") && (errorMessage.includes("failed") || errorMessage.includes("error"))) {
+      return new CloakError(
+        "Zero-knowledge proof generation failed. This is usually temporary - please try again.",
+        "prover",
+        true,
+        error instanceof Error ? error : void 0
+      );
+    }
+    if (errorMessage.includes("relay") || errorMessage.includes("withdraw")) {
+      return new CloakError(
+        "Relay service error. Please try again later.",
+        "relay",
+        true,
+        error instanceof Error ? error : void 0
+      );
+    }
+    return new CloakError(
+      `${context}: ${errorMessage}`,
+      "network",
+      false,
+      error instanceof Error ? error : void 0
+    );
+  }
 };
 
+// src/core/note.ts
+function serializeNote(note, pretty = false) {
+  validateNote(note);
+  return pretty ? JSON.stringify(note, null, 2) : JSON.stringify(note);
+}
+function downloadNote(note, filename) {
+  const g = globalThis;
+  const doc = g?.document;
+  const URL_ = g?.URL;
+  const Blob_ = g?.Blob;
+  if (!doc || !URL_ || !Blob_) {
+    throw new Error("downloadNote is only available in browser environments");
+  }
+  const json = serializeNote(note, true);
+  const blob = new Blob_([json], { type: "application/json" });
+  const url = URL_.createObjectURL(blob);
+  const defaultFilename = `cloak-note-${note.commitment.slice(0, 8)}.json`;
+  const link = doc.createElement("a");
+  link.href = url;
+  link.download = filename || defaultFilename;
+  link.click();
+  URL_.revokeObjectURL(url);
+}
+async function copyNoteToClipboard(note) {
+  const g = globalThis;
+  const nav = g?.navigator;
+  if (!nav || !nav.clipboard) {
+    throw new Error("Clipboard API not available");
+  }
+  const json = serializeNote(note, true);
+  await nav.clipboard.writeText(json);
+}
+
 // src/core/compliance-keys.ts
 import nacl2 from "tweetnacl";
 import { blake3 as blake32 } from "@noble/hashes/blake3";
@@ -2492,107 +4239,6 @@ async function decryptComplianceMetadataWithMasterKey(encrypted, masterComplianc
   return decryptWithSharedSecret(payload, sharedSecret);
 }
 
-// src/utils/fees.ts
-var LAMPORTS_PER_SOL = 1e9;
-var FIXED_FEE_LAMPORTS = 5e6;
-var VARIABLE_FEE_NUMERATOR = 3;
-var VARIABLE_FEE_DENOMINATOR = 1e3;
-var VARIABLE_FEE_RATE = VARIABLE_FEE_NUMERATOR / VARIABLE_FEE_DENOMINATOR;
-var MIN_DEPOSIT_LAMPORTS = 1e7;
-function calculateFee(amountLamports) {
-  const variableFee = Math.floor(amountLamports * VARIABLE_FEE_NUMERATOR / VARIABLE_FEE_DENOMINATOR);
-  return FIXED_FEE_LAMPORTS + variableFee;
-}
-function calculateFeeBigint(amountLamports) {
-  const fixed = BigInt(FIXED_FEE_LAMPORTS);
-  const variable = amountLamports * BigInt(VARIABLE_FEE_NUMERATOR) / BigInt(VARIABLE_FEE_DENOMINATOR);
-  return fixed + variable;
-}
-function isWithdrawAmountSufficient(amountLamports) {
-  return amountLamports > calculateFeeBigint(amountLamports);
-}
-function getDistributableAmount(amountLamports) {
-  return amountLamports - calculateFee(amountLamports);
-}
-function formatAmount(lamports, decimals = 9) {
-  return (lamports / LAMPORTS_PER_SOL).toFixed(decimals);
-}
-function parseAmount(sol) {
-  const num = parseFloat(sol);
-  if (isNaN(num) || num < 0) {
-    throw new Error(`Invalid SOL amount: ${sol}`);
-  }
-  return Math.floor(num * LAMPORTS_PER_SOL);
-}
-function validateOutputsSum(outputs, expectedTotal) {
-  const sum = outputs.reduce((acc, out) => acc + out.amount, 0);
-  return sum === expectedTotal;
-}
-function calculateRelayFee(amountLamports, feeBps) {
-  if (feeBps < 0 || feeBps > 1e4) {
-    throw new Error("Fee basis points must be between 0 and 10000");
-  }
-  return Math.floor(amountLamports * feeBps / 1e4);
-}
-
-// src/utils/validation.ts
-import { PublicKey as PublicKey3 } from "@solana/web3.js";
-function isValidSolanaAddress(address) {
-  try {
-    new PublicKey3(address);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-// src/utils/network.ts
-function detectNetworkFromRpcUrl(rpcUrl) {
-  const url = rpcUrl || process.env.NEXT_PUBLIC_SOLANA_RPC_URL || "";
-  const lowerUrl = url.toLowerCase();
-  if (lowerUrl.includes("mainnet") || lowerUrl.includes("api.mainnet-beta") || lowerUrl.includes("mainnet-beta")) {
-    return "mainnet";
-  }
-  if (lowerUrl.includes("testnet") || lowerUrl.includes("api.testnet")) {
-    return "testnet";
-  }
-  if (lowerUrl.includes("devnet") || lowerUrl.includes("api.devnet")) {
-    return "devnet";
-  }
-  if (lowerUrl.includes("localhost") || lowerUrl.includes("127.0.0.1") || lowerUrl.includes("local")) {
-    return "localnet";
-  }
-  return "mainnet";
-}
-function getRpcUrlForNetwork(network) {
-  switch (network) {
-    case "mainnet":
-      return "https://api.mainnet-beta.solana.com";
-    case "devnet":
-      return "https://api.devnet.solana.com";
-    case "localnet":
-      return "http://localhost:8899";
-    default:
-      return "https://api.mainnet-beta.solana.com";
-  }
-}
-function isValidRpcUrl(url) {
-  try {
-    const parsed = new URL(url);
-    return parsed.protocol === "http:" || parsed.protocol === "https:";
-  } catch {
-    return false;
-  }
-}
-function getExplorerUrl(signature, network = "devnet") {
-  const cluster = network === "mainnet" ? "" : `?cluster=${network}`;
-  return `https://explorer.solana.com/tx/${signature}${cluster}`;
-}
-function getAddressExplorerUrl(address, network = "devnet") {
-  const cluster = network === "mainnet" ? "" : `?cluster=${network}`;
-  return `https://explorer.solana.com/address/${address}${cluster}`;
-}
-
 // src/utils/verify-utxos.ts
 async function verifyUtxos(utxos, connection, programId, commitment = "confirmed") {
   const checkable = [];
@@ -2721,6 +4367,45 @@ async function fetchRiskQuoteIx(connection, wallet, rangeApiKey) {
   };
 }
 
+// src/helpers/encrypted-output.ts
+function prepareEncryptedOutput(note, cloakKeys) {
+  const noteData = {
+    amount: note.amount,
+    r: note.r,
+    sk_spend: note.sk_spend,
+    commitment: note.commitment
+  };
+  const encrypted = encryptNoteForRecipient(noteData, cloakKeys.view.pvk);
+  return btoa(JSON.stringify(encrypted));
+}
+function prepareEncryptedOutputForRecipient(note, recipientPvkHex) {
+  const noteData = {
+    amount: note.amount,
+    r: note.r,
+    sk_spend: note.sk_spend,
+    commitment: note.commitment
+  };
+  const recipientPvk = hexToBytes(recipientPvkHex);
+  const encrypted = encryptNoteForRecipient(noteData, recipientPvk);
+  return btoa(JSON.stringify(encrypted));
+}
+function encodeNoteSimple(note) {
+  const data = {
+    amount: note.amount,
+    r: note.r,
+    sk_spend: note.sk_spend,
+    commitment: note.commitment
+  };
+  const json = JSON.stringify(data);
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(json).toString("base64");
+  } else if (typeof btoa !== "undefined") {
+    return btoa(json);
+  } else {
+    throw new Error("No base64 encoding method available");
+  }
+}
+
 // src/helpers/wallet-integration.ts
 import {
   Keypair as Keypair2
@@ -3232,14 +4917,181 @@ async function preflightCheck(relayUrl, rootHex) {
   };
 }
 
+// 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/core/transact.ts
 import {
-  PublicKey as PublicKey5,
-  Transaction as Transaction2,
-  TransactionInstruction,
+  PublicKey as PublicKey6,
+  Transaction as Transaction3,
+  TransactionInstruction as TransactionInstruction3,
   sendAndConfirmTransaction,
-  SystemProgram,
-  ComputeBudgetProgram,
+  SystemProgram as SystemProgram2,
+  ComputeBudgetProgram as ComputeBudgetProgram2,
   SYSVAR_INSTRUCTIONS_PUBKEY,
   SYSVAR_SLOT_HASHES_PUBKEY,
   VersionedTransaction,
@@ -3252,7 +5104,7 @@ import {
   getAssociatedTokenAddressSync,
   TOKEN_PROGRAM_ID
 } from "@solana/spl-token";
-import * as snarkjs from "snarkjs";
+import * as snarkjs2 from "snarkjs";
 
 // src/core/chain-note.ts
 var NOTE_VERSION = 2;
@@ -3402,7 +5254,7 @@ function chainNoteFromBase64(base64) {
 // src/core/transact.ts
 import { buildPoseidon as buildPoseidon3 } from "circomlibjs";
 import nacl4 from "tweetnacl";
-var IS_BROWSER = typeof window !== "undefined" || typeof globalThis.document !== "undefined";
+var IS_BROWSER2 = typeof window !== "undefined" || typeof globalThis.document !== "undefined";
 var DEFAULT_TRANSACTION_CIRCUITS_URL = "https://storage.googleapis.com/cloak-circuits/circuits/0.1.0";
 var DEFAULT_CLOAK_RELAY_URL = "https://api.cloak.ag";
 function resolveDefaultTransactionCircuitsPath() {
@@ -3415,7 +5267,7 @@ async function resolveTransactionCircuitFiles() {
   const baseNorm = base.endsWith("/") ? base : `${base}/`;
   const wasmUrl = `${baseNorm}transaction_js/transaction.wasm`;
   const zkeyUrl = `${baseNorm}transaction_final.zkey`;
-  if (IS_BROWSER) {
+  if (IS_BROWSER2) {
     return { wasmPath: wasmUrl, zkeyPath: zkeyUrl };
   }
   if (_remoteTxCircuitsCache?.base === baseNorm) {
@@ -3552,7 +5404,7 @@ async function resolveAddressLookupTableAccounts(connection, relayUrl, altAddres
   const fetched = await Promise.all(
     altAddresses.map(async (addr) => {
       try {
-        const pubkey = new PublicKey5(addr);
+        const pubkey = new PublicKey6(addr);
         const result = await connection.getAddressLookupTable(pubkey);
         return result.value ?? null;
       } catch {
@@ -3714,7 +5566,7 @@ async function generateTransactionProof(inputs, onProgress) {
   onProgress?.(10);
   const { wasmPath: wasmInput, zkeyPath: zkeyInput } = await resolveTransactionCircuitFiles();
   onProgress?.(30);
-  const { proof, publicSignals } = await snarkjs.groth16.fullProve(
+  const { proof, publicSignals } = await snarkjs2.groth16.fullProve(
     inputs,
     wasmInput,
     zkeyInput
@@ -3794,7 +5646,7 @@ function buildPublicInputsBytesFromSignals(publicSignals) {
 }
 var TRANSACT_DISCRIMINATOR = 0;
 function deriveNullifierPDA(programId, poolPDA, nullifier) {
-  return PublicKey5.findProgramAddressSync(
+  return PublicKey6.findProgramAddressSync(
     [Buffer.from("nullifier"), poolPDA.toBuffer(), Buffer.from(nullifier)],
     programId
   );
@@ -3837,7 +5689,7 @@ function buildTransactInstruction(programId, payer, poolPDA, treasuryPDA, merkle
     // 4. nullifier PDA 0 (writable)
     { pubkey: nullifierPDA1, isSigner: false, isWritable: true },
     // 5. nullifier PDA 1 (writable)
-    { pubkey: SystemProgram.programId, isSigner: false, isWritable: false }
+    { pubkey: SystemProgram2.programId, isSigner: false, isWritable: false }
     // 6. system_program
   ];
   if (splAccounts) {
@@ -3862,7 +5714,7 @@ function buildTransactInstruction(programId, payer, poolPDA, treasuryPDA, merkle
       accounts.push({ pubkey: SYSVAR_INSTRUCTIONS_PUBKEY, isSigner: false, isWritable: false });
     }
   }
-  return new TransactionInstruction({
+  return new TransactionInstruction3({
     programId,
     keys: accounts,
     data
@@ -3870,10 +5722,10 @@ function buildTransactInstruction(programId, payer, poolPDA, treasuryPDA, merkle
 }
 function getCommonALTAddresses() {
   return [
-    SystemProgram.programId,
+    SystemProgram2.programId,
     SYSVAR_SLOT_HASHES_PUBKEY,
     SYSVAR_INSTRUCTIONS_PUBKEY,
-    ComputeBudgetProgram.programId
+    ComputeBudgetProgram2.programId
   ];
 }
 function dedupePubkeys(addresses) {
@@ -3934,7 +5786,7 @@ async function createEphemeralALT(connection, depositor, onProgress, additionalA
         lookupTable: altAddress,
         addresses: addressesForCreate
       });
-      const tx = new Transaction2().add(createIx).add(extendIx);
+      const tx = new Transaction3().add(createIx).add(extendIx);
       const { blockhash } = await connection.getLatestBlockhash();
       tx.recentBlockhash = blockhash;
       tx.feePayer = depositor.publicKey;
@@ -4100,8 +5952,8 @@ async function submitTransactionDirect(connection, programId, depositor, proofBy
   if (riskQuoteIx) {
     baseInstructions.unshift(riskQuoteIx);
   }
-  const cuLimitIx = ComputeBudgetProgram.setComputeUnitLimit({ units: 4e5 });
-  const cuPriceIx = ComputeBudgetProgram.setComputeUnitPrice({ microLamports: 1e5 });
+  const cuLimitIx = ComputeBudgetProgram2.setComputeUnitLimit({ units: 4e5 });
+  const cuPriceIx = ComputeBudgetProgram2.setComputeUnitPrice({ microLamports: 1e5 });
   const fullInstructions = [...baseInstructions, cuLimitIx, cuPriceIx, transactIx];
   const compactInstructions = [...baseInstructions, cuLimitIx, transactIx];
   const minimalInstructions = [...baseInstructions, transactIx];
@@ -4163,6 +6015,38 @@ async function submitTransactionDirect(connection, programId, depositor, proofBy
     const sendV0 = async (ixs, options) => {
       const maxBlockhashRetries = 2;
       const maxTransportRetries = 3;
+      const alreadyLanded = async (sig) => {
+        if (!sig) return false;
+        for (let i = 0; i < 6; i++) {
+          try {
+            const { value } = await connection.getSignatureStatus(sig, {
+              searchTransactionHistory: true
+            });
+            if (value) {
+              if (value.err) return false;
+              if (value.confirmationStatus === "confirmed" || value.confirmationStatus === "finalized") {
+                return true;
+              }
+            }
+          } catch {
+          }
+          await new Promise((r) => setTimeout(r, 400));
+        }
+        return false;
+      };
+      const looksLikeDoubleSpend = (error) => {
+        const m = error instanceof Error ? error.message : String(error);
+        return m.includes("0x1020") || // confirmTransaction().value.err is JSON-stringified, so 0x1020 appears as
+        // its decimal form ("Custom":4128) rather than the hex "0x1020".
+        m.includes('"Custom":4128') || m.includes("already been processed") || m.toLowerCase().includes("doublespend");
+      };
+      const sentSigs = [];
+      const anyLanded = async () => {
+        for (const s of sentSigs) {
+          if (await alreadyLanded(s)) return s;
+        }
+        return void 0;
+      };
       for (let blockhashRetry = 0; blockhashRetry <= maxBlockhashRetries; blockhashRetry++) {
         if (blockhashRetry > 0) {
           ({ blockhash, lastValidBlockHeight } = await connection.getLatestBlockhash());
@@ -4185,6 +6069,7 @@ async function submitTransactionDirect(connection, programId, depositor, proofBy
               signature = await connection.sendRawTransaction(versionedTx.serialize(), {
                 skipPreflight: options?.skipPreflight ?? false
               });
+              sentSigs.push(signature);
               onProgress?.("Confirming transaction...");
               const confirmation = await connection.confirmTransaction({
                 signature,
@@ -4201,6 +6086,7 @@ async function submitTransactionDirect(connection, programId, depositor, proofBy
               signature = await connection.sendRawTransaction(signedTx.serialize(), {
                 skipPreflight: options?.skipPreflight ?? false
               });
+              sentSigs.push(signature);
               onProgress?.("Confirming transaction...");
               const confirmation = await connection.confirmTransaction({
                 signature,
@@ -4215,8 +6101,10 @@ async function submitTransactionDirect(connection, programId, depositor, proofBy
             }
             return signature;
           } catch (error) {
-            if (isBlockhashExpiryError(error) && blockhashRetry < maxBlockhashRetries) {
-              break;
+            if (isBlockhashExpiryError(error)) {
+              const landed = await anyLanded();
+              if (landed) return landed;
+              if (blockhashRetry < maxBlockhashRetries) break;
             }
             if (isTransientTransportError(error) && transportAttempt < maxTransportRetries) {
               transportAttempt++;
@@ -4228,6 +6116,10 @@ async function submitTransactionDirect(connection, programId, depositor, proofBy
               ({ blockhash, lastValidBlockHeight } = await connection.getLatestBlockhash());
               continue;
             }
+            if (looksLikeDoubleSpend(error)) {
+              const landed = await anyLanded();
+              if (landed) return landed;
+            }
             throw error;
           }
         }
@@ -4310,7 +6202,7 @@ async function submitTransactionDirect(connection, programId, depositor, proofBy
     let legacyTransportAttempt = 0;
     while (true) {
       try {
-        const tx = new Transaction2();
+        const tx = new Transaction3();
         for (const ix of instructions) {
           tx.add(ix);
         }
@@ -4492,7 +6384,7 @@ async function fetchRiskQuoteInstruction(riskQuoteUrl, wallet, options) {
     const signerB58 = signerKey;
     const signatureBuf = Buffer.from(signatureB64, "base64");
     const messageArr = hexToBytes2(messageHex);
-    const publicKeyBytes = new PublicKey5(signerB58).toBytes();
+    const publicKeyBytes = new PublicKey6(signerB58).toBytes();
     if (signatureBuf.length !== 64 || messageArr.length !== 33 && messageArr.length !== 41 && messageArr.length !== 50 || publicKeyBytes.length !== 32) {
       throw new Error(
         `Invalid risk quote response: invalid lengths (sig=${signatureBuf.length}, msg=${messageArr.length}, pk=${publicKeyBytes.length})`
@@ -4514,10 +6406,10 @@ async function fetchRiskQuoteInstruction(riskQuoteUrl, wallet, options) {
       `Invalid risk quote response: expected relay format { signature, message, signer_pubkey } or { instruction }. Received keys: ${keys}`
     );
   }
-  return new TransactionInstruction({
-    programId: new PublicKey5(raw.programId),
+  return new TransactionInstruction3({
+    programId: new PublicKey6(raw.programId),
     keys: raw.keys.map((k) => ({
-      pubkey: new PublicKey5(k.pubkey),
+      pubkey: new PublicKey6(k.pubkey),
       isSigner: k.isSigner,
       isWritable: k.isWritable
     })),
@@ -5401,12 +7293,12 @@ async function transact(params, options) {
   if (lastError) {
     const classified = classifyRelayError(lastError.message);
     const isMerkleClass = !(classified instanceof UtxoAlreadySpentError) && !(classified instanceof SanctionsQuoteError) && !isRootNotFoundError2(lastError);
-    if (!IS_BROWSER && isMerkleClass && relayUrl) {
+    if (!IS_BROWSER2 && isMerkleClass && relayUrl) {
       onProgress?.(
         "All relay-tree attempts failed. Rebuilding merkle tree from chain as last resort..."
       );
       try {
-        const [merkleTreePda] = PublicKey5.findProgramAddressSync(
+        const [merkleTreePda] = PublicKey6.findProgramAddressSync(
           [Buffer.from("merkle_tree"), mint.toBuffer()],
           programId
         );
@@ -6475,7 +8367,7 @@ async function swapWithChange(inputUtxos, swapAmount, outputMint, recipientAta,
 // src/core/scanner.ts
 import _bs582 from "bs58";
 import {
-  PublicKey as PublicKey6
+  PublicKey as PublicKey7
 } from "@solana/web3.js";
 import { getAssociatedTokenAddressSync as getAssociatedTokenAddressSync2 } from "@solana/spl-token";
 var bs582 = _bs582.default || _bs582;
@@ -6563,7 +8455,7 @@ function parseSwapOutputMint(data) {
   const mintBytes = data.slice(SWAP_OUTPUT_MINT_OFFSET, end);
   if (mintBytes.every((byte) => byte === 0)) return void 0;
   try {
-    return new PublicKey6(mintBytes).toBase58();
+    return new PublicKey7(mintBytes).toBase58();
   } catch {
     return void 0;
   }
@@ -6653,7 +8545,7 @@ function parseSwapRecipientAta(data) {
   const recipientAtaBytes = data.slice(recipientAtaStart, recipientAtaEnd);
   if (recipientAtaBytes.every((byte) => byte === 0)) return void 0;
   try {
-    return new PublicKey6(recipientAtaBytes).toBase58();
+    return new PublicKey7(recipientAtaBytes).toBase58();
   } catch {
     return void 0;
   }
@@ -6968,8 +8860,8 @@ async function scanTransactions(opts) {
                   if (onChainAta) {
                     try {
                       const expectedAta = getAssociatedTokenAddressSync2(
-                        new PublicKey6(asset.mint),
-                        new PublicKey6(walletPublicKey)
+                        new PublicKey7(asset.mint),
+                        new PublicKey7(walletPublicKey)
                       ).toBase58();
                       if (onChainAta === expectedAta) {
                         isOurs = true;
@@ -7272,7 +9164,7 @@ function formatComplianceCsv(report) {
 }
 
 // src/core/wallet.ts
-import { PublicKey as PublicKey7 } from "@solana/web3.js";
+import { PublicKey as PublicKey8 } from "@solana/web3.js";
 var UtxoWallet = class _UtxoWallet {
   constructor(viewingKey) {
     this.wallets = /* @__PURE__ */ new Map();
@@ -7484,7 +9376,7 @@ var UtxoWallet = class _UtxoWallet {
       data.viewingKey ? new Uint8Array(data.viewingKey) : void 0
     );
     for (const w of data.wallets) {
-      const mint = new PublicKey7(w.mint);
+      const mint = new PublicKey8(w.mint);
       for (const u of w.utxos) {
         wallet.addUtxo({
           amount: BigInt(u.amount),
@@ -7567,13 +9459,15 @@ var SimpleWallet = class {
 };
 
 // src/index.ts
-var VERSION = "0.1.6";
+var VERSION = "0.1.5";
 var SCANNER_SUPPORTS_TRANSACT_SWAP = true;
 export {
   CLOAK_PROGRAM_ID,
   CloakError,
   CloakSDK,
+  DEFAULT_CIRCUITS_URL,
   DEFAULT_TRANSACTION_CIRCUITS_URL,
+  EXPECTED_CIRCUIT_HASHES,
   FIXED_FEE_LAMPORTS,
   LAMPORTS_PER_SOL,
   LocalStorageAdapter,
@@ -7596,6 +9490,7 @@ export {
   VARIABLE_FEE_NUMERATOR,
   VARIABLE_FEE_RATE,
   VERSION,
+  areCircuitsAvailable,
   bigintToBytes322 as bigintToBytes32,
   bigintToHex,
   buildMerkleTree,
@@ -7609,15 +9504,30 @@ export {
   chainNoteFromBase64,
   chainNoteToBase64,
   classifyRelayError,
+  cleanupStalePendingOperations,
+  clearPendingDeposits,
+  clearPendingWithdrawals,
   computeChainNoteHash,
+  computeCommitment2 as computeCommitment,
   computeExtDataHash,
   computeMerkleRoot,
+  computeNullifier2 as computeNullifier,
+  computeNullifierAsync,
+  computeNullifierSync,
+  computeOutputsHash,
+  computeOutputsHashAsync,
+  computeOutputsHashSync,
   computeProofForLatestDeposit,
   computeProofFromChain,
   computeSignature,
+  computeSwapOutputsHash,
+  computeSwapOutputsHashAsync,
+  computeSwapOutputsHashSync,
   computeCommitment as computeUtxoCommitment,
   computeNullifier as computeUtxoNullifier,
+  copyNoteToClipboard,
   createCloakError,
+  createDepositInstruction,
   createLogger,
   createUtxo,
   createZeroUtxo,
@@ -7637,52 +9547,78 @@ export {
   deriveViewingKeyFromUtxoPrivateKey,
   deserializeUtxo,
   detectNetworkFromRpcUrl,
+  downloadNote,
+  encodeNoteSimple,
   encryptCompactChainNote,
   encryptNoteForRecipient,
   encryptTransactionMetadata,
   encryptTransactionMetadataBundle,
   expandSpendKey,
   exportKeys,
+  exportNote,
+  exportWalletKeys,
   fetchCommitments,
   fetchRiskQuoteInstruction,
   fetchRiskQuoteIx,
+  filterNotesByNetwork,
+  filterWithdrawableNotes,
+  findNoteByCommitment,
   formatAmount,
   formatComplianceCsv,
   formatErrorForLogging,
   formatSol,
   fullWithdraw,
   generateCloakKeys,
+  generateCommitment,
+  generateCommitmentAsync,
   generateMasterSeed,
+  generateNote,
+  generateNoteFromWallet,
   generateUtxoKeypair,
   generateViewingKeyPair,
+  generateWithdrawRegularProof,
+  generateWithdrawSwapProof,
   getAddressExplorerUrl,
   getCircuitsPath,
+  getDefaultCircuitsPath,
   getDistributableAmount,
   getExplorerUrl,
   getNkFromUtxoPrivateKey,
   getNullifierPDA,
+  getPendingOperationsSummary,
   getPublicKey,
+  getPublicViewKey,
+  getRecipientAmount,
   getRpcUrlForNetwork,
   getShieldPoolPDAs,
   getSwapStatePDA,
+  getViewKey,
+  hasPendingOperations,
   hexToBigint2 as hexToBigint,
   hexToBytes,
   importKeys,
+  importWalletKeys,
   isDebugEnabled,
   isRootNotFoundError,
   isValidHex,
   isValidRpcUrl,
   isValidSolanaAddress,
   isWithdrawAmountSufficient,
+  isWithdrawable,
   keypairToAdapter,
+  loadPendingDeposits,
+  loadPendingWithdrawals,
   parseAmount,
   parseError,
+  parseNote,
   parseRelayErrorResponse,
   parseTransactionError,
   partialWithdraw,
   poseidonHash,
   preflightCheck,
   preflightNullifiers,
+  prepareEncryptedOutput,
+  prepareEncryptedOutputForRecipient,
   proofToBytes,
   pubkeyToFieldElement,
   pubkeyToLimbs,
@@ -7690,11 +9626,16 @@ export {
   randomFieldElement,
   readMerkleTreeState,
   registerViewingKey,
+  removePendingDeposit,
+  removePendingWithdrawal,
+  savePendingDeposit,
+  savePendingWithdrawal,
   scanNotesForWallet,
   scanTransactions,
   sdkLogger,
   selectUtxos,
   sendTransaction,
+  serializeNote,
   serializeUtxo,
   setCircuitsPath,
   setDebugMode,
@@ -7708,12 +9649,21 @@ export {
   transfer,
   truncate,
   tryDecryptNote,
+  updateNoteWithDeposit,
+  updatePendingDeposit,
+  updatePendingWithdrawal,
   bigintToBytes32 as utxoBigintToBytes32,
   utxoEquals,
   hexToBigint as utxoHexToBigint,
+  validateDepositParams,
+  validateNote,
   validateOutputsSum,
   validateRoot,
+  validateTransfers,
   validateWalletConnected,
+  validateWithdrawableNote,
+  verifyAllCircuits,
+  verifyCircuitIntegrity,
   verifyUtxos,
   waitForRoot,
   withTiming