@cloak.dev/sdk 0.2.2 → 0.2.3-staging.16d1078

package/dist/index.js

@@ -621,7 +621,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}$/;
@@ -2150,8 +2150,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);
     }
@@ -2221,8 +2221,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;
 }
@@ -3543,7 +3543,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;
@@ -3567,7 +3567,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));
     }
   }
@@ -4778,12 +4778,12 @@ function signRelayRequest(endpoint, programId, body, signer, nowSeconds, fields
     auth_signature: Buffer.from(signature).toString("base64")
   };
 }
-function assertApprovalWithinFreshnessWindow(elapsedMs) {
+function assertApprovalWithinFreshnessWindow(elapsedMs, maxAgeSeconds = REQUEST_AUTH_MAX_AGE_SECONDS) {
   const elapsedSeconds = elapsedMs / 1e3;
-  const budget = REQUEST_AUTH_MAX_AGE_SECONDS - RELAY_AUTH_APPROVAL_MARGIN_SECONDS;
+  const budget = maxAgeSeconds - RELAY_AUTH_APPROVAL_MARGIN_SECONDS;
   if (elapsedSeconds <= budget) return;
   throw new Error(
-    `The wallet approval took ${Math.round(elapsedSeconds)} seconds, and Cloak requests stay valid for ${REQUEST_AUTH_MAX_AGE_SECONDS} seconds from the moment they are signed (${RELAY_AUTH_APPROVAL_MARGIN_SECONDS} of those are held back for the request to reach the network). The timestamp is inside the signature, so it cannot be refreshed without your approval again. NOTHING WAS SUBMITTED and no funds moved. Start the same operation again and approve the prompt when it appears.`
+    `The wallet approval took ${Math.round(elapsedSeconds)} seconds, and Cloak requests stay valid for ${maxAgeSeconds} seconds from the moment they are signed (${RELAY_AUTH_APPROVAL_MARGIN_SECONDS} of those are held back for the request to reach the network). The timestamp is inside the signature, so it cannot be refreshed without your approval again. NOTHING WAS SUBMITTED and no funds moved. Start the same operation again and approve the prompt when it appears.`
   );
 }
 function explainRelayAuthRejection(responseText) {
@@ -4841,6 +4841,16 @@ async function buildRelayAuthFields(endpoint, programId, body, signers, fields =
     auth_signature: Buffer.from(signature).toString("base64")
   };
 }
+var REQUEST_AUTH_BATCH_DOMAIN = "CLOAK_RELAY_BATCH_AUTH_V1";
+var REQUEST_AUTH_BATCH_MAX_AGE_SECONDS = 600;
+var RELAY_BATCH_AUTH_MAX_ITEMS = 64;
+function relayRequestDigestHex(preimage) {
+  return bytesToHex3(sha2563(preimage.message));
+}
+function buildRelayBatchAuthMessage(programId, issuedAt, digests) {
+  const lines = [REQUEST_AUTH_BATCH_DOMAIN, programId.toBase58(), issuedAt, String(digests.length)];
+  return new TextEncoder().encode([...lines, ...digests].join("\n"));
+}
 
 // src/proving/artifacts.ts
 import { sha256 as sha2564 } from "@noble/hashes/sha2";
@@ -5117,6 +5127,7 @@ async function resolveTransactionCircuitFiles() {
 }
 var _transactPaddingSaltCounter = 0;
 var _registeredViewingKeys = /* @__PURE__ */ new Set();
+var _viewingKeyRegistrationsInFlight = /* @__PURE__ */ new Map();
 var _resolvedAltAccountsCache = /* @__PURE__ */ new Map();
 var _relayMerkleDisabledMints = /* @__PURE__ */ new Set();
 var _relayMerkleFallbackNotifiedMints = /* @__PURE__ */ new Set();
@@ -5449,6 +5460,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) {
@@ -5504,6 +5532,26 @@ async function ensureViewingKeyRegistered(options, onProgress, fallbackNk) {
   if (_registeredViewingKeys.has(cacheKey)) {
     return;
   }
+  const inFlight = _viewingKeyRegistrationsInFlight.get(cacheKey);
+  if (inFlight) {
+    return inFlight;
+  }
+  const registration = registerViewingKeyOnce(
+    relayUrl,
+    userPubkey,
+    viewingKeyHex,
+    cacheKey,
+    options,
+    onProgress
+  );
+  _viewingKeyRegistrationsInFlight.set(cacheKey, registration);
+  try {
+    await registration;
+  } finally {
+    _viewingKeyRegistrationsInFlight.delete(cacheKey);
+  }
+}
+async function registerViewingKeyOnce(relayUrl, userPubkey, viewingKeyHex, cacheKey, options, onProgress) {
   const challengeResponse = await relayFetch(`${relayUrl}/viewing-key/challenge`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
@@ -6859,12 +6907,12 @@ async function submitTransactToRelay(args) {
   const doFetch = args.fetchImpl ?? fetch;
   const maxNetworkRetries = args.maxNetworkRetries ?? relayNetworkRetries();
   const requestTimeoutMs = args.requestTimeoutMs ?? relayRequestTimeoutMs();
-  if (!depositorKeypair && args.relayAuthSigner) {
+  if (!depositorKeypair && args.relayAuthSigner && !args.relayAuthBatch) {
     onProgress?.(
       "Approve the request in your wallet. This signs the request for the relay, not a transaction, and it must be approved within a few minutes to stay valid."
     );
   }
-  const authFields = await buildRelayAuthFields("/transact", programId, requestBody, {
+  const authFields = args.relayAuthBatch ? await args.relayAuthBatch.authorize("/transact", programId, requestBody, TRANSACT_AUTH_FIELDS) : await buildRelayAuthFields("/transact", programId, requestBody, {
     depositorKeypair,
     relayAuthSigner: args.relayAuthSigner
   });
@@ -7060,7 +7108,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,
@@ -7115,6 +7163,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) {
@@ -7481,7 +7530,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);
@@ -7620,11 +7669,14 @@ async function transact(params, options) {
     }
     let proof;
     let publicSignals;
+    const releaseProofSlot = options.relayAuthBatch ? await options.relayAuthBatch.proofSlot() : void 0;
     try {
       const result = await generateTransactionProof(circuitInputs, onProofProgress);
       proof = result.proof;
       publicSignals = result.publicSignals;
+      releaseProofSlot?.();
     } catch (proofError) {
+      releaseProofSlot?.();
       const errorMsg = proofError?.message || String(proofError);
       if ((errorMsg.includes("ForceEqual") || errorMsg.includes("Assert Failed")) && submissionAttempts < maxRootRetries) {
         onProgress?.(`Merkle proof error (stale sibling data), will regenerate with fresh tree...`);
@@ -7644,7 +7696,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));
@@ -7937,6 +7989,7 @@ async function transact(params, options) {
       // point where they reach the relay submission instead of stopping at viewing-key
       // registration. The keypair still wins when both are present.
       relayAuthSigner: relayAuthPlan.kind === "wallet" ? relayAuthPlan.signer : void 0,
+      relayAuthBatch: options.relayAuthBatch,
       settlement: {
         connection,
         programId,
@@ -8338,7 +8391,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
@@ -8357,6 +8410,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"
@@ -8743,7 +8802,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);
@@ -8881,7 +8940,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));
@@ -9383,10 +9442,273 @@ function cleanupStalePendingOperations(maxAgeMs = 24 * 60 * 60 * 1e3) {
   return { removedDeposits, removedWithdrawals };
 }
 
+// src/relay/batch-auth.ts
+import { Keypair as Keypair3 } from "@solana/web3.js";
+import nacl7 from "tweetnacl";
+var RelayBatchAuthCoordinator = class {
+  constructor(options) {
+    this.proofSlotsInUse = 0;
+    this.proofQueue = [];
+    this.items = [];
+    this.signing = false;
+    this.slotsInUse = 0;
+    this.ready = [];
+    this.waves = 0;
+    if (!Number.isInteger(options.items) || options.items < 1) {
+      throw new Error(`A batch needs at least one item (got ${options.items}).`);
+    }
+    if (options.items > RELAY_BATCH_AUTH_MAX_ITEMS) {
+      throw new Error(
+        `A batch may cover at most ${RELAY_BATCH_AUTH_MAX_ITEMS} requests (got ${options.items}); the relay refuses longer digest lists. Chunk the payout. The practical bound is lower still: each spend appends two roots to the on-chain ring of 100, so a batch proved against one root evicts it by itself before 50 items.`
+      );
+    }
+    const concurrency = options.submitConcurrency ?? 3;
+    if (!Number.isInteger(concurrency) || concurrency < 1) {
+      throw new Error(`submitConcurrency must be a positive integer (got ${concurrency}).`);
+    }
+    this.signer = options.signer;
+    this.sender = options.signer instanceof Keypair3 ? options.signer.publicKey : options.signer.walletPublicKey;
+    this.expectedItems = options.items;
+    this.submitConcurrency = concurrency;
+    const proofConcurrency = options.proofConcurrency ?? 2;
+    if (!Number.isInteger(proofConcurrency) || proofConcurrency < 1) {
+      throw new Error(`proofConcurrency must be a positive integer (got ${proofConcurrency}).`);
+    }
+    this.proofConcurrency = proofConcurrency;
+    this.onProgress = options.onProgress;
+  }
+  /** The wallet that signs and is every item's authenticated `sender`. */
+  get walletPublicKey() {
+    return this.sender;
+  }
+  /** How many times the signer has been asked so far: one per wave. */
+  get approvals() {
+    return this.waves;
+  }
+  /** Where every item is right now. For progress UIs and for diagnosing a batch that never signs. */
+  snapshot() {
+    const count = (state) => this.items.filter((i) => i.state === state).length;
+    return {
+      building: count("building"),
+      waiting: count("waiting"),
+      submitting: count("submitting"),
+      done: count("done"),
+      proving: this.proofSlotsInUse,
+      proofQueue: this.proofQueue.length,
+      registered: this.items.length,
+      expected: this.expectedItems
+    };
+  }
+  /** Register one item. Throws past `items`: the wave condition would never be reachable. */
+  item() {
+    if (this.items.length >= this.expectedItems) {
+      throw new Error(
+        `This batch was created for ${this.expectedItems} item(s) and all of them are registered.`
+      );
+    }
+    const item = { state: "building", waiting: null, holdsSlot: false };
+    this.items.push(item);
+    return {
+      proofSlot: () => this.acquireProofSlot(),
+      authorize: (endpoint, programId, body, fields) => this.authorize(item, endpoint, programId, body, fields),
+      finish: () => this.finish(item)
+    };
+  }
+  acquireProofSlot() {
+    return new Promise((resolve) => {
+      const grant = () => {
+        this.proofSlotsInUse += 1;
+        let released = false;
+        resolve(() => {
+          if (released) return;
+          released = true;
+          this.proofSlotsInUse -= 1;
+          const next = this.proofQueue.shift();
+          if (next) next();
+        });
+      };
+      if (this.proofSlotsInUse < this.proofConcurrency) grant();
+      else this.proofQueue.push(grant);
+    });
+  }
+  authorize(item, endpoint, programId, body, fields) {
+    if (item.state === "done") {
+      return Promise.reject(new Error("This batch item already finished; it cannot authorize."));
+    }
+    if (item.state === "waiting") {
+      return Promise.reject(new Error("This batch item is already waiting for a signature."));
+    }
+    this.releaseSlot(item);
+    return new Promise((resolve, reject) => {
+      item.state = "waiting";
+      item.waiting = { endpoint, programId, body, fields, resolve, reject };
+      this.maybeSign();
+    });
+  }
+  finish(item) {
+    if (item.state === "done") return;
+    if (item.state === "waiting" && item.waiting) {
+      item.waiting.reject(new Error("Batch item finished before it was signed."));
+      item.waiting = null;
+    }
+    this.releaseSlot(item);
+    item.state = "done";
+    this.maybeSign();
+    this.pump();
+  }
+  releaseSlot(item) {
+    if (!item.holdsSlot) return;
+    item.holdsSlot = false;
+    this.slotsInUse -= 1;
+  }
+  /** Sign when every registered item is either waiting here or finished, and nothing is building. */
+  maybeSign() {
+    if (this.signing) return;
+    if (this.items.length < this.expectedItems) return;
+    if (this.items.some((item) => item.state === "building" || item.state === "submitting")) return;
+    const wave = this.items.filter((item) => item.state === "waiting");
+    if (wave.length === 0) return;
+    this.signing = true;
+    void this.signWave(wave).finally(() => {
+      this.signing = false;
+      this.maybeSign();
+    });
+  }
+  async signWave(wave) {
+    const waiting = wave.map((item) => item.waiting);
+    try {
+      const programId = waiting[0].programId;
+      for (const w of waiting) {
+        if (!w.programId.equals(programId)) {
+          throw new Error("Every item of a batch must target the same program id.");
+        }
+      }
+      const nowSeconds = Math.floor(Date.now() / 1e3);
+      const preimages = waiting.map(
+        (w) => buildRelayAuthPreimage(w.endpoint, programId, w.body, this.sender, nowSeconds, w.fields)
+      );
+      const digests = preimages.map(relayRequestDigestHex);
+      const issuedAt = preimages[0].auth_issued_at;
+      const message = buildRelayBatchAuthMessage(programId, issuedAt, digests);
+      this.waves += 1;
+      let signature;
+      if (this.signer instanceof Keypair3) {
+        signature = nacl7.sign.detached(message, this.signer.secretKey);
+      } else {
+        this.onProgress?.(
+          `Approve ${waiting.length} request(s) in your wallet` + (this.waves > 1 ? ` (approval ${this.waves}, for the rows that had to re-prove)` : "") + `. This signs the requests for the relay, not a transaction, and must be approved within a few minutes to stay valid.`
+        );
+        const approvalStartedMs = Date.now();
+        signature = await this.signer.signMessage(message);
+        assertApprovalWithinFreshnessWindow(
+          Date.now() - approvalStartedMs,
+          REQUEST_AUTH_BATCH_MAX_AGE_SECONDS
+        );
+        if (!(signature instanceof Uint8Array) || signature.length !== 64) {
+          throw new Error(
+            `The wallet's signMessage did not return a 64-byte ed25519 detached signature (got ${signature instanceof Uint8Array ? `${signature.length} bytes` : typeof signature}).`
+          );
+        }
+      }
+      const signatureB64 = Buffer.from(signature).toString("base64");
+      wave.forEach((item, i) => {
+        const preimage = preimages[i];
+        this.ready.push({
+          item,
+          fields: {
+            sender: preimage.sender,
+            auth_issued_at: preimage.auth_issued_at,
+            auth_nonce: preimage.auth_nonce,
+            auth_signature: signatureB64,
+            // A fresh array per item: `Object.assign` puts this on the wire body, and the body is
+            // serialized again on every network retry.
+            auth_batch: { digests: [...digests] }
+          }
+        });
+      });
+      this.pump();
+    } catch (error) {
+      for (const item of wave) {
+        const w = item.waiting;
+        item.waiting = null;
+        item.state = "done";
+        w?.reject(error);
+      }
+    }
+  }
+  /** Release signed items to submit, `submitConcurrency` at a time, in signing order. */
+  pump() {
+    while (this.ready.length > 0 && this.slotsInUse < this.submitConcurrency) {
+      const next = this.ready.shift();
+      const w = next.item.waiting;
+      next.item.waiting = null;
+      if (next.item.state !== "waiting" || !w) continue;
+      next.item.state = "submitting";
+      next.item.holdsSlot = true;
+      this.slotsInUse += 1;
+      w.resolve(next.fields);
+    }
+  }
+};
+function createRelayBatchAuthCoordinator(options) {
+  return new RelayBatchAuthCoordinator(options);
+}
+
+// src/flows/transact-batch.ts
+async function transactBatch(items, options) {
+  if (items.length === 0) {
+    return { results: [], approvals: 0 };
+  }
+  if (items.length > RELAY_BATCH_AUTH_MAX_ITEMS) {
+    throw new Error(
+      `transactBatch accepts at most ${RELAY_BATCH_AUTH_MAX_ITEMS} items per call (got ${items.length}). Chunk the payout; see RELAY_BATCH_AUTH_MAX_ITEMS for why the practical bound is lower.`
+    );
+  }
+  if (!options.relayUrl) {
+    throw new Error("transactBatch requires relayUrl: batch approval is a relay authentication scheme.");
+  }
+  const { proofConcurrency, submitConcurrency, ...shared } = options;
+  const signer = shared.depositorKeypair ? shared.depositorKeypair : shared.walletPublicKey && shared.signMessage ? { walletPublicKey: shared.walletPublicKey, signMessage: shared.signMessage } : shared.depositorPublicKey && shared.signMessage ? { walletPublicKey: shared.depositorPublicKey, signMessage: shared.signMessage } : null;
+  if (!signer) {
+    throw new Error(
+      "transactBatch requires an authenticated sender: pass `depositorKeypair` (a local Keypair) or `signMessage` together with `walletPublicKey` (a browser wallet adapter). Checked before proof generation, so nothing has been computed or submitted yet."
+    );
+  }
+  const coordinator = createRelayBatchAuthCoordinator({
+    signer,
+    items: items.length,
+    proofConcurrency,
+    submitConcurrency,
+    onProgress: shared.onProgress
+  });
+  const handles = items.map(() => coordinator.item());
+  const results = new Array(items.length);
+  const runOne = async (index) => {
+    const item = items[index];
+    const handle = handles[index];
+    const label = `[batch ${index + 1}/${items.length}]`;
+    try {
+      const value = await transact(item.params, {
+        ...shared,
+        ...item.options,
+        relayAuthBatch: handle,
+        onProgress: shared.onProgress ? (status) => shared.onProgress?.(`${label} ${status}`) : void 0
+      });
+      results[index] = { status: "fulfilled", value };
+    } catch (reason) {
+      results[index] = { status: "rejected", reason };
+    } finally {
+      handle.finish();
+    }
+  };
+  await Promise.all(items.map((_, index) => runOne(index)));
+  return { results, approvals: coordinator.approvals };
+}
+
 // src/scanning/scan.ts
 import _bs583 from "bs58";
 import {
-  PublicKey as PublicKey9
+  PublicKey as PublicKey10
 } from "@solana/web3.js";
 import { getAssociatedTokenAddressSync as getAssociatedTokenAddressSync2 } from "@solana/spl-token";
 var bs583 = _bs583.default || _bs583;
@@ -9474,7 +9796,7 @@ function parseSwapOutputMint(data) {
   const mintBytes = data.slice(SWAP_OUTPUT_MINT_OFFSET, end);
   if (mintBytes.every((byte) => byte === 0)) return void 0;
   try {
-    return new PublicKey9(mintBytes).toBase58();
+    return new PublicKey10(mintBytes).toBase58();
   } catch {
     return void 0;
   }
@@ -9564,7 +9886,7 @@ function parseSwapRecipientAta(data) {
   const recipientAtaBytes = data.slice(recipientAtaStart, recipientAtaEnd);
   if (recipientAtaBytes.every((byte) => byte === 0)) return void 0;
   try {
-    return new PublicKey9(recipientAtaBytes).toBase58();
+    return new PublicKey10(recipientAtaBytes).toBase58();
   } catch {
     return void 0;
   }
@@ -9726,7 +10048,7 @@ async function scanSwapNoteCarriers(connection, programId, viewingKeyNk, swapCtx
   let rpcCalls = 0;
   const candidates = Array.from(swapCtxByCommitment.keys());
   if (candidates.length === 0) return { records, rpcCalls };
-  const [registry] = PublicKey9.findProgramAddressSync(
+  const [registry] = PublicKey10.findProgramAddressSync(
     [Buffer.from("cloak_chain_note_registry")],
     programId
   );
@@ -10129,8 +10451,8 @@ async function scanTransactions(opts) {
                   if (onChainAta) {
                     try {
                       const expectedAta = getAssociatedTokenAddressSync2(
-                        new PublicKey9(asset.mint),
-                        new PublicKey9(walletPublicKey)
+                        new PublicKey10(asset.mint),
+                        new PublicKey10(walletPublicKey)
                       ).toBase58();
                       if (onChainAta === expectedAta) {
                         isOurs = true;
@@ -10344,7 +10666,7 @@ async function scanTransactions(opts) {
                   // deposit — that is the public deposit amount. A deposit that also merged inputs
                   // carries a larger output 0 and is not recoverable from public data alone.
                   amount: grossAmount,
-                  mintAddress: new PublicKey9(asset.mint),
+                  mintAddress: new PublicKey10(asset.mint),
                   outputCommitments: ixCtx.outputCommitments ?? []
                 });
                 if (recoveredDeposit) {
@@ -10370,7 +10692,7 @@ async function scanTransactions(opts) {
                   noteSalt: compactNote.noteSalt,
                   amount: compactNote.outAmount0,
                   keypair: { privateKey: 0n, publicKey: compactNote.outPubkey0 },
-                  mintAddress: new PublicKey9(asset.mint),
+                  mintAddress: new PublicKey10(asset.mint),
                   outputIndex: 0,
                   // v4 describes output 0, which is where change lands
                   outputCommitments: ixCtx.outputCommitments ?? []
@@ -10563,7 +10885,7 @@ function formatComplianceCsv(report) {
 }
 
 // src/wallet/utxo-wallet.ts
-import { PublicKey as PublicKey10 } from "@solana/web3.js";
+import { PublicKey as PublicKey11 } from "@solana/web3.js";
 var UtxoWallet = class _UtxoWallet {
   constructor(viewingKey) {
     this.wallets = /* @__PURE__ */ new Map();
@@ -10775,7 +11097,7 @@ var UtxoWallet = class _UtxoWallet {
       data.viewingKey ? new Uint8Array(data.viewingKey) : void 0
     );
     for (const w of data.wallets) {
-      const mint = new PublicKey10(w.mint);
+      const mint = new PublicKey11(w.mint);
       for (const u of w.utxos) {
         wallet.addUtxo({
           amount: BigInt(u.amount),
@@ -10857,12 +11179,799 @@ var SimpleWallet = class {
   }
 };
 
+// src/bridge/rail-verify.ts
+import nacl8 from "tweetnacl";
+import { sha256 as sha2565 } from "@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 = sha2565(new TextEncoder().encode(stable(payload)));
+  const message = new TextEncoder().encode(b58.encode(new Uint8Array(digest)));
+  const sig = resp.signature.replace(/^ed25519:/, "");
+  try {
+    return { valid: nacl8.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
+import {
+  PublicKey as PublicKey12,
+  SystemInstruction,
+  SystemProgram as SystemProgram3,
+  Transaction as Transaction3
+} from "@solana/web3.js";
+import { TOKEN_PROGRAM_ID as TOKEN_PROGRAM_ID3, decodeTransferInstruction, getAssociatedTokenAddressSync as getAssociatedTokenAddressSync3 } from "@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(SystemProgram3.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 = 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(TOKEN_PROGRAM_ID3)) {
+    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 = decodeTransferInstruction(ix1, TOKEN_PROGRAM_ID3);
+  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 = getAssociatedTokenAddressSync3(
+    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 PublicKey12(prepared.fee_mint);
+  const paymentAddress = new PublicKey12(prepared.payment_address);
+  const feeTokenAmount = BigInt(prepared.fee_token_amount);
+  const tx = Transaction3.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: Transaction3.from(Buffer.from(cosigned.transaction, "base64")),
+    feeTokenAmount,
+    feeMint: prepared.fee_mint,
+    paymentAddress: prepared.payment_address
+  };
+}
+
+// src/bridge/derive.ts
+import { Keypair as Keypair5 } from "@solana/web3.js";
+import { hmac } from "@noble/hashes/hmac";
+import { sha512 } from "@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 = hmac(sha512, new Uint8Array(nk), new TextEncoder().encode(`${BRIDGE_ESCROW_LABEL}:${index}`));
+  return Keypair5.fromSeed(h.slice(0, 32));
+}
+
+// src/bridge/discover.ts
+import { SolanaJSONRPCError } from "@solana/web3.js";
+import { getAssociatedTokenAddressSync as getAssociatedTokenAddressSync4 } from "@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 = getAssociatedTokenAddressSync4(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 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
+import {
+  SystemProgram as SystemProgram4,
+  Transaction as Transaction4,
+  VersionedTransaction as VersionedTransaction2,
+  sendAndConfirmTransaction as sendAndConfirmTransaction2
+} from "@solana/web3.js";
+import nacl9 from "tweetnacl";
+
+// src/bridge/funder.ts
+import { PublicKey as PublicKey14 } from "@solana/web3.js";
+import { getAssociatedTokenAddressSync as getAssociatedTokenAddressSync5 } from "@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) => PublicKey14.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: getAssociatedTokenAddressSync5(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 sendAndConfirmTransaction2(conn, new Transaction4().add(
+      SystemProgram4.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 VersionedTransaction2) {
+      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 ? [] : [SystemProgram4.transfer({
+        fromPubkey: funder.publicKey,
+        toPubkey: t.a,
+        lamports: t.need - (infos[i]?.lamports ?? 0)
+      })]);
+      if (ixs.length) {
+        const sig = await sendAndConfirmTransaction2(conn, new Transaction4().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) => nacl9.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
+import {
+  PublicKey as PublicKey16,
+  Transaction as Transaction5,
+  sendAndConfirmTransaction as sendAndConfirmTransaction3
+} from "@solana/web3.js";
+import {
+  getAssociatedTokenAddressSync as getAssociatedTokenAddressSync6,
+  createCloseAccountInstruction,
+  createTransferInstruction,
+  createAssociatedTokenAccountIdempotentInstruction,
+  getMinimumBalanceForRentExemptAccount
+} from "@solana/spl-token";
+var DEFAULT_MINT = new PublicKey16("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");
+async function cleanupReceivingAddress(conn, R, dustDestination, mint = DEFAULT_MINT) {
+  assertAllowedRpcConnection(conn);
+  const rAta = getAssociatedTokenAddressSync6(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 = getAssociatedTokenAddressSync6(mint, dustDestination);
+    const destInfo = await conn.getAccountInfo(destAta);
+    if (!destInfo) {
+      const ataRent = await 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(createAssociatedTokenAccountIdempotentInstruction(R.publicKey, destAta, dustDestination, mint));
+    }
+    ixs.push(createTransferInstruction(rAta, destAta, R.publicKey, bal));
+    destination = destAta.toBase58();
+  }
+  ixs.push(createCloseAccountInstruction(rAta, R.publicKey, R.publicKey));
+  const signature = await sendAndConfirmTransaction3(conn, new Transaction5().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;
 export {
+  BRIDGE_ESCROW_LABEL,
   BUILD_ALLOWS_LOCAL_ENDPOINTS,
   CHAIN_NOTE_SALT_BITS,
+  CLEANUP_FEE_BUDGET,
   CLOAK_PRODUCTION_RELAY_URL,
   CLOAK_PROGRAM_ID,
   CloakError,
@@ -10870,25 +11979,38 @@ export {
   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_HEIGHT2 as 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,
   RECIPIENT_DELIVERY_NOTE_BYTES,
   RECIPIENT_DELIVERY_PLAINTEXT_LEN,
   RECIPIENT_DELIVERY_TAG_LEN,
+  RELAY_BATCH_AUTH_MAX_ITEMS,
   RELAY_ORIGIN_ALLOWLIST,
+  REQUEST_AUTH_BATCH_DOMAIN,
+  REQUEST_AUTH_BATCH_MAX_AGE_SECONDS,
   REQUEST_AUTH_MAX_AGE_SECONDS,
   REQUEST_AUTH_MAX_FUTURE_SKEW_SECONDS,
+  RelayBatchAuthCoordinator,
   RelayInternalError,
   RelayService,
   RootNotFoundError,
@@ -10898,6 +12020,7 @@ export {
   SettlementVerificationError,
   ShieldPoolErrors,
   SimpleWallet,
+  TERMINAL_FAILURE,
   TRANSACTION_CIRCUITS_VERSION,
   TRANSACT_AUTH_FIELDS,
   TRANSACT_SWAP_AUTH_FIELDS,
@@ -10907,8 +12030,12 @@ export {
   VARIABLE_FEE_NUMERATOR,
   VARIABLE_FEE_RATE,
   VERSION,
+  WITHDRAW_FEE_BPS,
+  WITHDRAW_FIXED_FEE,
   assertDirectSubmissionLanded,
+  assertInputMints,
   assertTransactionCircuitIntegrity,
+  assessBridgeQuote,
   bigintToBytes32,
   bigintToHex,
   buildMerkleTree,
@@ -10916,6 +12043,7 @@ export {
   buildMerkleTreeFromRelay,
   buildRecipientDeliveryNotes,
   buildRelayAuthPreimage,
+  buildRelayBatchAuthMessage,
   buildTransactRequestBody,
   bytesToHex,
   calculateFee,
@@ -10923,12 +12051,16 @@ export {
   calculateRelayFee,
   canRebuildMerkleTreeFromChain,
   canonicalJson,
+  canonicalPayloadString,
   chainNoteFromBase64,
   chainNoteToBase64,
+  classifyPostFailure,
   classifyRelayError,
+  cleanupReceivingAddress,
   cleanupStalePendingOperations,
   clearPendingDeposits,
   clearPendingWithdrawals,
+  cloakBridgeRail,
   computeChainNoteHash,
   computeExtDataHash,
   computeMerkleRoot,
@@ -10945,15 +12077,19 @@ export {
   createLogger,
   createRecoverableChangeUtxo,
   createRecoverableDepositUtxo,
+  createRelayBatchAuthCoordinator,
   createUtxo,
   createZeroUtxo,
   decryptCompactChainNote,
   decryptComplianceMetadataWithMasterKey,
   decryptTransactionMetadata,
+  depositFromDerivedKey,
+  deriveBridgeReceiver,
   deriveChangeNoteBlinding,
   deriveDepositNoteSecrets,
   deriveDiversifiedViewingKey,
   deriveDiversifier,
+  deriveFundingTargets,
   deriveInputNullifierPdas,
   derivePublicKey,
   deriveSpendKey,
@@ -10992,6 +12128,7 @@ export {
   formatErrorForLogging,
   formatSol,
   fullWithdraw,
+  fundReceiverViaPaymaster,
   generateCloakKeys,
   generateCommitmentAsync,
   generateMasterSeed,
@@ -11027,18 +12164,21 @@ export {
   isReactNative,
   isRootNotFoundError,
   isSubmissionOutcomeUnknownResponse,
+  isTerminalFailure,
   isValidHex,
   isValidRpcUrl,
   isValidSolanaAddress,
   isWithdrawAmountSufficient,
   isWithdrawable,
   keypairToAdapter,
+  listBridgeDeposits,
   loadPendingDeposits,
   loadPendingWithdrawals,
   loadVerifiedCircuitArtifacts,
   matchChangeNote,
   matchDepositNote,
   matchSwapRefundLeaf,
+  mayRetry,
   openRecipientDeliveryNote,
   parseAmount,
   parseDeliveryCarrierMemo,
@@ -11061,11 +12201,15 @@ export {
   randomDepositNoteSalt,
   randomFieldElement,
   readMerkleTreeState,
+  readRent,
   recipientDeliveryNoteToBase64,
   registerViewingKey,
+  relayRequestDigestHex,
   removePendingDeposit,
   removePendingWithdrawal,
+  renderAssessment,
   resolveCircuitsBase,
+  retryDelayMs,
   savePendingDeposit,
   savePendingWithdrawal,
   scanNotesForWallet,
@@ -11086,6 +12230,7 @@ export {
   swapWithChange,
   toComplianceReport,
   transact,
+  transactBatch,
   transfer,
   truncate,
   tryDecryptNote,
@@ -11098,13 +12243,17 @@ export {
   validateDepositParams,
   validateNote,
   validateOutputsSum,
+  validatePaymasterTopUpTransaction,
   validateRoot,
   validateTransfers,
   validateWalletConnected,
   validateWithdrawableNote,
   verifyAllCircuits,
   verifyCircuitIntegrity,
+  verifyQuoteSignature,
   verifyUtxos,
   waitForRoot,
-  withTiming
+  withShieldRetries,
+  withTiming,
+  withdrawFeeFor
 };