@satora/swap 0.1.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;
         }
@@ -103,6 +119,8 @@ __export(src_exports, {
   DEFAULT_EVM_RPCS: () => DEFAULT_EVM_RPCS,
   EvmContractManager: () => EvmContractManager,
   SwapTracker: () => SwapTracker,
+  SwapWorker: () => SwapWorker,
+  WsStatusSource: () => WsStatusSource,
   buildArkadeVhtlcRef: () => buildArkadeVhtlcRef,
   createEvmRpcReader: () => createEvmRpcReader,
   defaultArkadeServerUrl: () => defaultArkadeServerUrl,
@@ -113,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,
@@ -133,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",
@@ -152,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."
@@ -171,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."
@@ -201,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."
@@ -219,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."
@@ -238,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."
@@ -248,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."
@@ -257,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."
@@ -268,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."
@@ -277,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."
@@ -299,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."
@@ -398,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");
@@ -463,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;
@@ -479,13 +522,15 @@ var ArkadeContractManager = class _ArkadeContractManager {
       chainTime: config.chainTime
     });
   }
+  canObserve(ref) {
+    return ref.ledger === "arkade";
+  }
   async register(ref) {
     if (ref.ledger !== "arkade")
       throw new Error(
         `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;
@@ -497,17 +542,28 @@ 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;
+    await this.#readClock();
+    await this.#reconcileRef(tracked);
   }
   dispose() {
     this.#listeners.clear();
@@ -516,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] });
@@ -608,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;
@@ -619,10 +688,15 @@ 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
     });
   }
+  canObserve(ref) {
+    return ref.ledger === "bitcoin";
+  }
   async register(ref) {
     if (ref.ledger !== "bitcoin")
       throw new Error(
@@ -641,18 +715,31 @@ 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))
     );
   }
+  async reconcile(ref) {
+    if (ref.ledger !== "bitcoin") return;
+    const tracked = this.#refs.get(ref.address);
+    if (!tracked) return;
+    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();
   }
@@ -661,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),
@@ -710,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;
@@ -727,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;
@@ -742,6 +871,9 @@ var EvmContractManager = class _EvmContractManager {
   static fromDeps(deps) {
     return new _EvmContractManager(deps);
   }
+  canObserve(ref) {
+    return ref.ledger === "evm" && this.#readers.has(ref.chainId);
+  }
   async register(ref) {
     if (ref.ledger !== "evm")
       throw new Error(`EvmContractManager can't track a '${ref.ledger}' HTLC`);
@@ -750,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;
@@ -759,91 +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;
+    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) {
@@ -858,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");
@@ -869,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);
 }
@@ -963,8 +1294,350 @@ function defaultEvmReaders(overrides) {
   return readers;
 }
 
+// src/hints/swap-worker.ts
+var AUTO_EXECUTABLE = /* @__PURE__ */ new Set([
+  "claim"
+]);
+var SwapWorker = class {
+  #tracker;
+  #hintSource;
+  #execute;
+  #onActionRequired;
+  #maxAttempts;
+  #baseDelayMs;
+  #maxDelayMs;
+  /** Swaps with an auto action in flight — guards against double-runs. */
+  #executing = /* @__PURE__ */ new Set();
+  /** Swaps with a scheduled auto-claim retry (backoff timer + attempt count). */
+  #retries = /* @__PURE__ */ new Map();
+  #unsubs = [];
+  #started = false;
+  constructor(options) {
+    this.#tracker = options.tracker;
+    this.#hintSource = options.hintSource;
+    this.#execute = options.execute;
+    this.#onActionRequired = options.onActionRequired;
+    this.#maxAttempts = options.retry?.maxAttempts ?? 5;
+    this.#baseDelayMs = options.retry?.baseDelayMs ?? 2e3;
+    this.#maxDelayMs = options.retry?.maxDelayMs ?? 3e4;
+  }
+  /** Watch tracked swaps on the hint feed, wire hints → verify, react to actions. */
+  start() {
+    if (this.#started) return;
+    this.#started = true;
+    this.#hintSource.subscribe(this.#tracker.trackedSwapIds());
+    this.#unsubs.push(
+      this.#hintSource.onStatus(({ swapId }) => {
+        void this.#tracker.applyHint(swapId).catch((error) => {
+          console.warn(`SwapWorker: applyHint(${swapId}) failed:`, error);
+        });
+      })
+    );
+    if (this.#hintSource.onReconnect)
+      this.#unsubs.push(
+        this.#hintSource.onReconnect(() => this.#reverifyAllTracked())
+      );
+    this.#hintSource.start();
+    this.#unsubs.push(
+      this.#tracker.subscribeToActions(
+        (swapId, actions) => this.#onActions(swapId, actions)
+      )
+    );
+  }
+  /** Stop reacting, cancel pending retries, and close the hint feed. */
+  stop() {
+    this.#started = false;
+    for (const unsub of this.#unsubs) unsub();
+    this.#unsubs = [];
+    this.#hintSource.stop();
+    for (const { timer } of this.#retries.values()) clearTimeout(timer);
+    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") {
+      this.#hintSource.unsubscribe([swapId]);
+      this.#cancelRetry(swapId);
+      return;
+    }
+    this.#hintSource.subscribe([swapId]);
+    if (recommended && AUTO_EXECUTABLE.has(recommended) && this.#execute) {
+      this.#autoExecute(swapId, actions);
+      return;
+    }
+    this.#cancelRetry(swapId);
+    if (!recommended) return;
+    const automation = actions.actions.find(
+      (a) => a.id === recommended
+    )?.automation;
+    if (automation === "manual" || automation === "confirm")
+      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 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));
+  }
+  /** Schedule the next backoff retry, or give up and surface once attempts run out. */
+  #scheduleRetry(swapId, actions) {
+    const attempts = (this.#retries.get(swapId)?.attempts ?? 0) + 1;
+    if (attempts > this.#maxAttempts) {
+      console.warn(
+        `SwapWorker: auto-claim for ${swapId} gave up after ${this.#maxAttempts} attempts`
+      );
+      this.#cancelRetry(swapId);
+      this.#onActionRequired?.(swapId, actions);
+      return;
+    }
+    this.#clearTimer(swapId);
+    const delay = Math.min(
+      this.#baseDelayMs * 2 ** (attempts - 1),
+      this.#maxDelayMs
+    );
+    const timer = setTimeout(() => this.#retry(swapId, actions), delay);
+    this.#retries.set(swapId, { attempts, timer });
+  }
+  /**
+   * A retry fires: re-verify against chain (forced re-emit), which drives
+   * {@link #onActions} to re-run the claim only if it is still recommended. If the
+   * re-verify itself fails we can't safely retry, so back off and try the cycle
+   * again.
+   */
+  #retry(swapId, actions) {
+    void this.#tracker.applyHint(swapId, { force: true }).catch((error) => {
+      console.warn(
+        `SwapWorker: re-verify before retrying ${swapId} failed:`,
+        error
+      );
+      this.#scheduleRetry(swapId, actions);
+    });
+  }
+  #cancelRetry(swapId) {
+    this.#clearTimer(swapId);
+    this.#retries.delete(swapId);
+  }
+  #clearTimer(swapId) {
+    const existing = this.#retries.get(swapId);
+    if (existing) clearTimeout(existing.timer);
+  }
+};
+
+// src/hints/ws-status-source.ts
+var MAX_ARGS_PER_FRAME = 64;
+var MAX_SUBSCRIPTIONS = 256;
+var WsStatusSource = class {
+  #url;
+  #factory;
+  #reconnectMinMs;
+  #reconnectMaxMs;
+  /**
+   * Ids actually subscribed on the wire — held at or below the server's
+   * per-connection cap, and resent in full on every (re)connect.
+   */
+  #active = /* @__PURE__ */ new Set();
+  /**
+   * 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 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) {
+    this.#url = toWsUrl(options.serverUrl);
+    this.#factory = options.webSocketFactory ?? defaultWebSocketFactory;
+    this.#reconnectMinMs = options.reconnectMinMs ?? 1e3;
+    this.#reconnectMaxMs = options.reconnectMaxMs ?? 3e4;
+    this.#backoffMs = this.#reconnectMinMs;
+  }
+  /** Open the connection and begin (re)subscribing. Idempotent. */
+  start() {
+    if (this.#ws || this.#reconnectTimer) return;
+    this.#stopped = false;
+    this.#connect();
+  }
+  /** Close the connection and stop reconnecting. */
+  stop() {
+    this.#stopped = true;
+    if (this.#reconnectTimer) clearTimeout(this.#reconnectTimer);
+    this.#reconnectTimer = void 0;
+    this.#open = false;
+    this.#ws?.close();
+    this.#ws = void 0;
+  }
+  /** Emit for each pushed status update. Returns an unsubscribe fn. */
+  onStatus(cb) {
+    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.
+   *
+   * Enforces the server's per-connection cap locally. The server silently stops
+   * adding once it is full (it breaks out of the loop but still acks every id),
+   * so sending more would leave us believing ids are subscribed that will never
+   * receive an update. Overflow is queued instead and promoted as slots free.
+   */
+  subscribe(swapIds) {
+    const fresh = swapIds.filter(
+      (id) => !this.#active.has(id) && !this.#pending.has(id)
+    );
+    if (fresh.length === 0) return;
+    const admitted = [];
+    for (const id of fresh) {
+      if (this.#active.size < MAX_SUBSCRIPTIONS) {
+        this.#active.add(id);
+        admitted.push(id);
+      } else {
+        this.#pending.add(id);
+      }
+    }
+    if (this.#pending.size > 0)
+      console.warn(
+        `WsStatusSource: at the server cap of ${MAX_SUBSCRIPTIONS} subscriptions; ${this.#pending.size} swap(s) queued for a slot and will advance on the chain poll until then`
+      );
+    if (this.#open && admitted.length > 0)
+      this.#sendFrame("subscribe", admitted);
+  }
+  /** Stop tracking these swap ids, promoting queued ones into the freed slots. */
+  unsubscribe(swapIds) {
+    const dropped = [];
+    for (const id of swapIds) {
+      if (this.#active.delete(id)) dropped.push(id);
+      else this.#pending.delete(id);
+    }
+    if (this.#open && dropped.length > 0)
+      this.#sendFrame("unsubscribe", dropped);
+    this.#promotePending();
+  }
+  /** Move queued ids into any free slots, subscribing them if the socket is open. */
+  #promotePending() {
+    if (this.#pending.size === 0) return;
+    const promoted = [];
+    for (const id of this.#pending) {
+      if (this.#active.size >= MAX_SUBSCRIPTIONS) break;
+      this.#pending.delete(id);
+      this.#active.add(id);
+      promoted.push(id);
+    }
+    if (this.#open && promoted.length > 0)
+      this.#sendFrame("subscribe", promoted);
+  }
+  #connect() {
+    this.#reconnectTimer = void 0;
+    const ws = this.#factory(this.#url);
+    this.#ws = ws;
+    ws.onopen = () => {
+      this.#backoffMs = this.#reconnectMinMs;
+      this.#promotePending();
+      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();
+    ws.onerror = () => this.#ws?.close();
+  }
+  #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);
+    this.#reconnectTimer = setTimeout(() => this.#connect(), delay);
+  }
+  #handleMessage(data) {
+    if (typeof data !== "string") return;
+    let frame;
+    try {
+      frame = JSON.parse(data);
+    } catch {
+      return;
+    }
+    if (!frame || typeof frame !== "object") return;
+    const f = frame;
+    if (f.data && typeof f.data === "object") {
+      for (const [swapId, status] of Object.entries(
+        f.data
+      ))
+        this.#emit({ swapId, status });
+      return;
+    }
+    if (typeof f.message === "string")
+      console.warn(`WsStatusSource: server error: ${f.message}`);
+  }
+  #emit(update) {
+    for (const cb of this.#listeners) cb(update);
+  }
+  #sendFrame(op, ids) {
+    for (let i = 0; i < ids.length; i += MAX_ARGS_PER_FRAME) {
+      const args = ids.slice(i, i + MAX_ARGS_PER_FRAME);
+      this.#ws?.send(JSON.stringify({ op, channel: "swap_status", args }));
+    }
+  }
+};
+function toWsUrl(serverUrl) {
+  const url = new URL(serverUrl);
+  const scheme = url.protocol === "https:" ? "wss" : "ws";
+  const path = url.pathname.replace(/\/+$/, "");
+  return `${scheme}://${url.host}${path}/ws`;
+}
+function defaultWebSocketFactory(url) {
+  const WS = globalThis.WebSocket;
+  if (!WS)
+    throw new Error(
+      "no global WebSocket available \u2014 pass options.webSocketFactory (Node < 22)"
+    );
+  return new WS(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) {
@@ -991,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),
@@ -1004,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) {
@@ -1017,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,
@@ -1028,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) {
@@ -1054,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)
@@ -1069,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),
@@ -1083,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,
@@ -1092,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)
@@ -1108,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,
@@ -1128,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,
@@ -1142,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)
@@ -1176,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
@@ -1210,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
@@ -1229,15 +1963,35 @@ 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
+   * derive its status from chain. `false` means a leg is on a ledger/chain this
+   * client can't reach (no manager, or an EVM chain with no RPC), so the swap
+   * can't be tracked. Pure predicate — callers decide the policy (skip vs reject).
+   */
+  canObserve(swap) {
+    return legsOf(swap).every(
+      (leg) => this.#managers.get(leg.ledger)?.canObserve(leg) ?? false
+    );
   }
   /** Register each swap's on-chain leg(s), subscribe to manager events, and seed state. */
   async startTracking(swaps) {
     for (const swap of swaps) {
+      if (!this.canObserve(swap)) {
+        console.warn(
+          `SwapTracker: skipping swap ${swap.swapId} \u2014 a leg is on a chain this client can't reach (configure it to track this swap)`
+        );
+        continue;
+      }
       this.#swaps.set(swap.swapId, swap);
       for (const leg of legsOf(swap)) await this.#managerFor(leg).register(leg);
     }
@@ -1246,31 +2000,140 @@ var SwapTracker = class {
     }
     await this.#refreshManagers();
     this.#recomputeAll();
+    this.#lastAtRiskReconcileAt = Date.now();
     if (this.#refreshIntervalMs > 0)
       this.#timer = setInterval(
         () => void this.#tick(),
         this.#refreshIntervalMs
       );
   }
+  /**
+   * Track one more swap after {@link startTracking} — register its on-chain
+   * leg(s), seed the managers they touch, and derive its first action. Idempotent:
+   * a swap already tracked, or one already seen through to a terminal action, is
+   * ignored. New swaps are picked up by the existing per-manager event listeners
+   * and poll timer, so nothing else needs re-wiring. Lets a swap created after
+   * start (e.g. via `createSwap`) be tracked without a restart.
+   */
+  async track(swap) {
+    if (this.#swaps.has(swap.swapId) || this.#lastActions.has(swap.swapId))
+      return;
+    if (!this.canObserve(swap)) {
+      console.warn(
+        `SwapTracker: skipping swap ${swap.swapId} \u2014 a leg is on a chain this client can't reach (configure it to track this swap)`
+      );
+      return;
+    }
+    this.#swaps.set(swap.swapId, swap);
+    const registered = [];
+    try {
+      for (const leg of legsOf(swap)) {
+        await this.#managerFor(leg).register(leg);
+        registered.push(leg);
+      }
+    } catch (error) {
+      this.#swaps.delete(swap.swapId);
+      for (const leg of registered) void this.#managerFor(leg).unregister(leg);
+      throw error;
+    }
+    const managers = new Set(legsOf(swap).map((leg) => this.#managerFor(leg)));
+    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() {
+    return [...this.#swaps.keys()];
+  }
+  /**
+   * Re-verify one swap against the chain right now — the hook a faster server
+   * status hint drives. Reconciles just that swap's legs (targeted, on the
+   * managers), then recomputes its action. The hint is only a *trigger*: the
+   * chain stays the source of truth, so a premature hint that the chain doesn't
+   * yet reflect changes nothing. A no-op for an untracked swap.
+   */
+  async applyHint(swapId, opts) {
+    const swap = this.#swaps.get(swapId);
+    if (!swap) return;
+    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. */
   subscribeToActions(cb) {
@@ -1306,7 +2169,7 @@ var SwapTracker = class {
   #recomputeAll() {
     for (const swap of this.#swaps.values()) this.#recompute(swap);
   }
-  #recompute(swap) {
+  #recompute(swap, force = false) {
     let clientHtlc;
     let serverHtlc;
     let clientChainNow = 0;
@@ -1327,17 +2190,23 @@ 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 (previous && JSON.stringify(previous) === JSON.stringify(actions))
+    if (!force && previous && JSON.stringify(previous) === JSON.stringify(actions))
       return;
     this.#lastActions.set(swap.swapId, actions);
     for (const cb of this.#subscribers) cb(swap.swapId, actions);
@@ -1364,15 +2233,19 @@ var Client = class {
   /** Per-ledger monitors, resolved once from {@link #tracking}. */
   #managers;
   #tracker;
-  #started = false;
+  /** Hint-driven auto-claim worker; only built when `withAutoClaim` opted in. */
+  #worker;
+  #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 };
@@ -1578,31 +2451,41 @@ var Client = class {
   }
   /** Delegated to the legacy client (migration checkpoint). */
   createSwap(...args) {
-    return this.#legacy.createSwap(...args);
+    return this.#trackAfterCreate(this.#legacy.createSwap(...args));
   }
   /** Delegated to the legacy client (migration checkpoint). */
   createArkadeToEvmSwapGeneric(...args) {
-    return this.#legacy.createArkadeToEvmSwapGeneric(...args);
+    return this.#trackAfterCreate(
+      this.#legacy.createArkadeToEvmSwapGeneric(...args)
+    );
   }
   /** Delegated to the legacy client (migration checkpoint). */
   createLightningToEvmSwapGeneric(...args) {
-    return this.#legacy.createLightningToEvmSwapGeneric(...args);
+    return this.#trackAfterCreate(
+      this.#legacy.createLightningToEvmSwapGeneric(...args)
+    );
   }
   /** Delegated to the legacy client (migration checkpoint). */
   createBitcoinToEvmSwap(...args) {
-    return this.#legacy.createBitcoinToEvmSwap(...args);
+    return this.#trackAfterCreate(this.#legacy.createBitcoinToEvmSwap(...args));
   }
   /** Delegated to the legacy client (migration checkpoint). */
   createBitcoinToArkadeSwap(...args) {
-    return this.#legacy.createBitcoinToArkadeSwap(...args);
+    return this.#trackAfterCreate(
+      this.#legacy.createBitcoinToArkadeSwap(...args)
+    );
   }
   /** Delegated to the legacy client (migration checkpoint). */
   createLightningToArkadeSwap(...args) {
-    return this.#legacy.createLightningToArkadeSwap(...args);
+    return this.#trackAfterCreate(
+      this.#legacy.createLightningToArkadeSwap(...args)
+    );
   }
   /** Delegated to the legacy client (migration checkpoint). */
   createArkadeToLightningSwap(...args) {
-    return this.#legacy.createArkadeToLightningSwap(...args);
+    return this.#trackAfterCreate(
+      this.#legacy.createArkadeToLightningSwap(...args)
+    );
   }
   /** Delegated to the legacy client (migration checkpoint). */
   getArkadeToLightningQuote(...args) {
@@ -1610,19 +2493,25 @@ var Client = class {
   }
   /** Delegated to the legacy client (migration checkpoint). */
   retryArkadeToLightningSwap(...args) {
-    return this.#legacy.retryArkadeToLightningSwap(...args);
+    return this.#trackAfterRetry(
+      this.#legacy.retryArkadeToLightningSwap(...args)
+    );
   }
   /** Delegated to the legacy client (migration checkpoint). */
   createEvmToArkadeSwapGeneric(...args) {
-    return this.#legacy.createEvmToArkadeSwapGeneric(...args);
+    return this.#trackAfterCreate(
+      this.#legacy.createEvmToArkadeSwapGeneric(...args)
+    );
   }
   /** Delegated to the legacy client (migration checkpoint). */
   createEvmToBitcoinSwap(...args) {
-    return this.#legacy.createEvmToBitcoinSwap(...args);
+    return this.#trackAfterCreate(this.#legacy.createEvmToBitcoinSwap(...args));
   }
   /** Delegated to the legacy client (migration checkpoint). */
   createEvmToLightningSwapGeneric(...args) {
-    return this.#legacy.createEvmToLightningSwapGeneric(...args);
+    return this.#trackAfterCreate(
+      this.#legacy.createEvmToLightningSwapGeneric(...args)
+    );
   }
   /** Delegated to the legacy client (migration checkpoint). */
   getCoordinatorFundingCallDataPermit2(...args) {
@@ -1657,6 +2546,14 @@ var Client = class {
     return this.#legacy.getEvmDepositorKey(...args);
   }
   /** Delegated to the legacy client (migration checkpoint). */
+  getRefundedEvmSwapContinuation(...args) {
+    return this.#legacy.getRefundedEvmSwapContinuation(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  continueRefundedEvmSwap(...args) {
+    return this.#trackAfterRetry(this.#legacy.continueRefundedEvmSwap(...args));
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
   recoverGaslessFunds(...args) {
     return this.#legacy.recoverGaslessFunds(...args);
   }
@@ -1674,28 +2571,157 @@ 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;
-      const swaps = await this.listAllSwaps();
-      const tracked = swaps.map(swapToTracked).filter((s) => s !== void 0);
-      await tracker.startTracking(tracked);
+      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.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.
+   *
+   * When tracking is active, first REJECT a swap this client can't reach: a leg on
+   * an unconfigured chain can be neither observed nor claimed, so creating it would
+   * strand funds. Throwing here (before the caller funds it) is deliberately
+   * stricter than {@link startTracking}, which only *skips* such a pre-existing
+   * swap. Otherwise fold the new swap(s) in — fire-and-forget, so a tracking hiccup
+   * never fails or delays the create; a no-op when tracking isn't running (a later
+   * {@link startTracking} picks it up from storage).
+   */
+  async #trackAfterCreate(op) {
+    const result = await op;
+    const tracker = this.#tracker;
+    if (!tracker) return result;
+    let swaps;
+    try {
+      swaps = await this.#loadTrackedSwaps();
+    } catch (error) {
+      console.warn("Client: loading swaps after create failed:", error);
+      return result;
+    }
+    const created = swaps.find((s) => s.swapId === createdSwapId(result));
+    if (created && !tracker.canObserve(created))
+      throw new Error(
+        `Refusing swap ${created.swapId}: a leg is on a chain this client can't reach, so it can be neither tracked nor claimed. Configure the chain (e.g. ClientBuilder.withEvmRpcUrls) before creating it.`
+      );
+    void this.#trackAll(tracker, swaps);
+    return result;
+  }
+  /**
+   * Run a retry, then fold its replacement swap into tracking.
+   *
+   * Unlike a create there is no unreachable-leg
+   * rejection: by the time the retry returns, the old VHTLC has already been
+   * collab-refunded into the new one, so refusing here can't protect any funds
+   * — and {@link SwapTracker.track} skips a swap it can't observe anyway.
+   */
+  async #trackAfterRetry(op) {
+    const result = await op;
+    const tracker = this.#tracker;
+    if (!tracker) return result;
+    try {
+      void this.#trackAll(tracker, await this.#loadTrackedSwaps());
+    } catch (error) {
+      console.warn("Client: loading swaps after retry failed:", error);
+    }
+    return result;
+  }
+  /** Track each given swap the tracker isn't already watching (isolated per swap). */
+  async #trackAll(tracker, swaps) {
+    for (const swap of swaps) {
+      try {
+        await tracker.track(swap);
+      } catch (error) {
+        console.warn(`Client: tracking swap ${swap.swapId} failed:`, error);
+      }
+    }
+  }
+  /**
+   * 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;
+    const hintSource = new WsStatusSource({ serverUrl });
+    const worker = new SwapWorker({
+      tracker,
+      hintSource,
+      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");
+      } : void 0,
+      onActionRequired: autoClaim?.onActionRequired
+    });
+    this.#worker = worker;
+    worker.start();
+  }
   /**
    * Subscribe to next-action updates: `cb` fires with the current action for each
    * tracked swap immediately, then on every change. Call after
@@ -1708,9 +2734,11 @@ var Client = class {
   }
   /** Stop tracking and drop subscribers. The managers themselves are not disposed. */
   stopTracking() {
+    this.#worker?.stop();
+    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
@@ -1725,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) {
@@ -1741,7 +2769,8 @@ var Client = class {
       "bitcoin",
       await BitcoinContractManager.create({
         esploraUrl: esploraUrl ? [esploraUrl] : DEFAULT_ESPLORA_URLS,
-        chainTime
+        chainTime,
+        minConfirmations: bitcoinMinConfirmations
       })
     );
     this.#managers = managers;
@@ -1749,14 +2778,17 @@ 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;
   /**
    * Override the EVM JSON-RPC endpoint per chainId. Optional — tracking uses
    * tested public defaults otherwise; an override is tried first, with the
@@ -1766,6 +2798,18 @@ var ClientBuilder = class {
     this.#evmRpcUrls = urls;
     return this;
   }
+  /**
+   * Opt in to hint-driven auto-claim. Tracking then also subscribes to the
+   * server status WebSocket (a faster trigger than the chain poll) and, when the
+   * chain confirms a swap is claimable, claims it automatically. Actions that
+   * need the user — a manual `fund`, or a refund to confirm — are surfaced via
+   * `onActionRequired` instead of being run. Off by default: this auto-spends on
+   * the user's behalf, so it must be explicit.
+   */
+  withAutoClaim(options) {
+    this.#autoClaim = { onActionRequired: options?.onActionRequired };
+    return this;
+  }
   /** Turn observe-mode tracking off. */
   withoutTracking() {
     this.#trackingEnabled = false;
@@ -1782,6 +2826,7 @@ var ClientBuilder = class {
   }
   withBaseUrl(...args) {
     this.#inner.withBaseUrl(...args);
+    this.#serverUrl = args[0];
     return this;
   }
   withReferralCode(...args) {
@@ -1805,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.
@@ -1845,13 +2902,28 @@ 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,
-      evmRpcUrls: this.#evmRpcUrls
+      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;
+}
 
 // src/index.ts
 init_bitcoin_reader_esplora();
@@ -1865,6 +2937,8 @@ init_bitcoin_reader_esplora();
   DEFAULT_EVM_RPCS,
   EvmContractManager,
   SwapTracker,
+  SwapWorker,
+  WsStatusSource,
   buildArkadeVhtlcRef,
   createEvmRpcReader,
   defaultArkadeServerUrl,
@@ -1875,6 +2949,7 @@ init_bitcoin_reader_esplora();
   evmReaderFromClient,
   htlcFactsFromEsploraTxs,
   htlcKey,
+  htlcQueryKey,
   swapToTracked,
   ...require("@lendasat/lendaswap-sdk-pure")
 });