@satora/swap 0.0.5 → 0.2.0

package/dist/index.js

@@ -1,3 +1,2317 @@
+import {
+  DEFAULT_ESPLORA_URLS,
+  esploraReader,
+  htlcFactsFromEsploraTxs
+} from "./chunk-J35RZBDW.js";
+
 // src/index.ts
 export * from "@lendasat/lendaswap-sdk-pure";
+
+// src/actions/derive.ts
+function deriveSwapActions(input) {
+  const {
+    status,
+    clientChainNow,
+    serverChainNow,
+    clientRefundLocktime,
+    serverRefundLocktime,
+    clientFunds = true
+  } = input;
+  switch (status) {
+    case "pending": {
+      if (!clientFunds) {
+        const wait = {
+          id: "wait",
+          recommended: true,
+          automation: "auto",
+          reason: "Waiting for the Lightning payment to be locked in."
+        };
+        return { recommended: "wait", actions: [wait] };
+      }
+      if (clientChainNow >= clientRefundLocktime) return { actions: [] };
+      const fund = {
+        id: "fund",
+        recommended: true,
+        // Funding spends new user money, so it is never auto-run.
+        automation: "manual",
+        reason: "Send the deposit to start the swap."
+      };
+      return { recommended: "fund", actions: [fund] };
+    }
+    case "clientfundingseen": {
+      const wait = {
+        id: "wait",
+        recommended: true,
+        automation: "auto",
+        reason: "Waiting for your funding transaction to confirm."
+      };
+      return { recommended: "wait", actions: [wait] };
+    }
+    case "clientfunded": {
+      const refundUnlocked = clientChainNow >= clientRefundLocktime;
+      if (refundUnlocked) {
+        const refund2 = {
+          id: "refund_unilateral",
+          recommended: true,
+          automation: "confirm",
+          reason: "Reclaim your deposit."
+        };
+        return { recommended: "refund_unilateral", actions: [refund2] };
+      }
+      const wait = {
+        id: "wait",
+        recommended: true,
+        automation: "auto",
+        reason: "Waiting for the server to fund the swap."
+      };
+      const refund = {
+        id: "refund_unilateral",
+        recommended: false,
+        automation: "confirm",
+        reason: "Refund becomes available once the timelock passes.",
+        blockedBy: {
+          kind: "timelock_not_expired",
+          message: "The refund timelock has not passed yet."
+        }
+      };
+      return { recommended: "wait", actions: [wait, refund] };
+    }
+    case "serverfunded": {
+      const claimWindowClosed = serverChainNow >= serverRefundLocktime;
+      if (!claimWindowClosed) {
+        const claim = {
+          id: "claim",
+          recommended: true,
+          automation: "auto",
+          reason: "Redeem the swap with your preimage."
+        };
+        return { recommended: "claim", actions: [claim] };
+      }
+      if (!clientFunds) {
+        const done = {
+          id: "none",
+          recommended: true,
+          automation: "auto",
+          reason: "The claim window passed \u2014 your Lightning payment will be refunded automatically."
+        };
+        return { recommended: "none", actions: [done] };
+      }
+      const refundUnlocked = clientChainNow >= clientRefundLocktime;
+      if (refundUnlocked) {
+        const refund2 = {
+          id: "refund_unilateral",
+          recommended: true,
+          automation: "confirm",
+          reason: "Reclaim your deposit \u2014 do not claim, as revealing the preimage would let the server take it."
+        };
+        return { recommended: "refund_unilateral", actions: [refund2] };
+      }
+      const wait = {
+        id: "wait",
+        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."
+      };
+      const refund = {
+        id: "refund_unilateral",
+        recommended: false,
+        automation: "confirm",
+        reason: "Refund becomes available once the timelock passes.",
+        blockedBy: {
+          kind: "timelock_not_expired",
+          message: "The refund timelock has not passed yet."
+        }
+      };
+      return { recommended: "wait", actions: [wait, refund] };
+    }
+    case "clientredeeming": {
+      const wait = {
+        id: "wait",
+        recommended: true,
+        automation: "auto",
+        reason: "Redeeming your funds \u2014 waiting for the claim to confirm."
+      };
+      return { recommended: "wait", actions: [wait] };
+    }
+    case "clientredeemed":
+    case "serverredeemed": {
+      const done = {
+        id: "none",
+        recommended: true,
+        automation: "auto",
+        reason: "Swap complete \u2014 you've received your funds."
+      };
+      return { recommended: "none", actions: [done] };
+    }
+    case "expired": {
+      const done = {
+        id: "none",
+        recommended: true,
+        automation: "auto",
+        reason: "The swap expired without funding \u2014 nothing was locked."
+      };
+      return { recommended: "none", actions: [done] };
+    }
+    case "clientrefunded":
+    case "clientrefundedserverrefunded":
+    case "clientrefundedserverfunded": {
+      const done = {
+        id: "none",
+        recommended: true,
+        automation: "auto",
+        reason: "Refunded \u2014 your deposit was returned."
+      };
+      return { recommended: "none", actions: [done] };
+    }
+    case "clientredeemedandclientrefunded": {
+      const done = {
+        id: "none",
+        recommended: true,
+        automation: "auto",
+        reason: "This swap ended in an anomalous state (redeemed and refunded); no action needed."
+      };
+      return { recommended: "none", actions: [done] };
+    }
+    case "clientfundedserverrefunded":
+    case "serverwontfund":
+    case "clientfundedtoolate":
+    case "clientinvalidfunded": {
+      const refundUnlocked = clientChainNow >= clientRefundLocktime;
+      if (refundUnlocked) {
+        const refund2 = {
+          id: "refund_unilateral",
+          recommended: true,
+          automation: "confirm",
+          reason: "Reclaim your deposit \u2014 the swap did not complete."
+        };
+        return { recommended: "refund_unilateral", actions: [refund2] };
+      }
+      const wait = {
+        id: "wait",
+        recommended: true,
+        automation: "auto",
+        reason: "The swap did not complete; waiting for the refund timelock to reclaim your deposit."
+      };
+      const refund = {
+        id: "refund_unilateral",
+        recommended: false,
+        automation: "confirm",
+        reason: "Refund becomes available once the timelock passes.",
+        blockedBy: {
+          kind: "timelock_not_expired",
+          message: "The refund timelock has not passed yet."
+        }
+      };
+      return { recommended: "wait", actions: [wait, refund] };
+    }
+    default:
+      return assertNever(status);
+  }
+}
+function assertNever(status) {
+  throw new Error(`unhandled swap status: ${String(status)}`);
+}
+
+// src/actions/status.ts
+function deriveSwapStatus(obs) {
+  const { clientHtlc, serverHtlc } = obs;
+  if (serverHtlc === void 0 && clientHtlc !== void 0) {
+    return receiveOnLightningStatus(clientHtlc);
+  }
+  if (clientHtlc === void 0 && serverHtlc !== void 0) {
+    return payOnLightningStatus(serverHtlc);
+  }
+  if (clientHtlc === void 0 || serverHtlc === void 0) return void 0;
+  if (clientHtlc === "spent_claim" && serverHtlc === "spent_claim") {
+    return "serverredeemed";
+  }
+  if (clientHtlc === "spent_refund" && serverHtlc === "spent_claim") {
+    return "clientredeemedandclientrefunded";
+  }
+  if (clientHtlc === "spent_refund" && serverHtlc === "spent_refund") {
+    return "clientrefundedserverrefunded";
+  }
+  if (clientHtlc === "spent_refund" && serverHtlc === "confirmed") {
+    return "clientrefundedserverfunded";
+  }
+  if (clientHtlc === "spent_refund" && (serverHtlc === "absent" || serverHtlc === "mempool")) {
+    return "clientrefunded";
+  }
+  if (clientHtlc === "confirmed" && serverHtlc === "spent_claim") {
+    return "clientredeemed";
+  }
+  if (clientHtlc === "confirmed" && serverHtlc === "spent_refund") {
+    return "clientfundedserverrefunded";
+  }
+  if (clientHtlc === "invalid") return "clientinvalidfunded";
+  if (clientHtlc === "absent") return "pending";
+  if (clientHtlc === "mempool") return "clientfundingseen";
+  if (clientHtlc === "confirmed") {
+    return serverHtlc === "confirmed" ? "serverfunded" : "clientfunded";
+  }
+  return void 0;
+}
+function receiveOnLightningStatus(clientHtlc) {
+  switch (clientHtlc) {
+    case "spent_claim":
+      return "serverredeemed";
+    // server swept the deposit ⟹ it paid the invoice
+    case "spent_refund":
+      return "clientrefunded";
+    case "invalid":
+      return "clientinvalidfunded";
+    case "confirmed":
+      return "clientfunded";
+    // funded; waiting for the server to pay + sweep
+    case "mempool":
+      return "clientfundingseen";
+    case "absent":
+      return "pending";
+  }
+}
+function payOnLightningStatus(serverHtlc) {
+  switch (serverHtlc) {
+    case "spent_claim":
+      return "clientredeemed";
+    // client claimed the on-chain leg ⟹ complete
+    case "confirmed":
+      return "serverfunded";
+    // ready to claim
+    case "spent_refund":
+      return "clientrefunded";
+    case "invalid":
+    case "mempool":
+    case "absent":
+      return "pending";
+  }
+}
+
+// src/client.ts
+import {
+  Client as LegacyClient
+} from "@lendasat/lendaswap-sdk-pure";
+
+// src/contracts/arkade-manager.ts
+import { RestIndexerProvider } from "@arkade-os/sdk";
+import { hex as hex2 } from "@scure/base";
+
+// src/contracts/arkade.ts
+import {
+  ConditionWitness,
+  getArkPsbtFields,
+  Transaction
+} from "@arkade-os/sdk";
+import { base64 } from "@scure/base";
+
+// src/contracts/preimage.ts
+import { ripemd160 } from "@noble/hashes/legacy.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+import { hex } from "@scure/base";
+function preimageMatches(element, hashLock) {
+  const digest = hashLock.length === 20 ? ripemd160(sha256(element)) : sha256(element);
+  return hex.encode(digest) === hex.encode(hashLock);
+}
+
+// src/contracts/arkade.ts
+function arkadeObservation(facts) {
+  if (facts.spend === "claim") return "spent_claim";
+  if (facts.spend === "refund") return "spent_refund";
+  if (!facts.funded) return "absent";
+  return facts.sufficient === false ? "invalid" : "confirmed";
+}
+function classifyArkadeSpend(encodedSpendTx, paymentHash) {
+  const tx = Transaction.fromPSBT(base64.decode(encodedSpendTx));
+  for (const witness of getArkPsbtFields(tx, 0, ConditionWitness)) {
+    for (const element of witness) {
+      if (element.length === 32 && preimageMatches(element, paymentHash)) {
+        return { spend: "claim", preimage: element };
+      }
+    }
+  }
+  return { spend: "refund" };
+}
+async function fetchArkadeSpend(source, spentByTxid, paymentHash) {
+  const { txs } = await source.getVirtualTxs([spentByTxid]);
+  const encoded = txs[0];
+  return encoded ? classifyArkadeSpend(encoded, paymentHash) : void 0;
+}
+
+// src/contracts/arkade-manager.ts
+function isFunded(vtxo) {
+  const { state } = vtxo.virtualStatus;
+  return state === "preconfirmed" || state === "settled";
+}
+function spendTxid(vtxos) {
+  const spent = vtxos.find(
+    (v) => v.arkTxId || v.spentBy || v.isSpent || v.virtualStatus.state === "spent"
+  );
+  return spent?.arkTxId ?? spent?.spentBy;
+}
+var ArkadeContractManager = class _ArkadeContractManager {
+  ledger = "arkade";
+  #indexer;
+  #chainTime;
+  /** pkScript → the ref we're tracking. */
+  #refs = /* @__PURE__ */ new Map();
+  /** pkScript → last known observation. */
+  #obs = /* @__PURE__ */ new Map();
+  /** pkScript → the verified preimage recovered from a claim spend. */
+  #preimages = /* @__PURE__ */ new Map();
+  #listeners = /* @__PURE__ */ new Set();
+  #now;
+  constructor(deps) {
+    this.#indexer = deps.indexer;
+    this.#chainTime = deps.chainTime;
+  }
+  static fromDeps(deps) {
+    return new _ArkadeContractManager(deps);
+  }
+  /** Construct a manager backed by a `RestIndexerProvider` over the Ark server. */
+  static async create(config) {
+    const indexer = new RestIndexerProvider(config.serverUrl);
+    return _ArkadeContractManager.fromDeps({
+      indexer,
+      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;
+    this.#refs.delete(ref.script);
+    this.#obs.delete(ref.script);
+    this.#preimages.delete(ref.script);
+  }
+  getState(ref) {
+    return ref.ledger === "arkade" ? this.#obs.get(ref.script) : void 0;
+  }
+  chainNow(_ref) {
+    return this.#now;
+  }
+  onEvent(cb) {
+    this.#listeners.add(cb);
+    return () => this.#listeners.delete(cb);
+  }
+  async refresh() {
+    if (this.#chainTime) this.#now = await this.#chainTime();
+    await Promise.all(
+      [...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();
+  }
+  /** The verified preimage recovered from a claim spend, if one was seen. */
+  getPreimage(ref) {
+    return ref.ledger === "arkade" ? this.#preimages.get(ref.script) : void 0;
+  }
+  /** Read the VHTLC's vtxos and map them to an observation. */
+  async #reconcileRef(ref) {
+    const { vtxos } = await this.#indexer.getVtxos({ scripts: [ref.script] });
+    const spend = spendTxid(vtxos);
+    if (spend) {
+      const resolved = await fetchArkadeSpend(
+        this.#indexer,
+        spend,
+        hex2.decode(ref.preimageHash)
+      );
+      if (resolved) {
+        if (resolved.spend === "claim")
+          this.#preimages.set(ref.script, resolved.preimage);
+        this.#set(
+          ref.script,
+          arkadeObservation({ funded: true, spend: resolved.spend })
+        );
+        return;
+      }
+    }
+    const funded = vtxos.filter(isFunded);
+    const total = funded.reduce((sum, vtxo) => sum + vtxo.value, 0);
+    this.#set(
+      ref.script,
+      arkadeObservation({
+        funded: funded.length > 0,
+        sufficient: total >= ref.expectedSats
+      })
+    );
+  }
+  /** Update an observation and notify on change; never downgrade a resolved spend. */
+  #set(script, observation) {
+    const ref = this.#refs.get(script);
+    if (!ref) return;
+    const current = this.#obs.get(script);
+    if (current === observation) return;
+    const spendStates = ["spent_claim", "spent_refund"];
+    if (current && spendStates.includes(current) && !spendStates.includes(observation))
+      return;
+    this.#obs.set(script, observation);
+    for (const listener of this.#listeners) listener(ref, observation);
+  }
+};
+
+// src/contracts/arkade-network.ts
+var DEFAULT_ARKADE_URLS = {
+  bitcoin: "https://arkade.computer",
+  mainnet: "https://arkade.computer",
+  signet: "https://mutinynet.arkade.sh",
+  mutinynet: "https://mutinynet.arkade.sh"
+};
+function defaultArkadeServerUrl(network) {
+  return DEFAULT_ARKADE_URLS[network.toLowerCase()];
+}
+
+// src/contracts/bitcoin-manager.ts
+import { hex as hex4 } from "@scure/base";
+
+// src/contracts/bitcoin.ts
+import { hex as hex3 } from "@scure/base";
+function classifyBitcoinSpend(witness, paymentHash) {
+  for (const item of witness) {
+    if (item.length !== 64) continue;
+    const bytes = hex3.decode(item);
+    if (preimageMatches(bytes, paymentHash))
+      return { spend: "claim", preimage: bytes };
+  }
+  return { spend: "refund" };
+}
+function bitcoinObservation(facts, paymentHash, expectedSats) {
+  if (facts.spendWitness) {
+    const spend = classifyBitcoinSpend(facts.spendWitness, paymentHash);
+    return spend.spend === "claim" ? { observation: "spent_claim", preimage: spend.preimage } : { observation: "spent_refund" };
+  }
+  if (facts.funding === "confirmed" && facts.fundedSats < expectedSats) {
+    return { observation: "invalid" };
+  }
+  return { observation: facts.funding };
+}
+
+// src/contracts/bitcoin-manager.ts
+var BitcoinContractManager = class _BitcoinContractManager {
+  ledger = "bitcoin";
+  #reader;
+  #chainTime;
+  /** address → the ref we're tracking. */
+  #refs = /* @__PURE__ */ new Map();
+  /** address → last known observation. */
+  #obs = /* @__PURE__ */ new Map();
+  /** address → the preimage a claim revealed. */
+  #preimages = /* @__PURE__ */ new Map();
+  #listeners = /* @__PURE__ */ new Set();
+  #now;
+  constructor(deps) {
+    this.#reader = deps.reader;
+    this.#chainTime = deps.chainTime;
+  }
+  static fromDeps(deps) {
+    return new _BitcoinContractManager(deps);
+  }
+  static async create(config) {
+    const { esploraReader: esploraReader2 } = await import("./bitcoin-reader-esplora-GRUP7RAG.js");
+    return _BitcoinContractManager.fromDeps({
+      reader: esploraReader2(config.esploraUrl),
+      chainTime: config.chainTime
+    });
+  }
+  canObserve(ref) {
+    return ref.ledger === "bitcoin";
+  }
+  async register(ref) {
+    if (ref.ledger !== "bitcoin")
+      throw new Error(
+        `BitcoinContractManager can't track a '${ref.ledger}' HTLC`
+      );
+    this.#refs.set(ref.address, ref);
+    await this.#reconcileRef(ref);
+  }
+  async unregister(ref) {
+    if (ref.ledger !== "bitcoin") return;
+    this.#refs.delete(ref.address);
+    this.#obs.delete(ref.address);
+    this.#preimages.delete(ref.address);
+  }
+  getState(ref) {
+    return ref.ledger === "bitcoin" ? this.#obs.get(ref.address) : void 0;
+  }
+  chainNow(_ref) {
+    return this.#now;
+  }
+  onEvent(cb) {
+    this.#listeners.add(cb);
+    return () => this.#listeners.delete(cb);
+  }
+  async refresh() {
+    if (this.#chainTime) this.#now = await this.#chainTime();
+    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;
+    if (this.#chainTime) this.#now = await this.#chainTime();
+    await this.#reconcileRef(tracked);
+  }
+  dispose() {
+    this.#listeners.clear();
+  }
+  /** The preimage a claim revealed on this HTLC, if one was seen. */
+  getPreimage(ref) {
+    return ref.ledger === "bitcoin" ? this.#preimages.get(ref.address) : void 0;
+  }
+  async #reconcileRef(ref) {
+    const facts = await this.#reader.getHtlcFacts(ref.address);
+    const { observation, preimage } = bitcoinObservation(
+      facts,
+      hex4.decode(ref.preimageHash),
+      ref.expectedSats
+    );
+    if (preimage) this.#preimages.set(ref.address, preimage);
+    this.#set(ref.address, observation);
+  }
+  /** Update an observation and notify on change; never downgrade a resolved spend. */
+  #set(address, observation) {
+    const ref = this.#refs.get(address);
+    if (!ref) return;
+    const current = this.#obs.get(address);
+    if (current === observation) return;
+    const spendStates = ["spent_claim", "spent_refund"];
+    if (current && spendStates.includes(current) && !spendStates.includes(observation))
+      return;
+    this.#obs.set(address, observation);
+    for (const listener of this.#listeners) listener(ref, observation);
+  }
+};
+
+// src/contracts/evm.ts
+function evmObservation(events, expected, pending = false) {
+  const redeemed = events.find((e) => e.kind === "redeemed");
+  if (redeemed?.kind === "redeemed")
+    return { observation: "spent_claim", preimage: redeemed.preimage };
+  if (events.some((e) => e.kind === "refunded"))
+    return { observation: "spent_refund" };
+  const created = events.find((e) => e.kind === "created");
+  if (created?.kind === "created") {
+    const amountOk = created.amount >= expected.amount;
+    const tokenOk = expected.token === void 0 || created.token.toLowerCase() === expected.token.toLowerCase();
+    return { observation: amountOk && tokenOk ? "confirmed" : "invalid" };
+  }
+  return { observation: pending ? "mempool" : "absent" };
+}
+
+// src/contracts/types.ts
+function htlcKey(ref) {
+  switch (ref.ledger) {
+    case "arkade":
+      return `arkade:${ref.script}`;
+    case "bitcoin":
+      return `bitcoin:${ref.address}`;
+    case "evm":
+      return `evm:${ref.chainId}:${ref.preimageHash}`;
+    case "lightning":
+      return `lightning:${ref.paymentHash}`;
+  }
+}
+
+// src/contracts/evm-manager.ts
+var EvmContractManager = class _EvmContractManager {
+  ledger = "evm";
+  #readers;
+  /** htlcKey → the ref we're tracking. */
+  #refs = /* @__PURE__ */ new Map();
+  /** htlcKey → last known observation. */
+  #obs = /* @__PURE__ */ new Map();
+  /** htlcKey → the preimage a claim revealed. */
+  #preimages = /* @__PURE__ */ new Map();
+  /** chainId → its latest block time (ms). */
+  #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;
+  }
+  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`);
+    if (!this.#readers.has(ref.chainId))
+      throw new Error(
+        `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;
+    const key = htlcKey(ref);
+    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);
+      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;
+  }
+  onEvent(cb) {
+    this.#listeners.add(cb);
+    return () => this.#listeners.delete(cb);
+  }
+  async refresh() {
+    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();
+    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);
+    });
+  }
+  /** 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 Promise.all(
+      [...this.#refs.values()].filter((r) => r.chainId === chainId).map((r) => this.#reconcileRef(reader, r))
+    );
+  }
+  async #reconcileRef(reader, ref) {
+    const events = await reader.getHtlcEvents(
+      ref.htlc,
+      ref.preimageHash,
+      ref.claimAddress
+    );
+    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);
+  }
+  /** Update an observation and notify on change; never downgrade a resolved spend. */
+  #set(key, observation) {
+    const ref = this.#refs.get(key);
+    if (!ref) return;
+    const current = this.#obs.get(key);
+    if (current === observation) return;
+    const spendStates = ["spent_claim", "spent_refund"];
+    if (current && spendStates.includes(current) && !spendStates.includes(observation))
+      return;
+    this.#obs.set(key, observation);
+    for (const listener of this.#listeners) listener(ref, observation);
+  }
+};
+
+// src/contracts/evm-reader-viem.ts
+import {
+  createPublicClient,
+  fallback,
+  http,
+  parseAbiItem
+} from "viem";
+var DEFAULT_EVM_RPCS = {
+  // Polygon — viem's default (polygon.drpc.org) misbehaves for some calls, so
+  // list working public RPCs explicitly.
+  137: [
+    "https://polygon.drpc.org",
+    "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"
+  ],
+  42161: [
+    "https://arbitrum-one-rpc.publicnode.com",
+    "https://rpc.ankr.com/arbitrum",
+    "https://arb1.arbitrum.io/rpc"
+  ]
+};
+var SWAP_CREATED = parseAbiItem(
+  "event SwapCreated(bytes32 indexed preimageHash, address indexed refundAddress, address indexed claimAddress, address token, uint256 amount, uint256 timelock)"
+);
+var SWAP_REDEEMED = parseAbiItem(
+  "event SwapRedeemed(bytes32 indexed preimageHash, bytes32 preimage)"
+);
+var SWAP_REFUNDED = parseAbiItem(
+  "event SwapRefunded(bytes32 indexed preimageHash)"
+);
+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"
+        })
+      ]);
+      const events = [];
+      for (const log of created) {
+        const args = log.args;
+        events.push({
+          kind: "created",
+          amount: args?.amount ?? 0n,
+          token: args?.token ?? "0x"
+        });
+      }
+      for (const log of redeemed) {
+        const preimage = log.args?.preimage;
+        if (preimage) events.push({ kind: "redeemed", preimage });
+      }
+      if (refunded.length > 0) events.push({ kind: "refunded" });
+      return events;
+    },
+    async getBlockTimeMs() {
+      const block = await client.getBlock();
+      return Number(block.timestamp) * 1e3;
+    },
+    watch(cb) {
+      return client.watchBlocks({ onBlock: () => cb() });
+    }
+  };
+}
+function createEvmRpcReader(rpcUrls) {
+  const urls = Array.isArray(rpcUrls) ? rpcUrls : [rpcUrls];
+  const transport = urls.length > 1 ? fallback(
+    urls.map((url) => http(url)),
+    { rank: { interval: 6e4, sampleCount: 3, timeout: 1e3 } }
+  ) : http(urls[0]);
+  const client = createPublicClient({ transport });
+  return evmReaderFromClient(client);
+}
+function defaultEvmReaders(overrides) {
+  const chainIds = /* @__PURE__ */ new Set([
+    ...Object.keys(DEFAULT_EVM_RPCS).map(Number),
+    ...Object.keys(overrides ?? {}).map(Number)
+  ]);
+  const readers = /* @__PURE__ */ new Map();
+  for (const chainId of chainIds) {
+    const override = overrides?.[chainId];
+    const defaults = DEFAULT_EVM_RPCS[chainId] ?? [];
+    const urls = override ? [override, ...defaults] : defaults;
+    if (urls.length > 0) readers.set(chainId, createEvmRpcReader(urls));
+  }
+  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
+import { VHTLC, VHTLCContractHandler } from "@arkade-os/sdk";
+import { ripemd160 as ripemd1602 } from "@noble/hashes/legacy.js";
+import { hex as hex5 } from "@scure/base";
+function strip0x(value) {
+  return value.startsWith("0x") ? value.slice(2) : value;
+}
+function xOnly(pubKeyHex) {
+  const bytes = hex5.decode(strip0x(pubKeyHex));
+  if (bytes.length === 33) return bytes.slice(1);
+  if (bytes.length === 32) return bytes;
+  throw new Error(`invalid public key length: ${bytes.length}`);
+}
+var seconds = (value) => ({ type: "seconds", value: BigInt(value) });
+function buildArkadeVhtlcRef(input) {
+  const hashLockBytes = hex5.decode(strip0x(input.hashLock));
+  const params = {
+    sender: xOnly(input.senderPk),
+    receiver: xOnly(input.receiverPk),
+    server: xOnly(input.serverPk),
+    preimageHash: hashLockBytes.length === 20 ? hashLockBytes : ripemd1602(hashLockBytes),
+    refundLocktime: BigInt(input.refundLocktime),
+    unilateralClaimDelay: seconds(input.unilateralClaimDelay),
+    unilateralRefundDelay: seconds(input.unilateralRefundDelay),
+    unilateralRefundWithoutReceiverDelay: seconds(
+      input.unilateralRefundWithoutReceiverDelay
+    )
+  };
+  const vhtlc = new VHTLC.Script(params);
+  return {
+    ledger: "arkade",
+    script: hex5.encode(vhtlc.pkScript),
+    address: input.address,
+    preimageHash: strip0x(input.hashLock),
+    expectedSats: input.expectedSats,
+    params: VHTLCContractHandler.serializeParams(params)
+  };
+}
+
+// src/tracker/from-swap.ts
+var ms = (seconds2) => seconds2 * 1e3;
+var ensure0x = (value) => value.startsWith("0x") ? value : `0x${value}`;
+var strip0x2 = (value) => value.startsWith("0x") ? value.slice(2) : value;
+function arkadeLeg(r, address, expectedSats) {
+  return buildArkadeVhtlcRef({
+    senderPk: r.sender_pk,
+    receiverPk: r.receiver_pk,
+    serverPk: r.arkade_server_pk,
+    hashLock: r.hash_lock,
+    address,
+    refundLocktime: r.vhtlc_refund_locktime,
+    unilateralClaimDelay: r.unilateral_claim_delay,
+    unilateralRefundDelay: r.unilateral_refund_delay,
+    unilateralRefundWithoutReceiverDelay: r.unilateral_refund_without_receiver_delay,
+    expectedSats
+  });
+}
+function evmLeg(args) {
+  return {
+    ledger: "evm",
+    chainId: args.chainId,
+    htlc: ensure0x(args.htlc),
+    preimageHash: ensure0x(args.hashLock),
+    claimAddress: ensure0x(args.claimAddress),
+    expectedAmount: BigInt(args.expectedSats),
+    expectedToken: args.token ? ensure0x(args.token) : void 0
+  };
+}
+function bitcoinLeg(address, hashLock, expectedSats) {
+  return {
+    ledger: "bitcoin",
+    address,
+    preimageHash: strip0x2(hashLock),
+    expectedSats
+  };
+}
+function swapToTracked(stored) {
+  const r = stored.response;
+  switch (r.direction) {
+    // Client sends Arkade (funds the VHTLC with source_amount sats) and claims EVM.
+    case "arkade_to_evm":
+      return {
+        swapId: r.id,
+        clientHtlc: arkadeLeg(r, r.btc_vhtlc_address, Number(r.source_amount)),
+        serverHtlc: evmLeg({
+          chainId: r.evm_chain_id,
+          htlc: r.evm_htlc_address,
+          hashLock: r.hash_lock,
+          claimAddress: r.client_evm_address,
+          // the client claims the server's EVM HTLC
+          expectedSats: r.evm_expected_sats,
+          token: r.wbtc_address
+        }),
+        clientRefundLocktime: ms(r.vhtlc_refund_locktime),
+        serverRefundLocktime: ms(r.evm_refund_locktime)
+      };
+    // Client sends EVM and claims the Arkade VHTLC (server funds it with target_amount sats).
+    case "evm_to_arkade":
+      return {
+        swapId: r.id,
+        clientHtlc: evmLeg({
+          chainId: r.evm_chain_id,
+          htlc: r.evm_htlc_address,
+          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.
+        }),
+        serverHtlc: arkadeLeg(r, r.btc_vhtlc_address, Number(r.target_amount)),
+        clientRefundLocktime: ms(r.evm_refund_locktime),
+        serverRefundLocktime: ms(r.vhtlc_refund_locktime)
+      };
+    // Client sends BTC (funds the on-chain HTLC with source_amount sats) and claims EVM.
+    case "bitcoin_to_evm":
+      return {
+        swapId: r.id,
+        clientHtlc: bitcoinLeg(
+          r.btc_htlc_address,
+          r.evm_hash_lock,
+          Number(r.source_amount)
+        ),
+        serverHtlc: evmLeg({
+          chainId: r.evm_chain_id,
+          htlc: r.evm_htlc_address,
+          hashLock: r.evm_hash_lock,
+          claimAddress: r.client_evm_address,
+          // the client claims the server's EVM HTLC
+          expectedSats: r.evm_expected_sats,
+          token: r.wbtc_address
+        }),
+        clientRefundLocktime: ms(r.btc_refund_locktime),
+        serverRefundLocktime: ms(r.evm_refund_locktime)
+      };
+    // Client sends EVM and claims the BTC HTLC (server funds it with target_amount sats).
+    case "evm_to_bitcoin":
+      return {
+        swapId: r.id,
+        clientHtlc: evmLeg({
+          chainId: r.evm_chain_id,
+          htlc: r.evm_htlc_address,
+          hashLock: r.evm_hash_lock,
+          claimAddress: r.server_evm_address,
+          // the server claims the client's EVM HTLC
+          expectedSats: r.evm_expected_sats,
+          token: r.wbtc_address
+        }),
+        serverHtlc: bitcoinLeg(
+          r.btc_htlc_address,
+          r.evm_hash_lock,
+          Number(r.target_amount)
+        ),
+        clientRefundLocktime: ms(r.evm_refund_locktime),
+        serverRefundLocktime: ms(r.btc_refund_locktime)
+      };
+    // Client sends BTC (funds the on-chain HTLC) and claims the Arkade VHTLC (the
+    // server funds it). Unlike the other Arkade directions, the VHTLC's receiver is
+    // the client's own key (not in the response) and its funder is `server_vhtlc_pk`;
+    // the hash lock is a 20-byte HASH160, which buildArkadeVhtlcRef takes as-is.
+    case "btc_to_arkade":
+      return {
+        swapId: r.id,
+        clientHtlc: bitcoinLeg(
+          r.btc_htlc_address,
+          r.hash_lock,
+          Number(r.source_amount)
+        ),
+        serverHtlc: buildArkadeVhtlcRef({
+          senderPk: r.server_vhtlc_pk,
+          // the server funds the VHTLC
+          receiverPk: stored.publicKey,
+          // the client claims it
+          serverPk: r.arkade_server_pk,
+          hashLock: r.hash_lock,
+          address: r.arkade_vhtlc_address,
+          refundLocktime: r.vhtlc_refund_locktime,
+          unilateralClaimDelay: r.unilateral_claim_delay,
+          unilateralRefundDelay: r.unilateral_refund_delay,
+          unilateralRefundWithoutReceiverDelay: r.unilateral_refund_without_receiver_delay,
+          expectedSats: Number(r.target_amount)
+        }),
+        clientRefundLocktime: ms(r.btc_refund_locktime),
+        serverRefundLocktime: ms(r.vhtlc_refund_locktime)
+      };
+    // ─── Lightning: one on-chain leg, one off-chain LN payment ───────────────
+    // Receive-on-Lightning: the client funds an on-chain HTLC and is paid over
+    // Lightning. No server leg to watch — the server sweeping the client's leg
+    // (with the preimage it got by paying the invoice) is the done signal.
+    // Client funds the Arkade VHTLC; Boltz pays the invoice. The deposit is
+    // `boltz_amount_sats` (source minus fees) — the amount actually locked, not
+    // `source_amount` — else the client's own funding reads as under-funded.
+    case "arkade_to_lightning":
+      return {
+        swapId: r.id,
+        clientHtlc: arkadeLeg(
+          r,
+          r.arkade_vhtlc_address,
+          Number(r.boltz_amount_sats)
+        ),
+        clientRefundLocktime: ms(r.vhtlc_refund_locktime),
+        serverRefundLocktime: 0
+        // no on-chain server leg
+      };
+    // Client funds the EVM HTLC (server claims it after paying the invoice).
+    case "evm_to_lightning":
+      return {
+        swapId: r.id,
+        clientHtlc: evmLeg({
+          chainId: r.evm_chain_id,
+          htlc: r.evm_htlc_address,
+          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.
+        }),
+        clientRefundLocktime: ms(r.evm_refund_locktime),
+        serverRefundLocktime: 0
+        // no on-chain server leg
+      };
+    // Pay-on-Lightning: the client pays a Lightning invoice (off-chain, nothing to
+    // watch) and claims an on-chain HTLC. No client-funded leg — the client's
+    // claim completes the swap; a hold invoice that never settles auto-unwinds.
+    // Client pays the invoice, then claims the Arkade VHTLC (target_amount).
+    case "lightning_to_arkade":
+      return {
+        swapId: r.id,
+        serverHtlc: arkadeLeg(
+          r,
+          r.arkade_vhtlc_address,
+          Number(r.target_amount)
+        ),
+        clientRefundLocktime: 0,
+        // no on-chain client leg
+        serverRefundLocktime: ms(r.vhtlc_refund_locktime)
+      };
+    // Client pays the invoice, then claims the EVM HTLC.
+    case "lightning_to_evm":
+      return {
+        swapId: r.id,
+        serverHtlc: evmLeg({
+          chainId: r.evm_chain_id,
+          htlc: r.evm_htlc_address,
+          hashLock: r.hash_lock,
+          claimAddress: r.client_evm_address,
+          // the client claims the server's leg
+          expectedSats: r.evm_expected_sats,
+          token: r.wbtc_address
+        }),
+        clientRefundLocktime: 0,
+        // no on-chain client leg
+        serverRefundLocktime: ms(r.evm_refund_locktime)
+      };
+    default:
+      return void 0;
+  }
+}
+
+// src/tracker/swap-tracker.ts
+var SwapTracker = class {
+  #managers;
+  #swaps = /* @__PURE__ */ new Map();
+  /** Last actions emitted per swap — for dedupe and the subscribe-time snapshot. */
+  #lastActions = /* @__PURE__ */ new Map();
+  #subscribers = /* @__PURE__ */ new Set();
+  #refreshIntervalMs;
+  #eventUnsubs = [];
+  #timer;
+  constructor(managers, options) {
+    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);
+    }
+    for (const manager of new Set(this.#managers.values())) {
+      this.#eventUnsubs.push(manager.onEvent(() => this.#recomputeAll()));
+    }
+    await this.#refreshManagers();
+    this.#recomputeAll();
+    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);
+  }
+  async #tick() {
+    await this.#refreshManagers();
+    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
+   * 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)
+    );
+    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);
+    for (const [swapId, actions] of this.#lastActions) cb(swapId, actions);
+    return () => this.#subscribers.delete(cb);
+  }
+  /**
+   * Stop tracking: unregister every still-tracked leg (releasing its manager's
+   * watch — e.g. the EVM per-chain block watch that only `unregister` tears down),
+   * drop the poll timer, and detach event listeners + subscribers. Mirrors
+   * `startTracking`'s `register`, so no manager keeps watching a stopped tracker's
+   * swaps. The managers themselves are not owned here, so they are unregistered but
+   * never disposed.
+   */
+  stop() {
+    if (this.#timer) clearInterval(this.#timer);
+    this.#timer = void 0;
+    for (const unsub of this.#eventUnsubs) unsub();
+    this.#eventUnsubs = [];
+    for (const swap of this.#swaps.values())
+      for (const leg of legsOf(swap))
+        void this.#managerFor(leg).unregister(leg);
+    this.#swaps.clear();
+    this.#subscribers.clear();
+  }
+  #managerFor(ref) {
+    const manager = this.#managers.get(ref.ledger);
+    if (!manager)
+      throw new Error(`no ContractManager for ledger '${ref.ledger}'`);
+    return manager;
+  }
+  #recomputeAll() {
+    for (const swap of this.#swaps.values()) this.#recompute(swap);
+  }
+  #recompute(swap, force = false) {
+    let clientHtlc;
+    let serverHtlc;
+    let clientChainNow = 0;
+    let serverChainNow = 0;
+    if (swap.clientHtlc) {
+      const m = this.#managerFor(swap.clientHtlc);
+      clientHtlc = m.getState(swap.clientHtlc);
+      const now = m.chainNow(swap.clientHtlc);
+      if (clientHtlc === void 0 || now === void 0) return;
+      clientChainNow = now;
+    }
+    if (swap.serverHtlc) {
+      const m = this.#managerFor(swap.serverHtlc);
+      serverHtlc = m.getState(swap.serverHtlc);
+      const now = m.chainNow(swap.serverHtlc);
+      if (serverHtlc === void 0 || now === void 0) return;
+      serverChainNow = now;
+    }
+    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 previous = this.#lastActions.get(swap.swapId);
+    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);
+    if (actions.recommended === "none") this.#untrack(swap);
+  }
+  #untrack(swap) {
+    this.#swaps.delete(swap.swapId);
+    for (const leg of legsOf(swap)) void this.#managerFor(leg).unregister(leg);
+  }
+};
+function legsOf(swap) {
+  const legs = [];
+  if (swap.clientHtlc) legs.push(swap.clientHtlc);
+  if (swap.serverHtlc) legs.push(swap.serverHtlc);
+  return legs;
+}
+
+// src/client.ts
+var Client = class {
+  /** The wrapped legacy client. Calls are forwarded here until migrated. */
+  #legacy;
+  /** Tracking configuration; managers are built lazily from it on first use. */
+  #tracking;
+  /** 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 LegacyClient) {
+      this.#legacy = args[0];
+      this.#tracking = args[1] ?? {
+        enabled: false
+      };
+    } else {
+      this.#legacy = new LegacyClient(
+        ...args
+      );
+      this.#tracking = { enabled: false };
+    }
+  }
+  /** Start building a {@link Client}. */
+  static builder() {
+    return new ClientBuilder();
+  }
+  /** Escape hatch: the underlying legacy client, during migration. */
+  get legacy() {
+    return this.#legacy;
+  }
+  // --- delegated legacy surface (getters) ---
+  /** Delegated to the legacy client (migration checkpoint). */
+  get api() {
+    return this.#legacy.api;
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  get baseUrl() {
+    return this.#legacy.baseUrl;
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  get cctpInbound() {
+    return this.#legacy.cctpInbound;
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  get swapStorage() {
+    return this.#legacy.swapStorage;
+  }
+  // --- delegated legacy surface (methods) ---
+  /** Delegated to the legacy client (migration checkpoint). */
+  subscribeToSwaps(...args) {
+    return this.#legacy.subscribeToSwaps(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  unsubscribeFromSwaps(...args) {
+    return this.#legacy.unsubscribeFromSwaps(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  closeSwapStatusSocket(...args) {
+    return this.#legacy.closeSwapStatusSocket(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  getMnemonic(...args) {
+    return this.#legacy.getMnemonic(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  loadMnemonic(...args) {
+    return this.#legacy.loadMnemonic(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  getNostrKeyHex(...args) {
+    return this.#legacy.getNostrKeyHex(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  getUserIdXpub(...args) {
+    return this.#legacy.getUserIdXpub(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  deriveSwapParams(...args) {
+    return this.#legacy.deriveSwapParams(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  deriveSwapParamsAtIndex(...args) {
+    return this.#legacy.deriveSwapParamsAtIndex(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  getEvmAddress(...args) {
+    return this.#legacy.getEvmAddress(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  getKeyIndex(...args) {
+    return this.#legacy.getKeyIndex(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  setKeyIndex(...args) {
+    return this.#legacy.setKeyIndex(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  getStatus(...args) {
+    return this.#legacy.getStatus(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  healthCheck(...args) {
+    return this.#legacy.healthCheck(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  getVersion(...args) {
+    return this.#legacy.getVersion(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  getSupportAgents(...args) {
+    return this.#legacy.getSupportAgents(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  getMtp(...args) {
+    return this.#legacy.getMtp(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  getTokens(...args) {
+    return this.#legacy.getTokens(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  getSwapPairs(...args) {
+    return this.#legacy.getSwapPairs(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  getChainConfig(...args) {
+    return this.#legacy.getChainConfig(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  getReferralFee(...args) {
+    return this.#legacy.getReferralFee(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  getNetworkFees(...args) {
+    return this.#legacy.getNetworkFees(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  getDexQuote(...args) {
+    return this.#legacy.getDexQuote(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  composeQuote(...args) {
+    return this.#legacy.composeQuote(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  getQuote(...args) {
+    return this.#legacy.getQuote(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  getSwap(...args) {
+    return this.#legacy.getSwap(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  getBulkStatus(...args) {
+    return this.#legacy.getBulkStatus(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  getStoredSwap(...args) {
+    return this.#legacy.getStoredSwap(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  listAllSwaps(...args) {
+    return this.#legacy.listAllSwaps(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  deleteSwap(...args) {
+    return this.#legacy.deleteSwap(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  clearSwapStorage(...args) {
+    return this.#legacy.clearSwapStorage(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  recoverSwaps(...args) {
+    return this.#legacy.recoverSwaps(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  recoverAllSwaps(...args) {
+    return this.#legacy.recoverAllSwaps(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  amountsForSwap(...args) {
+    return this.#legacy.amountsForSwap(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  claim(...args) {
+    return this.#legacy.claim(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  claimViaGasless(...args) {
+    return this.#legacy.claimViaGasless(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  claimArkade(...args) {
+    return this.#legacy.claimArkade(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  continueArkadeClaimSwap(...args) {
+    return this.#legacy.continueArkadeClaimSwap(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  refundSwap(...args) {
+    return this.#legacy.refundSwap(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  getCollabRefundEvmParams(...args) {
+    return this.#legacy.getCollabRefundEvmParams(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  buildCollabRefundEvmTypedData(...args) {
+    return this.#legacy.buildCollabRefundEvmTypedData(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  collabRefundEvmSwap(...args) {
+    return this.#legacy.collabRefundEvmSwap(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  submitCollabRefundEvm(...args) {
+    return this.#legacy.submitCollabRefundEvm(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  createSwap(...args) {
+    return this.#trackAfterCreate(this.#legacy.createSwap(...args));
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  createArkadeToEvmSwapGeneric(...args) {
+    return this.#trackAfterCreate(
+      this.#legacy.createArkadeToEvmSwapGeneric(...args)
+    );
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  createLightningToEvmSwapGeneric(...args) {
+    return this.#trackAfterCreate(
+      this.#legacy.createLightningToEvmSwapGeneric(...args)
+    );
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  createBitcoinToEvmSwap(...args) {
+    return this.#trackAfterCreate(this.#legacy.createBitcoinToEvmSwap(...args));
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  createBitcoinToArkadeSwap(...args) {
+    return this.#trackAfterCreate(
+      this.#legacy.createBitcoinToArkadeSwap(...args)
+    );
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  createLightningToArkadeSwap(...args) {
+    return this.#trackAfterCreate(
+      this.#legacy.createLightningToArkadeSwap(...args)
+    );
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  createArkadeToLightningSwap(...args) {
+    return this.#trackAfterCreate(
+      this.#legacy.createArkadeToLightningSwap(...args)
+    );
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  getArkadeToLightningQuote(...args) {
+    return this.#legacy.getArkadeToLightningQuote(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  retryArkadeToLightningSwap(...args) {
+    return this.#trackAfterRetry(
+      this.#legacy.retryArkadeToLightningSwap(...args)
+    );
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  createEvmToArkadeSwapGeneric(...args) {
+    return this.#trackAfterCreate(
+      this.#legacy.createEvmToArkadeSwapGeneric(...args)
+    );
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  createEvmToBitcoinSwap(...args) {
+    return this.#trackAfterCreate(this.#legacy.createEvmToBitcoinSwap(...args));
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  createEvmToLightningSwapGeneric(...args) {
+    return this.#trackAfterCreate(
+      this.#legacy.createEvmToLightningSwapGeneric(...args)
+    );
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  getCoordinatorFundingCallDataPermit2(...args) {
+    return this.#legacy.getCoordinatorFundingCallDataPermit2(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  getPermit2FundingParamsUnsigned(...args) {
+    return this.#legacy.getPermit2FundingParamsUnsigned(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  fundSwap(...args) {
+    return this.#legacy.fundSwap(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  refundEvmWithSigner(...args) {
+    return this.#legacy.refundEvmWithSigner(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  collabRefundEvmWithSigner(...args) {
+    return this.#legacy.collabRefundEvmWithSigner(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  fundSwapGasless(...args) {
+    return this.#legacy.fundSwapGasless(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  getSwapDepositorKey(...args) {
+    return this.#legacy.getSwapDepositorKey(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  getEvmDepositorKey(...args) {
+    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);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  hasReceivedVtxo(...args) {
+    return this.#legacy.hasReceivedVtxo(...args);
+  }
+  // --- Satora-native features go below ---
+  /**
+   * Start observing the user's active swaps and deriving each one's next action.
+   *
+   * Loads stored swaps, maps the ones whose ledgers are observable to
+   * {@link TrackedSwap}s, and runs the per-ledger monitors. Idempotent. Requires
+   * the client to have been built with {@link ClientBuilder.withTracking}.
+   * Subscribe with {@link subscribeToActions}; release with
+   * {@link stopTracking}.
+   */
+  async startTracking() {
+    if (!this.#tracking.enabled)
+      throw new Error(
+        "tracking is disabled \u2014 remove .withoutTracking() to enable it"
+      );
+    if (this.#started) return;
+    this.#started = true;
+    try {
+      const tracker = new SwapTracker(await this.#ensureManagers(), {
+        refreshIntervalMs: this.#tracking.refreshIntervalMs ?? 5e3
+      });
+      this.#tracker = tracker;
+      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
+   * {@link startTracking}. Returns an unsubscribe fn.
+   */
+  subscribeToActions(cb) {
+    if (!this.#tracker)
+      throw new Error("call startTracking() before subscribeToActions()");
+    return this.#tracker.subscribeToActions(cb);
+  }
+  /** 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;
+  }
+  /**
+   * Resolve the per-ledger managers once — the explicit override if given, else
+   * auto-built from config: an {@link ArkadeContractManager} from the configured
+   * Ark server URL (defaulting to the mainnet server), clocked by `getMtp`, and an
+   * {@link EvmContractManager} from the tested default RPCs.
+   */
+  async #ensureManagers() {
+    if (this.#managers) return this.#managers;
+    if (this.#tracking.managers) {
+      this.#managers = this.#tracking.managers;
+      return this.#managers;
+    }
+    const managers = /* @__PURE__ */ new Map();
+    const { arkadeServerUrl, evmRpcUrls, esploraUrl } = this.#tracking;
+    const chainTime = async () => (await this.getMtp()).mtp * 1e3;
+    const arkadeUrl = arkadeServerUrl ?? defaultArkadeServerUrl("bitcoin");
+    if (arkadeUrl) {
+      managers.set(
+        "arkade",
+        await ArkadeContractManager.create({ serverUrl: arkadeUrl, chainTime })
+      );
+    }
+    const readers = defaultEvmReaders(evmRpcUrls);
+    if (readers.size > 0)
+      managers.set("evm", EvmContractManager.fromDeps({ readers }));
+    managers.set(
+      "bitcoin",
+      await BitcoinContractManager.create({
+        esploraUrl: esploraUrl ? [esploraUrl] : DEFAULT_ESPLORA_URLS,
+        chainTime
+      })
+    );
+    this.#managers = managers;
+    return managers;
+  }
+};
+var ClientBuilder = class {
+  #inner = LegacyClient.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;
+  #arkadeServerUrl;
+  #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
+   * defaults kept as fallbacks.
+   */
+  withEvmRpcUrls(urls) {
+    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;
+    return this;
+  }
+  /**
+   * Advanced: supply per-ledger {@link ContractManager}s explicitly instead of
+   * letting the client auto-build them from config (useful for tests or custom
+   * chain sources).
+   */
+  withContractManagers(managers) {
+    this.#managers = managers;
+    return this;
+  }
+  withBaseUrl(...args) {
+    this.#inner.withBaseUrl(...args);
+    return this;
+  }
+  withReferralCode(...args) {
+    this.#inner.withReferralCode(...args);
+    return this;
+  }
+  withOrgCode(...args) {
+    this.#inner.withOrgCode(...args);
+    return this;
+  }
+  withDefaultHeaders(...args) {
+    this.#inner.withDefaultHeaders(...args);
+    return this;
+  }
+  /**
+   * Override the Esplora REST URL. Optional for tracking — the Bitcoin manager
+   * otherwise defaults to mainnet mempool.space; set this for a dev/regtest node.
+   */
+  withEsploraUrl(url) {
+    this.#inner.withEsploraUrl(url);
+    this.#esploraUrl = url;
+    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.
+   */
+  withArkadeServerUrl(url) {
+    this.#inner.withArkadeServerUrl(url);
+    this.#arkadeServerUrl = url;
+    return this;
+  }
+  withSignerStorage(...args) {
+    this.#inner.withSignerStorage(...args);
+    return this;
+  }
+  withSwapStorage(...args) {
+    this.#inner.withSwapStorage(...args);
+    return this;
+  }
+  withMnemonic(...args) {
+    this.#inner.withMnemonic(...args);
+    return this;
+  }
+  withXprv(...args) {
+    this.#inner.withXprv(...args);
+    return this;
+  }
+  withAa(...args) {
+    this.#inner.withAa(...args);
+    return this;
+  }
+  withLogger(...args) {
+    this.#inner.withLogger(...args);
+    return this;
+  }
+  withLogLevel(...args) {
+    this.#inner.withLogLevel(...args);
+    return this;
+  }
+  async build() {
+    return new Client(await this.#inner.build(), {
+      enabled: this.#trackingEnabled,
+      managers: this.#managers,
+      arkadeServerUrl: this.#arkadeServerUrl,
+      esploraUrl: this.#esploraUrl,
+      evmRpcUrls: this.#evmRpcUrls,
+      autoClaim: this.#autoClaim
+    });
+  }
+};
+function createdSwapId(result) {
+  const id = result?.response?.id;
+  return typeof id === "string" ? id : void 0;
+}
+export {
+  ArkadeContractManager,
+  BitcoinContractManager,
+  Client,
+  ClientBuilder,
+  DEFAULT_ESPLORA_URLS,
+  DEFAULT_EVM_RPCS,
+  EvmContractManager,
+  SwapTracker,
+  SwapWorker,
+  WsStatusSource,
+  buildArkadeVhtlcRef,
+  createEvmRpcReader,
+  defaultArkadeServerUrl,
+  defaultEvmReaders,
+  deriveSwapActions,
+  deriveSwapStatus,
+  esploraReader,
+  evmReaderFromClient,
+  htlcFactsFromEsploraTxs,
+  htlcKey,
+  swapToTracked
+};
 //# sourceMappingURL=index.js.map