@continuumdao/ctm-mpc-defi 0.2.59 → 0.2.61

package/dist/protocols/evm/railgun/index.js

@@ -1,6 +1,6 @@
-import { getAddress, parseAbi, zeroAddress, encodeFunctionData, defineChain, createPublicClient, parseGwei, serializeTransaction, keccak256, hashMessage, stringToHex, http } from 'viem';
+import { getAddress, parseAbi, zeroAddress, keccak256, hashMessage, recoverAddress, encodeFunctionData, defineChain, createPublicClient, parseGwei, serializeTransaction, stringToHex, http } from 'viem';
 import { fetchChainFeeParams, gasLimitFromEstimateAndChainConfig, gweiToDecimalString, proposalTxParamsToFeeSnapshot, alignEip1559FeesWithLatestBase, getClientIdFromKeyGenResult } from '@continuumdao/continuum-node-sdk';
-import { TXIDVersion, calculateGasPrice, ChainType, EVMGasType, RailgunWalletBalanceBucket } from '@railgun-community/shared-models';
+import { TXIDVersion, RailgunWalletBalanceBucket, ChainType, EVMGasType, getEVMGasTypeForTransaction, calculateGasPrice, NETWORK_CONFIG } from '@railgun-community/shared-models';
 
 // src/core/registry.ts
 var modules = [];
@@ -540,11 +540,44 @@ async function buildEvmMultisignBatch(args) {
   return result;
 }
 
+// src/protocols/evm/railgun/data-dir.ts
+var RAILGUN_CONTAINER_DATA_DIR = "/app/railgun_data";
+function railgunDataRoot() {
+  if (typeof process === "undefined") return "";
+  const fromEnv = process.env.RAILGUN_DATA_DIR?.trim() ?? "";
+  if (fromEnv) return fromEnv;
+  if (process.versions?.node && process.env.MCP_HTTP_PORT?.trim() && process.cwd() === "/app") {
+    return RAILGUN_CONTAINER_DATA_DIR;
+  }
+  return "";
+}
+async function resolveRailgunDataRoot() {
+  return railgunDataRoot();
+}
+function safeKeyGenFolderName(keyGenId) {
+  const name = keyGenId.trim();
+  if (!/^[A-Za-z0-9_-]{1,80}$/.test(name)) {
+    throw new Error("KeyGen id cannot be used as a Railgun data folder name.");
+  }
+  return name;
+}
+function under(root, ...parts) {
+  return [root.replace(/\/+$/, ""), ...parts].join("/");
+}
+function railgunEnginePath(root) {
+  return under(root, "engine");
+}
+function railgunArtifactPath(root) {
+  return under(root, "artifacts");
+}
+function railgunKeyGenWalletPath(root, keyGenId) {
+  return under(root, "keygens", safeKeyGenFolderName(keyGenId), "wallet.json");
+}
+
 // src/protocols/evm/railgun/engine.ts
 var artifacts = /* @__PURE__ */ new Map();
 var started = false;
 var loadedProviders = /* @__PURE__ */ new Set();
-var lastEngineError = "";
 function errorChain(err) {
   const parts = [];
   let current = err;
@@ -559,24 +592,72 @@ function errorChain(err) {
   }
   return parts.join(": ");
 }
-function latestRailgunEngineError() {
-  return lastEngineError;
-}
 var POI_NODE_URLS = ["https://ppoi.fdi.network"];
 async function walletModule() {
   return await import('@railgun-community/wallet');
 }
-var artifactStore = {
-  async get(path) {
-    return artifacts.get(path) ?? null;
-  },
-  async store(_dir, path, item) {
-    artifacts.set(path, item);
-  },
-  async exists(path) {
-    return artifacts.has(path);
+function artifactFile(root, itemPath) {
+  const relative = itemPath.replace(/^\/+/, "");
+  if (!relative || relative.split("/").some((part) => part === ".." || part === "")) {
+    throw new Error("Railgun artifact path is not valid.");
   }
-};
+  return `${railgunArtifactPath(root)}/${relative}`;
+}
+function memoryArtifactStore() {
+  return {
+    async get(path) {
+      return artifacts.get(path) ?? null;
+    },
+    async store(_dir, path, item) {
+      artifacts.set(path, item);
+    },
+    async exists(path) {
+      return artifacts.has(path);
+    }
+  };
+}
+function diskArtifactStore(root) {
+  const load = new Function("id", "return import(id)");
+  return {
+    async get(itemPath) {
+      const fs = await load("node:fs/promises");
+      try {
+        return await fs.readFile(artifactFile(root, itemPath));
+      } catch {
+        return null;
+      }
+    },
+    async store(_dir, itemPath, item) {
+      const fs = await load("node:fs/promises");
+      const file = artifactFile(root, itemPath);
+      await fs.mkdir(file.slice(0, file.lastIndexOf("/")), { recursive: true });
+      await fs.writeFile(file, item);
+    },
+    async exists(itemPath) {
+      const fs = await load("node:fs/promises");
+      try {
+        await fs.access(artifactFile(root, itemPath));
+        return true;
+      } catch {
+        return false;
+      }
+    }
+  };
+}
+async function railgunDatabase(root) {
+  if (!root) {
+    const memdown = (await import('memdown')).default;
+    return new memdown();
+  }
+  const load = new Function("id", "return import(id)");
+  const fs = await load("node:fs/promises");
+  const engineDir = railgunEnginePath(root);
+  await fs.mkdir(engineDir, { recursive: true });
+  await fs.mkdir(railgunArtifactPath(root), { recursive: true });
+  const leveldownModule = await load("leveldown");
+  const open = leveldownModule.default ?? leveldownModule;
+  return open(engineDir);
+}
 async function attachEngineErrorLogger() {
   if (typeof window !== "undefined") return;
   if (typeof process === "undefined" || !process.versions?.node) return;
@@ -589,21 +670,39 @@ async function attachEngineErrorLogger() {
   setLoggers(
     () => void 0,
     (err) => {
-      lastEngineError = errorChain(err);
+      errorChain(err);
     }
   );
 }
+async function attachSnarkJsGroth16() {
+  if (typeof window !== "undefined") return;
+  if (typeof process === "undefined" || !process.versions?.node) return;
+  const load = new Function("id", "return import(id)");
+  const nodeModule = await load("node:module");
+  const nodePath = await load("node:path");
+  const require2 = nodeModule.createRequire(import.meta.url);
+  const walletEntry = require2.resolve("@railgun-community/wallet");
+  const { getProver } = require2(nodePath.join(nodePath.dirname(walletEntry), "services/railgun/core/prover.js"));
+  const snark = require2("snarkjs");
+  const groth16 = snark.groth16;
+  if (!groth16 || typeof groth16.fullProve !== "function") {
+    throw new Error("snarkjs groth16 prover is missing.");
+  }
+  getProver().setSnarkJSGroth16(groth16);
+}
 async function ensureRailgunEngine() {
   if (started) return;
   const wallet = await walletModule();
   await attachEngineErrorLogger();
-  const memdown = (await import('memdown')).default;
+  const root = await resolveRailgunDataRoot();
+  const files = root ? diskArtifactStore(root) : memoryArtifactStore();
   const store = new wallet.ArtifactStore(
-    (path) => artifactStore.get(path),
-    (dir, path, item) => artifactStore.store(dir, path, item),
-    (path) => artifactStore.exists(path)
+    (path) => files.get(path),
+    (dir, path, item) => files.store(dir, path, item),
+    (path) => files.exists(path)
   );
-  await wallet.startRailgunEngine("continuum", new memdown(), true, store, false, false, POI_NODE_URLS, [], false);
+  await wallet.startRailgunEngine("continuum", await railgunDatabase(root), true, store, false, false, POI_NODE_URLS, [], false);
+  await attachSnarkJsGroth16();
   started = true;
 }
 async function ensureRailgunProvider(chainId, rpcUrl) {
@@ -625,21 +724,80 @@ async function ensureRailgunProvider(chainId, rpcUrl) {
   }
   return networkName;
 }
+var RAILGUN_TRANSFER_GAS_ESTIMATE = 2900000n;
+var RAILGUN_UNSHIELD_GAS_ESTIMATE = 3400000n;
+function weiFromGwei(gwei, fallback = 1) {
+  return BigInt(Math.round(Number(gwei ?? fallback) * 1e9));
+}
 function railgunGasDetails(chainDetail, gasEstimate) {
   if (chainDetail.legacy) {
     return {
       evmGasType: EVMGasType.Type0,
       gasEstimate,
-      gasPrice: BigInt(Math.round(Number(chainDetail.gasPrice ?? 1) * 1e9))
+      gasPrice: weiFromGwei(chainDetail.gasPrice)
     };
   }
   return {
     evmGasType: EVMGasType.Type2,
     gasEstimate,
-    maxFeePerGas: BigInt(Math.round(Number(chainDetail.baseFee ?? 1) * 1e9)),
-    maxPriorityFeePerGas: BigInt(Math.round(Number(chainDetail.priorityFee ?? 1) * 1e9))
+    maxFeePerGas: weiFromGwei(chainDetail.baseFee),
+    maxPriorityFeePerGas: weiFromGwei(chainDetail.priorityFee)
+  };
+}
+function railgunBroadcasterGasDetails(networkName, chainDetail, gasEstimate) {
+  const evmGasType = getEVMGasTypeForTransaction(networkName, false);
+  if (evmGasType === EVMGasType.Type2 || evmGasType === EVMGasType.Type4) {
+    return {
+      evmGasType,
+      gasEstimate,
+      maxFeePerGas: weiFromGwei(chainDetail.baseFee),
+      maxPriorityFeePerGas: weiFromGwei(chainDetail.priorityFee)
+    };
+  }
+  const gasPrice = evmGasType === EVMGasType.Type0 || chainDetail.legacy ? weiFromGwei(chainDetail.gasPrice) : weiFromGwei(chainDetail.baseFee) + weiFromGwei(chainDetail.priorityFee);
+  return { evmGasType, gasEstimate, gasPrice };
+}
+function gweiFromWei(wei) {
+  return Number(wei) / 1e9;
+}
+function chainDetailWithFetchedGas(chainDetail, live) {
+  if (chainDetail.legacy) {
+    if (chainDetail.gasPrice != null && chainDetail.gasPrice > 0) return chainDetail;
+    if (live.gasPriceWei == null) return chainDetail;
+    return { ...chainDetail, gasPrice: gweiFromWei(live.gasPriceWei) };
+  }
+  if (chainDetail.baseFee != null && chainDetail.baseFee > 0) return chainDetail;
+  return {
+    ...chainDetail,
+    baseFee: live.baseFeeWei != null ? gweiFromWei(live.baseFeeWei) : chainDetail.baseFee,
+    priorityFee: chainDetail.priorityFee != null && chainDetail.priorityFee > 0 ? chainDetail.priorityFee : live.priorityFeeWei != null ? gweiFromWei(live.priorityFeeWei) : chainDetail.priorityFee
   };
 }
+async function chainDetailWithLiveGas(rpcUrl, chainDetail) {
+  const needsLive = chainDetail.legacy ? chainDetail.gasPrice == null || chainDetail.gasPrice <= 0 : chainDetail.baseFee == null || chainDetail.baseFee <= 0;
+  if (!needsLive) return chainDetail;
+  const client = createPublicClient({ transport: defiEvmTransport(rpcUrl) });
+  if (chainDetail.legacy) {
+    const gasPriceWei = await client.getGasPrice();
+    return chainDetailWithFetchedGas(chainDetail, { gasPriceWei });
+  }
+  const block = await client.getBlock({ blockTag: "latest" });
+  let priorityFeeWei = 0n;
+  try {
+    priorityFeeWei = await client.estimateMaxPriorityFeePerGas();
+  } catch {
+    priorityFeeWei = 1000000000n;
+  }
+  return chainDetailWithFetchedGas(chainDetail, {
+    baseFeeWei: block.baseFeePerGas ?? 0n,
+    priorityFeeWei
+  });
+}
+function broadcasterTokenFee(feePerUnitGas, gasDetails) {
+  const price = gasDetails.evmGasType === EVMGasType.Type2 || gasDetails.evmGasType === EVMGasType.Type4 ? gasDetails.maxFeePerGas : gasDetails.gasPrice;
+  const maximumGas = gasDetails.gasEstimate * 12000n / 10000n * price;
+  return feePerUnitGas * maximumGas / 10n ** 18n;
+}
 
 // src/protocols/evm/railgun/shield.ts
 var erc20Abi = parseAbi([
@@ -659,6 +817,42 @@ async function shieldSignatureMessage() {
   const wallet = await import('@railgun-community/wallet');
   return wallet.getShieldPrivateKeySignatureMessage();
 }
+async function shieldPrivateKeyFromSignature(signature, executorAddress) {
+  return keccak256(await canonicalRailgunShieldSignature(signature, executorAddress));
+}
+async function canonicalRailgunShieldSignature(signature, executorAddress) {
+  const body = signature.trim().replace(/^0x/i, "").toLowerCase();
+  if (!/^[0-9a-f]+$/.test(body) || body.length % 2 !== 0) {
+    throw new Error("Shield-key signature must be hex.");
+  }
+  const rs = body.length === 130 ? body.slice(0, 128) : body;
+  if (rs.length !== 128) {
+    throw new Error("Shield-key signature must be the 65-byte personal_sign of RAILGUN_SHIELD.");
+  }
+  const stated = body.length === 130 ? body.slice(128) : "";
+  if (!executorAddress) {
+    if (stated === "00") return `0x${rs}1b`;
+    if (stated === "01") return `0x${rs}1c`;
+    if (body.length === 130) return `0x${body}`;
+    throw new Error("Shield-key signature must be the 65-byte personal_sign of RAILGUN_SHIELD.");
+  }
+  const preferred = stated === "01" || stated === "1c" ? ["1c", "1b"] : ["1b", "1c"];
+  const hash = hashMessage("RAILGUN_SHIELD");
+  const executor = getAddress(executorAddress).toLowerCase();
+  for (const v of preferred) {
+    const candidate = `0x${rs}${v}`;
+    try {
+      const recovered = await recoverAddress({ hash, signature: candidate });
+      if (recovered.toLowerCase() === executor) return candidate;
+    } catch {
+      continue;
+    }
+  }
+  if (body.length === 130 && stated !== "00" && stated !== "01" && stated !== "1b" && stated !== "1c") {
+    return `0x${body}`;
+  }
+  throw new Error("Shield-key signature does not recover to this KeyGen address.");
+}
 function personalSignBody(args, message) {
   const executor = getAddress(args.executorAddress);
   const digest = hashMessage(message);
@@ -748,6 +942,7 @@ async function buildEvmMultisignBodyRailgunShield(args) {
   const amount = BigInt(args.amountWei);
   if (amount <= 0n) throw new Error("Amount must be greater than zero.");
   const executor = getAddress(args.executorAddress);
+  const shieldPrivateKey = await shieldPrivateKeyFromSignature(signature, executor);
   const spender = getAddress(network.proxyContract);
   const rpcUrl = args.rpcUrl.trim();
   if (!rpcUrl) throw new Error("rpcUrl is required.");
@@ -790,7 +985,7 @@ async function buildEvmMultisignBodyRailgunShield(args) {
   const populated = await populate(
     TXIDVersion.V2_PoseidonMerkle,
     networkName,
-    signature,
+    shieldPrivateKey,
     [{ tokenAddress, amount, recipientAddress: args.railgunAddress.trim() }],
     [],
     railgunGasDetails(args.chainDetail, 1200000n)
@@ -825,6 +1020,105 @@ async function buildEvmMultisignBodyRailgunShield(args) {
     })
   });
 }
+
+// src/chains/evm/coingecko.ts
+var COINGECKO_PLATFORM_BY_CHAIN_ID = {
+  "1": "ethereum",
+  "10": "optimistic-ethereum",
+  "30": "rootstock",
+  "56": "binance-smart-chain",
+  "100": "xdai",
+  "137": "polygon-pos",
+  "146": "sonic",
+  "169": "manta-pacific",
+  "196": "x-layer",
+  "204": "op-bnb",
+  "239": "tac",
+  "250": "fantom",
+  "252": "fraxtal",
+  "288": "boba",
+  "324": "zk-sync-era",
+  "480": "world-chain",
+  "999": "hyperevm",
+  "1088": "metis-andromeda",
+  "1101": "polygon-zkevm",
+  "1116": "core",
+  "1135": "lisk",
+  "130": "unichain",
+  "1868": "soneium",
+  "1923": "swellchain",
+  "2222": "kava",
+  "2818": "morph-l2",
+  "34443": "mode",
+  "42161": "arbitrum-one",
+  "42220": "celo",
+  "43114": "avalanche",
+  "4663": "robinhood",
+  "5042": "arc",
+  "48900": "zircuit",
+  "5000": "mantle",
+  "534352": "scroll",
+  "57073": "ink",
+  "59144": "linea",
+  "60808": "bob-network",
+  "80084": "berachain",
+  "80094": "berachain",
+  "81457": "blast",
+  "8453": "base",
+  "9745": "plasma",
+  "167000": "taiko",
+  "7777777": "zora"
+};
+function coingeckoPlatformForChainId(chainId) {
+  return COINGECKO_PLATFORM_BY_CHAIN_ID[String(chainId).trim()];
+}
+
+// src/protocols/evm/railgun/broadcaster-choice.ts
+var FEE_RATIO_ONE_TO_ONE_MILLI = 1e3;
+function feeRatioMilli(feePerUnitGas, tokenDecimals, tokenUsd, nativeUsd) {
+  if (!Number.isInteger(tokenDecimals) || tokenDecimals < 0 || tokenDecimals > 36) return null;
+  if (!(tokenUsd > 0) || !(nativeUsd > 0) || !Number.isFinite(tokenUsd) || !Number.isFinite(nativeUsd)) return null;
+  const tokenMicro = BigInt(Math.round(tokenUsd * 1e6));
+  const nativeMicro = BigInt(Math.round(nativeUsd * 1e6));
+  if (tokenMicro <= 0n || nativeMicro <= 0n) return null;
+  const denom = 10n ** BigInt(tokenDecimals) * nativeMicro;
+  if (denom <= 0n) return null;
+  const milli = feePerUnitGas * tokenMicro * 1000n / denom;
+  if (milli > BigInt(Number.MAX_SAFE_INTEGER)) return null;
+  return Number(milli);
+}
+function formatFeeRatioMilli(milli) {
+  const abs = Math.abs(Math.trunc(milli));
+  const whole = Math.floor(abs / 1e3);
+  const frac = String(abs % 1e3).padStart(3, "0").slice(0, 2);
+  return `${milli < 0 ? "-" : ""}${whole}.${frac}`;
+}
+function coversGasCost(ratioMilli) {
+  return ratioMilli != null && ratioMilli >= FEE_RATIO_ONE_TO_ONE_MILLI;
+}
+function orderBroadcasterChoices(rows) {
+  return [...rows].sort((left, right) => {
+    if (left.coversGas !== right.coversGas) return left.coversGas ? -1 : 1;
+    if (left.ratioMilli != null && right.ratioMilli != null && left.ratioMilli !== right.ratioMilli) {
+      return left.coversGas ? left.ratioMilli - right.ratioMilli : right.ratioMilli - left.ratioMilli;
+    }
+    if (left.ratioMilli == null && right.ratioMilli != null) return 1;
+    if (left.ratioMilli != null && right.ratioMilli == null) return -1;
+    if (left.feePerUnitGas !== right.feePerUnitGas) return left.feePerUnitGas < right.feePerUnitGas ? -1 : 1;
+    return right.reliability - left.reliability;
+  });
+}
+function defaultBroadcasterChoice(rows) {
+  return rows.find((row) => row.coversGas) ?? rows[0];
+}
+function nextCoveringBroadcaster(rows, refused) {
+  return rows.find((row) => row.coversGas && !refused.has(row.feesId));
+}
+function isBroadcasterGasRefusal(message) {
+  return /gas cost is too high/i.test(message);
+}
+
+// src/protocols/evm/railgun/private-actions.ts
 function chainFor(chainId) {
   return { type: ChainType.EVM, id: chainId };
 }
@@ -838,6 +1132,53 @@ function parsedAmount(amountWei) {
   if (amount <= 0n) throw new Error("Amount must be greater than zero.");
   return amount;
 }
+function railgunDetailedError(err) {
+  const seen = /* @__PURE__ */ new Set();
+  let current = err;
+  let fallback = "Railgun spend proof failed.";
+  while (current != null && !seen.has(current)) {
+    seen.add(current);
+    if (!(current instanceof Error)) break;
+    const message = current.message.trim();
+    if (message && /amount required|balance:/i.test(message)) return message;
+    if (message) fallback = message;
+    current = current.cause;
+  }
+  return fallback;
+}
+function broadcasterAskedToRefreshProofStatus(err) {
+  const message = railgunDetailedError(err);
+  return message.includes(BROADCASTER_POI_INCOMPLETE) || /could not validate proof of innocence/i.test(message) || /failed to validate poi merkleroots/i.test(message) || /invalid poi merkleroots/i.test(message);
+}
+function broadcasterRefusedForGas(err) {
+  return isBroadcasterGasRefusal(railgunDetailedError(err));
+}
+function chainForNetwork(networkName) {
+  return NETWORK_CONFIG[networkName].chain;
+}
+async function refreshSpendingProofStatus(networkName, walletId) {
+  const wallet = await import('@railgun-community/wallet');
+  const chain = chainForNetwork(networkName);
+  wallet.resumePPOIBatching(chain);
+  await wallet.walletForID(walletId).refreshPOIsForTXIDVersion(chain, TXIDVersion.V2_PoseidonMerkle, true);
+}
+async function assertTokenSpendable(networkName, walletId, tokenAddress, amount) {
+  const wallet = await import('@railgun-community/wallet');
+  const balance = await wallet.walletForID(walletId).getBalanceERC20(
+    TXIDVersion.V2_PoseidonMerkle,
+    chainForNetwork(networkName),
+    tokenAddress,
+    ["Spendable"]
+  );
+  if ((balance ?? 0n) < amount) {
+    throw new Error(
+      "These notes are still waiting for proof-of-innocence. The private transfer can start once that status is spendable."
+    );
+  }
+}
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 async function broadcasterClient() {
   try {
     return await import('@railgun-community/waku-broadcaster-client-web');
@@ -845,40 +1186,340 @@ async function broadcasterClient() {
     throw new Error("Railgun broadcaster client is not available.");
   }
 }
-async function selectedBroadcaster(chain, tokenAddress) {
+var BROADCASTER_CACHE_MS = 6e4;
+var BROADCASTER_QUOTE_WAIT_MS = 2e4;
+var BROADCASTER_PROOF_WAIT_MS = 3 * 60 * 1e3;
+var BROADCASTER_FEE_MIN_REMAINING_MS = 4e4;
+var BROADCASTER_PROOF_ATTEMPTS = 3;
+var POI_STATUS_RETRY_MS = 2e4;
+var POI_ROOT_WAIT_MS = 3 * 60 * 1e3;
+var BROADCASTER_POI_INCOMPLETE = "Proof-of-innocence validation did not complete";
+function broadcasterFeeStillValid(expiration, now = Date.now()) {
+  return Number.isFinite(expiration) && expiration >= now + BROADCASTER_FEE_MIN_REMAINING_MS;
+}
+var BROADCASTER_LIST_CACHE_MS = 15e3;
+var MAX_GAS_BROADCASTERS = 3;
+var NATIVE_COINGECKO_ID = {
+  1: "ethereum",
+  10: "ethereum",
+  56: "binancecoin",
+  100: "xdai",
+  137: "polygon-ecosystem-token",
+  250: "fantom",
+  324: "ethereum",
+  1101: "ethereum",
+  5e3: "mantle",
+  8453: "ethereum",
+  34443: "ethereum",
+  42161: "ethereum",
+  43114: "avalanche-2",
+  59144: "ethereum",
+  81457: "ethereum",
+  534352: "ethereum",
+  167e3: "ethereum"
+};
+var broadcasterListCache = /* @__PURE__ */ new Map();
+var tokenDecimalsCache = /* @__PURE__ */ new Map();
+var tokenUsdCache = /* @__PURE__ */ new Map();
+async function ensureBroadcasterWaku(chain) {
   const { WakuBroadcasterClient } = await broadcasterClient();
   if (!WakuBroadcasterClient.isStarted()) {
     await WakuBroadcasterClient.start(chain, { useDNSDiscovery: true }, () => void 0);
   } else {
     await WakuBroadcasterClient.setChain(chain);
   }
-  const deadline = Date.now() + 2e4;
-  let selected;
+}
+async function findTokenBroadcasters(chain, tokenAddress) {
+  const node = await nodeRequire();
+  if (!node) throw new Error("Railgun broadcasters are listed from the node.");
+  const entry = node.require.resolve("@railgun-community/waku-broadcaster-client-web");
+  const loaded = node.require(node.path.join(node.path.dirname(entry), "search/best-broadcaster.js"));
+  return loaded.BroadcasterSearch.findBroadcastersForToken(chain, tokenAddress, false) ?? [];
+}
+async function erc20Decimals(rpcUrl, tokenAddress) {
+  const key = tokenAddress.toLowerCase();
+  const cached2 = tokenDecimalsCache.get(key);
+  if (cached2 != null) return cached2;
+  const client = createPublicClient({ transport: defiEvmTransport(rpcUrl) });
+  const decimals = await client.readContract({
+    address: getAddress(tokenAddress),
+    abi: parseAbi(["function decimals() view returns (uint8)"]),
+    functionName: "decimals"
+  });
+  const value = Number(decimals);
+  if (!Number.isInteger(value) || value < 0 || value > 36) throw new Error("Token decimals are not available.");
+  tokenDecimalsCache.set(key, value);
+  return value;
+}
+async function readUsd(url) {
+  try {
+    const response = await fetch(url, { signal: AbortSignal.timeout(8e3) });
+    if (!response.ok) return null;
+    const body = await response.json();
+    for (const row of Object.values(body)) {
+      if (typeof row?.usd === "number" && row.usd > 0) return row.usd;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+async function broadcasterUsdPrices(chainId, tokenAddress, wrappedAddress) {
+  const key = `${chainId}:${tokenAddress.toLowerCase()}`;
+  const cached2 = tokenUsdCache.get(key);
+  if (cached2 && Date.now() - cached2.at < 6e4) return cached2;
+  const nativeId = NATIVE_COINGECKO_ID[chainId];
+  const nativeUsd = nativeId ? await readUsd(`https://api.coingecko.com/api/v3/simple/price?ids=${encodeURIComponent(nativeId)}&vs_currencies=usd`) : null;
+  const wrapped = wrappedAddress.toLowerCase() === tokenAddress.toLowerCase();
+  let tokenUsd = wrapped ? nativeUsd : null;
+  if (!wrapped) {
+    const platform = coingeckoPlatformForChainId(chainId);
+    tokenUsd = platform ? await readUsd(
+      `https://api.coingecko.com/api/v3/simple/token_price/${encodeURIComponent(platform)}?contract_addresses=${encodeURIComponent(tokenAddress)}&vs_currencies=usd`
+    ) : null;
+  }
+  const prices = { tokenUsd, nativeUsd };
+  tokenUsdCache.set(key, { at: Date.now(), ...prices });
+  return prices;
+}
+async function loadRailgunBroadcasters(args) {
+  const tokenAddress = getAddress(args.tokenAddress);
+  const cacheKey = `${args.kind}:${args.chainId}:${tokenAddress.toLowerCase()}`;
+  const cached2 = broadcasterListCache.get(cacheKey);
+  if (cached2 && Date.now() - cached2.at < BROADCASTER_LIST_CACHE_MS) return cached2.rows;
+  const chain = chainFor(args.chainId);
+  await ensureBroadcasterWaku(chain);
+  const deadline = Date.now() + (args.waitMs ?? BROADCASTER_QUOTE_WAIT_MS);
+  let found = [];
+  while (Date.now() < deadline) {
+    found = (await findTokenBroadcasters(chain, tokenAddress)).filter((row) => broadcasterFeeStillValid(row.tokenFee.expiration));
+    if (found.length > 0) break;
+    await delay(1e3);
+  }
+  if (found.length === 0) throw new Error("No Railgun broadcaster is available for this token.");
+  const network = await railgunNetworkByChainId(args.chainId);
+  const [decimals, prices, priced] = await Promise.all([
+    erc20Decimals(args.rpcUrl, tokenAddress),
+    broadcasterUsdPrices(args.chainId, tokenAddress, network?.wrappedAddress ?? ""),
+    chainDetailWithLiveGas(args.rpcUrl, args.chainDetail)
+  ]);
+  const networkName = network?.networkName ?? "";
+  const gasEstimate = args.kind === "unshield" ? RAILGUN_UNSHIELD_GAS_ESTIMATE : RAILGUN_TRANSFER_GAS_ESTIMATE;
+  const gasDetails = railgunBroadcasterGasDetails(networkName, priced, gasEstimate);
+  const byFeesId = /* @__PURE__ */ new Map();
+  for (const selected of found) {
+    const feesId = selected.tokenFee.feesID;
+    if (!feesId) continue;
+    const feePerUnitGas = BigInt(selected.tokenFee.feePerUnitGas);
+    const ratioMilli = prices.tokenUsd != null && prices.nativeUsd != null ? feeRatioMilli(feePerUnitGas, decimals, prices.tokenUsd, prices.nativeUsd) : null;
+    const row = {
+      feesId,
+      railgunAddress: selected.railgunAddress,
+      feeWei: broadcasterTokenFee(feePerUnitGas, gasDetails).toString(),
+      ratio: ratioMilli == null ? null : formatFeeRatioMilli(ratioMilli),
+      coversGas: coversGasCost(ratioMilli),
+      reliability: Number(selected.tokenFee.reliability) || 0,
+      expiration: selected.tokenFee.expiration,
+      tokenDecimals: decimals,
+      feePerUnitGas,
+      ratioMilli,
+      selected
+    };
+    const previous = byFeesId.get(feesId);
+    if (!previous || row.reliability > previous.reliability) byFeesId.set(feesId, row);
+  }
+  const rows = orderBroadcasterChoices([...byFeesId.values()]);
+  broadcasterListCache.set(cacheKey, { at: Date.now(), rows });
+  return rows;
+}
+async function listRailgunBroadcasters(args) {
+  const kind = args.kind.trim();
+  if (kind !== "transfer" && kind !== "unshield") throw new Error("kind must be transfer or unshield.");
+  const rows = await loadRailgunBroadcasters({ ...args, kind });
+  return rows.map((row) => ({
+    feesId: row.feesId,
+    railgunAddress: row.railgunAddress,
+    feeWei: row.feeWei,
+    ratio: row.ratio,
+    coversGas: row.coversGas,
+    reliability: row.reliability,
+    expiration: row.expiration,
+    tokenDecimals: row.tokenDecimals
+  }));
+}
+function broadcasterNote(row, switching) {
+  const ratioLabel = row.ratio ? `${row.ratio}:1` : "the selected fee";
+  return switching ? `Trying the next broadcaster at ${ratioLabel}` : `Broadcaster ${ratioLabel}`;
+}
+function poiListsPresent(pois) {
+  return Object.values(pois).some((leaves) => Object.keys(leaves).length > 0);
+}
+function poiRoots(poi) {
+  if (!poi || typeof poi !== "object" || !("poiMerkleroots" in poi)) return [];
+  const roots = poi.poiMerkleroots;
+  return Array.isArray(roots) ? roots.filter((root) => typeof root === "string") : [];
+}
+async function nodeRequire() {
+  if (typeof window !== "undefined") return null;
+  if (typeof process === "undefined" || !process.versions?.node) return null;
+  const load = new Function("id", "return import(id)");
+  const nodeModule = await load("node:module");
+  const nodePath = await load("node:path");
+  return { require: nodeModule.createRequire(import.meta.url), path: nodePath };
+}
+async function poiRootValidator() {
+  const node = await nodeRequire();
+  if (!node) throw new Error("Proof-of-innocence checks need the node Railgun engine.");
+  const walletEntry = node.require.resolve("@railgun-community/wallet");
+  const engineEntry = node.require.resolve("@railgun-community/engine", {
+    paths: [node.path.dirname(walletEntry)]
+  });
+  const loaded = node.require(engineEntry);
+  if (!loaded.POI) throw new Error("The Railgun engine did not load its proof-of-innocence checker.");
+  return loaded.POI;
+}
+async function poiMerklerootsConfirmed(chain, pois) {
+  const poi = await poiRootValidator();
+  for (const [listKey, leaves] of Object.entries(pois)) {
+    for (const entry of Object.values(leaves)) {
+      const roots = poiRoots(entry);
+      if (roots.length === 0) return false;
+      const confirmed = await poi.validatePOIMerkleroots(TXIDVersion.V2_PoseidonMerkle, chain, listKey, roots);
+      if (!confirmed) return false;
+    }
+  }
+  return true;
+}
+async function waitForConfirmedPoiRoots(chain, proved, onProofStatusRefresh) {
+  const pois = proved.populated.preTransactionPOIsPerTxidLeafPerList;
+  if (!poiListsPresent(pois)) {
+    throw new Error("The proof did not include a proof of innocence.");
+  }
+  const deadline = Date.now() + POI_ROOT_WAIT_MS;
   while (Date.now() < deadline) {
-    selected = await WakuBroadcasterClient.findBestBroadcaster(chain, tokenAddress, false);
-    if (selected) return selected;
-    await new Promise((resolve) => setTimeout(resolve, 1e3));
+    try {
+      if (await poiMerklerootsConfirmed(chain, pois)) return;
+    } catch (err) {
+      if (!broadcasterAskedToRefreshProofStatus(err)) throw err;
+    }
+    onProofStatusRefresh?.();
+    await delay(POI_STATUS_RETRY_MS);
+  }
+  throw new Error("The proof-of-innocence list has not confirmed these notes. Wait a few minutes and try the private transfer again.");
+}
+async function submitFreshProof(args) {
+  if (args.refreshProofStatus) {
+    args.onProofStatusRefresh?.();
+    await args.refreshProofStatus().catch(() => void 0);
+  }
+  await args.assertSpendable?.();
+  const refused = /* @__PURE__ */ new Set();
+  let feesId = args.broadcasterFeesId?.trim() ?? "";
+  let lastError = new Error("No Railgun broadcaster is available for this token.");
+  let builds = 0;
+  while (builds < MAX_GAS_BROADCASTERS) {
+    args.onBroadcasterSearch?.();
+    const rows = await loadRailgunBroadcasters({
+      chainId: args.chainId,
+      rpcUrl: args.rpcUrl,
+      chainDetail: args.chainDetail,
+      tokenAddress: args.tokenAddress,
+      kind: args.kind,
+      waitMs: BROADCASTER_PROOF_WAIT_MS
+    });
+    const requested = feesId && !refused.has(feesId) ? rows.find((row2) => row2.feesId === feesId) : void 0;
+    if (builds === 0 && args.broadcasterFeesId?.trim() && !requested) {
+      throw new Error("That broadcaster fee expired. Refresh the list and choose again.");
+    }
+    const row = requested ?? nextCoveringBroadcaster(rows, refused) ?? (refused.size === 0 ? defaultBroadcasterChoice(rows) : void 0);
+    if (!row || !broadcasterFeeStillValid(row.expiration)) {
+      if (!row) break;
+      refused.add(row.feesId);
+      feesId = "";
+      if (refused.size >= rows.length) break;
+      continue;
+    }
+    builds += 1;
+    feesId = row.feesId;
+    args.onBroadcasterNote?.(broadcasterNote(row, refused.size > 0));
+    const broadcaster = row.selected;
+    const proved = await args.build(broadcaster);
+    if (!broadcasterFeeStillValid(broadcaster.tokenFee.expiration)) {
+      broadcasterListCache.clear();
+      refused.add(feesId);
+      feesId = "";
+      continue;
+    }
+    await waitForConfirmedPoiRoots(args.chain, proved, args.onProofStatusRefresh);
+    let switchBroadcaster = false;
+    for (let poiTry = 1; poiTry <= BROADCASTER_PROOF_ATTEMPTS && !switchBroadcaster; poiTry += 1) {
+      try {
+        return {
+          txHash: await submitProved({
+            chain: args.chain,
+            populated: proved.populated,
+            broadcaster,
+            overallBatchMinGasPrice: proved.overallBatchMinGasPrice
+          })
+        };
+      } catch (err) {
+        lastError = err;
+        if (broadcasterRefusedForGas(err)) {
+          refused.add(feesId);
+          feesId = "";
+          switchBroadcaster = true;
+          break;
+        }
+        if (poiTry === BROADCASTER_PROOF_ATTEMPTS || !broadcasterAskedToRefreshProofStatus(err)) throw err;
+        args.onProofStatusRefresh?.();
+        await delay(POI_STATUS_RETRY_MS);
+        await args.refreshProofStatus?.().catch(() => void 0);
+        if (!broadcasterFeeStillValid(broadcaster.tokenFee.expiration)) {
+          broadcasterListCache.clear();
+          refused.add(feesId);
+          feesId = "";
+          switchBroadcaster = true;
+          break;
+        }
+        await waitForConfirmedPoiRoots(args.chain, proved, args.onProofStatusRefresh);
+      }
+    }
   }
-  throw new Error("No Railgun broadcaster is available for this token.");
+  if (lastError instanceof Error) throw lastError;
+  throw new Error("The broadcaster fee expired while the proof was building. Try the private transfer again.");
 }
 async function submitProved(args) {
   const to = args.populated.transaction.to;
   const data = args.populated.transaction.data;
   if (!to || !data) throw new Error("Railgun proof did not produce a transaction.");
   const { BroadcasterTransaction } = await broadcasterClient();
-  const tx = await BroadcasterTransaction.create(
-    TXIDVersion.V2_PoseidonMerkle,
-    to,
-    data,
-    args.broadcaster.railgunAddress,
-    args.broadcaster.tokenFee.feesID,
-    args.chain,
-    args.populated.nullifiers ?? [],
-    args.overallBatchMinGasPrice,
-    false,
-    args.populated.preTransactionPOIsPerTxidLeafPerList
-  );
-  return tx.send();
+  const detail = await broadcasterDetailConfig();
+  const previousDetail = detail?.IS_DEV;
+  if (detail) detail.IS_DEV = true;
+  try {
+    const tx = await BroadcasterTransaction.create(
+      TXIDVersion.V2_PoseidonMerkle,
+      to,
+      data,
+      args.broadcaster.railgunAddress,
+      args.broadcaster.tokenFee.feesID,
+      args.chain,
+      args.populated.nullifiers ?? [],
+      args.overallBatchMinGasPrice,
+      false,
+      args.populated.preTransactionPOIsPerTxidLeafPerList
+    );
+    return tx.send();
+  } finally {
+    if (detail && previousDetail !== void 0) detail.IS_DEV = previousDetail;
+  }
+}
+async function broadcasterDetailConfig() {
+  const node = await nodeRequire();
+  if (!node) return null;
+  const entry = node.require.resolve("@railgun-community/waku-broadcaster-client-web");
+  const loaded = node.require(node.path.join(node.path.dirname(entry), "models/broadcaster-config.js"));
+  return loaded.BroadcasterConfig;
 }
 function feeRecipient(wallet, broadcaster, gasDetails) {
   const fee = wallet.calculateBroadcasterFeeERC20Amount(
@@ -894,71 +1535,175 @@ function feeRecipient(wallet, broadcaster, gasDetails) {
     recipientAddress: broadcaster.railgunAddress
   };
 }
-async function railgunPrivateTransfer(args) {
-  assertRailgunCtmAllowed(args.chainId, args.tokenAddress);
-  await assertDeployed(args.chainId);
+var broadcasterFeeCache = /* @__PURE__ */ new Map();
+async function quoteRailgunBroadcasterFee(args) {
   const tokenAddress = getAddress(args.tokenAddress);
+  const cacheKey = `${args.kind}:${args.chainId}:${tokenAddress.toLowerCase()}`;
+  const cached2 = broadcasterFeeCache.get(cacheKey);
+  if (cached2 && Date.now() - cached2.at < BROADCASTER_CACHE_MS) {
+    return { feeWei: cached2.feeWei, tokenAddress: cached2.tokenAddress };
+  }
   const amount = parsedAmount(args.amountWei);
-  const recipientAddress = args.recipientAddress.trim();
-  if (!recipientAddress.startsWith("0zk")) throw new Error("Private transfer recipient must be a 0zk address.");
-  const session2 = requireRailgunWalletSession();
-  const rpcUrl = args.rpcUrl?.trim() ?? "";
-  if (!rpcUrl || !args.chainDetail) throw new Error("rpcUrl and chain details are required.");
-  const networkName = await ensureRailgunProvider(args.chainId, rpcUrl);
+  const networkName = await ensureRailgunProvider(args.chainId, args.rpcUrl);
   const wallet = await import('@railgun-community/wallet');
-  const chain = chainFor(args.chainId);
-  const broadcaster = await selectedBroadcaster(chain, tokenAddress);
-  const recipients = [{ tokenAddress, amount, recipientAddress }];
+  const priced = await chainDetailWithLiveGas(args.rpcUrl, args.chainDetail);
+  const listed = await loadRailgunBroadcasters({
+    chainId: args.chainId,
+    rpcUrl: args.rpcUrl,
+    chainDetail: args.chainDetail,
+    tokenAddress,
+    kind: args.kind
+  });
+  const chosen = defaultBroadcasterChoice(listed);
+  if (!chosen) throw new Error("No Railgun broadcaster is available for this token.");
+  const broadcaster = chosen.selected;
   const feeToken = {
     tokenAddress: broadcaster.tokenAddress,
     feePerUnitGas: BigInt(broadcaster.tokenFee.feePerUnitGas)
   };
-  const original = railgunGasDetails(args.chainDetail, 0n);
-  const { gasEstimate } = await wallet.gasEstimateForUnprovenTransfer(
+  const original = railgunBroadcasterGasDetails(networkName, priced, 0n);
+  const recipientAddress = args.kind === "unshield" ? getAddress(args.recipientAddress || "0x0000000000000000000000000000000000000001") : args.recipientAddress.trim();
+  if (args.kind === "transfer" && !recipientAddress.startsWith("0zk")) {
+    throw new Error("A 0zk address is required to estimate the private-transfer fee.");
+  }
+  const recipients = [{ tokenAddress, amount, recipientAddress }];
+  const estimated = args.kind === "unshield" ? await wallet.gasEstimateForUnprovenUnshield(
     TXIDVersion.V2_PoseidonMerkle,
     networkName,
-    session2.walletId,
-    session2.encryptionKey,
-    args.memoText ?? null,
+    args.walletId,
+    args.encryptionKey,
     recipients,
     [],
     original,
     feeToken,
     false
-  );
-  const gasDetails = railgunGasDetails(args.chainDetail, gasEstimate);
-  const broadcasterFee = feeRecipient(wallet, broadcaster, gasDetails);
-  const overallBatchMinGasPrice = calculateGasPrice(gasDetails);
-  await wallet.generateTransferProof(
-    TXIDVersion.V2_PoseidonMerkle,
-    networkName,
-    session2.walletId,
-    session2.encryptionKey,
-    false,
-    args.memoText ?? null,
-    recipients,
-    [],
-    broadcasterFee,
-    false,
-    overallBatchMinGasPrice,
-    (progress) => args.onProofProgress?.(progress)
-  );
-  const populated = await wallet.populateProvedTransfer(
+  ) : await wallet.gasEstimateForUnprovenTransfer(
     TXIDVersion.V2_PoseidonMerkle,
     networkName,
-    session2.walletId,
-    false,
+    args.walletId,
+    args.encryptionKey,
     args.memoText ?? null,
     recipients,
     [],
-    broadcasterFee,
-    false,
-    overallBatchMinGasPrice,
-    gasDetails
+    original,
+    feeToken,
+    false
   );
-  return { txHash: await submitProved({ chain, populated, broadcaster, overallBatchMinGasPrice }) };
+  const fee = feeRecipient(wallet, broadcaster, railgunBroadcasterGasDetails(networkName, priced, estimated.gasEstimate));
+  const quoted = { feeWei: fee.amount.toString(), tokenAddress: getAddress(fee.tokenAddress) };
+  broadcasterFeeCache.set(cacheKey, { at: Date.now(), ...quoted });
+  return quoted;
+}
+async function quoteRailgunBroadcasterFeeRate(args) {
+  const tokenAddress = getAddress(args.tokenAddress);
+  const network = await railgunNetworkByChainId(args.chainId);
+  if (!network) throw new Error("Railgun is not deployed on this chain.");
+  const listed = await loadRailgunBroadcasters({
+    chainId: args.chainId,
+    rpcUrl: args.rpcUrl,
+    chainDetail: args.chainDetail,
+    tokenAddress,
+    kind: args.kind
+  });
+  const chosen = defaultBroadcasterChoice(listed);
+  if (!chosen) throw new Error("No Railgun broadcaster is available for this token.");
+  return { feeWei: chosen.feeWei, tokenAddress };
+}
+async function railgunPrivateTransfer(args) {
+  try {
+    return await provePrivateTransfer(args);
+  } catch (err) {
+    throw new Error(railgunDetailedError(err));
+  }
+}
+async function provePrivateTransfer(args) {
+  assertRailgunCtmAllowed(args.chainId, args.tokenAddress);
+  await assertDeployed(args.chainId);
+  const tokenAddress = getAddress(args.tokenAddress);
+  const amount = parsedAmount(args.amountWei);
+  const recipientAddress = args.recipientAddress.trim();
+  if (!recipientAddress.startsWith("0zk")) throw new Error("Private transfer recipient must be a 0zk address.");
+  const session2 = requireRailgunWalletSession();
+  const rpcUrl = args.rpcUrl?.trim() ?? "";
+  if (!rpcUrl || !args.chainDetail) throw new Error("rpcUrl and chain details are required.");
+  const networkName = await ensureRailgunProvider(args.chainId, rpcUrl);
+  const wallet = await import('@railgun-community/wallet');
+  const chain = chainFor(args.chainId);
+  const priced = await chainDetailWithLiveGas(rpcUrl, args.chainDetail);
+  const recipients = [{ tokenAddress, amount, recipientAddress }];
+  return submitFreshProof({
+    chainId: args.chainId,
+    rpcUrl,
+    chainDetail: args.chainDetail,
+    kind: "transfer",
+    chain,
+    tokenAddress,
+    broadcasterFeesId: args.broadcasterFeesId,
+    onBroadcasterSearch: args.onBroadcasterSearch,
+    onBroadcasterNote: args.onBroadcasterNote,
+    onProofStatusRefresh: args.onProofStatusRefresh,
+    refreshProofStatus: () => refreshSpendingProofStatus(networkName, session2.walletId),
+    assertSpendable: () => assertTokenSpendable(networkName, session2.walletId, tokenAddress, amount),
+    build: async (broadcaster) => {
+      const feeToken = {
+        tokenAddress: broadcaster.tokenAddress,
+        feePerUnitGas: BigInt(broadcaster.tokenFee.feePerUnitGas)
+      };
+      const original = railgunBroadcasterGasDetails(networkName, priced, 0n);
+      const { gasEstimate } = await wallet.gasEstimateForUnprovenTransfer(
+        TXIDVersion.V2_PoseidonMerkle,
+        networkName,
+        session2.walletId,
+        session2.encryptionKey,
+        args.memoText ?? null,
+        recipients,
+        [],
+        original,
+        feeToken,
+        false
+      );
+      const gasDetails = railgunBroadcasterGasDetails(networkName, priced, gasEstimate);
+      const broadcasterFee = feeRecipient(wallet, broadcaster, gasDetails);
+      const overallBatchMinGasPrice = calculateGasPrice(gasDetails);
+      await wallet.generateTransferProof(
+        TXIDVersion.V2_PoseidonMerkle,
+        networkName,
+        session2.walletId,
+        session2.encryptionKey,
+        false,
+        args.memoText ?? null,
+        recipients,
+        [],
+        broadcasterFee,
+        false,
+        overallBatchMinGasPrice,
+        (progress) => args.onProofProgress?.(progress)
+      );
+      const populated = await wallet.populateProvedTransfer(
+        TXIDVersion.V2_PoseidonMerkle,
+        networkName,
+        session2.walletId,
+        false,
+        args.memoText ?? null,
+        recipients,
+        [],
+        broadcasterFee,
+        false,
+        overallBatchMinGasPrice,
+        gasDetails
+      );
+      return { populated, overallBatchMinGasPrice };
+    }
+  });
 }
 async function railgunUnshield(args) {
+  try {
+    return await proveUnshield(args);
+  } catch (err) {
+    throw new Error(railgunDetailedError(err));
+  }
+}
+async function proveUnshield(args) {
   assertRailgunCtmAllowed(args.chainId, args.tokenAddress);
   await assertDeployed(args.chainId);
   const tokenAddress = getAddress(args.tokenAddress);
@@ -970,51 +1715,148 @@ async function railgunUnshield(args) {
   const networkName = await ensureRailgunProvider(args.chainId, rpcUrl);
   const wallet = await import('@railgun-community/wallet');
   const chain = chainFor(args.chainId);
-  const broadcaster = await selectedBroadcaster(chain, tokenAddress);
+  const priced = await chainDetailWithLiveGas(rpcUrl, args.chainDetail);
   const recipients = [{ tokenAddress, amount, recipientAddress }];
-  const feeToken = {
-    tokenAddress: broadcaster.tokenAddress,
-    feePerUnitGas: BigInt(broadcaster.tokenFee.feePerUnitGas)
+  return submitFreshProof({
+    chainId: args.chainId,
+    rpcUrl,
+    chainDetail: args.chainDetail,
+    kind: "unshield",
+    chain,
+    tokenAddress,
+    broadcasterFeesId: args.broadcasterFeesId,
+    onBroadcasterSearch: args.onBroadcasterSearch,
+    onBroadcasterNote: args.onBroadcasterNote,
+    onProofStatusRefresh: args.onProofStatusRefresh,
+    refreshProofStatus: () => refreshSpendingProofStatus(networkName, session2.walletId),
+    assertSpendable: () => assertTokenSpendable(networkName, session2.walletId, tokenAddress, amount),
+    build: async (broadcaster) => {
+      const feeToken = {
+        tokenAddress: broadcaster.tokenAddress,
+        feePerUnitGas: BigInt(broadcaster.tokenFee.feePerUnitGas)
+      };
+      const original = railgunBroadcasterGasDetails(networkName, priced, 0n);
+      const { gasEstimate } = await wallet.gasEstimateForUnprovenUnshield(
+        TXIDVersion.V2_PoseidonMerkle,
+        networkName,
+        session2.walletId,
+        session2.encryptionKey,
+        recipients,
+        [],
+        original,
+        feeToken,
+        false
+      );
+      const gasDetails = railgunBroadcasterGasDetails(networkName, priced, gasEstimate);
+      const broadcasterFee = feeRecipient(wallet, broadcaster, gasDetails);
+      const overallBatchMinGasPrice = calculateGasPrice(gasDetails);
+      await wallet.generateUnshieldProof(
+        TXIDVersion.V2_PoseidonMerkle,
+        networkName,
+        session2.walletId,
+        session2.encryptionKey,
+        recipients,
+        [],
+        broadcasterFee,
+        false,
+        overallBatchMinGasPrice,
+        (progress) => args.onProofProgress?.(progress)
+      );
+      const populated = await wallet.populateProvedUnshield(
+        TXIDVersion.V2_PoseidonMerkle,
+        networkName,
+        session2.walletId,
+        recipients,
+        [],
+        broadcasterFee,
+        false,
+        overallBatchMinGasPrice,
+        gasDetails
+      );
+      return { populated, overallBatchMinGasPrice };
+    }
+  });
+}
+var feeAbi = parseAbi([
+  "function shieldFee() view returns (uint256)",
+  "function unshieldFee() view returns (uint256)"
+]);
+var BASIS_POINTS = 10000n;
+var FEE_CACHE_MS = 6e4;
+var basisCache = /* @__PURE__ */ new Map();
+function railgunProtocolFee(amount, basisPoints) {
+  const value = amount > 0n ? amount : 0n;
+  const bps = basisPoints > 0n ? basisPoints : 0n;
+  const fee = value * bps / BASIS_POINTS;
+  return { fee, received: value - fee };
+}
+async function protocolBasisPoints(chainId, rpcUrl) {
+  const cached2 = basisCache.get(chainId);
+  if (cached2 && Date.now() - cached2.at < FEE_CACHE_MS) return cached2;
+  const network = await railgunNetworkByChainId(chainId);
+  if (!network) throw new Error("Railgun is not deployed on this chain.");
+  const client = createPublicClient({ transport: defiEvmTransport(rpcUrl) });
+  const address = getAddress(network.proxyContract);
+  const [shield, unshield] = await Promise.all([
+    client.readContract({ address, abi: feeAbi, functionName: "shieldFee" }),
+    client.readContract({ address, abi: feeAbi, functionName: "unshieldFee" })
+  ]);
+  const next = { shield, unshield, at: Date.now() };
+  basisCache.set(chainId, next);
+  return next;
+}
+function clearRailgunFeeCache() {
+  basisCache.clear();
+}
+async function quoteRailgunFee(args) {
+  const rpcUrl = args.rpcUrl.trim();
+  if (!rpcUrl) throw new Error("rpcUrl is required.");
+  const amount = (() => {
+    try {
+      return BigInt(args.amountWei.trim() || "0");
+    } catch {
+      throw new Error("Amount must be an integer in wei.");
+    }
+  })();
+  if (amount < 0n) throw new Error("Amount must be greater than zero.");
+  const rates = await protocolBasisPoints(args.chainId, rpcUrl);
+  const basisPoints = args.kind === "shield" ? rates.shield : args.kind === "unshield" ? rates.unshield : 0n;
+  const protocol = railgunProtocolFee(amount, basisPoints);
+  let broadcasterFee = 0n;
+  let broadcasterTokenAddress = "";
+  let broadcasterError;
+  if (args.kind !== "shield") {
+    if (!args.chainDetail) {
+      broadcasterError = "Chain gas details are required to estimate the broadcaster fee.";
+    } else {
+      try {
+        const quoted = await quoteRailgunBroadcasterFeeRate({
+          kind: args.kind,
+          chainId: args.chainId,
+          rpcUrl,
+          chainDetail: args.chainDetail,
+          tokenAddress: args.tokenAddress
+        });
+        broadcasterFee = BigInt(quoted.feeWei);
+        broadcasterTokenAddress = quoted.tokenAddress;
+      } catch (err) {
+        broadcasterError = err instanceof Error ? err.message : "Broadcaster fee is not available.";
+      }
+    }
+  }
+  const totalDebit = args.kind === "shield" ? amount : amount + broadcasterFee;
+  const quote = {
+    kind: args.kind,
+    amountWei: amount.toString(),
+    protocolFeeBasisPoints: basisPoints.toString(),
+    protocolFeeWei: protocol.fee.toString(),
+    receivedWei: (args.kind === "transfer" ? amount : protocol.received).toString(),
+    broadcasterFeeWei: broadcasterFee.toString(),
+    broadcasterTokenAddress,
+    totalDebitWei: totalDebit.toString()
   };
-  const original = railgunGasDetails(args.chainDetail, 0n);
-  const { gasEstimate } = await wallet.gasEstimateForUnprovenUnshield(
-    TXIDVersion.V2_PoseidonMerkle,
-    networkName,
-    session2.walletId,
-    session2.encryptionKey,
-    recipients,
-    [],
-    original,
-    feeToken,
-    false
-  );
-  const gasDetails = railgunGasDetails(args.chainDetail, gasEstimate);
-  const broadcasterFee = feeRecipient(wallet, broadcaster, gasDetails);
-  const overallBatchMinGasPrice = calculateGasPrice(gasDetails);
-  await wallet.generateUnshieldProof(
-    TXIDVersion.V2_PoseidonMerkle,
-    networkName,
-    session2.walletId,
-    session2.encryptionKey,
-    recipients,
-    [],
-    broadcasterFee,
-    false,
-    overallBatchMinGasPrice,
-    (progress) => args.onProofProgress?.(progress)
-  );
-  const populated = await wallet.populateProvedUnshield(
-    TXIDVersion.V2_PoseidonMerkle,
-    networkName,
-    session2.walletId,
-    recipients,
-    [],
-    broadcasterFee,
-    false,
-    overallBatchMinGasPrice,
-    gasDetails
-  );
-  return { txHash: await submitProved({ chain, populated, broadcaster, overallBatchMinGasPrice }) };
+  if (broadcasterError) quote.broadcasterError = broadcasterError;
+  return quote;
 }
 async function walletModule2() {
   return await import('@railgun-community/wallet');
@@ -1053,6 +1895,16 @@ async function railgunShareableViewingKey(walletId) {
   if (!viewingKey) throw new Error("Railgun viewing key is not available.");
   return viewingKey;
 }
+async function rememberKeyGenWallet(keyGenId, walletId, railgunAddress) {
+  const root = await resolveRailgunDataRoot();
+  if (!root) return;
+  const load = new Function("id", "return import(id)");
+  const fs = await load("node:fs/promises");
+  const file = railgunKeyGenWalletPath(root, keyGenId);
+  await fs.mkdir(file.slice(0, file.lastIndexOf("/")), { recursive: true });
+  await fs.writeFile(file, `${JSON.stringify({ walletId, railgunAddress })}
+`, { mode: 384 });
+}
 async function openRailgunViewOnlyWallet(args) {
   await ensureRailgunEngine();
   const network = await railgunNetworkByChainId(args.chainId);
@@ -1062,6 +1914,7 @@ async function openRailgunViewOnlyWallet(args) {
     args.shareableViewingKey,
     network ? { [network.networkName]: network.deploymentBlock } : void 0
   );
+  if (args.keyGenId) await rememberKeyGenWallet(args.keyGenId, created.id, created.railgunAddress);
   return { walletId: created.id, railgunAddress: created.railgunAddress };
 }
 async function discardRailgunWallet(walletId) {
@@ -1074,11 +1927,15 @@ function railgunAddressIsValid(address) {
   return walletModule2().then((wallet) => wallet.validateRailgunAddress(address));
 }
 var buckets = /* @__PURE__ */ new Map();
-function rowMap(chainId) {
-  let rows = buckets.get(chainId);
+function bucketKey(walletId, chainId) {
+  return `${walletId}:${chainId}`;
+}
+function rowMap(walletId, chainId) {
+  const key = bucketKey(walletId, chainId);
+  let rows = buckets.get(key);
   if (!rows) {
     rows = /* @__PURE__ */ new Map();
-    buckets.set(chainId, rows);
+    buckets.set(key, rows);
   }
   return rows;
 }
@@ -1091,9 +1948,18 @@ function cellFor(rows, tokenAddress) {
   }
   return cell;
 }
+function recordRailgunWalletBalance(event) {
+  applyBalanceEvent(event);
+}
+function railgunWalletBalanceSnapshot(walletId, chainId) {
+  return snapshotRows(walletId, chainId);
+}
+function clearRailgunWalletBalances() {
+  buckets.clear();
+}
 function applyBalanceEvent(event) {
-  if (event.txidVersion !== TXIDVersion.V2_PoseidonMerkle) return;
-  const rows = rowMap(event.chain.id);
+  if (!event.railgunWalletID || event.txidVersion !== TXIDVersion.V2_PoseidonMerkle) return;
+  const rows = rowMap(event.railgunWalletID, event.chain.id);
   const spendable = event.balanceBucket === RailgunWalletBalanceBucket.Spendable;
   const pending = event.balanceBucket === RailgunWalletBalanceBucket.ShieldPending || event.balanceBucket === RailgunWalletBalanceBucket.ProofSubmitted || event.balanceBucket === RailgunWalletBalanceBucket.MissingExternalPOI || event.balanceBucket === RailgunWalletBalanceBucket.MissingInternalPOI;
   if (!spendable && !pending) return;
@@ -1109,8 +1975,8 @@ function applyBalanceEvent(event) {
     if (pending) cell.pending.set(event.balanceBucket, amount.amount);
   }
 }
-function snapshotRows(chainId) {
-  const rows = buckets.get(chainId);
+function snapshotRows(walletId, chainId) {
+  const rows = buckets.get(bucketKey(walletId, chainId));
   if (!rows) return [];
   return [...rows.entries()].filter(([, cell]) => cell.spendable > 0n || [...cell.pending.values()].some((amount) => amount > 0n)).map(([tokenAddress, cell]) => ({
     tokenAddress,
@@ -1123,49 +1989,315 @@ function utxoScanTerminalStatus(scanStatus) {
   if (scanStatus === "Incomplete") return "failed";
   return "pending";
 }
-async function scanRailgunPrivateBalances(args) {
-  const rpcUrl = args.rpcUrl.trim();
-  if (!rpcUrl) throw new Error("rpcUrl is required.");
-  buckets.set(args.chainId, /* @__PURE__ */ new Map());
+var RAILGUN_RESCAN_QUIET_MS = 4e3;
+var RAILGUN_TXID_WAIT_AFTER_NOTES_MS = 45e3;
+var RAILGUN_CATCH_UP_MS = 12e4;
+var RAILGUN_MERKLETREE_STALL_MS = 5 * 60 * 1e3;
+var RAILGUN_SCAN_BEHIND_NOTE = "The shielded balance is saved. The newest blocks did not finish syncing, so a shield that just landed may be missing until the next scan.";
+var RAILGUN_SCAN_STOPPED_NOTE = "The note scan stopped before it reached the latest block. The shielded balance is unchanged until a scan finishes.";
+function merkletreeScanStillRunning(args) {
+  return args.sawProgress && !args.notesFinished && args.terminal === "pending";
+}
+function railgunScanRecord(merkletree, balanceCount, caughtUp) {
+  if (merkletree !== "done") {
+    return { scanStatus: "error", notes: RAILGUN_SCAN_STOPPED_NOTE };
+  }
+  if (!caughtUp) {
+    return {
+      scanStatus: balanceCount === 0 ? "empty" : "ready",
+      notes: RAILGUN_SCAN_BEHIND_NOTE
+    };
+  }
+  return {
+    scanStatus: balanceCount === 0 ? "empty" : "ready",
+    notes: balanceCount === 0 ? "No private balance on this chain yet." : ""
+  };
+}
+function balancesToKeepAfterNoteScan(decrypted, afterRefresh, previous) {
+  if (afterRefresh.length > 0) return afterRefresh;
+  if (decrypted.length > 0) return decrypted;
+  return previous;
+}
+var utxoListeners = /* @__PURE__ */ new Set();
+var utxoHooked = false;
+var balanceListeners = /* @__PURE__ */ new Set();
+var balanceHooked = false;
+var scansInFlight = /* @__PURE__ */ new Map();
+function delay2(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function hookUtxoScans(wallet) {
+  if (utxoHooked) return;
+  utxoHooked = true;
+  wallet.setOnUTXOMerkletreeScanCallback((event) => {
+    for (const listener of utxoListeners) listener(event);
+  });
+}
+async function hookBalanceUpdates(wallet) {
+  if (balanceHooked) return;
+  balanceHooked = true;
+  wallet.setOnBalanceUpdateCallback((event) => {
+    for (const listener of balanceListeners) listener(event);
+  });
+}
+function publishScan(chainId, scanStatus, balances, settled, notes) {
+  const text = notes ?? (balances.length === 0 ? "No private balance on this chain yet." : void 0);
+  publishRailgunPrivateBalanceSnapshot({
+    chainId,
+    scanStatus,
+    balances,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    notes: text
+  });
+  return { scanStatus, balances, settled, notes: text ?? "" };
+}
+async function scanRailgunPrivateBalancesOnce(args) {
+  const previous = snapshotRows(args.walletId, args.chainId);
   publishRailgunPrivateBalanceSnapshot({
     chainId: args.chainId,
     scanStatus: "scanning",
-    balances: [],
+    balances: previous,
     updatedAt: (/* @__PURE__ */ new Date()).toISOString()
   });
   const wallet = await walletModule2();
   let resolveScan = () => {
   };
-  const scanSettled = new Promise((resolve) => {
+  let scanSettled = new Promise((resolve) => {
     resolveScan = resolve;
   });
-  wallet.setOnBalanceUpdateCallback((event) => {
-    if (event.railgunWalletID !== args.walletId) return;
-    applyBalanceEvent(event);
+  const armScanWait = () => {
+    scanSettled = new Promise((resolve) => {
+      resolveScan = resolve;
+    });
+  };
+  let sawUtxoEvent = false;
+  let lastUtxoAt = 0;
+  let replacedBuckets = false;
+  let resolveNotesEnd = () => {
+  };
+  const notesEnded = new Promise((resolve) => {
+    resolveNotesEnd = resolve;
   });
-  wallet.setOnUTXOMerkletreeScanCallback((event) => {
+  const publishLiveBalances = () => {
+    const rows = snapshotRows(args.walletId, args.chainId);
+    if (rows.length > 0) args.onBalances?.(rows);
+  };
+  let notesFinished = false;
+  const listener = (event) => {
     if (event.chain.id !== args.chainId) return;
+    if (!replacedBuckets) {
+      buckets.set(bucketKey(args.walletId, args.chainId), /* @__PURE__ */ new Map());
+      replacedBuckets = true;
+    }
+    sawUtxoEvent = true;
+    lastUtxoAt = Date.now();
     args.onProgress?.(event.progress);
     const terminal = utxoScanTerminalStatus(event.scanStatus);
+    if (event.progress >= 1 || terminal === "done") {
+      notesFinished = true;
+      publishLiveBalances();
+      resolveNotesEnd();
+    }
     if (terminal !== "pending") resolveScan(terminal);
-  });
+  };
+  await hookUtxoScans(wallet);
+  await hookBalanceUpdates(wallet);
+  utxoListeners.add(listener);
+  const onBalance = (event) => {
+    if (event.railgunWalletID !== args.walletId || event.chain.id !== args.chainId) return;
+    recordRailgunWalletBalance(event);
+    publishLiveBalances();
+  };
+  balanceListeners.add(onBalance);
+  try {
+    await ensureRailgunProvider(args.chainId, args.rpcUrl);
+    const chain = { type: ChainType.EVM, id: args.chainId };
+    const refresh = wallet.refreshBalances(chain, [args.walletId]).then(
+      () => "returned",
+      () => "returned"
+    );
+    const quiet = delay2(RAILGUN_RESCAN_QUIET_MS).then(() => "quiet");
+    const notesTimeout = notesEnded.then(() => delay2(RAILGUN_TXID_WAIT_AFTER_NOTES_MS)).then(() => "notes-timeout");
+    let status = await Promise.race([
+      scanSettled,
+      refresh,
+      quiet,
+      notesTimeout
+    ]);
+    if (status === "quiet") {
+      status = await Promise.race([
+        scanSettled,
+        refresh,
+        notesTimeout,
+        delay2(RAILGUN_CATCH_UP_MS).then(() => "catch-up-timeout")
+      ]);
+    }
+    let historyFinished = status === "done" || (status === "notes-timeout" || status === "returned") && notesFinished;
+    const terminal = status === "done" || status === "failed" ? status : "pending";
+    if (!historyFinished && merkletreeScanStillRunning({ sawProgress: sawUtxoEvent, notesFinished, terminal })) {
+      let walked = "stalled";
+      while (walked === "stalled") {
+        const idle = Date.now() - lastUtxoAt;
+        const slice = Math.max(250, RAILGUN_MERKLETREE_STALL_MS - idle);
+        const step = await Promise.race([scanSettled, delay2(slice).then(() => "tick")]);
+        if (step === "done" || step === "failed") {
+          walked = step;
+          break;
+        }
+        if (Date.now() - lastUtxoAt >= RAILGUN_MERKLETREE_STALL_MS) break;
+      }
+      if (walked !== "done") {
+        const rows = snapshotRows(args.walletId, args.chainId);
+        const balances2 = rows.length > 0 ? rows : previous;
+        const record2 = railgunScanRecord("failed", balances2.length, false);
+        return publishScan(args.chainId, record2.scanStatus, balances2, false, record2.notes);
+      }
+      notesFinished = true;
+      historyFinished = true;
+    }
+    if (!historyFinished) {
+      armScanWait();
+      const retry = wallet.refreshBalances(chain, [args.walletId]).then(
+        () => "returned",
+        () => "returned"
+      );
+      const retried = await Promise.race([
+        scanSettled,
+        retry,
+        delay2(RAILGUN_CATCH_UP_MS).then(() => "catch-up-timeout")
+      ]);
+      if (retried !== "done" && !notesFinished) {
+        const rows = snapshotRows(args.walletId, args.chainId);
+        const balances2 = rows.length > 0 ? rows : previous;
+        const record2 = railgunScanRecord("failed", balances2.length, false);
+        return publishScan(args.chainId, record2.scanStatus, balances2, false, record2.notes);
+      }
+    }
+    const decrypted = snapshotRows(args.walletId, args.chainId);
+    publishLiveBalances();
+    const refreshed = await Promise.race([
+      refresh.then(() => true),
+      delay2(RAILGUN_TXID_WAIT_AFTER_NOTES_MS).then(() => false)
+    ]);
+    if (!refreshed) {
+      await Promise.race([refresh.then(() => void 0), delay2(RAILGUN_CATCH_UP_MS).then(() => void 0)]);
+    }
+    sawUtxoEvent = false;
+    armScanWait();
+    const followUpStarted = Date.now();
+    const followUp = wallet.refreshBalances(chain, [args.walletId]).then(
+      () => "returned",
+      () => "returned"
+    );
+    let followStatus = await Promise.race([
+      scanSettled,
+      followUp,
+      delay2(RAILGUN_RESCAN_QUIET_MS).then(() => "quiet"),
+      delay2(RAILGUN_CATCH_UP_MS).then(() => "catch-up-timeout")
+    ]);
+    if ((followStatus === "quiet" || followStatus === "returned") && sawUtxoEvent) {
+      const remaining = Math.max(0, RAILGUN_CATCH_UP_MS - (Date.now() - followUpStarted));
+      followStatus = await Promise.race([
+        scanSettled,
+        delay2(remaining).then(() => "catch-up-timeout")
+      ]);
+    }
+    const caughtUp = followStatus === "done" || followStatus === "quiet" && !sawUtxoEvent;
+    const balances = balancesToKeepAfterNoteScan(decrypted, snapshotRows(args.walletId, args.chainId), previous);
+    const record = railgunScanRecord("done", balances.length, caughtUp);
+    return publishScan(args.chainId, record.scanStatus, balances, refreshed && caughtUp, record.notes || void 0);
+  } finally {
+    utxoListeners.delete(listener);
+    balanceListeners.delete(onBalance);
+  }
+}
+var SPEND_DECRYPT_WAIT_MS = 3 * 60 * 1e3;
+var RAILGUN_SPEND_SCAN_STOPPED = "The spending wallet did not finish scanning private notes.";
+function spendingScanReadyAfterHistory(progress, scanStatus) {
+  return progress >= 1 || utxoScanTerminalStatus(scanStatus) === "done";
+}
+function spendingNoteScanGaveUp(args) {
+  if (args.walletReady || args.notesFinished) return false;
+  if (args.sawProgress) return args.msSinceProgress >= RAILGUN_MERKLETREE_STALL_MS;
+  if (args.msWaitingForDecrypt == null) return false;
+  return args.msWaitingForDecrypt >= SPEND_DECRYPT_WAIT_MS;
+}
+async function scanSpendingWalletNotes(args) {
+  const rpcUrl = args.rpcUrl.trim();
+  if (!rpcUrl) throw new Error("rpcUrl is required.");
   await ensureRailgunProvider(args.chainId, rpcUrl);
+  const wallet = await walletModule2();
   const chain = { type: ChainType.EVM, id: args.chainId };
-  await wallet.refreshBalances(chain, [args.walletId]);
-  if (await scanSettled === "failed") {
-    const cause = latestRailgunEngineError();
-    throw new Error(cause ? `Railgun note scan stopped before it finished. ${cause}` : "Railgun note scan stopped before it finished.");
+  await hookUtxoScans(wallet);
+  let sawUtxoEvent = false;
+  let lastUtxoAt = Date.now();
+  let notesFinished = false;
+  let walletReady = false;
+  const listener = (event) => {
+    if (event.chain.id !== args.chainId) return;
+    sawUtxoEvent = true;
+    lastUtxoAt = Date.now();
+    if (spendingScanReadyAfterHistory(event.progress, event.scanStatus)) {
+      notesFinished = true;
+      walletReady = true;
+    }
+    args.onProgress?.(event.progress);
+  };
+  utxoListeners.add(listener);
+  const listenForDecrypt = () => {
+    wallet.awaitWalletScan(args.walletId, chain).then(
+      () => {
+        walletReady = true;
+      },
+      () => {
+        listenForDecrypt();
+      }
+    );
+  };
+  listenForDecrypt();
+  let refreshSettled = false;
+  let refreshError = null;
+  void wallet.refreshBalances(chain, [args.walletId]).then(
+    () => {
+      refreshSettled = true;
+    },
+    (err) => {
+      refreshError = err;
+      refreshSettled = true;
+    }
+  );
+  let decryptWaitStarted = null;
+  try {
+    while (!walletReady) {
+      if (refreshError) throw refreshError;
+      const waitingForDecrypt = notesFinished || !sawUtxoEvent && refreshSettled ? decryptWaitStarted ??= Date.now() : null;
+      if (waitingForDecrypt == null) decryptWaitStarted = null;
+      if (spendingNoteScanGaveUp({
+        walletReady,
+        sawProgress: sawUtxoEvent,
+        notesFinished,
+        msSinceProgress: Date.now() - lastUtxoAt,
+        msWaitingForDecrypt: waitingForDecrypt == null ? null : Date.now() - waitingForDecrypt
+      })) {
+        throw new Error(RAILGUN_SPEND_SCAN_STOPPED);
+      }
+      await delay2(250);
+    }
+  } finally {
+    utxoListeners.delete(listener);
   }
-  const balances = snapshotRows(args.chainId);
-  const scanStatus = balances.length === 0 ? "empty" : "ready";
-  publishRailgunPrivateBalanceSnapshot({
-    chainId: args.chainId,
-    scanStatus,
-    balances,
-    updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    notes: balances.length === 0 ? "No private balance on this chain yet." : void 0
+}
+async function scanRailgunPrivateBalances(args) {
+  const rpcUrl = args.rpcUrl.trim();
+  if (!rpcUrl) throw new Error("rpcUrl is required.");
+  const key = `${args.chainId}:${args.walletId}`;
+  const existing = scansInFlight.get(key);
+  if (existing) return existing;
+  const run = scanRailgunPrivateBalancesOnce({ ...args, rpcUrl }).finally(() => {
+    if (scansInFlight.get(key) === run) scansInFlight.delete(key);
   });
-  return { scanStatus, balances };
+  scansInFlight.set(key, run);
+  return run;
 }
 
 // src/protocols/evm/railgun/index.ts
@@ -1202,7 +2334,16 @@ var railgunProtocolModule = {
       params: {
         tokenAddress: { type: "string", required: true, description: "Shielded ERC-20" },
         amountWei: { type: "string", required: true, description: "Amount in wei" },
-        recipientAddress: { type: "string", required: true, description: "Recipient 0zk address" }
+        recipientAddress: {
+          type: "string",
+          required: false,
+          description: "Recipient 0zk address. Omit when toContactName is set."
+        },
+        toContactName: {
+          type: "string",
+          required: false,
+          description: "Address-book contact name. Uses that contact\u2019s saved 0zk address, not their Ethereum address."
+        }
       }
     },
     {
@@ -1221,6 +2362,6 @@ var railgunProtocolModule = {
 };
 registerProtocolModule(railgunProtocolModule);
 
-export { RAILGUN_CTM_DISABLED_MESSAGE, RAILGUN_CTM_ENABLED, RAILGUN_POPULAR_ASSET_LIMIT, RAILGUN_PROTOCOL_ID, RAILGUN_WALLET_LOCKED_MESSAGE, assertRailgunCtmAllowed, buildEvmMultisignBodyRailgunShield, buildEvmMultisignBodyWethUnwrap, clearRailgunNetworkCache, clearRailgunPopularAssetCache, clearRailgunPrivateBalanceSnapshots, commitmentsFromShieldIndex, createRailgunBrowserWallet, discardRailgunWallet, getRailgunWalletSession, loadRailgunNetworks, loadRailgunPopularAssets, loadRailgunSupportedChainIds, openRailgunViewOnlyWallet, publishRailgunPrivateBalanceSnapshot, railgunAddressIsValid, railgunFetchPopularAssets, railgunFetchPrivateBalances, railgunFetchPrivateBalancesSummary, railgunNetworkByChainId, railgunPrivateTransfer, railgunProtocolModule, railgunShareableViewingKey, railgunUnshield, rankPopularShieldTokens, readRailgunPrivateBalanceSnapshot, requireRailgunWalletSession, scanRailgunPrivateBalances, selectRailgunNetworks, setRailgunAllowanceReaderForTests, setRailgunPopulateShieldForTests, setRailgunShieldLogReaderForTests, setRailgunWalletSession, shieldIndexEndpoint, unlockRailgunBrowserWallet, utxoScanTerminalStatus };
+export { BROADCASTER_FEE_MIN_REMAINING_MS, BROADCASTER_PROOF_WAIT_MS, RAILGUN_CATCH_UP_MS, RAILGUN_CTM_DISABLED_MESSAGE, RAILGUN_CTM_ENABLED, RAILGUN_MERKLETREE_STALL_MS, RAILGUN_POPULAR_ASSET_LIMIT, RAILGUN_PROTOCOL_ID, RAILGUN_SCAN_BEHIND_NOTE, RAILGUN_SCAN_STOPPED_NOTE, RAILGUN_SPEND_SCAN_STOPPED, RAILGUN_TXID_WAIT_AFTER_NOTES_MS, RAILGUN_WALLET_LOCKED_MESSAGE, assertRailgunCtmAllowed, balancesToKeepAfterNoteScan, broadcasterAskedToRefreshProofStatus, broadcasterFeeStillValid, broadcasterRefusedForGas, buildEvmMultisignBodyRailgunShield, buildEvmMultisignBodyWethUnwrap, clearRailgunFeeCache, clearRailgunNetworkCache, clearRailgunPopularAssetCache, clearRailgunPrivateBalanceSnapshots, clearRailgunWalletBalances, commitmentsFromShieldIndex, createRailgunBrowserWallet, discardRailgunWallet, getRailgunWalletSession, listRailgunBroadcasters, loadRailgunNetworks, loadRailgunPopularAssets, loadRailgunSupportedChainIds, merkletreeScanStillRunning, openRailgunViewOnlyWallet, publishRailgunPrivateBalanceSnapshot, quoteRailgunBroadcasterFee, quoteRailgunBroadcasterFeeRate, quoteRailgunFee, railgunAddressIsValid, railgunDetailedError, railgunFetchPopularAssets, railgunFetchPrivateBalances, railgunFetchPrivateBalancesSummary, railgunNetworkByChainId, railgunPrivateTransfer, railgunProtocolFee, railgunProtocolModule, railgunScanRecord, railgunShareableViewingKey, railgunUnshield, railgunWalletBalanceSnapshot, rankPopularShieldTokens, readRailgunPrivateBalanceSnapshot, recordRailgunWalletBalance, requireRailgunWalletSession, scanRailgunPrivateBalances, scanSpendingWalletNotes, selectRailgunNetworks, setRailgunAllowanceReaderForTests, setRailgunPopulateShieldForTests, setRailgunShieldLogReaderForTests, setRailgunWalletSession, shieldIndexEndpoint, shieldPrivateKeyFromSignature, spendingNoteScanGaveUp, spendingScanReadyAfterHistory, unlockRailgunBrowserWallet, utxoScanTerminalStatus };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map