@cloak.dev/sdk 0.1.0 → 0.1.2

package/README.md

@@ -28,12 +28,101 @@ npm install @solana/spl-token
 
 ## Quick Start
 
-### Risk Quote Configuration (Recommended)
+### SDK Defaults (Recommended)
+
+- Standard integrations should use SDK defaults for program, relay, and circuits.
+- Do not expose protocol-level config (`programId`, relay URL, circuits URL) as end-user input.
+- `transact`, `partialWithdraw`, and `fullWithdraw` already include stale-root retry handling.
+- For simple CLI sends, require only `SOLANA_RPC_URL` and `KEYPAIR_PATH`.
+
+### Minimal Private SOL Send (Single File, Keypair)
+
+Use this contract for one-shot scripts and AI-generated snippets.
+
+```ts
+import { readFileSync } from "fs";
+import {
+  CLOAK_PROGRAM_ID,
+  NATIVE_SOL_MINT,
+  createUtxo,
+  createZeroUtxo,
+  fullWithdraw,
+  generateUtxoKeypair,
+  transact,
+} from "@cloak.dev/sdk";
+import { Connection, Keypair, PublicKey } from "@solana/web3.js";
+
+async function main() {
+  const [recipientArg, lamportsArg] = process.argv.slice(2);
+  if (!recipientArg || !lamportsArg) {
+    throw new Error("Usage: npx tsx send-sol-private.ts <recipientPubkey> <lamports>");
+  }
+
+  const rpcUrl = process.env.SOLANA_RPC_URL;
+  const keypairPath = process.env.KEYPAIR_PATH;
+  if (!rpcUrl || !keypairPath) {
+    throw new Error("Set SOLANA_RPC_URL and KEYPAIR_PATH");
+  }
+
+  const connection = new Connection(rpcUrl, "confirmed");
+  const signer = Keypair.fromSecretKey(
+    Uint8Array.from(JSON.parse(readFileSync(keypairPath, "utf8"))),
+  );
+
+  const recipient = new PublicKey(recipientArg);
+  const amountLamports = BigInt(lamportsArg);
+
+  const owner = await generateUtxoKeypair();
+  const output = await createUtxo(amountLamports, owner, NATIVE_SOL_MINT);
+
+  const deposited = await transact(
+    {
+      inputUtxos: [await createZeroUtxo(NATIVE_SOL_MINT)],
+      outputUtxos: [output],
+      externalAmount: amountLamports,
+      depositor: signer.publicKey,
+    },
+    {
+      connection,
+      programId: CLOAK_PROGRAM_ID,
+      depositorKeypair: signer,
+      walletPublicKey: signer.publicKey,
+      enforceViewingKeyRegistration: false,
+    },
+  );
+
+  const withdrawn = await fullWithdraw(deposited.outputUtxos, recipient, {
+    connection,
+    programId: CLOAK_PROGRAM_ID,
+    depositorKeypair: signer,
+    walletPublicKey: signer.publicKey,
+    cachedMerkleTree: deposited.merkleTree,
+    enforceViewingKeyRegistration: false,
+  });
+
+  console.log(withdrawn.signature);
+}
+
+main().catch((e) => {
+  console.error(e instanceof Error ? e.message : String(e));
+  process.exit(1);
+});
+```
+
+Run:
+
+```bash
+SOLANA_RPC_URL="https://api.mainnet-beta.solana.com" \
+KEYPAIR_PATH="/absolute/path/to/id.json" \
+npx tsx send-sol-private.ts <recipientPubkey> <lamports>
+```
+
+Hard rules for minimal scripts:
 
-- Default production flow: set `CLOAK_RELAY_URL` and let relay handle Range quoting.
-- Keep `RANGE_API_KEY` only in relay/service backend, not in SDK clients.
-- SDK auto-uses `${CLOAK_RELAY_URL}/range-quote` when `relayUrl` is provided.
-- SDK-side `rangeApiKey` exists only as a server-side fallback (no-relay scenarios).
+- Use lamports from CLI (`<lamports>`) and keep transaction math in `bigint`.
+- Use `KEYPAIR_PATH`; do not ask for raw private key env vars.
+- Do not parse SOL decimals with float math (`parseFloat`, `AMOUNT_SOL`).
+- Keep `programId` fixed to `CLOAK_PROGRAM_ID` (no end-user override).
 
 ### Maintained Examples
 

package/dist/index.cjs

@@ -1863,6 +1863,22 @@ var ErrorPatterns = [
       recoverable: true
     }
   },
+  {
+    patterns: [
+      "Swap refunded",
+      "swap refunded",
+      "funds refunded as SOL",
+      "funds were refunded",
+      "Swap timed out and funds were refunded"
+    ],
+    result: {
+      title: "Swap Refunded",
+      message: "No swap route was available. Your funds have been refunded as SOL to your wallet.",
+      category: "service",
+      suggestion: "Check your wallet balance \u2014 the SOL should already be there (minus the protocol fee). Try again with a different token or amount.",
+      recoverable: true
+    }
+  },
   {
     patterns: [
       "Failed to get quote",
@@ -2615,8 +2631,8 @@ var IS_REACT_NATIVE = typeof navigator !== "undefined" && navigator.product ===
 var IS_BROWSER = IS_REACT_NATIVE || typeof window !== "undefined" || typeof globalThis !== "undefined" && typeof globalThis.document !== "undefined";
 var DEFAULT_CIRCUITS_URL = "https://cloak-circuits.s3.us-east-1.amazonaws.com/circuits/0.1.0";
 var SKIP_CIRCUIT_VERIFY_ENV = typeof process !== "undefined" && process.env && process.env.CLOAK_SKIP_CIRCUIT_INTEGRITY_CHECK === "1";
-function isUrl(path2) {
-  return path2.startsWith("http://") || path2.startsWith("https://");
+function isUrl(path) {
+  return path.startsWith("http://") || path.startsWith("https://");
 }
 function resolveCircuitsUrl(circuitsPath2) {
   if (circuitsPath2.trim() !== "" && circuitsPath2.trim() !== DEFAULT_CIRCUITS_URL) {
@@ -3083,7 +3099,7 @@ function createSetLoadedAccountsDataSizeLimitInstruction(bytes) {
     data
   });
 }
-var CLOAK_PROGRAM_ID = new import_web35.PublicKey("c1oak6tetxYnNfvXKFkpn1d98FxtK7B68vBQLYQpWKp");
+var CLOAK_PROGRAM_ID = new import_web35.PublicKey("zh1eLd6rSphLejbFfJEneUwzHRfMKxgzrgkfwA6qRkW");
 var CLOAK_API_URL = "https://api.cloak.ag";
 var CloakSDK = class {
   /**
@@ -5560,56 +5576,39 @@ function chainNoteFromBase64(base64) {
 // src/core/transact.ts
 var import_circomlibjs4 = require("circomlibjs");
 var import_tweetnacl4 = __toESM(require("tweetnacl"), 1);
-var path = __toESM(require("path"), 1);
-var import_crypto13 = require("crypto");
-var import_promises = require("fs/promises");
-var import_os = require("os");
+var IS_BROWSER2 = typeof window !== "undefined" || typeof globalThis.document !== "undefined";
 var DEFAULT_TRANSACTION_CIRCUITS_URL = "https://cloak-circuits.s3.us-east-1.amazonaws.com/circuits/0.1.0";
+var DEFAULT_CLOAK_RELAY_URL = "https://api.cloak.ag";
 function resolveDefaultTransactionCircuitsPath() {
   return DEFAULT_TRANSACTION_CIRCUITS_URL;
 }
 var circuitsPath = resolveDefaultTransactionCircuitsPath();
-function isHttpCircuitsPath(p) {
-  return p.startsWith("https://") || p.startsWith("http://");
-}
 var _remoteTxCircuitsCache = null;
 async function resolveTransactionCircuitFiles() {
   const base = circuitsPath;
-  const wasmRel = path.join("transaction_js", "transaction.wasm");
-  const zkeyRel = "transaction_final.zkey";
-  if (!isHttpCircuitsPath(base)) {
-    const root = base;
-    return {
-      wasmPath: path.join(root, wasmRel),
-      zkeyPath: path.join(root, zkeyRel)
-    };
-  }
   const baseNorm = base.endsWith("/") ? base : `${base}/`;
+  const wasmUrl = `${baseNorm}transaction_js/transaction.wasm`;
+  const zkeyUrl = `${baseNorm}transaction_final.zkey`;
+  if (IS_BROWSER2) {
+    return { wasmPath: wasmUrl, zkeyPath: zkeyUrl };
+  }
   if (_remoteTxCircuitsCache?.base === baseNorm) {
-    const { dir: dir2 } = _remoteTxCircuitsCache;
-    return {
-      wasmPath: path.join(dir2, "transaction.wasm"),
-      zkeyPath: path.join(dir2, "transaction_final.zkey")
-    };
+    return _remoteTxCircuitsCache.artifacts;
   }
-  const wasmUrl = new URL(wasmRel.split(path.sep).join("/"), baseNorm).toString();
-  const zkeyUrl = new URL(zkeyRel, baseNorm).toString();
-  const subdir = `cloak-tx-circuits-${(0, import_crypto13.createHash)("sha256").update(baseNorm).digest("hex").slice(0, 16)}`;
-  const dir = path.join((0, import_os.tmpdir)(), subdir);
-  await (0, import_promises.mkdir)(dir, { recursive: true });
-  const wasmPath = path.join(dir, "transaction.wasm");
-  const zkeyPath = path.join(dir, "transaction_final.zkey");
-  const download = async (url, dest) => {
+  const fetchAsBuffer = async (url) => {
     const res = await fetch(url);
     if (!res.ok) {
       throw new Error(`Failed to fetch circuit artifact ${url}: ${res.status} ${res.statusText}`);
     }
-    await (0, import_promises.writeFile)(dest, Buffer.from(await res.arrayBuffer()));
+    return new Uint8Array(await res.arrayBuffer());
   };
-  await download(wasmUrl, wasmPath);
-  await download(zkeyUrl, zkeyPath);
-  _remoteTxCircuitsCache = { base: baseNorm, dir };
-  return { wasmPath, zkeyPath };
+  const [wasmData, zkeyData] = await Promise.all([
+    fetchAsBuffer(wasmUrl),
+    fetchAsBuffer(zkeyUrl)
+  ]);
+  const artifacts = { wasmPath: wasmData, zkeyPath: zkeyData };
+  _remoteTxCircuitsCache = { base: baseNorm, artifacts };
+  return artifacts;
 }
 var _transactPaddingSaltCounter = 0;
 var _registeredViewingKeys = /* @__PURE__ */ new Set();
@@ -5703,6 +5702,12 @@ function deriveRelayUrlFromRiskQuoteUrl(riskQuoteUrl) {
   }
   return void 0;
 }
+function resolveRelayUrl(relayUrl) {
+  const trimmed = relayUrl?.trim();
+  if (trimmed === "") return void 0;
+  if (trimmed) return trimmed.replace(/\/$/, "");
+  return DEFAULT_CLOAK_RELAY_URL;
+}
 async function resolveAddressLookupTableAccounts(connection, relayUrl, altAddressesFromOptions, provided, onProgress) {
   if (provided && provided.length > 0) {
     return provided;
@@ -5800,9 +5805,8 @@ async function resolveChainNoteNk(options) {
   }
   return null;
 }
-function shouldDefaultUseUniqueNullifiers(connection) {
-  const endpoint = (connection.rpcEndpoint || "").toLowerCase();
-  return endpoint.includes("127.0.0.1") || endpoint.includes("localhost") || endpoint.includes("0.0.0.0");
+function shouldDefaultUseUniqueNullifiers(_connection) {
+  return true;
 }
 function toHex(bytes) {
   return Buffer.from(bytes).toString("hex");
@@ -5811,7 +5815,7 @@ async function ensureViewingKeyRegistered(options, onProgress, fallbackNk) {
   if (options.enforceViewingKeyRegistration === false) {
     return;
   }
-  const relayUrl = options.relayUrl?.replace(/\/$/, "");
+  const relayUrl = resolveRelayUrl(options.relayUrl);
   if (!relayUrl) {
     throw new Error("Viewing key registration is mandatory: relayUrl is required.");
   }
@@ -5882,12 +5886,12 @@ async function ensureViewingKeyRegistered(options, onProgress, fallbackNk) {
 }
 async function generateTransactionProof(inputs, onProgress) {
   onProgress?.(10);
-  const { wasmPath, zkeyPath } = await resolveTransactionCircuitFiles();
+  const { wasmPath: wasmInput, zkeyPath: zkeyInput } = await resolveTransactionCircuitFiles();
   onProgress?.(30);
   const { proof, publicSignals } = await snarkjs2.groth16.fullProve(
     inputs,
-    wasmPath,
-    zkeyPath
+    wasmInput,
+    zkeyInput
   );
   onProgress?.(100);
   return { proof, publicSignals };
@@ -6010,21 +6014,26 @@ function buildTransactInstruction(programId, payer, poolPDA, treasuryPDA, merkle
     { pubkey: import_web37.SystemProgram.programId, isSigner: false, isWritable: false }
     // 6. system_program
   ];
-  if (recipient) {
-    accounts.push({ pubkey: recipient, isSigner: false, isWritable: true });
-    if (enableRiskCheck) {
-      accounts.push({ pubkey: import_web37.SYSVAR_INSTRUCTIONS_PUBKEY, isSigner: false, isWritable: false });
-    }
-  } else if (enableRiskCheck) {
-    const instructionsSysvar = import_web37.SYSVAR_INSTRUCTIONS_PUBKEY;
-    accounts.push({ pubkey: instructionsSysvar, isSigner: false, isWritable: false });
-  }
   if (splAccounts) {
     accounts.push({ pubkey: splAccounts.vaultAuthority, isSigner: false, isWritable: false });
     accounts.push({ pubkey: splAccounts.poolVaultAta, isSigner: false, isWritable: true });
     accounts.push({ pubkey: splAccounts.tokenProgram, isSigner: false, isWritable: false });
     if (splAccounts.payerAta) {
+      if (enableRiskCheck) {
+        accounts.push({ pubkey: import_web37.SYSVAR_INSTRUCTIONS_PUBKEY, isSigner: false, isWritable: false });
+      }
       accounts.push({ pubkey: splAccounts.payerAta, isSigner: false, isWritable: true });
+    } else if (enableRiskCheck && !recipient) {
+      accounts.push({ pubkey: import_web37.SYSVAR_INSTRUCTIONS_PUBKEY, isSigner: false, isWritable: false });
+    }
+  } else {
+    if (recipient) {
+      accounts.push({ pubkey: recipient, isSigner: false, isWritable: true });
+      if (enableRiskCheck) {
+        accounts.push({ pubkey: import_web37.SYSVAR_INSTRUCTIONS_PUBKEY, isSigner: false, isWritable: false });
+      }
+    } else if (enableRiskCheck) {
+      accounts.push({ pubkey: import_web37.SYSVAR_INSTRUCTIONS_PUBKEY, isSigner: false, isWritable: false });
     }
   }
   return new import_web37.TransactionInstruction({
@@ -6140,13 +6149,7 @@ async function submitTransactionDirect(connection, programId, depositor, proofBy
   let riskQuoteIx = null;
   const isDeposit = recipient === void 0;
   const isSplPool = !mint.equals(NATIVE_SOL_MINT);
-  const riskCheckRequested = !!(riskOracleQueue || getRiskQuoteInstruction || riskQuoteUrl || rangeApiKey);
-  const riskCheckEnabled = !isSplPool && riskCheckRequested;
-  if (isSplPool && riskCheckRequested) {
-    onProgress?.(
-      "Skipping risk quote for SPL direct transaction path (not consumed by on-chain SPL transact handler)."
-    );
-  }
+  const riskCheckEnabled = true;
   if (isDeposit && riskCheckEnabled && !getRiskQuoteInstruction && !riskQuoteUrl && rangeApiKey) {
     onProgress?.("Fetching risk quote from Switchboard (SDK-internal)...");
     const result = await fetchRiskQuoteIx(connection, depositor.publicKey, rangeApiKey);
@@ -6216,11 +6219,12 @@ async function submitTransactionDirect(connection, programId, depositor, proofBy
     proofBytes,
     publicInputsBytes,
     recipient,
-    isDeposit && riskCheckEnabled,
+    (isDeposit || !recipient) && riskCheckEnabled,
     encryptedNoteBytes,
     splAccounts
   );
-  if (isDeposit && riskCheckEnabled && !riskQuoteIx) {
+  const isSend = !recipient && publicAmount === BigInt(0);
+  if ((isDeposit || isSend) && riskCheckEnabled && !riskQuoteIx) {
     if (getRiskQuoteInstruction) {
       onProgress?.("Fetching risk quote (custom)...");
       riskQuoteIx = await getRiskQuoteInstruction(depositor.publicKey);
@@ -6684,7 +6688,7 @@ async function transact(params, options) {
     onProofProgress,
     relayerFee = BigInt(0),
     relayer,
-    relayUrl,
+    relayUrl: relayUrlOverride,
     depositorKeypair,
     signTransaction: signTransaction2,
     depositorPublicKey,
@@ -6705,6 +6709,7 @@ async function transact(params, options) {
     enforceViewingKeyRegistration = true,
     useChainRootForProof = true
   } = options;
+  const relayUrl = resolveRelayUrl(relayUrlOverride);
   const useUniqueNullifiersEffective = useUniqueNullifiers ?? shouldDefaultUseUniqueNullifiers(connection);
   void enforceViewingKeyRegistration;
   const disableAutoRiskQuoteDerive = typeof process !== "undefined" && !!process.env && (process.env.CLOAK_DISABLE_RELAY_RISK_QUOTE_AUTO_DERIVE === "1" || process.env.CLOAK_DISABLE_RELAY_RISK_QUOTE_AUTO_DERIVE === "true");
@@ -6761,6 +6766,7 @@ async function transact(params, options) {
   const needsTreeForProof = paddedInputs.some(
     (utxo) => utxo.amount > BigInt(0) && utxo.index !== void 0
   );
+  const hasCachedTree = !!cachedMerkleTree && cachedMerkleTree.length > 0;
   let merkleTree = cachedMerkleTree ?? null;
   let treeState = null;
   const chainIndexingEnabled = options.useChainForMerkle === true || typeof process !== "undefined" && !!process.env && (process.env.CLOAK_BUILD_TREE_FROM_CHAIN === "true" || process.env.CLOAK_BUILD_TREE_FROM_CHAIN === "1");
@@ -6784,7 +6790,7 @@ async function transact(params, options) {
       treeState = await readMerkleTreeState(connection, pdas.merkleTree, forceRefresh, relayUrl, useChainRootForProof, mint);
     }
     const relaySyncTargetIndex = treeState && treeState.nextIndex > 0 ? Math.max(requiredRelayIndex, treeState.nextIndex - 1) : requiredRelayIndex;
-    if (needsTreeForProof && relayTreeDisabledForMint && relayUrl && !forceChainIndexing && (forceRefresh || !merkleTree)) {
+    if (needsTreeForProof && relayTreeDisabledForMint && relayUrl && !forceChainIndexing && (forceRefresh || !merkleTree) && !hasCachedTree) {
       if (!_relayMerkleFallbackNotifiedMints.has(relayMintKey)) {
         onProgress?.(`Using on-chain proof mode for ${relayMintKey} in this environment.`);
         _relayMerkleFallbackNotifiedMints.add(relayMintKey);
@@ -7596,14 +7602,40 @@ async function transact(params, options) {
       resultTree = merkleTree;
     }
   } else {
-    try {
-      const indexedCommitments = outputCommitments.map((c, i) => ({ c, idx: commitmentIndices[i], amount: paddedOutputs[i]?.amount ?? BigInt(0) })).filter((x) => x.idx >= 0 && x.amount > BigInt(0)).sort((a, b) => a.idx - b.idx);
-      const isContiguousFromZero = indexedCommitments.length > 0 && indexedCommitments.every((x, i) => x.idx === i);
-      if (isContiguousFromZero) {
-        const leaves = indexedCommitments.map((x) => x.c);
-        resultTree = await MerkleTree.create(32, leaves);
+    if (relayUrl) {
+      try {
+        const maxIdx = Math.max(...commitmentIndices);
+        if (maxIdx >= 0) {
+          const postTree = await buildMerkleTreeFromRelay(relayUrl, {
+            mint,
+            sync: true,
+            repair: true,
+            timeoutMs: 8e3,
+            maxRetries: 0,
+            waitForIndex: maxIdx
+          });
+          if (postTree && postTree.length > 0) {
+            const treeLenBefore = postTree.length;
+            const toInsert = outputCommitments.filter((_, i) => commitmentIndices[i] >= treeLenBefore);
+            if (toInsert.length > 0) {
+              postTree.bulkInsert(toInsert);
+            }
+            resultTree = postTree;
+          }
+        }
+      } catch {
+      }
+    }
+    if (!resultTree) {
+      try {
+        const indexedCommitments = outputCommitments.map((c, i) => ({ c, idx: commitmentIndices[i], amount: paddedOutputs[i]?.amount ?? BigInt(0) })).filter((x) => x.idx >= 0 && x.amount > BigInt(0)).sort((a, b) => a.idx - b.idx);
+        const isContiguousFromZero = indexedCommitments.length > 0 && indexedCommitments.every((x, i) => x.idx === i);
+        if (isContiguousFromZero) {
+          const leaves = indexedCommitments.map((x) => x.c);
+          resultTree = await MerkleTree.create(32, leaves);
+        }
+      } catch {
       }
-    } catch {
     }
   }
   return {
@@ -7655,9 +7687,37 @@ async function partialWithdraw(inputUtxos, recipient, withdrawAmount, options) {
   if (inputSum < withdrawAmount) {
     throw new Error(`Insufficient funds: have ${inputSum}, need ${withdrawAmount}`);
   }
-  const change = inputSum - withdrawAmount;
   const myKeypair = inputUtxos[0].keypair;
   const mint = inputUtxos[0].mintAddress;
+  let utxos = [...inputUtxos];
+  let cachedTree = options.cachedMerkleTree;
+  while (utxos.length > 2) {
+    options.onProgress?.(`Consolidating notes (${utxos.length} remaining)...`);
+    utxos.sort((a, b) => a.amount > b.amount ? 1 : a.amount < b.amount ? -1 : 0);
+    const [small1, small2, ...rest] = utxos;
+    const mergedAmount = small1.amount + small2.amount;
+    const mergedOutput = await createUtxo(mergedAmount, myKeypair, mint);
+    const mergeResult = await transact(
+      {
+        inputUtxos: [small1, small2],
+        outputUtxos: [mergedOutput],
+        externalAmount: BigInt(0)
+        // Shield-to-shield, no external movement
+      },
+      {
+        ...options,
+        cachedMerkleTree: cachedTree
+      }
+    );
+    cachedTree = mergeResult.merkleTree;
+    const consolidatedUtxo = mergeResult.outputUtxos?.[0] ?? mergedOutput;
+    if (mergeResult.commitmentIndices?.[0] >= 0) {
+      consolidatedUtxo.index = mergeResult.commitmentIndices[0];
+    }
+    utxos = [consolidatedUtxo, ...rest];
+  }
+  const finalInputSum = sumUtxoAmounts(utxos);
+  const change = finalInputSum - withdrawAmount;
   const outputUtxos = [];
   if (change > BigInt(0)) {
     const changeUtxo = await createUtxo(change, myKeypair, mint);
@@ -7665,13 +7725,15 @@ async function partialWithdraw(inputUtxos, recipient, withdrawAmount, options) {
   }
   return transact(
     {
-      inputUtxos,
+      inputUtxos: utxos,
       outputUtxos,
       recipient,
       externalAmount: -withdrawAmount
-      // Negative = withdraw
     },
-    options
+    {
+      ...options,
+      cachedMerkleTree: cachedTree
+    }
   );
 }
 async function fullWithdraw(inputUtxos, recipient, options) {
@@ -7699,6 +7761,10 @@ async function waitForSwapCompletion(relayUrl, requestId, onProgress, maxAttempt
           const detail = typeof json.data.error === "string" && json.data.error.length > 0 ? json.data.error : "likely refunded after timeout";
           throw new Error(`Swap execution cancelled: ${detail}`);
         }
+        if (status === "refunded") {
+          const detail = typeof json.data.error === "string" && json.data.error.length > 0 ? json.data.error : "Swap route unavailable \u2014 funds refunded as SOL to your wallet";
+          throw new Error(`Swap refunded: ${detail}`);
+        }
         if (swapPhase && swapPhase !== lastSwapPhase) {
           lastSwapPhase = swapPhase;
           if (swapPhase === "waiting_timeout") {
@@ -7711,7 +7777,7 @@ async function waitForSwapCompletion(relayUrl, requestId, onProgress, maxAttempt
       }
     } catch (e) {
       const msg = e.message ?? "";
-      if (msg.includes("Swap execution failed") || msg.includes("Swap execution cancelled") || msg.startsWith("Swap failed") || msg.toLowerCase().includes("cancelled")) {
+      if (msg.includes("Swap execution failed") || msg.includes("Swap execution cancelled") || msg.includes("Swap refunded") || msg.startsWith("Swap failed") || msg.toLowerCase().includes("cancelled") || msg.toLowerCase().includes("refunded")) {
         throw e;
       }
     }
@@ -7730,10 +7796,14 @@ async function waitForSwapCompletion(relayUrl, requestId, onProgress, maxAttempt
         const detail = typeof json.data.error === "string" && json.data.error.length > 0 ? json.data.error : "likely refunded after timeout";
         throw new Error(`Swap execution cancelled: ${detail}`);
       }
+      if (status === "refunded") {
+        const detail = typeof json.data.error === "string" && json.data.error.length > 0 ? json.data.error : "Swap route unavailable \u2014 funds refunded as SOL to your wallet";
+        throw new Error(`Swap refunded: ${detail}`);
+      }
     }
   } catch (e) {
     const msg = e.message ?? "";
-    if (msg.includes("Swap execution failed") || msg.includes("Swap execution cancelled") || msg.startsWith("Swap failed") || msg.toLowerCase().includes("cancelled")) {
+    if (msg.includes("Swap execution failed") || msg.includes("Swap execution cancelled") || msg.includes("Swap refunded") || msg.startsWith("Swap failed") || msg.toLowerCase().includes("cancelled") || msg.toLowerCase().includes("refunded")) {
       throw e;
     }
   }
@@ -7758,7 +7828,7 @@ async function swapUtxo(params, options) {
     useChainForMerkle,
     relayerFee = BigInt(0),
     relayer,
-    relayUrl,
+    relayUrl: relayUrlOverride,
     riskQuoteUrl,
     maxRootRetries = 40,
     // Increased to handle prolonged relay sync recovery under high concurrency
@@ -7767,6 +7837,7 @@ async function swapUtxo(params, options) {
     useUniqueNullifiers,
     useChainRootForProof = true
   } = options;
+  const relayUrl = resolveRelayUrl(relayUrlOverride);
   const useUniqueNullifiersEffective = useUniqueNullifiers ?? shouldDefaultUseUniqueNullifiers(connection);
   if (inputUtxos.length === 0) {
     throw new Error("At least one input UTXO required");
@@ -7821,6 +7892,7 @@ async function swapUtxo(params, options) {
   const useRelayMerkleByDefault = shouldUseRelayMerkleByDefault(connection);
   const relayMintKey = swapPoolMint.toBase58();
   let relayTreeDisabledForMint = _relayMerkleDisabledMints.has(relayMintKey) || !useRelayMerkleByDefault;
+  const hasCachedTree = !!cachedMerkleTree && cachedMerkleTree.length > 0;
   const requiredRelayIndex = paddedInputs.reduce((maxIndex, utxo) => {
     if (utxo.amount === BigInt(0) || utxo.index === void 0 || utxo.index < 0) {
       return maxIndex;
@@ -7837,7 +7909,7 @@ async function swapUtxo(params, options) {
       merkleState = await readMerkleTreeState(connection, pdas.merkleTree, forceRefresh, relayUrl, useChainRootForProof, swapPoolMint);
     }
     const relaySyncTargetIndex = merkleState && merkleState.nextIndex > 0 ? Math.max(requiredRelayIndex, merkleState.nextIndex - 1) : requiredRelayIndex;
-    if (needsTreeForProof && relayTreeDisabledForMint && relayUrl && !forceChainIndexing && (forceRefresh || !merkleTree)) {
+    if (needsTreeForProof && relayTreeDisabledForMint && relayUrl && !forceChainIndexing && (forceRefresh || !merkleTree) && !hasCachedTree) {
       if (!_relayMerkleFallbackNotifiedMints.has(relayMintKey)) {
         onProgress?.(`Using on-chain proof mode for ${relayMintKey} in this environment.`);
         _relayMerkleFallbackNotifiedMints.add(relayMintKey);

package/dist/index.d.cts

@@ -2843,7 +2843,10 @@ interface TransactOptions {
     relayerFee?: bigint;
     /** Relayer address for fee payment */
     relayer?: PublicKey;
-    /** Relay service URL for submitting transactions */
+    /**
+     * Relay URL override.
+     * Defaults to `https://api.cloak.ag` when omitted.
+     */
     relayUrl?: string;
     /** Keypair of the depositor (signs the deposit transaction) - for programmatic use */
     depositorKeypair?: Keypair;

package/dist/index.d.ts

@@ -2843,7 +2843,10 @@ interface TransactOptions {
     relayerFee?: bigint;
     /** Relayer address for fee payment */
     relayer?: PublicKey;
-    /** Relay service URL for submitting transactions */
+    /**
+     * Relay URL override.
+     * Defaults to `https://api.cloak.ag` when omitted.
+     */
     relayUrl?: string;
     /** Keypair of the depositor (signs the deposit transaction) - for programmatic use */
     depositorKeypair?: Keypair;

package/dist/index.js

@@ -1401,6 +1401,22 @@ var ErrorPatterns = [
       recoverable: true
     }
   },
+  {
+    patterns: [
+      "Swap refunded",
+      "swap refunded",
+      "funds refunded as SOL",
+      "funds were refunded",
+      "Swap timed out and funds were refunded"
+    ],
+    result: {
+      title: "Swap Refunded",
+      message: "No swap route was available. Your funds have been refunded as SOL to your wallet.",
+      category: "service",
+      suggestion: "Check your wallet balance \u2014 the SOL should already be there (minus the protocol fee). Try again with a different token or amount.",
+      recoverable: true
+    }
+  },
   {
     patterns: [
       "Failed to get quote",
@@ -2156,8 +2172,8 @@ var IS_REACT_NATIVE = typeof navigator !== "undefined" && navigator.product ===
 var IS_BROWSER = IS_REACT_NATIVE || typeof window !== "undefined" || typeof globalThis !== "undefined" && typeof globalThis.document !== "undefined";
 var DEFAULT_CIRCUITS_URL = "https://cloak-circuits.s3.us-east-1.amazonaws.com/circuits/0.1.0";
 var SKIP_CIRCUIT_VERIFY_ENV = typeof process !== "undefined" && process.env && process.env.CLOAK_SKIP_CIRCUIT_INTEGRITY_CHECK === "1";
-function isUrl(path2) {
-  return path2.startsWith("http://") || path2.startsWith("https://");
+function isUrl(path) {
+  return path.startsWith("http://") || path.startsWith("https://");
 }
 function resolveCircuitsUrl(circuitsPath2) {
   if (circuitsPath2.trim() !== "" && circuitsPath2.trim() !== DEFAULT_CIRCUITS_URL) {
@@ -2621,7 +2637,7 @@ function createSetLoadedAccountsDataSizeLimitInstruction(bytes) {
     data
   });
 }
-var CLOAK_PROGRAM_ID = new PublicKey4("c1oak6tetxYnNfvXKFkpn1d98FxtK7B68vBQLYQpWKp");
+var CLOAK_PROGRAM_ID = new PublicKey4("zh1eLd6rSphLejbFfJEneUwzHRfMKxgzrgkfwA6qRkW");
 var CLOAK_API_URL = "https://api.cloak.ag";
 var CloakSDK = class {
   /**
@@ -5113,56 +5129,39 @@ function chainNoteFromBase64(base64) {
 // src/core/transact.ts
 import { buildPoseidon as buildPoseidon3 } from "circomlibjs";
 import nacl4 from "tweetnacl";
-import * as path from "path";
-import { createHash } from "crypto";
-import { mkdir, writeFile } from "fs/promises";
-import { tmpdir } from "os";
+var IS_BROWSER2 = typeof window !== "undefined" || typeof globalThis.document !== "undefined";
 var DEFAULT_TRANSACTION_CIRCUITS_URL = "https://cloak-circuits.s3.us-east-1.amazonaws.com/circuits/0.1.0";
+var DEFAULT_CLOAK_RELAY_URL = "https://api.cloak.ag";
 function resolveDefaultTransactionCircuitsPath() {
   return DEFAULT_TRANSACTION_CIRCUITS_URL;
 }
 var circuitsPath = resolveDefaultTransactionCircuitsPath();
-function isHttpCircuitsPath(p) {
-  return p.startsWith("https://") || p.startsWith("http://");
-}
 var _remoteTxCircuitsCache = null;
 async function resolveTransactionCircuitFiles() {
   const base = circuitsPath;
-  const wasmRel = path.join("transaction_js", "transaction.wasm");
-  const zkeyRel = "transaction_final.zkey";
-  if (!isHttpCircuitsPath(base)) {
-    const root = base;
-    return {
-      wasmPath: path.join(root, wasmRel),
-      zkeyPath: path.join(root, zkeyRel)
-    };
-  }
   const baseNorm = base.endsWith("/") ? base : `${base}/`;
+  const wasmUrl = `${baseNorm}transaction_js/transaction.wasm`;
+  const zkeyUrl = `${baseNorm}transaction_final.zkey`;
+  if (IS_BROWSER2) {
+    return { wasmPath: wasmUrl, zkeyPath: zkeyUrl };
+  }
   if (_remoteTxCircuitsCache?.base === baseNorm) {
-    const { dir: dir2 } = _remoteTxCircuitsCache;
-    return {
-      wasmPath: path.join(dir2, "transaction.wasm"),
-      zkeyPath: path.join(dir2, "transaction_final.zkey")
-    };
+    return _remoteTxCircuitsCache.artifacts;
   }
-  const wasmUrl = new URL(wasmRel.split(path.sep).join("/"), baseNorm).toString();
-  const zkeyUrl = new URL(zkeyRel, baseNorm).toString();
-  const subdir = `cloak-tx-circuits-${createHash("sha256").update(baseNorm).digest("hex").slice(0, 16)}`;
-  const dir = path.join(tmpdir(), subdir);
-  await mkdir(dir, { recursive: true });
-  const wasmPath = path.join(dir, "transaction.wasm");
-  const zkeyPath = path.join(dir, "transaction_final.zkey");
-  const download = async (url, dest) => {
+  const fetchAsBuffer = async (url) => {
     const res = await fetch(url);
     if (!res.ok) {
       throw new Error(`Failed to fetch circuit artifact ${url}: ${res.status} ${res.statusText}`);
     }
-    await writeFile(dest, Buffer.from(await res.arrayBuffer()));
+    return new Uint8Array(await res.arrayBuffer());
   };
-  await download(wasmUrl, wasmPath);
-  await download(zkeyUrl, zkeyPath);
-  _remoteTxCircuitsCache = { base: baseNorm, dir };
-  return { wasmPath, zkeyPath };
+  const [wasmData, zkeyData] = await Promise.all([
+    fetchAsBuffer(wasmUrl),
+    fetchAsBuffer(zkeyUrl)
+  ]);
+  const artifacts = { wasmPath: wasmData, zkeyPath: zkeyData };
+  _remoteTxCircuitsCache = { base: baseNorm, artifacts };
+  return artifacts;
 }
 var _transactPaddingSaltCounter = 0;
 var _registeredViewingKeys = /* @__PURE__ */ new Set();
@@ -5256,6 +5255,12 @@ function deriveRelayUrlFromRiskQuoteUrl(riskQuoteUrl) {
   }
   return void 0;
 }
+function resolveRelayUrl(relayUrl) {
+  const trimmed = relayUrl?.trim();
+  if (trimmed === "") return void 0;
+  if (trimmed) return trimmed.replace(/\/$/, "");
+  return DEFAULT_CLOAK_RELAY_URL;
+}
 async function resolveAddressLookupTableAccounts(connection, relayUrl, altAddressesFromOptions, provided, onProgress) {
   if (provided && provided.length > 0) {
     return provided;
@@ -5353,9 +5358,8 @@ async function resolveChainNoteNk(options) {
   }
   return null;
 }
-function shouldDefaultUseUniqueNullifiers(connection) {
-  const endpoint = (connection.rpcEndpoint || "").toLowerCase();
-  return endpoint.includes("127.0.0.1") || endpoint.includes("localhost") || endpoint.includes("0.0.0.0");
+function shouldDefaultUseUniqueNullifiers(_connection) {
+  return true;
 }
 function toHex(bytes) {
   return Buffer.from(bytes).toString("hex");
@@ -5364,7 +5368,7 @@ async function ensureViewingKeyRegistered(options, onProgress, fallbackNk) {
   if (options.enforceViewingKeyRegistration === false) {
     return;
   }
-  const relayUrl = options.relayUrl?.replace(/\/$/, "");
+  const relayUrl = resolveRelayUrl(options.relayUrl);
   if (!relayUrl) {
     throw new Error("Viewing key registration is mandatory: relayUrl is required.");
   }
@@ -5435,12 +5439,12 @@ async function ensureViewingKeyRegistered(options, onProgress, fallbackNk) {
 }
 async function generateTransactionProof(inputs, onProgress) {
   onProgress?.(10);
-  const { wasmPath, zkeyPath } = await resolveTransactionCircuitFiles();
+  const { wasmPath: wasmInput, zkeyPath: zkeyInput } = await resolveTransactionCircuitFiles();
   onProgress?.(30);
   const { proof, publicSignals } = await snarkjs2.groth16.fullProve(
     inputs,
-    wasmPath,
-    zkeyPath
+    wasmInput,
+    zkeyInput
   );
   onProgress?.(100);
   return { proof, publicSignals };
@@ -5563,21 +5567,26 @@ function buildTransactInstruction(programId, payer, poolPDA, treasuryPDA, merkle
     { pubkey: SystemProgram2.programId, isSigner: false, isWritable: false }
     // 6. system_program
   ];
-  if (recipient) {
-    accounts.push({ pubkey: recipient, isSigner: false, isWritable: true });
-    if (enableRiskCheck) {
-      accounts.push({ pubkey: SYSVAR_INSTRUCTIONS_PUBKEY, isSigner: false, isWritable: false });
-    }
-  } else if (enableRiskCheck) {
-    const instructionsSysvar = SYSVAR_INSTRUCTIONS_PUBKEY;
-    accounts.push({ pubkey: instructionsSysvar, isSigner: false, isWritable: false });
-  }
   if (splAccounts) {
     accounts.push({ pubkey: splAccounts.vaultAuthority, isSigner: false, isWritable: false });
     accounts.push({ pubkey: splAccounts.poolVaultAta, isSigner: false, isWritable: true });
     accounts.push({ pubkey: splAccounts.tokenProgram, isSigner: false, isWritable: false });
     if (splAccounts.payerAta) {
+      if (enableRiskCheck) {
+        accounts.push({ pubkey: SYSVAR_INSTRUCTIONS_PUBKEY, isSigner: false, isWritable: false });
+      }
       accounts.push({ pubkey: splAccounts.payerAta, isSigner: false, isWritable: true });
+    } else if (enableRiskCheck && !recipient) {
+      accounts.push({ pubkey: SYSVAR_INSTRUCTIONS_PUBKEY, isSigner: false, isWritable: false });
+    }
+  } else {
+    if (recipient) {
+      accounts.push({ pubkey: recipient, isSigner: false, isWritable: true });
+      if (enableRiskCheck) {
+        accounts.push({ pubkey: SYSVAR_INSTRUCTIONS_PUBKEY, isSigner: false, isWritable: false });
+      }
+    } else if (enableRiskCheck) {
+      accounts.push({ pubkey: SYSVAR_INSTRUCTIONS_PUBKEY, isSigner: false, isWritable: false });
     }
   }
   return new TransactionInstruction3({
@@ -5693,13 +5702,7 @@ async function submitTransactionDirect(connection, programId, depositor, proofBy
   let riskQuoteIx = null;
   const isDeposit = recipient === void 0;
   const isSplPool = !mint.equals(NATIVE_SOL_MINT);
-  const riskCheckRequested = !!(riskOracleQueue || getRiskQuoteInstruction || riskQuoteUrl || rangeApiKey);
-  const riskCheckEnabled = !isSplPool && riskCheckRequested;
-  if (isSplPool && riskCheckRequested) {
-    onProgress?.(
-      "Skipping risk quote for SPL direct transaction path (not consumed by on-chain SPL transact handler)."
-    );
-  }
+  const riskCheckEnabled = true;
   if (isDeposit && riskCheckEnabled && !getRiskQuoteInstruction && !riskQuoteUrl && rangeApiKey) {
     onProgress?.("Fetching risk quote from Switchboard (SDK-internal)...");
     const result = await fetchRiskQuoteIx(connection, depositor.publicKey, rangeApiKey);
@@ -5769,11 +5772,12 @@ async function submitTransactionDirect(connection, programId, depositor, proofBy
     proofBytes,
     publicInputsBytes,
     recipient,
-    isDeposit && riskCheckEnabled,
+    (isDeposit || !recipient) && riskCheckEnabled,
     encryptedNoteBytes,
     splAccounts
   );
-  if (isDeposit && riskCheckEnabled && !riskQuoteIx) {
+  const isSend = !recipient && publicAmount === BigInt(0);
+  if ((isDeposit || isSend) && riskCheckEnabled && !riskQuoteIx) {
     if (getRiskQuoteInstruction) {
       onProgress?.("Fetching risk quote (custom)...");
       riskQuoteIx = await getRiskQuoteInstruction(depositor.publicKey);
@@ -6237,7 +6241,7 @@ async function transact(params, options) {
     onProofProgress,
     relayerFee = BigInt(0),
     relayer,
-    relayUrl,
+    relayUrl: relayUrlOverride,
     depositorKeypair,
     signTransaction: signTransaction2,
     depositorPublicKey,
@@ -6258,6 +6262,7 @@ async function transact(params, options) {
     enforceViewingKeyRegistration = true,
     useChainRootForProof = true
   } = options;
+  const relayUrl = resolveRelayUrl(relayUrlOverride);
   const useUniqueNullifiersEffective = useUniqueNullifiers ?? shouldDefaultUseUniqueNullifiers(connection);
   void enforceViewingKeyRegistration;
   const disableAutoRiskQuoteDerive = typeof process !== "undefined" && !!process.env && (process.env.CLOAK_DISABLE_RELAY_RISK_QUOTE_AUTO_DERIVE === "1" || process.env.CLOAK_DISABLE_RELAY_RISK_QUOTE_AUTO_DERIVE === "true");
@@ -6314,6 +6319,7 @@ async function transact(params, options) {
   const needsTreeForProof = paddedInputs.some(
     (utxo) => utxo.amount > BigInt(0) && utxo.index !== void 0
   );
+  const hasCachedTree = !!cachedMerkleTree && cachedMerkleTree.length > 0;
   let merkleTree = cachedMerkleTree ?? null;
   let treeState = null;
   const chainIndexingEnabled = options.useChainForMerkle === true || typeof process !== "undefined" && !!process.env && (process.env.CLOAK_BUILD_TREE_FROM_CHAIN === "true" || process.env.CLOAK_BUILD_TREE_FROM_CHAIN === "1");
@@ -6337,7 +6343,7 @@ async function transact(params, options) {
       treeState = await readMerkleTreeState(connection, pdas.merkleTree, forceRefresh, relayUrl, useChainRootForProof, mint);
     }
     const relaySyncTargetIndex = treeState && treeState.nextIndex > 0 ? Math.max(requiredRelayIndex, treeState.nextIndex - 1) : requiredRelayIndex;
-    if (needsTreeForProof && relayTreeDisabledForMint && relayUrl && !forceChainIndexing && (forceRefresh || !merkleTree)) {
+    if (needsTreeForProof && relayTreeDisabledForMint && relayUrl && !forceChainIndexing && (forceRefresh || !merkleTree) && !hasCachedTree) {
       if (!_relayMerkleFallbackNotifiedMints.has(relayMintKey)) {
         onProgress?.(`Using on-chain proof mode for ${relayMintKey} in this environment.`);
         _relayMerkleFallbackNotifiedMints.add(relayMintKey);
@@ -7149,14 +7155,40 @@ async function transact(params, options) {
       resultTree = merkleTree;
     }
   } else {
-    try {
-      const indexedCommitments = outputCommitments.map((c, i) => ({ c, idx: commitmentIndices[i], amount: paddedOutputs[i]?.amount ?? BigInt(0) })).filter((x) => x.idx >= 0 && x.amount > BigInt(0)).sort((a, b) => a.idx - b.idx);
-      const isContiguousFromZero = indexedCommitments.length > 0 && indexedCommitments.every((x, i) => x.idx === i);
-      if (isContiguousFromZero) {
-        const leaves = indexedCommitments.map((x) => x.c);
-        resultTree = await MerkleTree.create(32, leaves);
+    if (relayUrl) {
+      try {
+        const maxIdx = Math.max(...commitmentIndices);
+        if (maxIdx >= 0) {
+          const postTree = await buildMerkleTreeFromRelay(relayUrl, {
+            mint,
+            sync: true,
+            repair: true,
+            timeoutMs: 8e3,
+            maxRetries: 0,
+            waitForIndex: maxIdx
+          });
+          if (postTree && postTree.length > 0) {
+            const treeLenBefore = postTree.length;
+            const toInsert = outputCommitments.filter((_, i) => commitmentIndices[i] >= treeLenBefore);
+            if (toInsert.length > 0) {
+              postTree.bulkInsert(toInsert);
+            }
+            resultTree = postTree;
+          }
+        }
+      } catch {
+      }
+    }
+    if (!resultTree) {
+      try {
+        const indexedCommitments = outputCommitments.map((c, i) => ({ c, idx: commitmentIndices[i], amount: paddedOutputs[i]?.amount ?? BigInt(0) })).filter((x) => x.idx >= 0 && x.amount > BigInt(0)).sort((a, b) => a.idx - b.idx);
+        const isContiguousFromZero = indexedCommitments.length > 0 && indexedCommitments.every((x, i) => x.idx === i);
+        if (isContiguousFromZero) {
+          const leaves = indexedCommitments.map((x) => x.c);
+          resultTree = await MerkleTree.create(32, leaves);
+        }
+      } catch {
       }
-    } catch {
     }
   }
   return {
@@ -7208,9 +7240,37 @@ async function partialWithdraw(inputUtxos, recipient, withdrawAmount, options) {
   if (inputSum < withdrawAmount) {
     throw new Error(`Insufficient funds: have ${inputSum}, need ${withdrawAmount}`);
   }
-  const change = inputSum - withdrawAmount;
   const myKeypair = inputUtxos[0].keypair;
   const mint = inputUtxos[0].mintAddress;
+  let utxos = [...inputUtxos];
+  let cachedTree = options.cachedMerkleTree;
+  while (utxos.length > 2) {
+    options.onProgress?.(`Consolidating notes (${utxos.length} remaining)...`);
+    utxos.sort((a, b) => a.amount > b.amount ? 1 : a.amount < b.amount ? -1 : 0);
+    const [small1, small2, ...rest] = utxos;
+    const mergedAmount = small1.amount + small2.amount;
+    const mergedOutput = await createUtxo(mergedAmount, myKeypair, mint);
+    const mergeResult = await transact(
+      {
+        inputUtxos: [small1, small2],
+        outputUtxos: [mergedOutput],
+        externalAmount: BigInt(0)
+        // Shield-to-shield, no external movement
+      },
+      {
+        ...options,
+        cachedMerkleTree: cachedTree
+      }
+    );
+    cachedTree = mergeResult.merkleTree;
+    const consolidatedUtxo = mergeResult.outputUtxos?.[0] ?? mergedOutput;
+    if (mergeResult.commitmentIndices?.[0] >= 0) {
+      consolidatedUtxo.index = mergeResult.commitmentIndices[0];
+    }
+    utxos = [consolidatedUtxo, ...rest];
+  }
+  const finalInputSum = sumUtxoAmounts(utxos);
+  const change = finalInputSum - withdrawAmount;
   const outputUtxos = [];
   if (change > BigInt(0)) {
     const changeUtxo = await createUtxo(change, myKeypair, mint);
@@ -7218,13 +7278,15 @@ async function partialWithdraw(inputUtxos, recipient, withdrawAmount, options) {
   }
   return transact(
     {
-      inputUtxos,
+      inputUtxos: utxos,
       outputUtxos,
       recipient,
       externalAmount: -withdrawAmount
-      // Negative = withdraw
     },
-    options
+    {
+      ...options,
+      cachedMerkleTree: cachedTree
+    }
   );
 }
 async function fullWithdraw(inputUtxos, recipient, options) {
@@ -7252,6 +7314,10 @@ async function waitForSwapCompletion(relayUrl, requestId, onProgress, maxAttempt
           const detail = typeof json.data.error === "string" && json.data.error.length > 0 ? json.data.error : "likely refunded after timeout";
           throw new Error(`Swap execution cancelled: ${detail}`);
         }
+        if (status === "refunded") {
+          const detail = typeof json.data.error === "string" && json.data.error.length > 0 ? json.data.error : "Swap route unavailable \u2014 funds refunded as SOL to your wallet";
+          throw new Error(`Swap refunded: ${detail}`);
+        }
         if (swapPhase && swapPhase !== lastSwapPhase) {
           lastSwapPhase = swapPhase;
           if (swapPhase === "waiting_timeout") {
@@ -7264,7 +7330,7 @@ async function waitForSwapCompletion(relayUrl, requestId, onProgress, maxAttempt
       }
     } catch (e) {
       const msg = e.message ?? "";
-      if (msg.includes("Swap execution failed") || msg.includes("Swap execution cancelled") || msg.startsWith("Swap failed") || msg.toLowerCase().includes("cancelled")) {
+      if (msg.includes("Swap execution failed") || msg.includes("Swap execution cancelled") || msg.includes("Swap refunded") || msg.startsWith("Swap failed") || msg.toLowerCase().includes("cancelled") || msg.toLowerCase().includes("refunded")) {
         throw e;
       }
     }
@@ -7283,10 +7349,14 @@ async function waitForSwapCompletion(relayUrl, requestId, onProgress, maxAttempt
         const detail = typeof json.data.error === "string" && json.data.error.length > 0 ? json.data.error : "likely refunded after timeout";
         throw new Error(`Swap execution cancelled: ${detail}`);
       }
+      if (status === "refunded") {
+        const detail = typeof json.data.error === "string" && json.data.error.length > 0 ? json.data.error : "Swap route unavailable \u2014 funds refunded as SOL to your wallet";
+        throw new Error(`Swap refunded: ${detail}`);
+      }
     }
   } catch (e) {
     const msg = e.message ?? "";
-    if (msg.includes("Swap execution failed") || msg.includes("Swap execution cancelled") || msg.startsWith("Swap failed") || msg.toLowerCase().includes("cancelled")) {
+    if (msg.includes("Swap execution failed") || msg.includes("Swap execution cancelled") || msg.includes("Swap refunded") || msg.startsWith("Swap failed") || msg.toLowerCase().includes("cancelled") || msg.toLowerCase().includes("refunded")) {
       throw e;
     }
   }
@@ -7311,7 +7381,7 @@ async function swapUtxo(params, options) {
     useChainForMerkle,
     relayerFee = BigInt(0),
     relayer,
-    relayUrl,
+    relayUrl: relayUrlOverride,
     riskQuoteUrl,
     maxRootRetries = 40,
     // Increased to handle prolonged relay sync recovery under high concurrency
@@ -7320,6 +7390,7 @@ async function swapUtxo(params, options) {
     useUniqueNullifiers,
     useChainRootForProof = true
   } = options;
+  const relayUrl = resolveRelayUrl(relayUrlOverride);
   const useUniqueNullifiersEffective = useUniqueNullifiers ?? shouldDefaultUseUniqueNullifiers(connection);
   if (inputUtxos.length === 0) {
     throw new Error("At least one input UTXO required");
@@ -7374,6 +7445,7 @@ async function swapUtxo(params, options) {
   const useRelayMerkleByDefault = shouldUseRelayMerkleByDefault(connection);
   const relayMintKey = swapPoolMint.toBase58();
   let relayTreeDisabledForMint = _relayMerkleDisabledMints.has(relayMintKey) || !useRelayMerkleByDefault;
+  const hasCachedTree = !!cachedMerkleTree && cachedMerkleTree.length > 0;
   const requiredRelayIndex = paddedInputs.reduce((maxIndex, utxo) => {
     if (utxo.amount === BigInt(0) || utxo.index === void 0 || utxo.index < 0) {
       return maxIndex;
@@ -7390,7 +7462,7 @@ async function swapUtxo(params, options) {
       merkleState = await readMerkleTreeState(connection, pdas.merkleTree, forceRefresh, relayUrl, useChainRootForProof, swapPoolMint);
     }
     const relaySyncTargetIndex = merkleState && merkleState.nextIndex > 0 ? Math.max(requiredRelayIndex, merkleState.nextIndex - 1) : requiredRelayIndex;
-    if (needsTreeForProof && relayTreeDisabledForMint && relayUrl && !forceChainIndexing && (forceRefresh || !merkleTree)) {
+    if (needsTreeForProof && relayTreeDisabledForMint && relayUrl && !forceChainIndexing && (forceRefresh || !merkleTree) && !hasCachedTree) {
       if (!_relayMerkleFallbackNotifiedMints.has(relayMintKey)) {
         onProgress?.(`Using on-chain proof mode for ${relayMintKey} in this environment.`);
         _relayMerkleFallbackNotifiedMints.add(relayMintKey);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cloak.dev/sdk",
   "description": "TypeScript SDK for Cloak",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -21,6 +21,7 @@
     "test:watch": "NODE_OPTIONS=--experimental-vm-modules jest --watch",
     "test:coverage": "NODE_OPTIONS=--experimental-vm-modules jest --coverage",
     "test:verbose": "NODE_OPTIONS=--experimental-vm-modules jest --verbose",
+    "prepare": "npm run build",
     "prepublishOnly": "npm run build",
     "example:fast-send": "tsx examples/fast-send.ts",
     "example:fast-usdc-send": "tsx examples/fast-usdc-send.ts",