@satora/swap 0.2.0 → 0.3.0

package/dist/index.cjs

@@ -28,7 +28,7 @@ __export(bitcoin_reader_esplora_exports, {
   esploraReader: () => esploraReader,
   htlcFactsFromEsploraTxs: () => htlcFactsFromEsploraTxs
 });
-function htlcFactsFromEsploraTxs(txs, address) {
+function htlcFactsFromEsploraTxs(txs, address, opts) {
   for (const tx of txs) {
     const spend = tx.vin.find(
       (vin) => vin.prevout?.scriptpubkey_address === address
@@ -46,20 +46,29 @@ function htlcFactsFromEsploraTxs(txs, address) {
   );
   if (funding) {
     const fundedSats = funding.vout.filter((vout) => vout.scriptpubkey_address === address).reduce((sum, vout) => sum + (vout.value ?? 0), 0);
+    const minConf = opts?.minConfirmations ?? 0;
+    let deepEnough;
+    if (funding.status?.confirmed) {
+      deepEnough = minConf <= 1 || opts?.tipHeight !== void 0 && funding.status.block_height !== void 0 && opts.tipHeight - funding.status.block_height + 1 >= minConf;
+    } else {
+      deepEnough = minConf === 0;
+    }
     return {
-      funding: funding.status?.confirmed ? "confirmed" : "mempool",
+      funding: deepEnough ? "confirmed" : "mempool",
       fundedSats
     };
   }
   return { funding: "absent", fundedSats: 0 };
 }
-function esploraReader(esploraUrls, fetchImpl = fetch) {
+function esploraReader(esploraUrls, fetchImpl = fetch, policy) {
   const bases = (Array.isArray(esploraUrls) ? esploraUrls : [esploraUrls]).map(
     (url) => url.replace(/\/+$/, "")
   );
+  const minConf = policy?.minConfirmations ?? 0;
   let start = 0;
   return {
-    async getHtlcFacts(address) {
+    async getHtlcFacts(address, minConfirmations) {
+      const required = minConfirmations ?? minConf;
       const from = start++ % bases.length;
       let lastError;
       for (let i = 0; i < bases.length; i++) {
@@ -69,10 +78,17 @@ function esploraReader(esploraUrls, fetchImpl = fetch) {
             `${base}/address/${encodeURIComponent(address)}/txs`
           );
           if (!res.ok) throw new Error(`esplora ${res.status} at ${base}`);
-          return htlcFactsFromEsploraTxs(
-            await res.json(),
-            address
-          );
+          const txs = await res.json();
+          let tipHeight;
+          if (required > 1) {
+            const tip = await fetchImpl(`${base}/blocks/tip/height`);
+            if (!tip.ok) throw new Error(`esplora ${tip.status} at ${base}`);
+            tipHeight = Number(await tip.text());
+          }
+          return htlcFactsFromEsploraTxs(txs, address, {
+            minConfirmations: required,
+            tipHeight
+          });
         } catch (error) {
           lastError = error;
         }
@@ -115,12 +131,14 @@ __export(src_exports, {
   evmReaderFromClient: () => evmReaderFromClient,
   htlcFactsFromEsploraTxs: () => htlcFactsFromEsploraTxs,
   htlcKey: () => htlcKey,
+  htlcQueryKey: () => htlcQueryKey,
   swapToTracked: () => swapToTracked
 });
 module.exports = __toCommonJS(src_exports);
 __reExport(src_exports, require("@lendasat/lendaswap-sdk-pure"), module.exports);
 
 // src/actions/derive.ts
+var FUNDING_REAP_GRACE_MS = 60 * 60 * 1e3;
 function deriveSwapActions(input) {
   const {
     status,
@@ -135,12 +153,23 @@ function deriveSwapActions(input) {
       if (!clientFunds) {
         const wait = {
           id: "wait",
+          waitingOn: "client_payment",
           recommended: true,
           automation: "auto",
           reason: "Waiting for the Lightning payment to be locked in."
         };
         return { recommended: "wait", actions: [wait] };
       }
+      if (clientChainNow >= clientRefundLocktime + FUNDING_REAP_GRACE_MS) {
+        const done = {
+          id: "none",
+          outcome: "expired",
+          recommended: true,
+          automation: "auto",
+          reason: "The funding window closed."
+        };
+        return { recommended: "none", actions: [done] };
+      }
       if (clientChainNow >= clientRefundLocktime) return { actions: [] };
       const fund = {
         id: "fund",
@@ -154,6 +183,7 @@ function deriveSwapActions(input) {
     case "clientfundingseen": {
       const wait = {
         id: "wait",
+        waitingOn: "client_funding_confirmation",
         recommended: true,
         automation: "auto",
         reason: "Waiting for your funding transaction to confirm."
@@ -173,6 +203,7 @@ function deriveSwapActions(input) {
       }
       const wait = {
         id: "wait",
+        waitingOn: "server_funding",
         recommended: true,
         automation: "auto",
         reason: "Waiting for the server to fund the swap."
@@ -203,6 +234,7 @@ function deriveSwapActions(input) {
       if (!clientFunds) {
         const done = {
           id: "none",
+          outcome: "refunded",
           recommended: true,
           automation: "auto",
           reason: "The claim window passed \u2014 your Lightning payment will be refunded automatically."
@@ -221,6 +253,7 @@ function deriveSwapActions(input) {
       }
       const wait = {
         id: "wait",
+        waitingOn: "refund_timelock",
         recommended: true,
         automation: "auto",
         reason: "Wait for your refund timelock \u2014 do not claim, as revealing the preimage would let the server take your deposit."
@@ -240,6 +273,7 @@ function deriveSwapActions(input) {
     case "clientredeeming": {
       const wait = {
         id: "wait",
+        waitingOn: "claim_confirmation",
         recommended: true,
         automation: "auto",
         reason: "Redeeming your funds \u2014 waiting for the claim to confirm."
@@ -250,6 +284,7 @@ function deriveSwapActions(input) {
     case "serverredeemed": {
       const done = {
         id: "none",
+        outcome: "completed",
         recommended: true,
         automation: "auto",
         reason: "Swap complete \u2014 you've received your funds."
@@ -259,6 +294,7 @@ function deriveSwapActions(input) {
     case "expired": {
       const done = {
         id: "none",
+        outcome: "expired",
         recommended: true,
         automation: "auto",
         reason: "The swap expired without funding \u2014 nothing was locked."
@@ -270,6 +306,7 @@ function deriveSwapActions(input) {
     case "clientrefundedserverfunded": {
       const done = {
         id: "none",
+        outcome: "refunded",
         recommended: true,
         automation: "auto",
         reason: "Refunded \u2014 your deposit was returned."
@@ -279,6 +316,8 @@ function deriveSwapActions(input) {
     case "clientredeemedandclientrefunded": {
       const done = {
         id: "none",
+        // The client holds both sides' funds — "completed" from its viewpoint.
+        outcome: "completed",
         recommended: true,
         automation: "auto",
         reason: "This swap ended in an anomalous state (redeemed and refunded); no action needed."
@@ -301,6 +340,7 @@ function deriveSwapActions(input) {
       }
       const wait = {
         id: "wait",
+        waitingOn: "refund_timelock",
         recommended: true,
         automation: "auto",
         reason: "The swap did not complete; waiting for the refund timelock to reclaim your deposit."
@@ -400,7 +440,7 @@ function payOnLightningStatus(serverHtlc) {
 }
 
 // src/client.ts
-var import_lendaswap_sdk_pure = require("@lendasat/lendaswap-sdk-pure");
+var import_lendaswap_sdk_pure2 = require("@lendasat/lendaswap-sdk-pure");
 
 // src/contracts/arkade-manager.ts
 var import_sdk2 = require("@arkade-os/sdk");
@@ -465,6 +505,7 @@ var ArkadeContractManager = class _ArkadeContractManager {
   /** pkScript → the verified preimage recovered from a claim spend. */
   #preimages = /* @__PURE__ */ new Map();
   #listeners = /* @__PURE__ */ new Set();
+  /** Last MTP reading (ms) + when it was fetched, for extrapolation. */
   #now;
   constructor(deps) {
     this.#indexer = deps.indexer;
@@ -490,7 +531,6 @@ var ArkadeContractManager = class _ArkadeContractManager {
         `ArkadeContractManager can't track a '${ref.ledger}' HTLC`
       );
     this.#refs.set(ref.script, ref);
-    await this.#reconcileRef(ref);
   }
   async unregister(ref) {
     if (ref.ledger !== "arkade") return;
@@ -502,23 +542,27 @@ var ArkadeContractManager = class _ArkadeContractManager {
     return ref.ledger === "arkade" ? this.#obs.get(ref.script) : void 0;
   }
   chainNow(_ref) {
-    return this.#now;
+    if (!this.#now) return void 0;
+    return this.#now.mtpMs + Math.max(0, Date.now() - this.#now.fetchedAtMs);
   }
   onEvent(cb) {
     this.#listeners.add(cb);
     return () => this.#listeners.delete(cb);
   }
+  /**
+   * Full reconcile of every tracked ref (clock + vtxos). Called on demand
+   * (tracker start / newly tracked swap), NOT periodically: onward, hints and
+   * the tracker's at-risk safety net drive targeted `reconcile`s.
+   */
   async refresh() {
-    if (this.#chainTime) this.#now = await this.#chainTime();
-    await Promise.all(
-      [...this.#refs.values()].map((ref) => this.#reconcileRef(ref))
-    );
+    await this.#scanAll();
   }
+  /** Targeted verify (hint / pre-action path) — never gated. */
   async reconcile(ref) {
     if (ref.ledger !== "arkade") return;
     const tracked = this.#refs.get(ref.script);
     if (!tracked) return;
-    if (this.#chainTime) this.#now = await this.#chainTime();
+    await this.#readClock();
     await this.#reconcileRef(tracked);
   }
   dispose() {
@@ -528,6 +572,18 @@ var ArkadeContractManager = class _ArkadeContractManager {
   getPreimage(ref) {
     return ref.ledger === "arkade" ? this.#preimages.get(ref.script) : void 0;
   }
+  /** Read and store the MTP clock (with fetch time, for extrapolation). */
+  async #readClock() {
+    if (!this.#chainTime) return;
+    this.#now = { mtpMs: await this.#chainTime(), fetchedAtMs: Date.now() };
+  }
+  /** Full scan of every tracked ref (clock + vtxos). */
+  async #scanAll() {
+    await this.#readClock();
+    await Promise.all(
+      [...this.#refs.values()].map((ref) => this.#reconcileRef(ref))
+    );
+  }
   /** Read the VHTLC's vtxos and map them to an observation. */
   async #reconcileRef(ref) {
     const { vtxos } = await this.#indexer.getVtxos({ scripts: [ref.script] });
@@ -620,6 +676,7 @@ var BitcoinContractManager = class _BitcoinContractManager {
   /** address → the preimage a claim revealed. */
   #preimages = /* @__PURE__ */ new Map();
   #listeners = /* @__PURE__ */ new Set();
+  /** Last MTP reading (ms) + when it was fetched, for extrapolation. */
   #now;
   constructor(deps) {
     this.#reader = deps.reader;
@@ -631,7 +688,9 @@ var BitcoinContractManager = class _BitcoinContractManager {
   static async create(config) {
     const { esploraReader: esploraReader2 } = await Promise.resolve().then(() => (init_bitcoin_reader_esplora(), bitcoin_reader_esplora_exports));
     return _BitcoinContractManager.fromDeps({
-      reader: esploraReader2(config.esploraUrl),
+      reader: esploraReader2(config.esploraUrl, void 0, {
+        minConfirmations: config.minConfirmations
+      }),
       chainTime: config.chainTime
     });
   }
@@ -656,14 +715,15 @@ var BitcoinContractManager = class _BitcoinContractManager {
     return ref.ledger === "bitcoin" ? this.#obs.get(ref.address) : void 0;
   }
   chainNow(_ref) {
-    return this.#now;
+    if (!this.#now) return void 0;
+    return this.#now.mtpMs + Math.max(0, Date.now() - this.#now.fetchedAtMs);
   }
   onEvent(cb) {
     this.#listeners.add(cb);
     return () => this.#listeners.delete(cb);
   }
   async refresh() {
-    if (this.#chainTime) this.#now = await this.#chainTime();
+    await this.#readClock();
     await Promise.all(
       [...this.#refs.values()].map((ref) => this.#reconcileRef(ref))
     );
@@ -672,9 +732,14 @@ var BitcoinContractManager = class _BitcoinContractManager {
     if (ref.ledger !== "bitcoin") return;
     const tracked = this.#refs.get(ref.address);
     if (!tracked) return;
-    if (this.#chainTime) this.#now = await this.#chainTime();
+    await this.#readClock();
     await this.#reconcileRef(tracked);
   }
+  /** Read and store the MTP clock (with fetch time, for extrapolation). */
+  async #readClock() {
+    if (!this.#chainTime) return;
+    this.#now = { mtpMs: await this.#chainTime(), fetchedAtMs: Date.now() };
+  }
   dispose() {
     this.#listeners.clear();
   }
@@ -683,7 +748,10 @@ var BitcoinContractManager = class _BitcoinContractManager {
     return ref.ledger === "bitcoin" ? this.#preimages.get(ref.address) : void 0;
   }
   async #reconcileRef(ref) {
-    const facts = await this.#reader.getHtlcFacts(ref.address);
+    const facts = await this.#reader.getHtlcFacts(
+      ref.address,
+      ref.minConfirmations
+    );
     const { observation, preimage } = bitcoinObservation(
       facts,
       import_base5.hex.decode(ref.preimageHash),
@@ -732,14 +800,59 @@ function htlcKey(ref) {
       return `arkade:${ref.script}`;
     case "bitcoin":
       return `bitcoin:${ref.address}`;
-    case "evm":
-      return `evm:${ref.chainId}:${ref.preimageHash}`;
+    case "evm": {
+      const base = `evm:${ref.chainId}:${ref.htlc.toLowerCase()}:${ref.preimageHash.toLowerCase()}`;
+      if (!ref.expectedToken || !ref.sender || ref.timelockSec === void 0) {
+        return base;
+      }
+      return [
+        base,
+        ref.expectedAmount,
+        ref.expectedToken.toLowerCase(),
+        ref.sender.toLowerCase(),
+        ref.claimAddress.toLowerCase(),
+        ref.timelockSec
+      ].join(":");
+    }
     case "lightning":
       return `lightning:${ref.paymentHash}`;
   }
 }
 
 // src/contracts/evm-manager.ts
+function htlcQueryKey(q) {
+  const base = `${q.htlc.toLowerCase()}:${q.preimageHash.toLowerCase()}`;
+  if (!q.terms || !q.claimAddress) return base;
+  const { amount, token, sender, timelockSec } = q.terms;
+  return [
+    base,
+    amount,
+    token.toLowerCase(),
+    sender.toLowerCase(),
+    q.claimAddress.toLowerCase(),
+    timelockSec
+  ].join(":");
+}
+function refQueryKey(ref) {
+  const full = activeQuery(ref);
+  return htlcQueryKey({
+    htlc: ref.htlc,
+    preimageHash: ref.preimageHash,
+    claimAddress: ref.claimAddress,
+    terms: full && {
+      amount: full.amount,
+      token: full.token,
+      sender: full.sender,
+      timelockSec: full.timelockSec
+    }
+  });
+}
+var AVG_BLOCK_MS = {
+  1: 12e3,
+  137: 2100,
+  42161: 250
+};
+var SCAN_MARGIN_BLOCKS = 1000n;
 var EvmContractManager = class _EvmContractManager {
   ledger = "evm";
   #readers;
@@ -749,14 +862,8 @@ var EvmContractManager = class _EvmContractManager {
   #obs = /* @__PURE__ */ new Map();
   /** htlcKey → the preimage a claim revealed. */
   #preimages = /* @__PURE__ */ new Map();
-  /** chainId → its latest block time (ms). */
+  /** chainId → its last clock reading (extrapolated in {@link chainNow}). */
   #now = /* @__PURE__ */ new Map();
-  /** chainId → unsubscribe for its (single, shared) watch. */
-  #watchUnsubs = /* @__PURE__ */ new Map();
-  /** chainId → a block-event reconcile is currently running (coalescing). */
-  #reconciling = /* @__PURE__ */ new Set();
-  /** chainId → a block event arrived mid-reconcile; run exactly one more. */
-  #reconcileAgain = /* @__PURE__ */ new Set();
   #listeners = /* @__PURE__ */ new Set();
   constructor(deps) {
     this.#readers = deps.readers;
@@ -775,8 +882,6 @@ var EvmContractManager = class _EvmContractManager {
         `no EVM reader for chain ${ref.chainId} \u2014 configure it via ClientBuilder.withEvmRpcUrls()`
       );
     this.#refs.set(htlcKey(ref), ref);
-    this.#ensureWatch(ref.chainId);
-    await this.#reconcileChain(ref.chainId);
   }
   async unregister(ref) {
     if (ref.ledger !== "evm") return;
@@ -784,100 +889,176 @@ var EvmContractManager = class _EvmContractManager {
     this.#refs.delete(key);
     this.#obs.delete(key);
     this.#preimages.delete(key);
-    if (![...this.#refs.values()].some((r) => r.chainId === ref.chainId)) {
-      this.#watchUnsubs.get(ref.chainId)?.();
-      this.#watchUnsubs.delete(ref.chainId);
+    if (![...this.#refs.values()].some((r) => r.chainId === ref.chainId))
       this.#now.delete(ref.chainId);
-      this.#reconcileAgain.delete(ref.chainId);
-    }
   }
   getState(ref) {
     return ref.ledger === "evm" ? this.#obs.get(htlcKey(ref)) : void 0;
   }
   chainNow(ref) {
-    return ref.ledger === "evm" ? this.#now.get(ref.chainId) : void 0;
+    if (ref.ledger !== "evm") return void 0;
+    const clock = this.#now.get(ref.chainId);
+    if (!clock) return void 0;
+    return clock.blockTimeMs + Math.max(0, Date.now() - clock.fetchedAtMs);
   }
   onEvent(cb) {
     this.#listeners.add(cb);
     return () => this.#listeners.delete(cb);
   }
+  /**
+   * Full reconcile of every tracked chain — seeds clocks + observations. Called
+   * on demand (tracker start / newly tracked swap), NOT periodically: onward,
+   * hints drive targeted `reconcile`s and the tracker's at-risk safety net
+   * re-reads only swaps with client funds on the line.
+   */
   async refresh() {
-    const chainIds = new Set([...this.#refs.values()].map((r) => r.chainId));
-    await Promise.all([...chainIds].map((c) => this.#reconcileChain(c)));
+    const chainIds = [
+      ...new Set([...this.#refs.values()].map((r) => r.chainId))
+    ];
+    const results = await Promise.allSettled(
+      chainIds.map((c) => this.#reconcileChain(c))
+    );
+    results.forEach((result, index) => {
+      if (result.status === "rejected")
+        console.warn(
+          `EVM reconcile failed for chain ${chainIds[index]}:`,
+          result.reason
+        );
+    });
   }
+  /** Targeted verify (hint / pre-action path) — never gated. */
   async reconcile(ref) {
     if (ref.ledger !== "evm") return;
     const tracked = this.#refs.get(htlcKey(ref));
     if (!tracked) return;
     const reader = this.#readers.get(tracked.chainId);
     if (!reader) return;
-    this.#now.set(tracked.chainId, await reader.getBlockTimeMs());
-    await this.#reconcileRef(reader, tracked);
+    await this.#readClock(reader, tracked.chainId);
+    await this.#reconcileRefs(reader, tracked.chainId, [tracked]);
   }
   dispose() {
-    for (const unsub of this.#watchUnsubs.values()) unsub();
-    this.#watchUnsubs.clear();
-    this.#reconciling.clear();
-    this.#reconcileAgain.clear();
     this.#listeners.clear();
   }
   /** The preimage a claim revealed on this HTLC, if one was seen. */
   getPreimage(ref) {
     return ref.ledger === "evm" ? this.#preimages.get(htlcKey(ref)) : void 0;
   }
-  #ensureWatch(chainId) {
-    if (this.#watchUnsubs.has(chainId)) return;
-    const reader = this.#readers.get(chainId);
-    if (!reader) return;
-    this.#watchUnsubs.set(
-      chainId,
-      reader.watch(() => this.#scheduleReconcile(chainId))
-    );
-  }
-  /**
-   * Reconcile a chain in response to a block/log event, coalesced: at most one
-   * reconcile runs per chain at a time, with at most one queued rerun to pick up
-   * changes that arrived mid-run. This stops fast chains / slow RPCs from stacking
-   * redundant full-log scans (which amplify rate limits), and the `.catch` keeps a
-   * transient RPC failure in a background reconcile from becoming an unhandled
-   * rejection. `register`/`refresh` still await `#reconcileChain` directly.
-   */
-  #scheduleReconcile(chainId) {
-    if (this.#reconciling.has(chainId)) {
-      this.#reconcileAgain.add(chainId);
-      return;
-    }
-    this.#reconciling.add(chainId);
-    void this.#reconcileChain(chainId).catch((error) => {
-      console.warn(`EVM reconcile failed for chain ${chainId}:`, error);
-    }).finally(() => {
-      this.#reconciling.delete(chainId);
-      if (this.#reconcileAgain.delete(chainId))
-        this.#scheduleReconcile(chainId);
+  /** Read and store a chain's clock (with its fetch time, for extrapolation). */
+  async #readClock(reader, chainId) {
+    const block = await reader.getLatestBlock();
+    this.#now.set(chainId, {
+      blockTimeMs: block.timeMs,
+      blockNumber: block.number,
+      fetchedAtMs: Date.now()
     });
   }
   /** Refresh one chain's clock and re-observe every HTLC tracked on it. */
   async #reconcileChain(chainId) {
     const reader = this.#readers.get(chainId);
     if (!reader) return;
-    this.#now.set(chainId, await reader.getBlockTimeMs());
+    await this.#readClock(reader, chainId);
+    const refs = [...this.#refs.values()].filter((r) => r.chainId === chainId);
+    await this.#reconcileRefs(reader, chainId, refs);
+  }
+  /**
+   * Re-observe the given refs. Two tiers:
+   *
+   * 1. Refs with the full contract tuple get the cheap `isActive` check —
+   *    `true` proves open-and-on-expected-terms (the swap key hashes them) →
+   *    `confirmed`, no log scan at all. This is the common case.
+   * 2. Everything else — an incomplete tuple, an inactive-and-unclassified
+   *    HTLC (never funded vs claimed vs refunded), or an `isActive` transport
+   *    failure (e.g. no Multicall3 on a dev chain) — is classified from one
+   *    batched log read, lower-bounded by the swaps' creation-block estimate.
+   *
+   * A ref already latched on a spend is skipped entirely: terminal per leg,
+   * nothing left to learn.
+   */
+  async #reconcileRefs(reader, chainId, refs) {
+    const open = refs.filter((r) => !this.#isSpent(r));
+    if (open.length === 0) return;
+    const fast = open.filter((r) => activeQuery(r) !== void 0);
+    let needLogs = open.filter((r) => activeQuery(r) === void 0);
+    if (fast.length > 0) {
+      try {
+        const active = await reader.isActiveBatch(
+          fast.map((r) => activeQuery(r))
+        );
+        for (const ref of fast) {
+          if (active.get(refQueryKey(ref)) === true)
+            this.#set(htlcKey(ref), "confirmed");
+          else needLogs.push(ref);
+        }
+      } catch (error) {
+        console.warn(
+          `EVM isActive check failed for chain ${chainId} \u2014 falling back to logs:`,
+          error
+        );
+        needLogs = open;
+      }
+    }
+    if (needLogs.length === 0) return;
+    const known = needLogs.filter((r) => r.createdAtMs !== void 0);
+    const unknown = needLogs.filter((r) => r.createdAtMs === void 0);
     await Promise.all(
-      [...this.#refs.values()].filter((r) => r.chainId === chainId).map((r) => this.#reconcileRef(reader, r))
+      [
+        [known, this.#estimateFromBlock(chainId, known)],
+        [unknown, 0n]
+      ].filter(([refs2]) => refs2.length > 0).map(
+        ([refs2, fromBlock]) => this.#classifyFromLogs(reader, refs2, fromBlock)
+      )
     );
   }
-  async #reconcileRef(reader, ref) {
-    const events = await reader.getHtlcEvents(
-      ref.htlc,
-      ref.preimageHash,
-      ref.claimAddress
+  /** Read the refs' lifecycle logs (from `fromBlock`) and set observations. */
+  async #classifyFromLogs(reader, refs, fromBlock) {
+    const events = await reader.getHtlcEventsBatch(
+      refs.map((r) => {
+        const full = activeQuery(r);
+        return {
+          htlc: r.htlc,
+          preimageHash: r.preimageHash,
+          claimAddress: r.claimAddress,
+          terms: full && {
+            amount: full.amount,
+            token: full.token,
+            sender: full.sender,
+            timelockSec: full.timelockSec
+          }
+        };
+      }),
+      fromBlock
     );
-    const { observation, preimage } = evmObservation(events, {
-      amount: ref.expectedAmount,
-      token: ref.expectedToken
-    });
-    const key = htlcKey(ref);
-    if (preimage) this.#preimages.set(key, preimage);
-    this.#set(key, observation);
+    for (const ref of refs) {
+      const { observation, preimage } = evmObservation(
+        events.get(refQueryKey(ref)) ?? [],
+        { amount: ref.expectedAmount, token: ref.expectedToken }
+      );
+      const key = htlcKey(ref);
+      if (preimage) this.#preimages.set(key, preimage);
+      this.#set(key, observation);
+    }
+  }
+  #isSpent(ref) {
+    const obs = this.#obs.get(htlcKey(ref));
+    return obs === "spent_claim" || obs === "spent_refund";
+  }
+  /**
+   * The block to scan logs from: roughly where the OLDEST of the given swaps
+   * was created (an HTLC has no events before its swap existed). Only a lower
+   * bound, so estimation errs early — ×1.5 on elapsed time plus a fixed block
+   * margin. Falls back to genesis when the creation time, clock, or the
+   * chain's block time is unknown.
+   */
+  #estimateFromBlock(chainId, refs) {
+    const clock = this.#now.get(chainId);
+    const avgBlockMs = AVG_BLOCK_MS[chainId];
+    const createdAts = refs.map((r) => r.createdAtMs ?? 0);
+    const oldestMs = Math.min(...createdAts);
+    if (!clock || !avgBlockMs || oldestMs <= 0) return 0n;
+    const elapsedMs = Math.max(0, clock.blockTimeMs - oldestMs);
+    const blocksBehind = BigInt(Math.ceil(elapsedMs / avgBlockMs * 1.5)) + SCAN_MARGIN_BLOCKS;
+    const from = clock.blockNumber - blocksBehind;
+    return from > 0n ? from : 0n;
   }
   /** Update an observation and notify on change; never downgrade a resolved spend. */
   #set(key, observation) {
@@ -892,6 +1073,19 @@ var EvmContractManager = class _EvmContractManager {
     for (const listener of this.#listeners) listener(ref, observation);
   }
 };
+function activeQuery(ref) {
+  if (ref.sender === void 0 || ref.expectedToken === void 0 || ref.timelockSec === void 0)
+    return void 0;
+  return {
+    htlc: ref.htlc,
+    preimageHash: ref.preimageHash,
+    amount: ref.expectedAmount,
+    token: ref.expectedToken,
+    sender: ref.sender,
+    claimAddress: ref.claimAddress,
+    timelockSec: ref.timelockSec
+  };
+}
 
 // src/contracts/evm-reader-viem.ts
 var import_viem = require("viem");
@@ -903,82 +1097,185 @@ var DEFAULT_EVM_RPCS = {
     "https://tenderly.rpc.polygon.community",
     "https://polygon-bor-rpc.publicnode.com"
   ],
-  1: [
-    "https://ethereum-rpc.publicnode.com",
-    "https://rpc.ankr.com/eth",
-    "https://eth.drpc.org"
-  ],
+  // No publicnode: it rate-limits by IP across its whole fleet (403s), and as
+  // a PRIMARY that costs a full retry cycle per read before failing over.
+  // Both entries verified for eth_getLogs + eth_call from a browser origin.
+  1: ["https://eth.drpc.org", "https://rpc.mevblocker.io"],
+  // The official gateway first; publicnode last (see above).
   42161: [
-    "https://arbitrum-one-rpc.publicnode.com",
-    "https://rpc.ankr.com/arbitrum",
-    "https://arb1.arbitrum.io/rpc"
+    "https://arb1.arbitrum.io/rpc",
+    "https://arbitrum.drpc.org",
+    "https://arbitrum-one-rpc.publicnode.com"
   ]
 };
 var SWAP_CREATED = (0, import_viem.parseAbiItem)(
-  "event SwapCreated(bytes32 indexed preimageHash, address indexed refundAddress, address indexed claimAddress, address token, uint256 amount, uint256 timelock)"
+  "event SwapCreated(bytes32 indexed preimageHash, address indexed refundAddress, address indexed claimAddress, address token, uint256 amount, uint256 timelock, bytes32 key)"
 );
 var SWAP_REDEEMED = (0, import_viem.parseAbiItem)(
-  "event SwapRedeemed(bytes32 indexed preimageHash, bytes32 preimage)"
+  "event SwapRedeemed(bytes32 indexed preimageHash, bytes32 indexed key, bytes32 preimage)"
 );
 var SWAP_REFUNDED = (0, import_viem.parseAbiItem)(
-  "event SwapRefunded(bytes32 indexed preimageHash)"
+  "event SwapRefunded(bytes32 indexed preimageHash, bytes32 indexed key)"
+);
+var HTLC_EVENTS_ABI = [SWAP_CREATED, SWAP_REDEEMED, SWAP_REFUNDED];
+var HTLC_EVENT_TOPICS = HTLC_EVENTS_ABI.map(import_viem.toEventSelector);
+var IS_ACTIVE = (0, import_viem.parseAbiItem)(
+  "function isActive(bytes32 preimageHash, uint256 amount, address token, address sender, address claimAddress, uint256 timelock) view returns (bool)"
 );
+var MULTICALL3_ADDRESS = "0xcA11bde05977b3631167028862bE2a173976CA11";
+var AGGREGATE3 = (0, import_viem.parseAbiItem)(
+  "function aggregate3((address target, bool allowFailure, bytes callData)[] calls) payable returns ((bool success, bytes returnData)[] returnData)"
+);
+function activeKey(q) {
+  return htlcQueryKey({
+    htlc: q.htlc,
+    preimageHash: q.preimageHash,
+    claimAddress: q.claimAddress,
+    terms: {
+      amount: q.amount,
+      token: q.token,
+      sender: q.sender,
+      timelockSec: q.timelockSec
+    }
+  });
+}
 function evmReaderFromClient(client) {
   return {
-    async getHtlcEvents(htlc, preimageHash, claimAddress) {
-      const [created, redeemed, refunded] = await Promise.all([
-        // Filter by claimAddress too (also indexed), so only the HTLC actually
-        // claimable on the swap's terms is seen.
-        client.getLogs({
-          address: htlc,
-          event: SWAP_CREATED,
-          args: { preimageHash, claimAddress },
-          fromBlock: "earliest"
-        }),
-        client.getLogs({
-          address: htlc,
-          event: SWAP_REDEEMED,
-          args: { preimageHash },
-          fromBlock: "earliest"
-        }),
-        client.getLogs({
-          address: htlc,
-          event: SWAP_REFUNDED,
-          args: { preimageHash },
-          fromBlock: "earliest"
+    async getHtlcEventsBatch(queries, fromBlock = 0n) {
+      const results = /* @__PURE__ */ new Map();
+      if (queries.length === 0) return results;
+      for (const q of queries) results.set(htlcQueryKey(q), []);
+      const logs = await client.request({
+        method: "eth_getLogs",
+        params: [
+          {
+            address: unique(queries.map((q) => q.htlc)),
+            topics: [
+              HTLC_EVENT_TOPICS,
+              unique(queries.map((q) => q.preimageHash))
+            ],
+            fromBlock: (0, import_viem.numberToHex)(fromBlock)
+          }
+        ]
+      });
+      const grouped = /* @__PURE__ */ new Map();
+      for (const log of logs) {
+        const decoded = tryDecode(log);
+        if (!decoded) continue;
+        const group = `${log.address.toLowerCase()}:${decoded.preimageHash.toLowerCase()}`;
+        const existing = grouped.get(group);
+        if (existing) existing.push(decoded);
+        else grouped.set(group, [decoded]);
+      }
+      for (const query of queries) {
+        const group = `${query.htlc.toLowerCase()}:${query.preimageHash.toLowerCase()}`;
+        const events = results.get(htlcQueryKey(query));
+        if (!events) continue;
+        for (const decoded of grouped.get(group) ?? []) {
+          const event = toHtlcEvent(decoded, query);
+          if (event) events.push(event);
+        }
+      }
+      return results;
+    },
+    async isActiveBatch(queries) {
+      const results = /* @__PURE__ */ new Map();
+      if (queries.length === 0) return results;
+      const calldatas = queries.map(
+        (q) => (0, import_viem.encodeFunctionData)({
+          abi: [IS_ACTIVE],
+          args: [
+            q.preimageHash,
+            q.amount,
+            q.token,
+            q.sender,
+            q.claimAddress,
+            BigInt(q.timelockSec)
+          ]
         })
-      ]);
-      const events = [];
-      for (const log of created) {
-        const args = log.args;
-        events.push({
-          kind: "created",
-          amount: args?.amount ?? 0n,
-          token: args?.token ?? "0x"
+      );
+      const callOne = async (i) => {
+        const { data } = await client.call({
+          to: queries[i].htlc,
+          data: calldatas[i]
         });
+        results.set(activeKey(queries[i]), decodeIsActive(data));
+      };
+      if (queries.length === 1) {
+        await callOne(0);
+        return results;
       }
-      for (const log of redeemed) {
-        const preimage = log.args?.preimage;
-        if (preimage) events.push({ kind: "redeemed", preimage });
+      try {
+        const { data } = await client.call({
+          to: MULTICALL3_ADDRESS,
+          data: (0, import_viem.encodeFunctionData)({
+            abi: [AGGREGATE3],
+            args: [
+              queries.map((q, i) => ({
+                target: q.htlc,
+                allowFailure: true,
+                callData: calldatas[i]
+              }))
+            ]
+          })
+        });
+        if (data === void 0 || data === "0x")
+          throw new Error("empty multicall result");
+        const decoded = (0, import_viem.decodeFunctionResult)({
+          abi: [AGGREGATE3],
+          data
+        });
+        queries.forEach((q, i) => {
+          const r = decoded[i];
+          results.set(
+            activeKey(q),
+            r?.success === true && decodeIsActive(r.returnData)
+          );
+        });
+      } catch {
+        await Promise.all(queries.map((_, i) => callOne(i)));
       }
-      if (refunded.length > 0) events.push({ kind: "refunded" });
-      return events;
+      return results;
     },
-    async getBlockTimeMs() {
+    async getLatestBlock() {
       const block = await client.getBlock();
-      return Number(block.timestamp) * 1e3;
-    },
-    watch(cb) {
-      return client.watchBlocks({ onBlock: () => cb() });
+      return {
+        timeMs: Number(block.timestamp) * 1e3,
+        number: block.number ?? 0n
+      };
     }
   };
 }
+function decodeIsActive(data) {
+  if (data === void 0 || data === "0x") return false;
+  return (0, import_viem.decodeFunctionResult)({ abi: [IS_ACTIVE], data }) === true;
+}
+function tryDecode(log) {
+  try {
+    const { eventName, args } = (0, import_viem.decodeEventLog)({
+      abi: HTLC_EVENTS_ABI,
+      data: log.data,
+      topics: log.topics
+    });
+    return { eventName, ...args };
+  } catch {
+    return void 0;
+  }
+}
+function toHtlcEvent(decoded, query) {
+  if (decoded.eventName === "SwapCreated") {
+    if (decoded.claimAddress.toLowerCase() !== query.claimAddress.toLowerCase())
+      return void 0;
+    return { kind: "created", amount: decoded.amount, token: decoded.token };
+  }
+  return decoded.eventName === "SwapRedeemed" ? { kind: "redeemed", preimage: decoded.preimage } : { kind: "refunded" };
+}
+function unique(values) {
+  return [...new Set(values)];
+}
 function createEvmRpcReader(rpcUrls) {
   const urls = Array.isArray(rpcUrls) ? rpcUrls : [rpcUrls];
-  const transport = urls.length > 1 ? (0, import_viem.fallback)(
-    urls.map((url) => (0, import_viem.http)(url)),
-    { rank: { interval: 6e4, sampleCount: 3, timeout: 1e3 } }
-  ) : (0, import_viem.http)(urls[0]);
+  const transport = urls.length > 1 ? (0, import_viem.fallback)(urls.map((url) => (0, import_viem.http)(url))) : (0, import_viem.http)(urls[0]);
   const client = (0, import_viem.createPublicClient)({ transport });
   return evmReaderFromClient(client);
 }
@@ -1036,6 +1333,10 @@ var SwapWorker = class {
         });
       })
     );
+    if (this.#hintSource.onReconnect)
+      this.#unsubs.push(
+        this.#hintSource.onReconnect(() => this.#reverifyAllTracked())
+      );
     this.#hintSource.start();
     this.#unsubs.push(
       this.#tracker.subscribeToActions(
@@ -1053,6 +1354,17 @@ var SwapWorker = class {
     this.#retries.clear();
     this.#executing.clear();
   }
+  /** Chain-reconcile every tracked swap (the post-outage catch-up sweep). */
+  #reverifyAllTracked() {
+    for (const swapId of this.#tracker.trackedSwapIds()) {
+      void this.#tracker.applyHint(swapId).catch((error) => {
+        console.warn(
+          `SwapWorker: post-reconnect re-verify of ${swapId} failed:`,
+          error
+        );
+      });
+    }
+  }
   #onActions(swapId, actions) {
     const recommended = actions.recommended;
     if (recommended === "none") {
@@ -1061,7 +1373,7 @@ var SwapWorker = class {
       return;
     }
     this.#hintSource.subscribe([swapId]);
-    if (recommended && AUTO_EXECUTABLE.has(recommended)) {
+    if (recommended && AUTO_EXECUTABLE.has(recommended) && this.#execute) {
       this.#autoExecute(swapId, actions);
       return;
     }
@@ -1074,11 +1386,13 @@ var SwapWorker = class {
       this.#onActionRequired?.(swapId, actions);
   }
   #autoExecute(swapId, actions) {
+    const execute = this.#execute;
+    if (!execute) return;
     if (this.#executing.has(swapId)) return;
     const actionId = actions.recommended;
     if (!actionId) return;
     this.#executing.add(swapId);
-    void this.#execute(swapId, actionId).then(() => this.#cancelRetry(swapId)).catch((error) => {
+    void execute(swapId, actionId).then(() => this.#cancelRetry(swapId)).catch((error) => {
       console.warn(`SwapWorker: ${actionId}(${swapId}) failed:`, error);
       this.#scheduleRetry(swapId, actions);
     }).finally(() => this.#executing.delete(swapId));
@@ -1143,14 +1457,17 @@ var WsStatusSource = class {
   /**
    * Ids we want but have no slot for. Promoted FIFO as slots free (the worker
    * unsubscribes each swap when it reaches a terminal action, so they do free).
-   * A pending swap is not broken, only slower: it gets no hints, so it advances
-   * on the tracker's chain poll instead.
+   * A queued swap is not broken, only slower: it gets no hints, so it advances
+   * on the tracker's at-risk reconciles and the worker's reconnect sweep.
    */
   #pending = /* @__PURE__ */ new Set();
   #listeners = /* @__PURE__ */ new Set();
+  #reconnectListeners = /* @__PURE__ */ new Set();
   #ws;
   #open = false;
   #stopped = false;
+  /** A connect failed or the socket dropped — the next open is a RE-connect. */
+  #hadDisruption = false;
   #backoffMs;
   #reconnectTimer;
   constructor(options) {
@@ -1180,6 +1497,18 @@ var WsStatusSource = class {
     this.#listeners.add(cb);
     return () => this.#listeners.delete(cb);
   }
+  /**
+   * Emit whenever the socket comes (back) up after a disruption — a drop, or a
+   * first connect that had to be retried. NOT emitted on a pristine first open:
+   * hints were never live before it, so there is no gap to recover from. While
+   * the socket was down, pushed transitions were lost for good (the server only
+   * snapshots on subscribe), so a consumer should re-verify its world against
+   * the chain on this signal.
+   */
+  onReconnect(cb) {
+    this.#reconnectListeners.add(cb);
+    return () => this.#reconnectListeners.delete(cb);
+  }
   /**
    * Track these swap ids — subscribe on the socket now if open, else on next open.
    *
@@ -1243,6 +1572,10 @@ var WsStatusSource = class {
       this.#open = true;
       if (this.#active.size > 0)
         this.#sendFrame("subscribe", [...this.#active]);
+      if (this.#hadDisruption) {
+        this.#hadDisruption = false;
+        for (const cb of this.#reconnectListeners) cb();
+      }
     };
     ws.onmessage = (event) => this.#handleMessage(event.data);
     ws.onclose = () => this.#onDisconnect();
@@ -1251,6 +1584,7 @@ var WsStatusSource = class {
   #onDisconnect() {
     this.#open = false;
     this.#ws = void 0;
+    this.#hadDisruption = true;
     if (this.#stopped || this.#reconnectTimer) return;
     const delay = this.#backoffMs;
     this.#backoffMs = Math.min(this.#backoffMs * 2, this.#reconnectMaxMs);
@@ -1303,6 +1637,7 @@ function defaultWebSocketFactory(url) {
 
 // src/contracts/arkade-vhtlc.ts
 var import_sdk3 = require("@arkade-os/sdk");
+var import_lendaswap_sdk_pure = require("@lendasat/lendaswap-sdk-pure");
 var import_legacy2 = require("@noble/hashes/legacy.js");
 var import_base6 = require("@scure/base");
 function strip0x(value) {
@@ -1329,7 +1664,18 @@ function buildArkadeVhtlcRef(input) {
       input.unilateralRefundWithoutReceiverDelay
     )
   };
-  const vhtlc = new import_sdk3.VHTLC.Script(params);
+  const vhtlc = (() => {
+    switch (input.arkadeHtlcScriptVersion ?? import_lendaswap_sdk_pure.ARKADE_HTLC_SCRIPT_VERSION_LEGACY) {
+      case import_lendaswap_sdk_pure.ARKADE_HTLC_SCRIPT_VERSION_LEGACY:
+        return new import_sdk3.VHTLC.Script(params);
+      case import_lendaswap_sdk_pure.ARKADE_HTLC_SCRIPT_VERSION_STRICT:
+        return new import_lendaswap_sdk_pure.StrictVhtlcScript(params);
+      default:
+        throw new Error(
+          `Unsupported Arkade HTLC script version: ${input.arkadeHtlcScriptVersion}`
+        );
+    }
+  })();
   return {
     ledger: "arkade",
     script: import_base6.hex.encode(vhtlc.pkScript),
@@ -1342,6 +1688,18 @@ function buildArkadeVhtlcRef(input) {
 
 // src/tracker/from-swap.ts
 var ms = (seconds2) => seconds2 * 1e3;
+var MAINNET_LOCKED_TOKEN = {
+  1: "0x18084fba666a33d37592fa2633fd49a74dd93a88",
+  // tBTC
+  42161: "0x6c84a8f1c29108F47a79964b5Fe888D4f4D0dE40",
+  // tBTC
+  137: "0x1BFD67037B42Cf73acF2047067bd4F2C47D9BfD6"
+  // WBTC
+};
+function lockedTokenFallback(chainId, network) {
+  const net = network?.toLowerCase();
+  return net === "bitcoin" || net === "mainnet" ? MAINNET_LOCKED_TOKEN[chainId] : void 0;
+}
 var ensure0x = (value) => value.startsWith("0x") ? value : `0x${value}`;
 var strip0x2 = (value) => value.startsWith("0x") ? value.slice(2) : value;
 function arkadeLeg(r, address, expectedSats) {
@@ -1355,10 +1713,12 @@ function arkadeLeg(r, address, expectedSats) {
     unilateralClaimDelay: r.unilateral_claim_delay,
     unilateralRefundDelay: r.unilateral_refund_delay,
     unilateralRefundWithoutReceiverDelay: r.unilateral_refund_without_receiver_delay,
-    expectedSats
+    expectedSats,
+    arkadeHtlcScriptVersion: r.arkade_htlc_script_version
   });
 }
 function evmLeg(args) {
+  const createdAtMs = args.createdAt ? Date.parse(args.createdAt) : Number.NaN;
   return {
     ledger: "evm",
     chainId: args.chainId,
@@ -1366,15 +1726,20 @@ function evmLeg(args) {
     preimageHash: ensure0x(args.hashLock),
     claimAddress: ensure0x(args.claimAddress),
     expectedAmount: BigInt(args.expectedSats),
-    expectedToken: args.token ? ensure0x(args.token) : void 0
+    expectedToken: args.token ? ensure0x(args.token) : void 0,
+    sender: args.sender ? ensure0x(args.sender) : void 0,
+    timelockSec: args.timelockSec,
+    createdAtMs: Number.isNaN(createdAtMs) ? void 0 : createdAtMs
   };
 }
-function bitcoinLeg(address, hashLock, expectedSats) {
+var CLIENT_FUNDING_MIN_CONFIRMATIONS = 1;
+function bitcoinLeg(address, hashLock, expectedSats, minConfirmations) {
   return {
     ledger: "bitcoin",
     address,
     preimageHash: strip0x2(hashLock),
-    expectedSats
+    expectedSats,
+    minConfirmations
   };
 }
 function swapToTracked(stored) {
@@ -1392,7 +1757,11 @@ function swapToTracked(stored) {
           claimAddress: r.client_evm_address,
           // the client claims the server's EVM HTLC
           expectedSats: r.evm_expected_sats,
-          token: r.wbtc_address
+          token: r.wbtc_address,
+          sender: r.server_evm_address,
+          // the server funded it
+          timelockSec: r.evm_refund_locktime,
+          createdAt: r.created_at
         }),
         clientRefundLocktime: ms(r.vhtlc_refund_locktime),
         serverRefundLocktime: ms(r.evm_refund_locktime)
@@ -1407,8 +1776,14 @@ function swapToTracked(stored) {
           hashLock: r.hash_lock,
           claimAddress: r.server_evm_address,
           // the server claims the client's EVM HTLC
-          expectedSats: r.evm_expected_sats
-          // evm_to_arkade doesn't expose the locked token — verify amount only.
+          expectedSats: r.evm_expected_sats,
+          // evm_to_arkade doesn't expose the locked token — fall back to the
+          // per-chain mainnet constant so the isActive tuple is complete.
+          token: lockedTokenFallback(r.evm_chain_id, r.network),
+          sender: r.client_evm_address,
+          // the client funded it
+          timelockSec: r.evm_refund_locktime,
+          createdAt: r.created_at
         }),
         serverHtlc: arkadeLeg(r, r.btc_vhtlc_address, Number(r.target_amount)),
         clientRefundLocktime: ms(r.evm_refund_locktime),
@@ -1421,7 +1796,8 @@ function swapToTracked(stored) {
         clientHtlc: bitcoinLeg(
           r.btc_htlc_address,
           r.evm_hash_lock,
-          Number(r.source_amount)
+          Number(r.source_amount),
+          CLIENT_FUNDING_MIN_CONFIRMATIONS
         ),
         serverHtlc: evmLeg({
           chainId: r.evm_chain_id,
@@ -1430,7 +1806,11 @@ function swapToTracked(stored) {
           claimAddress: r.client_evm_address,
           // the client claims the server's EVM HTLC
           expectedSats: r.evm_expected_sats,
-          token: r.wbtc_address
+          token: r.wbtc_address,
+          sender: r.server_evm_address,
+          // the server funded it
+          timelockSec: r.evm_refund_locktime,
+          createdAt: r.created_at
         }),
         clientRefundLocktime: ms(r.btc_refund_locktime),
         serverRefundLocktime: ms(r.evm_refund_locktime)
@@ -1446,7 +1826,11 @@ function swapToTracked(stored) {
           claimAddress: r.server_evm_address,
           // the server claims the client's EVM HTLC
           expectedSats: r.evm_expected_sats,
-          token: r.wbtc_address
+          token: r.wbtc_address,
+          sender: r.client_evm_address,
+          // the client funded it
+          timelockSec: r.evm_refund_locktime,
+          createdAt: r.created_at
         }),
         serverHtlc: bitcoinLeg(
           r.btc_htlc_address,
@@ -1466,7 +1850,8 @@ function swapToTracked(stored) {
         clientHtlc: bitcoinLeg(
           r.btc_htlc_address,
           r.hash_lock,
-          Number(r.source_amount)
+          Number(r.source_amount),
+          CLIENT_FUNDING_MIN_CONFIRMATIONS
         ),
         serverHtlc: buildArkadeVhtlcRef({
           senderPk: r.server_vhtlc_pk,
@@ -1480,7 +1865,8 @@ function swapToTracked(stored) {
           unilateralClaimDelay: r.unilateral_claim_delay,
           unilateralRefundDelay: r.unilateral_refund_delay,
           unilateralRefundWithoutReceiverDelay: r.unilateral_refund_without_receiver_delay,
-          expectedSats: Number(r.target_amount)
+          expectedSats: Number(r.target_amount),
+          arkadeHtlcScriptVersion: r.arkade_htlc_script_version
         }),
         clientRefundLocktime: ms(r.btc_refund_locktime),
         serverRefundLocktime: ms(r.vhtlc_refund_locktime)
@@ -1514,8 +1900,14 @@ function swapToTracked(stored) {
           hashLock: r.hash_lock,
           claimAddress: r.server_evm_address,
           // the server claims the client's leg
-          expectedSats: r.evm_expected_sats
-          // evm_to_lightning doesn't expose the locked token — verify amount only.
+          expectedSats: r.evm_expected_sats,
+          // evm_to_lightning doesn't expose the locked token — fall back to the
+          // per-chain mainnet constant so the isActive tuple is complete.
+          token: lockedTokenFallback(r.evm_chain_id, r.network),
+          sender: r.client_evm_address,
+          // the client funded it
+          timelockSec: r.evm_refund_locktime,
+          createdAt: r.created_at
         }),
         clientRefundLocktime: ms(r.evm_refund_locktime),
         serverRefundLocktime: 0
@@ -1548,7 +1940,11 @@ function swapToTracked(stored) {
           claimAddress: r.client_evm_address,
           // the client claims the server's leg
           expectedSats: r.evm_expected_sats,
-          token: r.wbtc_address
+          token: r.wbtc_address,
+          sender: r.server_evm_address,
+          // the server funded it
+          timelockSec: r.evm_refund_locktime,
+          createdAt: r.created_at
         }),
         clientRefundLocktime: 0,
         // no on-chain client leg
@@ -1567,11 +1963,14 @@ var SwapTracker = class {
   #lastActions = /* @__PURE__ */ new Map();
   #subscribers = /* @__PURE__ */ new Set();
   #refreshIntervalMs;
+  #atRiskReconcileIntervalMs;
+  #lastAtRiskReconcileAt = 0;
   #eventUnsubs = [];
   #timer;
   constructor(managers, options) {
     this.#managers = managers;
     this.#refreshIntervalMs = options?.refreshIntervalMs ?? 0;
+    this.#atRiskReconcileIntervalMs = options?.atRiskReconcileIntervalMs ?? 6e4;
   }
   /**
    * Whether every on-chain leg of `swap` is observable — i.e. the tracker can
@@ -1601,6 +2000,7 @@ var SwapTracker = class {
     }
     await this.#refreshManagers();
     this.#recomputeAll();
+    this.#lastAtRiskReconcileAt = Date.now();
     if (this.#refreshIntervalMs > 0)
       this.#timer = setInterval(
         () => void this.#tick(),
@@ -1640,25 +2040,73 @@ var SwapTracker = class {
     await Promise.all([...managers].map((manager) => manager.refresh()));
     this.#recompute(swap);
   }
+  /**
+   * The periodic tick: recompute every swap from extrapolated clocks (pure
+   * local work), and — at most every `atRiskReconcileIntervalMs` — re-read the
+   * chain for at-risk swaps. This is the trust boundary: the happy path rides
+   * server hints, but once the client's funds sit in an HTLC, refund
+   * availability (and the counterparty leg's state) is verified against the
+   * chain on a cadence the server can't influence.
+   */
   async #tick() {
-    await this.#refreshManagers();
+    const now = Date.now();
+    if (now - this.#lastAtRiskReconcileAt >= this.#atRiskReconcileIntervalMs) {
+      this.#lastAtRiskReconcileAt = now;
+      const legs = [...this.#swaps.values()].filter((swap) => this.#isAtRisk(swap)).flatMap((swap) => legsOf(swap));
+      await Promise.all(
+        legs.map(
+          (leg) => this.#managerFor(leg).reconcile(leg).catch((error) => {
+            console.warn("SwapTracker: at-risk reconcile failed:", error);
+          })
+        )
+      );
+    }
     this.#recomputeAll();
   }
   /**
-   * Re-poll the managers that have a registered leg — seeding/advancing their
-   * clocks and reconciling observations. Managers with nothing tracked are
-   * skipped: refreshing them still hits their clock source (e.g. Arkade/Bitcoin
-   * MTP via the API), so a swap that doesn't touch a ledger can't fail on that
+   * Whether a swap needs chain-verified monitoring independent of the server:
+   * its client leg holds (or held) funds on-chain, so knowing when a refund
+   * unlocks — or that the counterparty resolved a leg — must not depend on a
+   * hint arriving. An unfunded client leg (`absent`) is server-hint territory;
+   * an unseeded one (`undefined`, e.g. the prime failed on a flaky RPC) counts
+   * as at-risk so the tick heals it. A swap with no on-chain client leg
+   * (paying via Lightning) is at-risk while tracked: once the invoice is paid
+   * there is no on-chain trace of the client's exposure, and the server leg is
+   * the only thing left to watch.
+   */
+  #isAtRisk(swap) {
+    if (!swap.clientHtlc) return true;
+    const obs = this.#managerFor(swap.clientHtlc).getState(swap.clientHtlc);
+    return obs !== "absent";
+  }
+  /**
+   * Refresh the managers that have a registered leg — seeding their clocks and
+   * reconciling observations (the on-demand full read backing startTracking's
+   * prime and track()'s seed). Managers with nothing tracked are skipped:
+   * refreshing them still hits their clock source (e.g. Arkade/Bitcoin MTP via
+   * the API), so a swap that doesn't touch a ledger can't fail on that
    * ledger's endpoint being down (the default client builds every manager).
    */
   async #refreshManagers() {
     const active = /* @__PURE__ */ new Set();
     for (const swap of this.#swaps.values())
       for (const leg of legsOf(swap)) active.add(leg.ledger);
-    const managers = new Set(
-      [...active].map((ledger) => this.#managers.get(ledger)).filter((m) => m !== void 0)
+    const byManager = /* @__PURE__ */ new Map();
+    for (const ledger of active) {
+      const manager = this.#managers.get(ledger);
+      if (manager && !byManager.has(manager)) byManager.set(manager, ledger);
+    }
+    const ledgers = [...byManager.values()];
+    const results = await Promise.allSettled(
+      [...byManager.keys()].map((manager) => manager.refresh())
     );
-    await Promise.all([...managers].map((manager) => manager.refresh()));
+    results.forEach((result, index) => {
+      if (result.status === "rejected")
+        console.warn(
+          `SwapTracker: refreshing ${ledgers[index]} failed:`,
+          result.reason
+        );
+    });
   }
   /** The swap ids currently tracked — e.g. to subscribe them to a hint feed. */
   trackedSwapIds() {
@@ -1674,9 +2122,17 @@ var SwapTracker = class {
   async applyHint(swapId, opts) {
     const swap = this.#swaps.get(swapId);
     if (!swap) return;
-    await Promise.all(
-      legsOf(swap).map((leg) => this.#managerFor(leg).reconcile(leg))
+    const legs = legsOf(swap);
+    const results = await Promise.allSettled(
+      legs.map((leg) => this.#managerFor(leg).reconcile(leg))
     );
+    results.forEach((result, index) => {
+      if (result.status === "rejected")
+        console.warn(
+          `SwapTracker: hint reconcile failed for ${legs[index].ledger}:`,
+          result.reason
+        );
+    });
     this.#recompute(swap, opts?.force ?? false);
   }
   /** Notify `cb` of the current action for each tracked swap, then on every change. */
@@ -1734,15 +2190,21 @@ var SwapTracker = class {
     }
     const status = deriveSwapStatus({ clientHtlc, serverHtlc });
     if (status === void 0) return;
-    const actions = deriveSwapActions({
-      status,
-      clientChainNow,
-      serverChainNow,
-      clientRefundLocktime: swap.clientRefundLocktime,
-      serverRefundLocktime: swap.serverRefundLocktime,
-      // Pay-on-Lightning swaps have no client-funded on-chain leg.
-      clientFunds: swap.clientHtlc !== void 0
-    });
+    const actions = {
+      ...deriveSwapActions({
+        status,
+        clientChainNow,
+        serverChainNow,
+        clientRefundLocktime: swap.clientRefundLocktime,
+        serverRefundLocktime: swap.serverRefundLocktime,
+        // Pay-on-Lightning swaps have no client-funded on-chain leg.
+        clientFunds: swap.clientHtlc !== void 0
+      }),
+      // Expose the raw observations so consumers can render progress from
+      // chain facts (which leg is funded/spent) even when the server is
+      // stale/unreachable — without interpreting the SwapStatus enum.
+      observations: { clientHtlc, serverHtlc }
+    };
     const previous = this.#lastActions.get(swap.swapId);
     if (!force && previous && JSON.stringify(previous) === JSON.stringify(actions))
       return;
@@ -1773,15 +2235,17 @@ var Client = class {
   #tracker;
   /** Hint-driven auto-claim worker; only built when `withAutoClaim` opted in. */
   #worker;
-  #started = false;
+  #startPromise;
+  /** Swap ids whose settled status was already re-fetched this session. */
+  #settledSyncDone = /* @__PURE__ */ new Set();
   constructor(...args) {
-    if (args[0] instanceof import_lendaswap_sdk_pure.Client) {
+    if (args[0] instanceof import_lendaswap_sdk_pure2.Client) {
       this.#legacy = args[0];
       this.#tracking = args[1] ?? {
         enabled: false
       };
     } else {
-      this.#legacy = new import_lendaswap_sdk_pure.Client(
+      this.#legacy = new import_lendaswap_sdk_pure2.Client(
         ...args
       );
       this.#tracking = { enabled: false };
@@ -2107,33 +2571,69 @@ var Client = class {
    * Subscribe with {@link subscribeToActions}; release with
    * {@link stopTracking}.
    */
-  async startTracking() {
+  startTracking() {
     if (!this.#tracking.enabled)
-      throw new Error(
-        "tracking is disabled \u2014 remove .withoutTracking() to enable it"
+      return Promise.reject(
+        new Error(
+          "tracking is disabled \u2014 remove .withoutTracking() to enable it"
+        )
       );
-    if (this.#started) return;
-    this.#started = true;
+    this.#startPromise ??= this.#doStartTracking().catch((error) => {
+      this.#startPromise = void 0;
+      throw error;
+    });
+    return this.#startPromise;
+  }
+  async #doStartTracking() {
     try {
       const tracker = new SwapTracker(await this.#ensureManagers(), {
         refreshIntervalMs: this.#tracking.refreshIntervalMs ?? 5e3
       });
       this.#tracker = tracker;
       await tracker.startTracking(await this.#loadTrackedSwaps());
+      tracker.subscribeToActions(
+        (swapId, actions) => this.#syncSettledStatus(swapId, actions)
+      );
       this.#startWorker(tracker);
     } catch (error) {
       this.#worker?.stop();
       this.#worker = void 0;
       this.#tracker?.stop();
       this.#tracker = void 0;
-      this.#started = false;
       throw error;
     }
   }
+  /**
+   * The chain says this swap is finished (`none`) — if the STORED status still
+   * reads active, re-fetch and persist it so the next session's
+   * {@link #loadTrackedSwaps} settled-filter catches it (instead of tracking
+   * and scanning the swap once per session forever). Fire-and-forget with a
+   * per-session dedupe: a failed fetch just means one more one-scan round next
+   * session, which is exactly the current behavior. A swap whose stored status
+   * is already settled costs nothing (no server call).
+   */
+  #syncSettledStatus(swapId, actions) {
+    if (actions.recommended !== "none") return;
+    if (this.#settledSyncDone.has(swapId)) return;
+    this.#settledSyncDone.add(swapId);
+    void (async () => {
+      const stored = (await this.listAllSwaps()).find(
+        (s) => s.response.id === swapId
+      );
+      if (!stored || SETTLED_STORED_STATUSES.has(stored.response.status))
+        return;
+      await this.getSwap(swapId, { updateStorage: true });
+    })().catch((error) => {
+      console.warn(
+        `Client: refreshing settled status of swap ${swapId} failed:`,
+        error
+      );
+    });
+  }
   /** Every stored swap whose ledgers are observable, mapped to a {@link TrackedSwap}. */
   async #loadTrackedSwaps() {
     const swaps = await this.listAllSwaps();
-    return swaps.map(swapToTracked).filter((s) => s !== void 0);
+    return swaps.filter((s) => !SETTLED_STORED_STATUSES.has(s.response.status)).map(swapToTracked).filter((s) => s !== void 0);
   }
   /**
    * Run a create, then fold the new swap into tracking.
@@ -2195,27 +2695,29 @@ var Client = class {
     }
   }
   /**
-   * If auto-claim was opted in, wire the server status WebSocket into a
-   * {@link SwapWorker}: hints trigger a chain re-verify, and a swap the chain
-   * confirms claimable is auto-claimed; `fund`/refund actions are surfaced via the
-   * configured `onActionRequired`. A no-op unless `withAutoClaim` was set and a
-   * base URL is configured (the WebSocket needs a server to reach).
+   * Wire the server status WebSocket into a {@link SwapWorker} whenever a server
+   * URL is configured: pushed status transitions trigger a targeted chain
+   * re-verify (`applyHint`), which is what lets the chain pollers stay slow.
+   * Auto-EXECUTION on top of that is opt-in: only with `withAutoClaim` does the
+   * worker get an `execute` (claims) and an `onActionRequired` surface —
+   * otherwise it runs observe-only, hints in, no spends.
    */
   #startWorker(tracker) {
+    const serverUrl = this.#tracking.serverUrl;
+    if (!serverUrl) return;
     const autoClaim = this.#tracking.autoClaim;
-    if (!autoClaim) return;
-    if (!this.baseUrl) return;
-    const hintSource = new WsStatusSource({ serverUrl: this.baseUrl });
+    const hintSource = new WsStatusSource({ serverUrl });
     const worker = new SwapWorker({
       tracker,
       hintSource,
-      execute: async (swapId, actionId) => {
+      execute: autoClaim ? async (swapId, actionId) => {
         if (actionId !== "claim")
           throw new Error(`refusing to auto-run action '${actionId}'`);
         const result = await this.claim(swapId);
-        if (!result.success) throw new Error(result.message ?? "claim failed");
-      },
-      onActionRequired: autoClaim.onActionRequired
+        if (!result.success)
+          throw new Error(result.message ?? "claim failed");
+      } : void 0,
+      onActionRequired: autoClaim?.onActionRequired
     });
     this.#worker = worker;
     worker.start();
@@ -2236,7 +2738,7 @@ var Client = class {
     this.#worker = void 0;
     this.#tracker?.stop();
     this.#tracker = void 0;
-    this.#started = false;
+    this.#startPromise = void 0;
   }
   /**
    * Resolve the per-ledger managers once — the explicit override if given, else
@@ -2251,7 +2753,7 @@ var Client = class {
       return this.#managers;
     }
     const managers = /* @__PURE__ */ new Map();
-    const { arkadeServerUrl, evmRpcUrls, esploraUrl } = this.#tracking;
+    const { arkadeServerUrl, evmRpcUrls, esploraUrl, bitcoinMinConfirmations } = this.#tracking;
     const chainTime = async () => (await this.getMtp()).mtp * 1e3;
     const arkadeUrl = arkadeServerUrl ?? defaultArkadeServerUrl("bitcoin");
     if (arkadeUrl) {
@@ -2267,7 +2769,8 @@ var Client = class {
       "bitcoin",
       await BitcoinContractManager.create({
         esploraUrl: esploraUrl ? [esploraUrl] : DEFAULT_ESPLORA_URLS,
-        chainTime
+        chainTime,
+        minConfirmations: bitcoinMinConfirmations
       })
     );
     this.#managers = managers;
@@ -2275,12 +2778,14 @@ var Client = class {
   }
 };
 var ClientBuilder = class {
-  #inner = import_lendaswap_sdk_pure.Client.builder();
+  #inner = import_lendaswap_sdk_pure2.Client.builder();
   // Observe-mode tracking is on by default; the built client auto-builds its
   // managers from config unless disabled or given an explicit override.
   #trackingEnabled = true;
+  #serverUrl;
   #arkadeServerUrl;
   #esploraUrl;
+  #bitcoinMinConfirmations;
   #evmRpcUrls;
   #managers;
   #autoClaim;
@@ -2321,6 +2826,7 @@ var ClientBuilder = class {
   }
   withBaseUrl(...args) {
     this.#inner.withBaseUrl(...args);
+    this.#serverUrl = args[0];
     return this;
   }
   withReferralCode(...args) {
@@ -2344,6 +2850,18 @@ var ClientBuilder = class {
     this.#esploraUrl = url;
     return this;
   }
+  /**
+   * Confirmations a Bitcoin funding tx needs before it observes as `confirmed`
+   * (gating e.g. the evm→bitcoin claim). Default `0`: claim as soon as the
+   * funding hits the mempool, which TRUSTS the funder not to double-spend it
+   * (claiming publishes the preimage, so a funder that then replaced its
+   * funding could take both legs). Set `1` (or more) for a block-depth policy
+   * that doesn't rely on the funder's good behaviour.
+   */
+  withBitcoinMinConfirmations(minConfirmations) {
+    this.#bitcoinMinConfirmations = minConfirmations;
+    return this;
+  }
   /**
    * Override the Ark server URL. Optional for tracking — it otherwise defaults to
    * the mainnet server; set this to track a non-mainnet (dev/signet) deployment.
@@ -2384,14 +2902,24 @@ var ClientBuilder = class {
   async build() {
     return new Client(await this.#inner.build(), {
       enabled: this.#trackingEnabled,
+      serverUrl: this.#serverUrl,
       managers: this.#managers,
       arkadeServerUrl: this.#arkadeServerUrl,
       esploraUrl: this.#esploraUrl,
+      bitcoinMinConfirmations: this.#bitcoinMinConfirmations,
       evmRpcUrls: this.#evmRpcUrls,
       autoClaim: this.#autoClaim
     });
   }
 };
+var SETTLED_STORED_STATUSES = /* @__PURE__ */ new Set([
+  "serverredeemed",
+  "clientrefunded",
+  "clientrefundedserverfunded",
+  "clientrefundedserverrefunded",
+  "clientredeemedandclientrefunded",
+  "expired"
+]);
 function createdSwapId(result) {
   const id = result?.response?.id;
   return typeof id === "string" ? id : void 0;
@@ -2421,6 +2949,7 @@ init_bitcoin_reader_esplora();
   evmReaderFromClient,
   htlcFactsFromEsploraTxs,
   htlcKey,
+  htlcQueryKey,
   swapToTracked,
   ...require("@lendasat/lendaswap-sdk-pure")
 });