@cloak.dev/sdk 0.2.2 → 0.2.3-staging.f2d7f2a

package/dist/index.cjs

@@ -542,8 +542,10 @@ var init_utxo = __esm({
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  BRIDGE_ESCROW_LABEL: () => BRIDGE_ESCROW_LABEL,
   BUILD_ALLOWS_LOCAL_ENDPOINTS: () => BUILD_ALLOWS_LOCAL_ENDPOINTS,
   CHAIN_NOTE_SALT_BITS: () => CHAIN_NOTE_SALT_BITS,
+  CLEANUP_FEE_BUDGET: () => CLEANUP_FEE_BUDGET,
   CLOAK_PRODUCTION_RELAY_URL: () => CLOAK_PRODUCTION_RELAY_URL,
   CLOAK_PROGRAM_ID: () => CLOAK_PROGRAM_ID,
   CloakError: () => CloakError,
@@ -551,16 +553,25 @@ __export(index_exports, {
   DEFAULT_TRANSACTION_CIRCUITS_URL: () => DEFAULT_TRANSACTION_CIRCUITS_URL,
   DELIVERY_MEMO_TAG: () => DELIVERY_MEMO_TAG,
   DELIVERY_REGISTRY_SEED: () => DELIVERY_REGISTRY_SEED,
+  DepositError: () => DepositError,
+  DoNotRetry: () => DoNotRetry,
+  ECONOMIC_MINIMUM: () => ECONOMIC_MINIMUM,
   EXPECTED_CIRCUIT_HASHES: () => EXPECTED_CIRCUIT_HASHES,
+  FEE_BUDGET: () => FEE_BUDGET,
   FIXED_FEE_LAMPORTS: () => FIXED_FEE_LAMPORTS,
   InsecureRandomnessError: () => InsecureRandomnessError,
   LAMPORTS_PER_SOL: () => LAMPORTS_PER_SOL,
   LocalStorageAdapter: () => LocalStorageAdapter,
+  MAINNET_RENT_0: () => MAINNET_RENT_0,
+  MAINNET_RENT_1: () => MAINNET_RENT_1,
+  MAX_RECEIVER_INDEX: () => MAX_RECEIVER_INDEX,
   MERKLE_TREE_HEIGHT: () => MERKLE_TREE_HEIGHT2,
   MIN_DEPOSIT_LAMPORTS: () => MIN_DEPOSIT_LAMPORTS,
+  MIN_DEPOSIT_SPL_BASE_UNITS: () => MIN_DEPOSIT_SPL_BASE_UNITS,
   MemoryStorageAdapter: () => MemoryStorageAdapter,
   MerkleTree: () => MerkleTree,
   NATIVE_SOL_MINT: () => NATIVE_SOL_MINT,
+  ONECLICK_PUBKEY_B58: () => ONECLICK_PUBKEY_B58,
   RECIPIENT_DELIVERY_CIPHERTEXT_LEN: () => RECIPIENT_DELIVERY_CIPHERTEXT_LEN,
   RECIPIENT_DELIVERY_EPHEMERAL_PK_LEN: () => RECIPIENT_DELIVERY_EPHEMERAL_PK_LEN,
   RECIPIENT_DELIVERY_NONCE_LEN: () => RECIPIENT_DELIVERY_NONCE_LEN,
@@ -579,6 +590,7 @@ __export(index_exports, {
   SettlementVerificationError: () => SettlementVerificationError,
   ShieldPoolErrors: () => ShieldPoolErrors,
   SimpleWallet: () => SimpleWallet,
+  TERMINAL_FAILURE: () => TERMINAL_FAILURE,
   TRANSACTION_CIRCUITS_VERSION: () => TRANSACTION_CIRCUITS_VERSION,
   TRANSACT_AUTH_FIELDS: () => TRANSACT_AUTH_FIELDS,
   TRANSACT_SWAP_AUTH_FIELDS: () => TRANSACT_SWAP_AUTH_FIELDS,
@@ -588,8 +600,12 @@ __export(index_exports, {
   VARIABLE_FEE_NUMERATOR: () => VARIABLE_FEE_NUMERATOR,
   VARIABLE_FEE_RATE: () => VARIABLE_FEE_RATE,
   VERSION: () => VERSION,
+  WITHDRAW_FEE_BPS: () => WITHDRAW_FEE_BPS,
+  WITHDRAW_FIXED_FEE: () => WITHDRAW_FIXED_FEE,
   assertDirectSubmissionLanded: () => assertDirectSubmissionLanded,
+  assertInputMints: () => assertInputMints,
   assertTransactionCircuitIntegrity: () => assertTransactionCircuitIntegrity,
+  assessBridgeQuote: () => assessBridgeQuote,
   bigintToBytes32: () => bigintToBytes32,
   bigintToHex: () => bigintToHex,
   buildMerkleTree: () => buildMerkleTree,
@@ -604,12 +620,16 @@ __export(index_exports, {
   calculateRelayFee: () => calculateRelayFee,
   canRebuildMerkleTreeFromChain: () => canRebuildMerkleTreeFromChain,
   canonicalJson: () => canonicalJson,
+  canonicalPayloadString: () => canonicalPayloadString,
   chainNoteFromBase64: () => chainNoteFromBase64,
   chainNoteToBase64: () => chainNoteToBase64,
+  classifyPostFailure: () => classifyPostFailure,
   classifyRelayError: () => classifyRelayError,
+  cleanupReceivingAddress: () => cleanupReceivingAddress,
   cleanupStalePendingOperations: () => cleanupStalePendingOperations,
   clearPendingDeposits: () => clearPendingDeposits,
   clearPendingWithdrawals: () => clearPendingWithdrawals,
+  cloakBridgeRail: () => cloakBridgeRail,
   computeChainNoteHash: () => computeChainNoteHash,
   computeExtDataHash: () => computeExtDataHash,
   computeMerkleRoot: () => computeMerkleRoot,
@@ -631,10 +651,13 @@ __export(index_exports, {
   decryptCompactChainNote: () => decryptCompactChainNote,
   decryptComplianceMetadataWithMasterKey: () => decryptComplianceMetadataWithMasterKey,
   decryptTransactionMetadata: () => decryptTransactionMetadata,
+  depositFromDerivedKey: () => depositFromDerivedKey,
+  deriveBridgeReceiver: () => deriveBridgeReceiver,
   deriveChangeNoteBlinding: () => deriveChangeNoteBlinding,
   deriveDepositNoteSecrets: () => deriveDepositNoteSecrets,
   deriveDiversifiedViewingKey: () => deriveDiversifiedViewingKey,
   deriveDiversifier: () => deriveDiversifier,
+  deriveFundingTargets: () => deriveFundingTargets,
   deriveInputNullifierPdas: () => deriveInputNullifierPdas,
   derivePublicKey: () => derivePublicKey,
   deriveSpendKey: () => deriveSpendKey,
@@ -673,6 +696,7 @@ __export(index_exports, {
   formatErrorForLogging: () => formatErrorForLogging,
   formatSol: () => formatSol,
   fullWithdraw: () => fullWithdraw,
+  fundReceiverViaPaymaster: () => fundReceiverViaPaymaster,
   generateCloakKeys: () => generateCloakKeys,
   generateCommitmentAsync: () => generateCommitmentAsync,
   generateMasterSeed: () => generateMasterSeed,
@@ -708,18 +732,21 @@ __export(index_exports, {
   isReactNative: () => isReactNative,
   isRootNotFoundError: () => isRootNotFoundError,
   isSubmissionOutcomeUnknownResponse: () => isSubmissionOutcomeUnknownResponse,
+  isTerminalFailure: () => isTerminalFailure,
   isValidHex: () => isValidHex,
   isValidRpcUrl: () => isValidRpcUrl,
   isValidSolanaAddress: () => isValidSolanaAddress,
   isWithdrawAmountSufficient: () => isWithdrawAmountSufficient,
   isWithdrawable: () => isWithdrawable,
   keypairToAdapter: () => keypairToAdapter,
+  listBridgeDeposits: () => listBridgeDeposits,
   loadPendingDeposits: () => loadPendingDeposits,
   loadPendingWithdrawals: () => loadPendingWithdrawals,
   loadVerifiedCircuitArtifacts: () => loadVerifiedCircuitArtifacts,
   matchChangeNote: () => matchChangeNote,
   matchDepositNote: () => matchDepositNote,
   matchSwapRefundLeaf: () => matchSwapRefundLeaf,
+  mayRetry: () => mayRetry,
   openRecipientDeliveryNote: () => openRecipientDeliveryNote,
   parseAmount: () => parseAmount,
   parseDeliveryCarrierMemo: () => parseDeliveryCarrierMemo,
@@ -742,11 +769,14 @@ __export(index_exports, {
   randomDepositNoteSalt: () => randomDepositNoteSalt,
   randomFieldElement: () => randomFieldElement,
   readMerkleTreeState: () => readMerkleTreeState,
+  readRent: () => readRent,
   recipientDeliveryNoteToBase64: () => recipientDeliveryNoteToBase64,
   registerViewingKey: () => registerViewingKey,
   removePendingDeposit: () => removePendingDeposit,
   removePendingWithdrawal: () => removePendingWithdrawal,
+  renderAssessment: () => renderAssessment,
   resolveCircuitsBase: () => resolveCircuitsBase,
+  retryDelayMs: () => retryDelayMs,
   savePendingDeposit: () => savePendingDeposit,
   savePendingWithdrawal: () => savePendingWithdrawal,
   scanNotesForWallet: () => scanNotesForWallet,
@@ -779,15 +809,19 @@ __export(index_exports, {
   validateDepositParams: () => validateDepositParams,
   validateNote: () => validateNote,
   validateOutputsSum: () => validateOutputsSum,
+  validatePaymasterTopUpTransaction: () => validatePaymasterTopUpTransaction,
   validateRoot: () => validateRoot,
   validateTransfers: () => validateTransfers,
   validateWalletConnected: () => validateWalletConnected,
   validateWithdrawableNote: () => validateWithdrawableNote,
   verifyAllCircuits: () => verifyAllCircuits,
   verifyCircuitIntegrity: () => verifyCircuitIntegrity,
+  verifyQuoteSignature: () => verifyQuoteSignature,
   verifyUtxos: () => verifyUtxos,
   waitForRoot: () => waitForRoot,
-  withTiming: () => withTiming
+  withShieldRetries: () => withShieldRetries,
+  withTiming: () => withTiming,
+  withdrawFeeFor: () => withdrawFeeFor
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -1391,7 +1425,7 @@ function parseStrictViewingKeyChallenge(response, userPubkey, viewingKeyHex) {
 
 // src/config/relay.ts
 var CLOAK_PRODUCTION_RELAY_URL = "https://api.cloak.ag";
-var RELAY_ORIGIN_ALLOWLIST = [CLOAK_PRODUCTION_RELAY_URL];
+var RELAY_ORIGIN_ALLOWLIST = ["https://staging-api.cloak.ag"];
 var ABSOLUTE_URL = /^[a-z][a-z0-9+.-]*:\/\//i;
 var LOOPBACK_IPV4 = /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/;
 var THIS_NETWORK_IPV4 = /^0\.\d{1,3}\.\d{1,3}\.\d{1,3}$/;
@@ -2929,8 +2963,8 @@ async function verifyUtxos(utxos, connection, programId, commitment = "confirmed
       const nullifierHex = nullifierBig.toString(16).padStart(64, "0");
       const nullifierBytes = Buffer.from(nullifierHex, "hex");
       const { pool } = getShieldPoolPDAs(programId, utxo.mintAddress);
-      const [pda] = getNullifierPDA(pool, nullifierBytes, programId);
-      checkable.push({ utxo, pda });
+      const [pda2] = getNullifierPDA(pool, nullifierBytes, programId);
+      checkable.push({ utxo, pda: pda2 });
     } catch {
       skipped.push(utxo);
     }
@@ -3000,8 +3034,8 @@ function deriveInputNullifierPdas(programId, mint, inputNullifiers) {
   const pdas = [];
   for (const nullifier of inputNullifiers) {
     if (nullifier === BigInt(0)) continue;
-    const [pda] = getNullifierPDA(pool, bigintToBytes324(nullifier), programId);
-    pdas.push(pda);
+    const [pda2] = getNullifierPDA(pool, bigintToBytes324(nullifier), programId);
+    pdas.push(pda2);
   }
   return pdas;
 }
@@ -4320,7 +4354,7 @@ async function fetchWithRetry(url, options = {}) {
   const {
     timeoutMs = DEFAULT_TIMEOUT_MS,
     maxRetries = DEFAULT_MAX_RETRIES,
-    retryDelayMs = 1e3
+    retryDelayMs: retryDelayMs2 = 1e3
   } = options;
   assertAllowedRelayOrigin(url);
   let lastError = null;
@@ -4344,7 +4378,7 @@ async function fetchWithRetry(url, options = {}) {
           `Relay request failed after ${attempt + 1} attempts: ${lastError.message}`
         );
       }
-      const delay = retryDelayMs * Math.pow(2, attempt) + Math.random() * 500;
+      const delay = retryDelayMs2 * Math.pow(2, attempt) + Math.random() * 500;
       await new Promise((resolve) => setTimeout(resolve, delay));
     }
   }
@@ -6220,6 +6254,23 @@ async function computeSwapExtDataHash(outputMint, recipientAta, minOutputAmount,
   ]);
   return poseidonHasher.F.toObject(hash);
 }
+function assertInputMints(inputUtxos, expectedMint) {
+  const funded = inputUtxos.filter((u) => u.amount > BigInt(0));
+  if (funded.length === 0) return;
+  const first = funded[0].mintAddress;
+  for (const utxo of funded) {
+    if (!utxo.mintAddress.equals(first)) {
+      throw new Error(
+        `Input notes span more than one mint (${first.toBase58()} and ${utxo.mintAddress.toBase58()}). Every pool holds a single mint, so this cannot be a valid spend of either. Select notes of one mint.`
+      );
+    }
+  }
+  if (expectedMint && !first.equals(expectedMint)) {
+    throw new Error(
+      `Input notes are ${first.toBase58()} but this transaction expects ${expectedMint.toBase58()}. The notes decide which pool is spent, so proceeding would move the wrong asset \u2014 refusing. This usually means note selection ignored the mint.`
+    );
+  }
+}
 function parseNkInput(input) {
   if (typeof input !== "string") {
     if (input.length !== 32) {
@@ -7831,7 +7882,7 @@ async function transact(params, options) {
     // names is refused.
     maxRootRetries = 40,
     // Increased to handle prolonged relay sync recovery under high concurrency
-    retryDelayMs = 500,
+    retryDelayMs: retryDelayMs2 = 500,
     // Start with short delay, will exponentially back off
     riskOracleQueue,
     riskQuoteUrl: riskQuoteUrlOption,
@@ -7886,6 +7937,7 @@ async function transact(params, options) {
     }
   }
   assertAllowedRpcConnection(connection);
+  assertInputMints(inputUtxos, options.expectedMint);
   await ensureViewingKeyRegistered(options, onProgress, fallbackNk);
   const resolvedChainNoteNk = explicitChainNoteNk ?? fallbackNk ?? null;
   if (inputUtxos.length > 2) {
@@ -8252,7 +8304,7 @@ async function transact(params, options) {
   while (submissionAttempts <= maxRootRetries) {
     const isRetry = submissionAttempts > 0;
     if (isRetry) {
-      const exponentialDelay = Math.min(retryDelayMs * Math.pow(1.5, submissionAttempts - 1), 5e3);
+      const exponentialDelay = Math.min(retryDelayMs2 * Math.pow(1.5, submissionAttempts - 1), 5e3);
       const jitter = Math.random() * 500;
       const totalDelay = Math.floor(exponentialDelay + jitter);
       await sleep2(totalDelay);
@@ -8415,7 +8467,7 @@ async function transact(params, options) {
         }
         treeState = null;
         useSiblingInfo = false;
-        const waitMs = Math.min(retryDelayMs * Math.pow(2, Math.min(submissionAttempts, 4)), 5e3);
+        const waitMs = Math.min(retryDelayMs2 * Math.pow(2, Math.min(submissionAttempts, 4)), 5e3);
         if (waitMs > 0) {
           onProgress?.(`Waiting ${waitMs}ms for relay sync before retry...`);
           await new Promise((r) => setTimeout(r, waitMs));
@@ -9109,7 +9161,7 @@ async function swapUtxo(params, options) {
     riskQuoteUrl: riskQuoteUrlOption,
     maxRootRetries = 40,
     // Increased to handle prolonged relay sync recovery under high concurrency
-    retryDelayMs = 500,
+    retryDelayMs: retryDelayMs2 = 500,
     // Start with short delay, will exponentially back off
     useUniqueNullifiers,
     useChainRootForProof = true
@@ -9128,6 +9180,12 @@ async function swapUtxo(params, options) {
   if (inputUtxos.length > 2) {
     throw new Error("Maximum 2 input UTXOs allowed");
   }
+  assertInputMints(inputUtxos, NATIVE_SOL_MINT);
+  if (options.expectedMint && !options.expectedMint.equals(NATIVE_SOL_MINT)) {
+    throw new Error(
+      `swapUtxo expects ${NATIVE_SOL_MINT.toBase58()} input notes (a swap always spends from the wSOL pool), but expectedMint was ${options.expectedMint.toBase58()}. Drop expectedMint, or spend the other mint with transact/transfer instead.`
+    );
+  }
   await preflightNullifiers(inputUtxos, connection, programId);
   const outputMintAccount = await connection.getAccountInfo(outputMint, {
     commitment: "confirmed"
@@ -9514,7 +9572,7 @@ async function swapUtxo(params, options) {
   let walletApprovals = 0;
   for (let attempt = 0; attempt <= maxRootRetries; attempt++) {
     if (attempt > 0) {
-      const exponentialDelay = Math.min(retryDelayMs * Math.pow(1.5, attempt - 1), 5e3);
+      const exponentialDelay = Math.min(retryDelayMs2 * Math.pow(1.5, attempt - 1), 5e3);
       const jitter = Math.random() * 500;
       const totalDelay = Math.floor(exponentialDelay + jitter);
       await sleep2(totalDelay);
@@ -9652,7 +9710,7 @@ async function swapUtxo(params, options) {
         }
         merkleState = null;
         useSiblingInfo = false;
-        const waitMs = Math.min(retryDelayMs * Math.pow(2, Math.min(attempt, 4)), 5e3);
+        const waitMs = Math.min(retryDelayMs2 * Math.pow(2, Math.min(attempt, 4)), 5e3);
         if (waitMs > 0) {
           onProgress?.(`Waiting ${waitMs}ms for relay sync before retry...`);
           await new Promise((r) => setTimeout(r, waitMs));
@@ -11632,13 +11690,781 @@ var SimpleWallet = class {
   }
 };
 
+// src/bridge/rail-verify.ts
+var import_tweetnacl7 = __toESM(require("tweetnacl"), 1);
+var import_sha256 = require("@noble/hashes/sha256");
+var ONECLICK_PUBKEY_B58 = "reYaWhvwu8Jzo3WUM3zhn6VrhuMEF4eADL17qtRVifc";
+var b58 = /* @__PURE__ */ (() => {
+  const A = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+  return {
+    decode(s) {
+      let n = 0n;
+      for (const c of s) {
+        const i = A.indexOf(c);
+        if (i < 0) throw new Error("bad base58");
+        n = n * 58n + BigInt(i);
+      }
+      const bytes = [];
+      while (n > 0n) {
+        bytes.unshift(Number(n & 255n));
+        n >>= 8n;
+      }
+      for (const c of s) {
+        if (c === "1") bytes.unshift(0);
+        else break;
+      }
+      return Uint8Array.from(bytes);
+    },
+    encode(b) {
+      let n = 0n;
+      for (const x of b) n = n * 256n + BigInt(x);
+      let s = "";
+      while (n > 0n) {
+        s = A[Number(n % 58n)] + s;
+        n /= 58n;
+      }
+      for (const x of b) {
+        if (x === 0) s = "1" + s;
+        else break;
+      }
+      return s;
+    }
+  };
+})();
+function stable(v) {
+  if (v === null || typeof v !== "object") return JSON.stringify(v) ?? "null";
+  if (Array.isArray(v)) return `[${v.map(stable).join(",")}]`;
+  const o = v;
+  const parts = Object.keys(o).sort().filter((k) => o[k] !== void 0).map((k) => `${JSON.stringify(k)}:${stable(o[k])}`);
+  return `{${parts.join(",")}}`;
+}
+function signedRequest(r) {
+  const q = r.quoteRequest ?? {};
+  return {
+    dry: q.dry,
+    swapType: q.swapType,
+    slippageTolerance: q.slippageTolerance,
+    originAsset: q.originAsset,
+    depositType: q.depositType,
+    destinationAsset: q.destinationAsset,
+    amount: q.amount,
+    refundTo: q.refundTo,
+    refundType: q.refundType,
+    recipient: q.recipient,
+    recipientType: q.recipientType,
+    deadline: q.deadline,
+    quoteWaitingTimeMs: q.quoteWaitingTimeMs || void 0,
+    referral: q.referral || void 0,
+    virtualChainRecipient: q.virtualChainRecipient || void 0,
+    virtualChainRefundRecipient: q.virtualChainRefundRecipient || void 0,
+    customRecipientMsg: q.customRecipientMsg || void 0
+    // Deliberately unsigned by the rail: sessionId, connectedWallets, correlationId, appFees,
+    // partnerId, userAccountId, depositMode. APP FEES ARE NOT AUTHENTICATED — never display a fee
+    // caption as if the signature vouched for it.
+  };
+}
+function signedQuote(r) {
+  const q = r.quote ?? {};
+  const base = {
+    amountIn: q.amountIn,
+    amountInFormatted: q.amountInFormatted,
+    amountInUsd: q.amountInUsd,
+    minAmountIn: q.minAmountIn,
+    amountOut: q.amountOut,
+    amountOutFormatted: q.amountOutFormatted,
+    amountOutUsd: q.amountOutUsd,
+    minAmountOut: q.minAmountOut
+  };
+  if (r.quoteRequest?.dry) return base;
+  return {
+    ...base,
+    depositAddress: q.depositAddress || void 0,
+    // <- the field that makes substitution detectable
+    depositMemo: q.depositMemo || void 0,
+    deadline: q.deadline || void 0,
+    // <- a real, SIGNED expiry
+    timeWhenInactive: q.timeWhenInactive || void 0,
+    timeEstimate: q.timeEstimate || void 0,
+    virtualChainRecipient: q.virtualChainRecipient || void 0,
+    virtualChainRefundRecipient: q.virtualChainRefundRecipient || void 0,
+    customRecipientMsg: q.customRecipientMsg || void 0,
+    refundFee: q.refundFee || void 0,
+    withdrawFee: q.withdrawFee || void 0
+  };
+}
+function canonicalPayloadString(resp) {
+  return stable({ ...signedRequest(resp), ...signedQuote(resp), timestamp: resp.timestamp });
+}
+function verifyQuoteSignature(resp) {
+  if (!resp?.signature) return { valid: false, reason: "no signature on the response" };
+  const payload = { ...signedRequest(resp), ...signedQuote(resp), timestamp: resp.timestamp };
+  const digest = (0, import_sha256.sha256)(new TextEncoder().encode(stable(payload)));
+  const message = new TextEncoder().encode(b58.encode(new Uint8Array(digest)));
+  const sig = resp.signature.replace(/^ed25519:/, "");
+  try {
+    return { valid: import_tweetnacl7.default.sign.detached.verify(message, b58.decode(sig), b58.decode(ONECLICK_PUBKEY_B58)) };
+  } catch (e) {
+    return { valid: false, reason: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+// src/bridge/rails.ts
+async function parseBridgeResponse(res, what) {
+  let body;
+  try {
+    body = await res.json();
+  } catch {
+    throw new Error(`${what} failed: ${res.status} ${res.statusText} (response body was not JSON)`);
+  }
+  if (!res.ok) {
+    const b = body ?? {};
+    throw new Error(
+      `${what} failed: ${b.message ?? res.statusText} (${b.code ?? res.status}${b.retryable ? ", retryable" : ""})`
+    );
+  }
+  return body;
+}
+function toAttestation(raw) {
+  if (raw.kind === "ed25519") {
+    return { kind: "ed25519", verified: raw.verified ?? false, signer: raw.signer ?? "" };
+  }
+  return { kind: "none", checks: raw.checks ?? [], note: raw.note ?? "" };
+}
+async function fetchBridgeQuote(relayUrl, req) {
+  const body = {
+    recipient: req.recipient,
+    origin_chain: req.originChain,
+    amount_base_units: req.amountBaseUnits.toString(),
+    allocate: req.allocate ?? false
+  };
+  if (req.refundTo !== void 0) body.refund_to = req.refundTo;
+  if (req.rails !== void 0) body.rails = req.rails;
+  const res = await relayFetch(`${relayUrl}/bridge/quote`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  const raw = await parseBridgeResponse(res, "bridge quote");
+  const options = [];
+  const unavailable = (raw.unavailable ?? []).map((p) => ({
+    rail: p.rail,
+    reason: p.reason
+  }));
+  for (const opt of raw.options) {
+    const attestation = toAttestation(opt.attestation);
+    if (attestation.kind === "ed25519") {
+      const verdict = opt.rail_response ? verifyQuoteSignature(opt.rail_response) : { valid: false, reason: "no rail_response to verify against" };
+      if (!verdict.valid) {
+        unavailable.push({
+          rail: opt.rail,
+          reason: `deposit address failed independent signature verification, refusing to display it (${verdict.reason ?? "signature did not verify"})`
+        });
+        continue;
+      }
+    }
+    options.push({
+      rail: opt.rail,
+      refunds: opt.refunds,
+      addressLifetime: opt.address_lifetime,
+      amountOut: BigInt(opt.amount_out),
+      minAmountOut: BigInt(opt.min_amount_out),
+      timeEstimateSeconds: opt.time_estimate_s,
+      expiresAt: opt.expires_at,
+      depositAddress: opt.deposit_address,
+      attestation
+    });
+  }
+  return { options, unavailable };
+}
+var STATUS_STATES = [
+  "pending",
+  "delivered",
+  "refunded",
+  "expired",
+  "unknown"
+];
+async function fetchBridgeStatus(relayUrl, depositAddress, rail) {
+  const qs = new URLSearchParams({ deposit_address: depositAddress, rail });
+  const res = await relayFetch(`${relayUrl}/bridge/status?${qs.toString()}`);
+  const raw = await parseBridgeResponse(res, "bridge status");
+  const state = STATUS_STATES.includes(raw.state ?? "") ? raw.state : "unknown";
+  return { rail: raw.rail ?? rail, state, detail: raw.detail ?? "" };
+}
+function cloakBridgeRail(relayUrl) {
+  assertAllowedRelayOrigin(relayUrl);
+  return {
+    id: "cloak-bridge",
+    quote: (req) => fetchBridgeQuote(relayUrl, req),
+    status: (depositAddress, rail) => fetchBridgeStatus(relayUrl, depositAddress, rail)
+  };
+}
+
+// src/bridge/paymaster-client.ts
+var import_web312 = require("@solana/web3.js");
+var import_spl_token3 = require("@solana/spl-token");
+function validatePaymasterTopUpTransaction(tx, expect) {
+  const ixs = tx.instructions;
+  if (ixs.length !== 1 && ixs.length !== 2) {
+    throw new Error(
+      `paymaster top-up must be exactly 1 or 2 instructions, got ${ixs.length} \u2014 refusing to sign a transaction whose shape does not match the documented top-up contract`
+    );
+  }
+  const ix0 = ixs[0];
+  if (!ix0.programId.equals(import_web312.SystemProgram.programId)) {
+    throw new Error(
+      `paymaster top-up instruction 0 is owned by ${ix0.programId.toBase58()}, not the System Program \u2014 refusing to sign an unrecognised first instruction`
+    );
+  }
+  const transfer2 = import_web312.SystemInstruction.decodeTransfer(ix0);
+  if (!transfer2.toPubkey.equals(expect.recipient)) {
+    throw new Error(
+      `paymaster top-up sends SOL to ${transfer2.toPubkey.toBase58()}, which is not our recipient ${expect.recipient.toBase58()} \u2014 refusing to sign a transaction that funds a key we do not control`
+    );
+  }
+  if (BigInt(transfer2.lamports) > expect.maxGrantLamports) {
+    throw new Error(
+      `paymaster top-up grants ${transfer2.lamports} lamports, more than the ${expect.maxGrantLamports} we asked for \u2014 refusing a transaction that funds beyond our own request`
+    );
+  }
+  if (ixs.length === 1) return;
+  const ix1 = ixs[1];
+  if (!ix1.programId.equals(import_spl_token3.TOKEN_PROGRAM_ID)) {
+    throw new Error(
+      `paymaster top-up instruction 1 is owned by ${ix1.programId.toBase58()}, not the SPL Token program \u2014 refusing to sign an unrecognised second instruction`
+    );
+  }
+  const spl = (0, import_spl_token3.decodeTransferInstruction)(ix1, import_spl_token3.TOKEN_PROGRAM_ID);
+  const authority = spl.keys.owner.pubkey;
+  if (!authority.equals(expect.recipient)) {
+    throw new Error(
+      `paymaster top-up's fee transfer is authorised by ${authority.toBase58()}, not our recipient ${expect.recipient.toBase58()} \u2014 refusing to sign away tokens from an account we do not control`
+    );
+  }
+  const expectedDestination = (0, import_spl_token3.getAssociatedTokenAddressSync)(
+    expect.feeMint,
+    expect.paymentAddress,
+    false
+  );
+  const destination = spl.keys.destination.pubkey;
+  if (!destination.equals(expectedDestination)) {
+    throw new Error(
+      `paymaster top-up's fee transfer is addressed to ${destination.toBase58()}, not the paymaster's own payment ATA ${expectedDestination.toBase58()} \u2014 refusing to sign a payment to an unverified destination`
+    );
+  }
+  const paidAmount = BigInt(spl.data.amount);
+  if (paidAmount !== expect.feeTokenAmount) {
+    throw new Error(
+      `paymaster top-up's fee amount is ${paidAmount}, not the ${expect.feeTokenAmount} Kora quoted at prepare time \u2014 refusing to sign a payment that does not match the quote`
+    );
+  }
+}
+async function parseBridgeResponse2(res, what) {
+  let body;
+  try {
+    body = await res.json();
+  } catch {
+    throw new Error(`${what} failed: ${res.status} ${res.statusText} (response body was not JSON)`);
+  }
+  if (!res.ok) {
+    const b = body ?? {};
+    throw new Error(
+      `${what} failed: ${b.message ?? res.statusText} (${b.code ?? res.status}${b.retryable ? ", retryable" : ""})`
+    );
+  }
+  return body;
+}
+async function fundReceiverViaPaymaster(relayUrl, receiver, grantLamports) {
+  assertAllowedRelayOrigin(relayUrl);
+  if (grantLamports <= 0n || grantLamports > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new Error(
+      `grantLamports must be a positive value representable as a JS number, got ${grantLamports}`
+    );
+  }
+  const prepareRes = await relayFetch(`${relayUrl}/bridge/paymaster/prepare`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      recipient: receiver.publicKey.toBase58(),
+      grant_lamports: Number(grantLamports)
+    })
+  });
+  const prepared = await parseBridgeResponse2(prepareRes, "paymaster prepare");
+  if (Math.floor(Date.now() / 1e3) >= prepared.expires_at_unix) {
+    throw new Error(
+      "paymaster prepare returned a voucher that is already expired \u2014 refusing to sign a stale top-up rather than fail confusingly at cosign"
+    );
+  }
+  const feeMint = new import_web312.PublicKey(prepared.fee_mint);
+  const paymentAddress = new import_web312.PublicKey(prepared.payment_address);
+  const feeTokenAmount = BigInt(prepared.fee_token_amount);
+  const tx = import_web312.Transaction.from(Buffer.from(prepared.transaction, "base64"));
+  validatePaymasterTopUpTransaction(tx, {
+    recipient: receiver.publicKey,
+    maxGrantLamports: grantLamports,
+    feeMint,
+    feeTokenAmount,
+    paymentAddress
+  });
+  tx.partialSign(receiver);
+  const cosignRes = await relayFetch(`${relayUrl}/bridge/paymaster/cosign`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      transaction: tx.serialize({ requireAllSignatures: false, verifySignatures: false }).toString("base64"),
+      voucher: prepared.voucher
+    })
+  });
+  const cosigned = await parseBridgeResponse2(cosignRes, "paymaster cosign");
+  return {
+    transaction: import_web312.Transaction.from(Buffer.from(cosigned.transaction, "base64")),
+    feeTokenAmount,
+    feeMint: prepared.fee_mint,
+    paymentAddress: prepared.payment_address
+  };
+}
+
+// src/bridge/derive.ts
+var import_web313 = require("@solana/web3.js");
+var import_hmac = require("@noble/hashes/hmac");
+var import_sha512 = require("@noble/hashes/sha512");
+var BRIDGE_ESCROW_LABEL = "cloak_bridge_escrow";
+var MAX_RECEIVER_INDEX = 1e4;
+function deriveBridgeReceiver(nk, index) {
+  if (!Number.isInteger(index) || index < 0) {
+    throw new Error(`index must be a non-negative integer, got ${index}`);
+  }
+  if (index > MAX_RECEIVER_INDEX) {
+    throw new Error(
+      `index ${index} exceeds MAX_RECEIVER_INDEX (${MAX_RECEIVER_INDEX}). Indices must be a small sequential counter \u2014 discovery derives 0\u2026N and reads each on chain, so a timestamp index is unreachable by any scan and the deposit would be invisible to every device but this one.`
+    );
+  }
+  const h = (0, import_hmac.hmac)(import_sha512.sha512, new Uint8Array(nk), new TextEncoder().encode(`${BRIDGE_ESCROW_LABEL}:${index}`));
+  return import_web313.Keypair.fromSeed(h.slice(0, 32));
+}
+
+// src/bridge/discover.ts
+var import_web314 = require("@solana/web3.js");
+var import_spl_token4 = require("@solana/spl-token");
+function describeError(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+async function listBridgeDeposits(conn, nk, opts) {
+  const scanDepth = Math.min(opts.scanDepth ?? 20, MAX_RECEIVER_INDEX + 1);
+  const stopAfterUnused = opts.stopAfterUnused ?? 5;
+  const out = [];
+  let consecutiveUnused = 0;
+  for (let index = 0; index < scanDepth; index++) {
+    const kp = deriveBridgeReceiver(nk, index);
+    const receiver = kp.publicKey;
+    const tokenAccount = (0, import_spl_token4.getAssociatedTokenAddressSync)(opts.mint, receiver, false);
+    try {
+      const [recvInfo, ataInfo] = await conn.getMultipleAccountsInfo([receiver, tokenAccount]);
+      const lamports = recvInfo?.lamports ?? 0;
+      let tokenBalance = 0n;
+      if (ataInfo) {
+        try {
+          tokenBalance = BigInt((await conn.getTokenAccountBalance(tokenAccount)).value.amount);
+        } catch (err) {
+          if (!(err instanceof import_web314.SolanaJSONRPCError && /could not find account/i.test(err.message))) {
+            throw err;
+          }
+        }
+      }
+      if (lamports === 0 && !ataInfo) {
+        consecutiveUnused++;
+        if (consecutiveUnused >= stopAfterUnused) break;
+        continue;
+      }
+      consecutiveUnused = 0;
+      const shieldSignatures = [];
+      const sigs = await conn.getSignaturesForAddress(receiver, { limit: 20 });
+      for (const s of sigs) {
+        if (s.err) continue;
+        const tx = await conn.getTransaction(s.signature, { maxSupportedTransactionVersion: 0 });
+        const keys = tx?.transaction.message.getAccountKeys({
+          accountKeysFromLookups: tx.meta?.loadedAddresses
+        });
+        if (keys && [...Array(keys.length).keys()].some((i) => keys.get(i)?.equals(opts.programId))) {
+          shieldSignatures.push(s.signature);
+        }
+      }
+      const shieldSignature = shieldSignatures[0];
+      const indexReused = shieldSignatures.length > 1;
+      let state;
+      if (tokenBalance > 0n) state = shieldSignature ? "needs-cleanup" : "arrived";
+      else if (shieldSignature) state = ataInfo ? "needs-cleanup" : "complete";
+      else state = "awaiting";
+      out.push({
+        index,
+        receiver,
+        tokenAccount,
+        state,
+        tokenBalance,
+        lamports,
+        shieldSignature,
+        ...indexReused ? { indexReused, shieldSignatures } : {}
+      });
+    } catch (err) {
+      out.push({
+        index,
+        receiver,
+        tokenAccount,
+        state: "unknown",
+        tokenBalance: 0n,
+        lamports: 0,
+        error: describeError(err)
+      });
+    }
+  }
+  return out;
+}
+
+// src/bridge/deposit-core.ts
+var import_web316 = require("@solana/web3.js");
+var import_tweetnacl8 = __toESM(require("tweetnacl"), 1);
+init_utxo();
+
+// src/bridge/funder.ts
+var import_web315 = require("@solana/web3.js");
+var import_spl_token5 = require("@solana/spl-token");
+var MAINNET_RENT_0 = 890880;
+var MAINNET_RENT_1 = 897840;
+var FEE_BUDGET = 13e4;
+var CLEANUP_FEE_BUDGET = 5e3;
+var pda = (seeds, programId) => import_web315.PublicKey.findProgramAddressSync(seeds.map((s) => Buffer.from(s)), programId)[0];
+function deriveFundingTargets(d) {
+  const pool = pda([Buffer.from("pool"), d.mint.toBuffer()], d.programId);
+  return {
+    pool,
+    // program: NullifierAccount::derive_pda_with_pool -> [b"nullifier", pool, nullifier]
+    nullifier0: pda([Buffer.from("nullifier"), pool.toBuffer(), d.nullifiers[0]], d.programId),
+    nullifier1: pda([Buffer.from("nullifier"), pool.toBuffer(), d.nullifiers[1]], d.programId),
+    // relay: derive_risk_nonce_pda -> [b"risk_nonce", bind0]
+    riskNonce: pda([Buffer.from("risk_nonce"), d.bind0], d.programId),
+    depositorAta: (0, import_spl_token5.getAssociatedTokenAddressSync)(d.mint, d.depositor, false)
+  };
+}
+async function readRent(conn) {
+  const [zero, one] = await Promise.all([
+    conn.getMinimumBalanceForRentExemption(0),
+    conn.getMinimumBalanceForRentExemption(1)
+  ]);
+  return { zero, one };
+}
+
+// src/bridge/deposit-core.ts
+var DepositError = class extends Error {
+  constructor(message, fundedAccounts, measuredTxSize) {
+    super(message);
+    this.fundedAccounts = fundedAccounts;
+    this.measuredTxSize = measuredTxSize;
+    this.name = "DepositError";
+  }
+};
+async function depositFromDerivedKey(conn, R, funder, amount, log = console.log, grantOverride, opts) {
+  if (!opts.noteSpendKey || opts.noteSpendKey.length !== 32) {
+    throw new Error(
+      "opts.noteSpendKey (32 bytes) is required. It derives the note's spending key, and a note whose key is not derived from something you can reproduce is unspendable forever. Pass the same Cloak seed you derived the receiving address from."
+    );
+  }
+  if (!opts.relayUrl) {
+    throw new Error(
+      "opts.relayUrl is required. There is no default: a missing relay used to resolve silently to the local stack, which is how a live run built a deposit against infrastructure that only existed on someone's laptop. Say which relay, every call."
+    );
+  }
+  if (!opts.programId) {
+    throw new Error(
+      "opts.programId is required. There is no default: this is the exact field a live mainnet run once inherited from this module's local-stack constant, built a deposit against a program that does not exist on mainnet, and failed hunting a merkle tree that was never there."
+    );
+  }
+  if (!opts.mint) {
+    throw new Error(
+      "opts.mint is required. There is no default: a deposit built for the wrong mint produces a note for an asset that never arrived at R, and there is nothing to silently fall back to."
+    );
+  }
+  assertAllowedRpcConnection(conn);
+  const relayUrl = opts.relayUrl;
+  const programId = opts.programId;
+  const mint = opts.mint;
+  setCircuitsPath(resolveCircuitsBase());
+  const grantR = grantOverride ?? MAINNET_RENT_0 + FEE_BUDGET + CLEANUP_FEE_BUDGET;
+  const heldByR = await conn.getBalance(R.publicKey);
+  if (heldByR >= grantR) {
+    log(`   R already holds ${heldByR} (>= ${grantR}) \u2014 no top-up needed`);
+  } else {
+    await (0, import_web316.sendAndConfirmTransaction)(conn, new import_web316.Transaction().add(
+      import_web316.SystemProgram.transfer({ fromPubkey: funder.publicKey, toPubkey: R.publicKey, lamports: grantR - heldByR })
+    ), [funder]);
+    log(`   funder topped R up by ${grantR - heldByR} to ${grantR}${grantOverride !== void 0 ? " (OVERRIDDEN for a deliberate test)" : " \u2014 floor + deposit fee + cleanup fee, no rent"}`);
+  }
+  let measuredSize = -1;
+  let fundedAccounts = [];
+  const signTransaction2 = async (tx) => {
+    if (tx instanceof import_web316.VersionedTransaction) {
+      measuredSize = tx.serialize().length;
+      const alts = await Promise.all(
+        tx.message.addressTableLookups.map(async (l) => (await conn.getAddressLookupTable(l.accountKey)).value)
+      );
+      const keys = tx.message.getAccountKeys({ addressLookupTableAccounts: alts });
+      const ix = tx.message.compiledInstructions.find((i) => keys.get(i.programIdIndex).equals(programId));
+      const at = (n) => keys.get(ix.accountKeyIndexes[n]);
+      const targets = [
+        { a: at(12), need: MAINNET_RENT_0, name: "risk_nonce" },
+        { a: at(4), need: MAINNET_RENT_1, name: "nullifier_0" },
+        { a: at(5), need: MAINNET_RENT_1, name: "nullifier_1" }
+      ];
+      const infos = await conn.getMultipleAccountsInfo(targets.map((t) => t.a));
+      fundedAccounts = targets.map((t, i) => ({
+        name: t.name,
+        address: t.a.toBase58(),
+        lamportsSent: Math.max(0, t.need - (infos[i]?.lamports ?? 0))
+      }));
+      const ixs = targets.flatMap((t, i) => (infos[i]?.lamports ?? 0) >= t.need ? [] : [import_web316.SystemProgram.transfer({
+        fromPubkey: funder.publicKey,
+        toPubkey: t.a,
+        lamports: t.need - (infos[i]?.lamports ?? 0)
+      })]);
+      if (ixs.length) {
+        const sig = await (0, import_web316.sendAndConfirmTransaction)(conn, new import_web316.Transaction().add(...ixs), [funder]);
+        log(`   seam: funded ${ixs.length} program accounts read off the built tx \u2014 ${sig.slice(0, 16)}\u2026`);
+      }
+      tx.sign([R]);
+      return tx;
+    }
+    tx.partialSign(R);
+    return tx;
+  };
+  const signMessage = async (m) => import_tweetnacl8.default.sign.detached(m, R.secretKey);
+  const utxoKeypair = await deriveUtxoKeypairFromSpendKey(opts.noteSpendKey);
+  const nk = getNkFromUtxoPrivateKey(utxoKeypair.privateKey);
+  const { utxo, noteSalt } = await createRecoverableDepositUtxo(amount, nk, mint);
+  const zeroInput = await createZeroUtxo(mint);
+  const rBefore = await conn.getBalance(R.publicKey);
+  let result;
+  try {
+    result = await transact(
+      { inputUtxos: [zeroInput], outputUtxos: [utxo], externalAmount: amount, depositor: R.publicKey },
+      {
+        connection: conn,
+        programId,
+        relayUrl,
+        // NO depositorKeypair: the SDK branches `if (keypair) … else if (signTransaction)`
+        // (transact.ts:2786, :2936), so passing one silently skips the funding seam.
+        depositorPublicKey: R.publicKey,
+        walletPublicKey: R.publicKey,
+        signTransaction: signTransaction2,
+        signMessage,
+        chainNoteViewingKeyNk: nk,
+        chainNoteSalt: noteSalt,
+        relaySupplementalAlt: true,
+        onProgress: (s) => log(`   \xB7 ${s}`)
+      }
+    );
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    throw new DepositError(msg, fundedAccounts, measuredSize);
+  }
+  const rAfter = await conn.getBalance(R.publicKey);
+  const noteIndex = result.outputUtxos[0].index;
+  if (noteIndex === void 0) throw new Error("deposit landed but the note has no index \u2014 it cannot be discovered later");
+  return {
+    signature: result.signature,
+    noteIndex,
+    amount: result.outputUtxos[0].amount,
+    txSize: measuredSize,
+    rBefore,
+    rAfter,
+    rentExempt: rAfter >= MAINNET_RENT_0,
+    inputNullifiers: result.inputNullifiers,
+    fundedAccounts
+  };
+}
+
+// src/bridge/cleanup.ts
+var import_web317 = require("@solana/web3.js");
+var import_spl_token6 = require("@solana/spl-token");
+var DEFAULT_MINT = new import_web317.PublicKey("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");
+async function cleanupReceivingAddress(conn, R, dustDestination, mint = DEFAULT_MINT) {
+  assertAllowedRpcConnection(conn);
+  const rAta = (0, import_spl_token6.getAssociatedTokenAddressSync)(mint, R.publicKey);
+  const info = await conn.getAccountInfo(rAta);
+  if (!info) {
+    return {
+      closed: false,
+      dustSwept: 0n,
+      rentReturned: 0,
+      destination: null,
+      signature: null,
+      note: "no token account \u2014 nothing to recover"
+    };
+  }
+  const bal = BigInt((await conn.getTokenAccountBalance(rAta)).value.amount);
+  const rentHeld = info.lamports;
+  const before = await conn.getBalance(R.publicKey);
+  const ixs = [];
+  let destination = null;
+  if (bal > 0n && !dustDestination) {
+    return {
+      closed: false,
+      dustSwept: 0n,
+      rentReturned: 0,
+      destination: null,
+      signature: null,
+      note: `dusted with ${bal} base units after the deposit; leaving the account open and ${rentHeld.toLocaleString()} lamports of rent unrecovered, because sweeping it would publish a link from this deposit to whoever receives it`
+    };
+  }
+  if (bal > 0n && dustDestination) {
+    const destAta = (0, import_spl_token6.getAssociatedTokenAddressSync)(mint, dustDestination);
+    const destInfo = await conn.getAccountInfo(destAta);
+    if (!destInfo) {
+      const ataRent = await (0, import_spl_token6.getMinimumBalanceForRentExemptAccount)(conn);
+      if (before < ataRent + CLEANUP_FEE_BUDGET) {
+        throw new Error(
+          `dustDestination ${dustDestination.toBase58()} has no token account for mint ${mint.toBase58()}, and creating one costs ${ataRent} lamports of rent that R does not have: R holds ${before}, which deposit-core.ts reserved only for this transaction's own fee (CLEANUP_FEE_BUDGET = ${CLEANUP_FEE_BUDGET} in funder.ts), not for a fresh account's rent. Fund R with at least ${ataRent + CLEANUP_FEE_BUDGET - before} more lamports first, or choose a destination that already has a token account for this mint.`
+        );
+      }
+      ixs.push((0, import_spl_token6.createAssociatedTokenAccountIdempotentInstruction)(R.publicKey, destAta, dustDestination, mint));
+    }
+    ixs.push((0, import_spl_token6.createTransferInstruction)(rAta, destAta, R.publicKey, bal));
+    destination = destAta.toBase58();
+  }
+  ixs.push((0, import_spl_token6.createCloseAccountInstruction)(rAta, R.publicKey, R.publicKey));
+  const signature = await (0, import_web317.sendAndConfirmTransaction)(conn, new import_web317.Transaction().add(...ixs), [R], {
+    commitment: "confirmed"
+  });
+  const after = await conn.getBalance(R.publicKey);
+  const gone = await conn.getAccountInfo(rAta) === null;
+  return {
+    closed: gone,
+    dustSwept: bal,
+    rentReturned: after - before,
+    destination,
+    signature,
+    note: bal > 0n ? `swept ${bal} base units of dust to the caller-chosen destination and closed, in one transaction \u2014 note this publishes a link from the deposit to that destination` : `closed cleanly, nothing to sweep`
+  };
+}
+
+// src/bridge/quote.ts
+var MIN_DEPOSIT_SPL_BASE_UNITS = 1000000n;
+var WITHDRAW_FIXED_FEE = 450000n;
+var WITHDRAW_FEE_BPS = 30n;
+function withdrawFeeAt(amount, fixedFee, feeBps) {
+  return fixedFee + amount * feeBps / 10000n;
+}
+var MAX_FEE_FRACTION = 0.063;
+var FIXED_ROUND_TRIP = 903000n;
+var ECONOMIC_MINIMUM = FIXED_ROUND_TRIP * 1000000n / BigInt(Math.round((MAX_FEE_FRACTION - 3e-3) * 1e6));
+function withdrawFeeFor(amount) {
+  return withdrawFeeAt(amount, WITHDRAW_FIXED_FEE, WITHDRAW_FEE_BPS);
+}
+function assessBridgeQuote(q) {
+  if (q.sent < 0n) {
+    throw new Error(`assessBridgeQuote: sent must not be negative (got ${q.sent}).`);
+  }
+  if (q.arrivesMin > q.sent) {
+    throw new Error(
+      `assessBridgeQuote: arrivesMin (${q.arrivesMin}) exceeds sent (${q.sent}) \u2014 no rail returns more than it was given, so this input did not come from a real quote.`
+    );
+  }
+  const shieldedMinRaw = q.arrivesMin - q.paymasterFee;
+  const shieldedTargetRaw = q.arrivesTarget - q.paymasterFee;
+  const shieldedMin = shieldedMinRaw > 0n ? shieldedMinRaw : 0n;
+  const shieldedTarget = shieldedTargetRaw > 0n ? shieldedTargetRaw : 0n;
+  const viable = shieldedMinRaw >= MIN_DEPOSIT_SPL_BASE_UNITS;
+  const economic = q.sent >= ECONOMIC_MINIMUM;
+  const withdrawFee = shieldedMin > 0n ? withdrawFeeAt(shieldedMin, q.liveWithdrawFixedFee ?? WITHDRAW_FIXED_FEE, q.liveWithdrawFeeBps ?? WITHDRAW_FEE_BPS) : 0n;
+  const roundTripCost = q.sent - (shieldedMin > withdrawFee ? shieldedMin - withdrawFee : 0n);
+  const roundTripFraction = q.sent > 0n ? Number(roundTripCost) / Number(q.sent) : 0;
+  const reasons = [];
+  if (!viable) {
+    const short = MIN_DEPOSIT_SPL_BASE_UNITS - shieldedMinRaw;
+    reasons.push(
+      (shieldedMinRaw <= 0n ? `The ${fmt(q.paymasterFee)} paymaster fee alone is ${shieldedMinRaw < 0n ? `${fmt(-shieldedMinRaw)} more than` : "all of"} the ${fmt(q.arrivesMin)} the rail guarantees, so nothing would be left to shield.` : `Only ${fmt(shieldedMinRaw)} would be left to shield after the ${fmt(q.paymasterFee)} paymaster fee.`) + ` The program's minimum deposit is ${fmt(MIN_DEPOSIT_SPL_BASE_UNITS)}. Send at least ${fmt(q.sent + short)} to clear it.`
+    );
+  }
+  if (viable && !economic) {
+    reasons.push(
+      `This works, but ${fmt(roundTripCost)} of ${fmt(q.sent)} goes to fees (${(roundTripFraction * 100).toFixed(0)}%). The costs are almost all fixed, so bridging ${fmt(ECONOMIC_MINIMUM)} or more spreads them much further.`
+    );
+  }
+  return {
+    ...q,
+    shieldedMin,
+    shieldedTarget,
+    viable,
+    economic,
+    withdrawFee,
+    roundTripCost,
+    roundTripFraction,
+    reasons
+  };
+}
+var fmt = (v) => `${(Number(v) / 1e6).toFixed(6)} USDC`;
+function renderAssessment(a) {
+  const L = [];
+  L.push(`  you send            ${fmt(a.sent)}`);
+  L.push(`  arrives at least    ${fmt(a.arrivesMin)}        (target ${fmt(a.arrivesTarget)}, not a promise)`);
+  L.push(`  paymaster fee       ${fmt(a.paymasterFee)}        buys the receiver its SOL, so your wallet stays off chain`);
+  L.push(`  SHIELDED            ${fmt(a.shieldedMin)}        at least \u2014 this is what you end up with`);
+  L.push(`  to withdraw later   ${fmt(a.withdrawFee)}        the program's fee, whenever you take it out`);
+  for (const r of a.reasons) L.push(`
+  ${a.viable ? "NOTE" : "REFUSED"}: ${r}`);
+  return L.join("\n");
+}
+
+// src/bridge/retry.ts
+var TERMINAL_FAILURE = /DepositTooSmall|minimum is 1\.000000|insufficient|holds only|below the program|kora wants|over the .* ceiling/i;
+function isTerminalFailure(message) {
+  return TERMINAL_FAILURE.test(message);
+}
+function classifyPostFailure(attempted, after) {
+  if (after === null) return "unknown";
+  if (after === 0n) return "landed";
+  if (after >= attempted) return "did-not-land";
+  return "unknown";
+}
+function mayRetry(verdict, message) {
+  return verdict === "did-not-land" && !isTerminalFailure(message);
+}
+function retryDelayMs(attempt) {
+  return 15e3 * Math.max(0, attempt - 1);
+}
+var DoNotRetry = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "DoNotRetry";
+  }
+};
+async function withShieldRetries(attempt, hooks = {}) {
+  const attempts = hooks.attempts ?? 3;
+  const sleep4 = hooks.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  let last = "";
+  for (let n = 1; n <= attempts; n++) {
+    if (n > 1) {
+      const delay = retryDelayMs(n);
+      hooks.onRetry?.(n, delay, last);
+      await sleep4(delay);
+    }
+    try {
+      return await attempt(n);
+    } catch (e) {
+      if (e instanceof DoNotRetry) throw e;
+      last = e instanceof Error ? e.message : String(e);
+      if (isTerminalFailure(last) || n === attempts) throw e;
+    }
+  }
+  throw new Error("unreachable");
+}
+
 // src/index.ts
-var VERSION = "0.2.1";
+var VERSION = "0.2.3";
 var SCANNER_SUPPORTS_TRANSACT_SWAP = true;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BRIDGE_ESCROW_LABEL,
   BUILD_ALLOWS_LOCAL_ENDPOINTS,
   CHAIN_NOTE_SALT_BITS,
+  CLEANUP_FEE_BUDGET,
   CLOAK_PRODUCTION_RELAY_URL,
   CLOAK_PROGRAM_ID,
   CloakError,
@@ -11646,16 +12472,25 @@ var SCANNER_SUPPORTS_TRANSACT_SWAP = true;
   DEFAULT_TRANSACTION_CIRCUITS_URL,
   DELIVERY_MEMO_TAG,
   DELIVERY_REGISTRY_SEED,
+  DepositError,
+  DoNotRetry,
+  ECONOMIC_MINIMUM,
   EXPECTED_CIRCUIT_HASHES,
+  FEE_BUDGET,
   FIXED_FEE_LAMPORTS,
   InsecureRandomnessError,
   LAMPORTS_PER_SOL,
   LocalStorageAdapter,
+  MAINNET_RENT_0,
+  MAINNET_RENT_1,
+  MAX_RECEIVER_INDEX,
   MERKLE_TREE_HEIGHT,
   MIN_DEPOSIT_LAMPORTS,
+  MIN_DEPOSIT_SPL_BASE_UNITS,
   MemoryStorageAdapter,
   MerkleTree,
   NATIVE_SOL_MINT,
+  ONECLICK_PUBKEY_B58,
   RECIPIENT_DELIVERY_CIPHERTEXT_LEN,
   RECIPIENT_DELIVERY_EPHEMERAL_PK_LEN,
   RECIPIENT_DELIVERY_NONCE_LEN,
@@ -11674,6 +12509,7 @@ var SCANNER_SUPPORTS_TRANSACT_SWAP = true;
   SettlementVerificationError,
   ShieldPoolErrors,
   SimpleWallet,
+  TERMINAL_FAILURE,
   TRANSACTION_CIRCUITS_VERSION,
   TRANSACT_AUTH_FIELDS,
   TRANSACT_SWAP_AUTH_FIELDS,
@@ -11683,8 +12519,12 @@ var SCANNER_SUPPORTS_TRANSACT_SWAP = true;
   VARIABLE_FEE_NUMERATOR,
   VARIABLE_FEE_RATE,
   VERSION,
+  WITHDRAW_FEE_BPS,
+  WITHDRAW_FIXED_FEE,
   assertDirectSubmissionLanded,
+  assertInputMints,
   assertTransactionCircuitIntegrity,
+  assessBridgeQuote,
   bigintToBytes32,
   bigintToHex,
   buildMerkleTree,
@@ -11699,12 +12539,16 @@ var SCANNER_SUPPORTS_TRANSACT_SWAP = true;
   calculateRelayFee,
   canRebuildMerkleTreeFromChain,
   canonicalJson,
+  canonicalPayloadString,
   chainNoteFromBase64,
   chainNoteToBase64,
+  classifyPostFailure,
   classifyRelayError,
+  cleanupReceivingAddress,
   cleanupStalePendingOperations,
   clearPendingDeposits,
   clearPendingWithdrawals,
+  cloakBridgeRail,
   computeChainNoteHash,
   computeExtDataHash,
   computeMerkleRoot,
@@ -11726,10 +12570,13 @@ var SCANNER_SUPPORTS_TRANSACT_SWAP = true;
   decryptCompactChainNote,
   decryptComplianceMetadataWithMasterKey,
   decryptTransactionMetadata,
+  depositFromDerivedKey,
+  deriveBridgeReceiver,
   deriveChangeNoteBlinding,
   deriveDepositNoteSecrets,
   deriveDiversifiedViewingKey,
   deriveDiversifier,
+  deriveFundingTargets,
   deriveInputNullifierPdas,
   derivePublicKey,
   deriveSpendKey,
@@ -11768,6 +12615,7 @@ var SCANNER_SUPPORTS_TRANSACT_SWAP = true;
   formatErrorForLogging,
   formatSol,
   fullWithdraw,
+  fundReceiverViaPaymaster,
   generateCloakKeys,
   generateCommitmentAsync,
   generateMasterSeed,
@@ -11803,18 +12651,21 @@ var SCANNER_SUPPORTS_TRANSACT_SWAP = true;
   isReactNative,
   isRootNotFoundError,
   isSubmissionOutcomeUnknownResponse,
+  isTerminalFailure,
   isValidHex,
   isValidRpcUrl,
   isValidSolanaAddress,
   isWithdrawAmountSufficient,
   isWithdrawable,
   keypairToAdapter,
+  listBridgeDeposits,
   loadPendingDeposits,
   loadPendingWithdrawals,
   loadVerifiedCircuitArtifacts,
   matchChangeNote,
   matchDepositNote,
   matchSwapRefundLeaf,
+  mayRetry,
   openRecipientDeliveryNote,
   parseAmount,
   parseDeliveryCarrierMemo,
@@ -11837,11 +12688,14 @@ var SCANNER_SUPPORTS_TRANSACT_SWAP = true;
   randomDepositNoteSalt,
   randomFieldElement,
   readMerkleTreeState,
+  readRent,
   recipientDeliveryNoteToBase64,
   registerViewingKey,
   removePendingDeposit,
   removePendingWithdrawal,
+  renderAssessment,
   resolveCircuitsBase,
+  retryDelayMs,
   savePendingDeposit,
   savePendingWithdrawal,
   scanNotesForWallet,
@@ -11874,13 +12728,17 @@ var SCANNER_SUPPORTS_TRANSACT_SWAP = true;
   validateDepositParams,
   validateNote,
   validateOutputsSum,
+  validatePaymasterTopUpTransaction,
   validateRoot,
   validateTransfers,
   validateWalletConnected,
   validateWithdrawableNote,
   verifyAllCircuits,
   verifyCircuitIntegrity,
+  verifyQuoteSignature,
   verifyUtxos,
   waitForRoot,
-  withTiming
+  withShieldRetries,
+  withTiming,
+  withdrawFeeFor
 });