@satora/swap 0.0.5 → 0.1.0

package/dist/index.js

@@ -1,3 +1,1773 @@
+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
+    });
+  }
+  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))
+    );
+  }
+  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
+    });
+  }
+  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))
+    );
+  }
+  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);
+  }
+  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)));
+  }
+  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/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;
+  }
+  /** Register each swap's on-chain leg(s), subscribe to manager events, and seed state. */
+  async startTracking(swaps) {
+    for (const swap of swaps) {
+      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
+      );
+  }
+  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()));
+  }
+  /** 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) {
+    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 (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;
+  #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.#legacy.createSwap(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  createArkadeToEvmSwapGeneric(...args) {
+    return this.#legacy.createArkadeToEvmSwapGeneric(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  createLightningToEvmSwapGeneric(...args) {
+    return this.#legacy.createLightningToEvmSwapGeneric(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  createBitcoinToEvmSwap(...args) {
+    return this.#legacy.createBitcoinToEvmSwap(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  createBitcoinToArkadeSwap(...args) {
+    return this.#legacy.createBitcoinToArkadeSwap(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  createLightningToArkadeSwap(...args) {
+    return this.#legacy.createLightningToArkadeSwap(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  createArkadeToLightningSwap(...args) {
+    return 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.#legacy.retryArkadeToLightningSwap(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  createEvmToArkadeSwapGeneric(...args) {
+    return this.#legacy.createEvmToArkadeSwapGeneric(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  createEvmToBitcoinSwap(...args) {
+    return this.#legacy.createEvmToBitcoinSwap(...args);
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
+  createEvmToLightningSwapGeneric(...args) {
+    return 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). */
+  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;
+      const swaps = await this.listAllSwaps();
+      const tracked = swaps.map(swapToTracked).filter((s) => s !== void 0);
+      await tracker.startTracking(tracked);
+    } catch (error) {
+      this.#tracker?.stop();
+      this.#tracker = void 0;
+      this.#started = false;
+      throw error;
+    }
+  }
+  /**
+   * 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.#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;
+  /**
+   * 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;
+  }
+  /** 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
+    });
+  }
+};
+export {
+  ArkadeContractManager,
+  BitcoinContractManager,
+  Client,
+  ClientBuilder,
+  DEFAULT_ESPLORA_URLS,
+  DEFAULT_EVM_RPCS,
+  EvmContractManager,
+  SwapTracker,
+  buildArkadeVhtlcRef,
+  createEvmRpcReader,
+  defaultArkadeServerUrl,
+  defaultEvmReaders,
+  deriveSwapActions,
+  deriveSwapStatus,
+  esploraReader,
+  evmReaderFromClient,
+  htlcFactsFromEsploraTxs,
+  htlcKey,
+  swapToTracked
+};
 //# sourceMappingURL=index.js.map