@satora/swap 0.1.0 → 0.2.0

package/dist/index.cjs

@@ -103,6 +103,8 @@ __export(src_exports, {
   DEFAULT_EVM_RPCS: () => DEFAULT_EVM_RPCS,
   EvmContractManager: () => EvmContractManager,
   SwapTracker: () => SwapTracker,
+  SwapWorker: () => SwapWorker,
+  WsStatusSource: () => WsStatusSource,
   buildArkadeVhtlcRef: () => buildArkadeVhtlcRef,
   createEvmRpcReader: () => createEvmRpcReader,
   defaultArkadeServerUrl: () => defaultArkadeServerUrl,
@@ -479,6 +481,9 @@ var ArkadeContractManager = class _ArkadeContractManager {
       chainTime: config.chainTime
     });
   }
+  canObserve(ref) {
+    return ref.ledger === "arkade";
+  }
   async register(ref) {
     if (ref.ledger !== "arkade")
       throw new Error(
@@ -509,6 +514,13 @@ var ArkadeContractManager = class _ArkadeContractManager {
       [...this.#refs.values()].map((ref) => this.#reconcileRef(ref))
     );
   }
+  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.#reconcileRef(tracked);
+  }
   dispose() {
     this.#listeners.clear();
   }
@@ -623,6 +635,9 @@ var BitcoinContractManager = class _BitcoinContractManager {
       chainTime: config.chainTime
     });
   }
+  canObserve(ref) {
+    return ref.ledger === "bitcoin";
+  }
   async register(ref) {
     if (ref.ledger !== "bitcoin")
       throw new Error(
@@ -653,6 +668,13 @@ var BitcoinContractManager = class _BitcoinContractManager {
       [...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;
+    if (this.#chainTime) this.#now = await this.#chainTime();
+    await this.#reconcileRef(tracked);
+  }
   dispose() {
     this.#listeners.clear();
   }
@@ -742,6 +764,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`);
@@ -780,6 +805,15 @@ var EvmContractManager = class _EvmContractManager {
     const chainIds = new Set([...this.#refs.values()].map((r) => r.chainId));
     await Promise.all([...chainIds].map((c) => this.#reconcileChain(c)));
   }
+  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);
+  }
   dispose() {
     for (const unsub of this.#watchUnsubs.values()) unsub();
     this.#watchUnsubs.clear();
@@ -963,6 +997,310 @@ 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);
+        });
+      })
+    );
+    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();
+  }
+  #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.#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) {
+    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) => {
+      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 pending swap is not broken, only slower: it gets no hints, so it advances
+   * on the tracker's chain poll instead.
+   */
+  #pending = /* @__PURE__ */ new Set();
+  #listeners = /* @__PURE__ */ new Set();
+  #ws;
+  #open = false;
+  #stopped = 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);
+  }
+  /**
+   * 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]);
+    };
+    ws.onmessage = (event) => this.#handleMessage(event.data);
+    ws.onclose = () => this.#onDisconnect();
+    ws.onerror = () => this.#ws?.close();
+  }
+  #onDisconnect() {
+    this.#open = false;
+    this.#ws = void 0;
+    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_legacy2 = require("@noble/hashes/legacy.js");
@@ -1235,9 +1573,26 @@ var SwapTracker = class {
     this.#managers = managers;
     this.#refreshIntervalMs = options?.refreshIntervalMs ?? 0;
   }
+  /**
+   * 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);
     }
@@ -1252,6 +1607,39 @@ var SwapTracker = class {
         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);
+  }
   async #tick() {
     await this.#refreshManagers();
     this.#recomputeAll();
@@ -1272,6 +1660,25 @@ var SwapTracker = class {
     );
     await Promise.all([...managers].map((manager) => manager.refresh()));
   }
+  /** 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;
+    await Promise.all(
+      legsOf(swap).map((leg) => this.#managerFor(leg).reconcile(leg))
+    );
+    this.#recompute(swap, opts?.force ?? false);
+  }
   /** Notify `cb` of the current action for each tracked swap, then on every change. */
   subscribeToActions(cb) {
     this.#subscribers.add(cb);
@@ -1306,7 +1713,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;
@@ -1337,7 +1744,7 @@ var SwapTracker = class {
       clientFunds: swap.clientHtlc !== void 0
     });
     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,6 +1771,8 @@ var Client = class {
   /** Per-ledger monitors, resolved once from {@link #tracking}. */
   #managers;
   #tracker;
+  /** Hint-driven auto-claim worker; only built when `withAutoClaim` opted in. */
+  #worker;
   #started = false;
   constructor(...args) {
     if (args[0] instanceof import_lendaswap_sdk_pure.Client) {
@@ -1578,31 +1987,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 +2029,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 +2082,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);
   }
@@ -1686,16 +2119,107 @@ var Client = class {
         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());
+      this.#startWorker(tracker);
     } catch (error) {
+      this.#worker?.stop();
+      this.#worker = void 0;
       this.#tracker?.stop();
       this.#tracker = void 0;
       this.#started = false;
       throw 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);
+  }
+  /**
+   * 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);
+      }
+    }
+  }
+  /**
+   * 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).
+   */
+  #startWorker(tracker) {
+    const autoClaim = this.#tracking.autoClaim;
+    if (!autoClaim) return;
+    if (!this.baseUrl) return;
+    const hintSource = new WsStatusSource({ serverUrl: this.baseUrl });
+    const worker = new SwapWorker({
+      tracker,
+      hintSource,
+      execute: 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
+    });
+    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,6 +2232,8 @@ 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;
@@ -1757,6 +2283,7 @@ var ClientBuilder = class {
   #esploraUrl;
   #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 +2293,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;
@@ -1848,10 +2387,15 @@ var ClientBuilder = class {
       managers: this.#managers,
       arkadeServerUrl: this.#arkadeServerUrl,
       esploraUrl: this.#esploraUrl,
-      evmRpcUrls: this.#evmRpcUrls
+      evmRpcUrls: this.#evmRpcUrls,
+      autoClaim: this.#autoClaim
     });
   }
 };
+function createdSwapId(result) {
+  const id = result?.response?.id;
+  return typeof id === "string" ? id : void 0;
+}
 
 // src/index.ts
 init_bitcoin_reader_esplora();
@@ -1865,6 +2409,8 @@ init_bitcoin_reader_esplora();
   DEFAULT_EVM_RPCS,
   EvmContractManager,
   SwapTracker,
+  SwapWorker,
+  WsStatusSource,
   buildArkadeVhtlcRef,
   createEvmRpcReader,
   defaultArkadeServerUrl,