@satora/swap 1.0.0 → 1.2.0

package/README.md

@@ -94,7 +94,7 @@ await client.claim(swapId);
 
 // Refund after timeout
 await client.refundSwap(swapId, {destinationAddress: "bc1q…"}); // or "ark1…"
-await client.collabRefundEvmWithSigner(swapId, signer, "swap-back"); // EVM, instant/gasless
+await client.collabRefundEvmWithSigner(swapId, signer); // EVM, instant/gasless
 ```
 
 ## License

package/dist/bitcoin-reader-electrum-PY7DHD6T.js

@@ -0,0 +1,7 @@
+import {
+  electrumReader
+} from "./chunk-FTPIQSRW.js";
+export {
+  electrumReader
+};
+//# sourceMappingURL=bitcoin-reader-electrum-PY7DHD6T.js.map

package/dist/{bitcoin-reader-esplora-HV6CANAA.js → bitcoin-reader-esplora-ZLPMM5FF.js}

@@ -2,10 +2,10 @@ import {
   DEFAULT_ESPLORA_URLS,
   esploraReader,
   htlcFactsFromEsploraTxs
-} from "./chunk-EIWELJJK.js";
+} from "./chunk-THI4UO6R.js";
 export {
   DEFAULT_ESPLORA_URLS,
   esploraReader,
   htlcFactsFromEsploraTxs
 };
-//# sourceMappingURL=bitcoin-reader-esplora-HV6CANAA.js.map
+//# sourceMappingURL=bitcoin-reader-esplora-ZLPMM5FF.js.map

package/dist/{chunk-VHXEU534.js → chunk-FTPIQSRW.js}

@@ -62,7 +62,17 @@ function electrumReader(client, opts) {
       }
       return indices;
     };
-    const funding = txs.find(({ tx }) => outputIndicesPaying(tx).length > 0);
+    let funding;
+    let fundedSats = 0;
+    for (const candidate of txs) {
+      let paid = 0;
+      for (const i of outputIndicesPaying(candidate.tx))
+        paid += Number(candidate.tx.getOutput(i).amount ?? 0n);
+      if (paid > fundedSats) {
+        funding = candidate;
+        fundedSats = paid;
+      }
+    }
     if (!funding) return { funding: "absent", fundedSats: 0 };
     const fundedVouts = outputIndicesPaying(funding.tx);
     for (const { tx } of txs) {
@@ -80,9 +90,6 @@ function electrumReader(client, opts) {
         }
       }
     }
-    let fundedSats = 0;
-    for (const i of fundedVouts)
-      fundedSats += Number(funding.tx.getOutput(i).amount ?? 0n);
     const height = funding.entry.height;
     const isConfirmed = height > 0;
     let deepEnough;
@@ -142,4 +149,4 @@ function electrumReader(client, opts) {
 export {
   electrumReader
 };
-//# sourceMappingURL=chunk-VHXEU534.js.map
+//# sourceMappingURL=chunk-FTPIQSRW.js.map

package/dist/chunk-FTPIQSRW.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/contracts/bitcoin-reader-electrum.ts"],"sourcesContent":["/**\n * An Electrum-backed {@link BitcoinChainReader} — reads HTLC facts from our own\n * Fulcrum over WebSocket instead of public esplora REST endpoints.\n *\n * Two advantages over the esplora reader:\n *\n * - **Freshness**: our Fulcrum sees a transaction the moment its bitcoind\n *   accepts it, while public explorers index with a lag — the exact lag that\n *   made a server-funding hint's targeted verify come back \"absent\" and park\n *   the claim on the 60s at-risk poller.\n * - **Push**: implements the reader's optional `subscribe` capability via\n *   `blockchain.scripthash.subscribe`, so the manager reconciles the moment\n *   an HTLC address's history changes instead of waiting for a poll tick.\n *\n * Reads fall back to a wrapped reader (typically the esplora one) whenever the\n * Electrum server errors, so a Fulcrum outage degrades to today's behavior\n * rather than blinding the tracker.\n */\n\nimport { sha256 } from \"@noble/hashes/sha2.js\";\nimport { hex } from \"@scure/base\";\nimport * as btc from \"@scure/btc-signer\";\nimport type { BitcoinHtlcFacts } from \"./bitcoin.js\";\nimport type { BitcoinChainReader } from \"./bitcoin-manager.js\";\nimport type { BitcoinConfirmationPolicy } from \"./bitcoin-reader-esplora.js\";\n\n/** One entry of `blockchain.scripthash.get_history`. */\ntype ElectrumHistoryEntry = {\n  tx_hash: string;\n  /** Block height; 0 for mempool, -1 for mempool with unconfirmed parents. */\n  height: number;\n};\n\n/**\n * The Electrum client surface this reader needs. The pure SDK's\n * `ElectrumWsClient` satisfies it; tests inject a fake.\n */\nexport type ElectrumRpc = {\n  request<T>(method: string, params: unknown[]): Promise<T>;\n  subscribeScriptHash(\n    scripthash: string,\n    onChange: (status: string | null) => void,\n  ): Promise<string | null>;\n  unsubscribeScriptHash(\n    scripthash: string,\n    onChange: (status: string | null) => void,\n  ): void;\n};\n\nexport type ElectrumReaderNetwork =\n  | \"mainnet\"\n  | \"testnet\"\n  | \"signet\"\n  | \"regtest\";\n\n/** btc-signer only ships mainnet/testnet; regtest differs in bech32 prefix. */\nconst REGTEST_NETWORK = {\n  bech32: \"bcrt\",\n  pubKeyHash: 0x6f,\n  scriptHash: 0xc4,\n  wif: 0xef,\n} as const;\n\nfunction toBtcSignerNetwork(network: ElectrumReaderNetwork) {\n  switch (network) {\n    case \"mainnet\":\n      return btc.NETWORK;\n    case \"testnet\":\n    case \"signet\":\n      return btc.TEST_NETWORK;\n    case \"regtest\":\n      return REGTEST_NETWORK;\n  }\n}\n\n/** Electrum scripthash: sha256 of the output script, reversed, hex. */\nfunction scriptHashOf(script: Uint8Array): string {\n  return hex.encode(sha256(script).reverse());\n}\n\n/**\n * Build a {@link BitcoinChainReader} over an Electrum connection, with push\n * support and an optional fallback reader for outages.\n */\nexport function electrumReader(\n  client: ElectrumRpc,\n  opts?: BitcoinConfirmationPolicy & {\n    /** Network the HTLC addresses live on; defaults to mainnet. */\n    network?: ElectrumReaderNetwork;\n    /** Reader consulted when the Electrum server errors (e.g. esplora). */\n    fallback?: BitcoinChainReader;\n  },\n): BitcoinChainReader {\n  const network = opts?.network ?? \"mainnet\";\n  const defaultMinConf = opts?.minConfirmations ?? 0;\n  const fallback = opts?.fallback;\n\n  const scriptFor = (address: string): Uint8Array =>\n    btc.OutScript.encode(\n      btc.Address(toBtcSignerNetwork(network)).decode(address),\n    );\n\n  async function getHtlcFactsElectrum(\n    address: string,\n    required: number,\n  ): Promise<BitcoinHtlcFacts> {\n    const script = scriptFor(address);\n    const scripthash = scriptHashOf(script);\n    const history = await client.request<ElectrumHistoryEntry[]>(\n      \"blockchain.scripthash.get_history\",\n      [scripthash],\n    );\n    if (!history || history.length === 0)\n      return { funding: \"absent\", fundedSats: 0 };\n\n    // HTLC addresses see at most a handful of txs (fund + resolve), so\n    // fetching each raw tx is cheap.\n    const txs = await Promise.all(\n      history.map(async (entry) => {\n        const raw = await client.request<string>(\"blockchain.transaction.get\", [\n          entry.tx_hash,\n        ]);\n        return {\n          entry,\n          tx: btc.Transaction.fromRaw(hex.decode(raw), {\n            allowUnknownOutputs: true,\n            allowUnknownInputs: true,\n            disableScriptCheck: true,\n          }),\n        };\n      }),\n    );\n\n    const scriptHex = hex.encode(script);\n    const outputIndicesPaying = (tx: btc.Transaction): number[] => {\n      const indices: number[] = [];\n      for (let i = 0; i < tx.outputsLength; i++) {\n        const out = tx.getOutput(i);\n        if (out.script && hex.encode(out.script) === scriptHex) indices.push(i);\n      }\n      return indices;\n    };\n\n    // Among all txs paying the address, the one paying the MOST is the\n    // funding candidate — same rule as the pure SDK's UTXO lookup. The\n    // address is public, so a stray dust payment (whether it landed before\n    // or after the real funding) must not be mistaken for the funding and\n    // observe the swap as underfunded/invalid.\n    let funding: (typeof txs)[number] | undefined;\n    let fundedSats = 0;\n    for (const candidate of txs) {\n      let paid = 0;\n      for (const i of outputIndicesPaying(candidate.tx))\n        paid += Number(candidate.tx.getOutput(i).amount ?? 0n);\n      if (paid > fundedSats) {\n        funding = candidate;\n        fundedSats = paid;\n      }\n    }\n    if (!funding) return { funding: \"absent\", fundedSats: 0 };\n    const fundedVouts = outputIndicesPaying(funding.tx);\n\n    // A tx spending one of the funding outputs is the resolving spend; its\n    // witness classifies claim vs refund.\n    for (const { tx } of txs) {\n      for (let i = 0; i < tx.inputsLength; i++) {\n        const input = tx.getInput(i);\n        if (\n          input.txid &&\n          hex.encode(input.txid) === funding.entry.tx_hash &&\n          input.index !== undefined &&\n          fundedVouts.includes(input.index)\n        ) {\n          return {\n            funding: \"confirmed\",\n            fundedSats: 0, // already spent — the amount no longer matters\n            spendWitness: (input.finalScriptWitness ?? []).map((item) =>\n              hex.encode(item),\n            ),\n          };\n        }\n      }\n    }\n\n    // Same depth policy as the esplora reader: 0/1 read straight off the\n    // confirmed flag; deeper policies need the tip to compute depth.\n    const height = funding.entry.height;\n    const isConfirmed = height > 0;\n    let deepEnough: boolean;\n    if (isConfirmed) {\n      if (required <= 1) {\n        deepEnough = true;\n      } else {\n        const tip = await client.request<{ height: number }>(\n          \"blockchain.headers.subscribe\",\n          [],\n        );\n        deepEnough = tip.height - height + 1 >= required;\n      }\n    } else {\n      deepEnough = required === 0;\n    }\n    return { funding: deepEnough ? \"confirmed\" : \"mempool\", fundedSats };\n  }\n\n  return {\n    async getHtlcFacts(address, minConfirmations) {\n      const required = minConfirmations ?? defaultMinConf;\n      try {\n        return await getHtlcFactsElectrum(address, required);\n      } catch (error) {\n        if (!fallback) throw error;\n        console.warn(\n          \"electrumReader: falling back to secondary reader:\",\n          error instanceof Error ? error.message : error,\n        );\n        return fallback.getHtlcFacts(address, minConfirmations);\n      }\n    },\n\n    subscribe(address, onChange) {\n      // An address the configured network can't decode (e.g. a signet address\n      // under a mainnet-configured reader) must not throw out of register()\n      // and abort tracking — degrade to the poll cadence instead.\n      let scripthash: string;\n      try {\n        scripthash = scriptHashOf(scriptFor(address));\n      } catch (error) {\n        console.warn(\n          \"electrumReader: subscribe skipped (address decode failed):\",\n          error instanceof Error ? error.message : error,\n        );\n        return () => {};\n      }\n      const handler = () => onChange();\n      // Best-effort: if the subscription fails the tracker's poll cadence\n      // remains the backstop, so the error is logged, not thrown.\n      client.subscribeScriptHash(scripthash, handler).catch((error) => {\n        console.warn(\n          \"electrumReader: scripthash subscribe failed:\",\n          error instanceof Error ? error.message : error,\n        );\n      });\n      return () => client.unsubscribeScriptHash(scripthash, handler);\n    },\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-EIWELJJK.js → chunk-THI4UO6R.js}

@@ -12,11 +12,17 @@ function htlcFactsFromEsploraTxs(txs, address, opts) {
         spendWitness: spend.witness ?? []
       };
   }
-  const funding = txs.find(
-    (tx) => tx.vout.some((vout) => vout.scriptpubkey_address === address)
-  );
+  const paidSats = (tx) => tx.vout.filter((vout) => vout.scriptpubkey_address === address).reduce((sum, vout) => sum + (vout.value ?? 0), 0);
+  let funding;
+  let fundedSats = 0;
+  for (const tx of txs) {
+    const paid = paidSats(tx);
+    if (paid > fundedSats) {
+      funding = tx;
+      fundedSats = paid;
+    }
+  }
   if (funding) {
-    const fundedSats = funding.vout.filter((vout) => vout.scriptpubkey_address === address).reduce((sum, vout) => sum + (vout.value ?? 0), 0);
     const minConf = opts?.minConfirmations ?? 0;
     let deepEnough;
     if (funding.status?.confirmed) {
@@ -78,4 +84,4 @@ export {
   DEFAULT_ESPLORA_URLS,
   esploraReader
 };
-//# sourceMappingURL=chunk-EIWELJJK.js.map
+//# sourceMappingURL=chunk-THI4UO6R.js.map

package/dist/chunk-THI4UO6R.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/contracts/bitcoin-reader-esplora.ts"],"sourcesContent":["/**\n * A esplora-backed {@link BitcoinChainReader} — the concrete chain source the\n * {@link BitcoinContractManager} uses in production.\n *\n * Kept separate from the manager so the manager stays free of any HTTP/esplora\n * dependency (and unit-testable against a fake reader). A single\n * `GET /address/{addr}/txs` yields both the funding state and the spending\n * input's witness, so no extra round-trips are needed.\n */\n\nimport type { BitcoinHtlcFacts } from \"./bitcoin.js\";\nimport type { BitcoinChainReader } from \"./bitcoin-manager.js\";\n\n/** The slice of esplora's tx JSON we read. */\ntype EsploraTx = {\n  vin: Array<{\n    witness?: string[];\n    prevout?: { scriptpubkey_address?: string } | null;\n  }>;\n  vout: Array<{ scriptpubkey_address?: string; value?: number }>;\n  status?: { confirmed?: boolean; block_height?: number };\n};\n\n/**\n * When a funding tx counts as `confirmed` for observation purposes.\n *\n * `minConfirmations: 0` (the default) accepts an UNCONFIRMED funding, so a swap\n * claims as soon as the funding hits the mempool instead of waiting ~10min for\n * a block. This TRUSTS the funder not to double-spend: claiming publishes the\n * preimage, so a funder who then replaces its funding tx could take both legs.\n * Our own server therefore broadcasts HTLC fundings without signalling RBF.\n * Note that a non-signalling tx is still replaceable by full-RBF miners — set\n * `1` (or more) for a policy that doesn't rely on the funder's good behaviour;\n * values above 1 make the reader fetch the tip height to compute depth.\n */\nexport type BitcoinConfirmationPolicy = {\n  minConfirmations?: number;\n};\n\n/**\n * Reduce an address's esplora tx history to HTLC facts. If a tx spends an output\n * at the address, that's the resolving spend (its witness classifies claim vs\n * refund); otherwise a tx paying the address is the funding, gated by the\n * confirmation policy (see {@link BitcoinConfirmationPolicy}).\n */\nexport function htlcFactsFromEsploraTxs(\n  txs: EsploraTx[],\n  address: string,\n  opts?: BitcoinConfirmationPolicy & { tipHeight?: number },\n): BitcoinHtlcFacts {\n  for (const tx of txs) {\n    const spend = tx.vin.find(\n      (vin) => vin.prevout?.scriptpubkey_address === address,\n    );\n    if (spend)\n      return {\n        funding: \"confirmed\",\n        fundedSats: 0, // already spent — the amount no longer matters\n        spendWitness: spend.witness ?? [],\n      };\n  }\n  // Among all txs paying the address, the one paying the MOST is the funding\n  // candidate — matching the pure SDK's UTXO lookup. The address is public,\n  // so a stray dust payment must not be mistaken for the funding and observe\n  // the swap as underfunded/invalid.\n  const paidSats = (tx: EsploraTx): number =>\n    tx.vout\n      .filter((vout) => vout.scriptpubkey_address === address)\n      .reduce((sum, vout) => sum + (vout.value ?? 0), 0);\n  let funding: EsploraTx | undefined;\n  let fundedSats = 0;\n  for (const tx of txs) {\n    const paid = paidSats(tx);\n    if (paid > fundedSats) {\n      funding = tx;\n      fundedSats = paid;\n    }\n  }\n  if (funding) {\n    const minConf = opts?.minConfirmations ?? 0;\n    let deepEnough: boolean;\n    if (funding.status?.confirmed) {\n      deepEnough =\n        minConf <= 1 ||\n        (opts?.tipHeight !== undefined &&\n          funding.status.block_height !== undefined &&\n          opts.tipHeight - funding.status.block_height + 1 >= minConf);\n    } else {\n      deepEnough = minConf === 0;\n    }\n    return {\n      funding: deepEnough ? \"confirmed\" : \"mempool\",\n      fundedSats,\n    };\n  }\n  return { funding: \"absent\", fundedSats: 0 };\n}\n\n/**\n * Public esplora endpoints tried in rotation (mainnet). blockstream.info runs the\n * reference esplora, so it's API-compatible with mempool.space; spreading calls\n * across both halves the per-provider load and survives one being throttled.\n */\nexport const DEFAULT_ESPLORA_URLS = [\n  \"https://mempool.space/api\",\n  \"https://blockstream.info/api\",\n];\n\n/**\n * Build a {@link BitcoinChainReader} over one or more esplora REST endpoints.\n * With several, each call starts at a rotating endpoint (to spread load across\n * providers) and fails over to the rest on error — so a throttled or failing\n * provider doesn't stall tracking.\n */\nexport function esploraReader(\n  esploraUrls: string | string[],\n  fetchImpl: typeof fetch = fetch,\n  policy?: BitcoinConfirmationPolicy,\n): BitcoinChainReader {\n  const bases = (Array.isArray(esploraUrls) ? esploraUrls : [esploraUrls]).map(\n    (url) => url.replace(/\\/+$/, \"\"),\n  );\n  const minConf = policy?.minConfirmations ?? 0;\n  let start = 0;\n  return {\n    async getHtlcFacts(address, minConfirmations) {\n      const required = minConfirmations ?? minConf;\n      const from = start++ % bases.length; // rotate the primary to spread load\n      let lastError: unknown;\n      for (let i = 0; i < bases.length; i++) {\n        const base = bases[(from + i) % bases.length];\n        try {\n          const res = await fetchImpl(\n            `${base}/address/${encodeURIComponent(address)}/txs`,\n          );\n          if (!res.ok) throw new Error(`esplora ${res.status} at ${base}`);\n          const txs = (await res.json()) as EsploraTx[];\n          // Depth policies beyond 1 need the tip to compute confirmations;\n          // 0 and 1 read straight off the tx's confirmed flag.\n          let tipHeight: number | undefined;\n          if (required > 1) {\n            const tip = await fetchImpl(`${base}/blocks/tip/height`);\n            if (!tip.ok) throw new Error(`esplora ${tip.status} at ${base}`);\n            tipHeight = Number(await tip.text());\n          }\n          return htlcFactsFromEsploraTxs(txs, address, {\n            minConfirmations: required,\n            tipHeight,\n          });\n        } catch (error) {\n          lastError = error;\n        }\n      }\n      throw lastError ?? new Error(\"no esplora endpoints configured\");\n    },\n  };\n}\n"],"mappings":";AA6CO,SAAS,wBACd,KACA,SACA,MACkB;AAClB,aAAW,MAAM,KAAK;AACpB,UAAM,QAAQ,GAAG,IAAI;AAAA,MACnB,CAAC,QAAQ,IAAI,SAAS,yBAAyB;AAAA,IACjD;AACA,QAAI;AACF,aAAO;AAAA,QACL,SAAS;AAAA,QACT,YAAY;AAAA;AAAA,QACZ,cAAc,MAAM,WAAW,CAAC;AAAA,MAClC;AAAA,EACJ;AAKA,QAAM,WAAW,CAAC,OAChB,GAAG,KACA,OAAO,CAAC,SAAS,KAAK,yBAAyB,OAAO,EACtD,OAAO,CAAC,KAAK,SAAS,OAAO,KAAK,SAAS,IAAI,CAAC;AACrD,MAAI;AACJ,MAAI,aAAa;AACjB,aAAW,MAAM,KAAK;AACpB,UAAM,OAAO,SAAS,EAAE;AACxB,QAAI,OAAO,YAAY;AACrB,gBAAU;AACV,mBAAa;AAAA,IACf;AAAA,EACF;AACA,MAAI,SAAS;AACX,UAAM,UAAU,MAAM,oBAAoB;AAC1C,QAAI;AACJ,QAAI,QAAQ,QAAQ,WAAW;AAC7B,mBACE,WAAW,KACV,MAAM,cAAc,UACnB,QAAQ,OAAO,iBAAiB,UAChC,KAAK,YAAY,QAAQ,OAAO,eAAe,KAAK;AAAA,IAC1D,OAAO;AACL,mBAAa,YAAY;AAAA,IAC3B;AACA,WAAO;AAAA,MACL,SAAS,aAAa,cAAc;AAAA,MACpC;AAAA,IACF;AAAA,EACF;AACA,SAAO,EAAE,SAAS,UAAU,YAAY,EAAE;AAC5C;AAOO,IAAM,uBAAuB;AAAA,EAClC;AAAA,EACA;AACF;AAQO,SAAS,cACd,aACA,YAA0B,OAC1B,QACoB;AACpB,QAAM,SAAS,MAAM,QAAQ,WAAW,IAAI,cAAc,CAAC,WAAW,GAAG;AAAA,IACvE,CAAC,QAAQ,IAAI,QAAQ,QAAQ,EAAE;AAAA,EACjC;AACA,QAAM,UAAU,QAAQ,oBAAoB;AAC5C,MAAI,QAAQ;AACZ,SAAO;AAAA,IACL,MAAM,aAAa,SAAS,kBAAkB;AAC5C,YAAM,WAAW,oBAAoB;AACrC,YAAM,OAAO,UAAU,MAAM;AAC7B,UAAI;AACJ,eAAS,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;AACrC,cAAM,OAAO,OAAO,OAAO,KAAK,MAAM,MAAM;AAC5C,YAAI;AACF,gBAAM,MAAM,MAAM;AAAA,YAChB,GAAG,IAAI,YAAY,mBAAmB,OAAO,CAAC;AAAA,UAChD;AACA,cAAI,CAAC,IAAI,GAAI,OAAM,IAAI,MAAM,WAAW,IAAI,MAAM,OAAO,IAAI,EAAE;AAC/D,gBAAM,MAAO,MAAM,IAAI,KAAK;AAG5B,cAAI;AACJ,cAAI,WAAW,GAAG;AAChB,kBAAM,MAAM,MAAM,UAAU,GAAG,IAAI,oBAAoB;AACvD,gBAAI,CAAC,IAAI,GAAI,OAAM,IAAI,MAAM,WAAW,IAAI,MAAM,OAAO,IAAI,EAAE;AAC/D,wBAAY,OAAO,MAAM,IAAI,KAAK,CAAC;AAAA,UACrC;AACA,iBAAO,wBAAwB,KAAK,SAAS;AAAA,YAC3C,kBAAkB;AAAA,YAClB;AAAA,UACF,CAAC;AAAA,QACH,SAAS,OAAO;AACd,sBAAY;AAAA,QACd;AAAA,MACF;AACA,YAAM,aAAa,IAAI,MAAM,iCAAiC;AAAA,IAChE;AAAA,EACF;AACF;","names":[]}

package/dist/index.cjs

@@ -51,11 +51,17 @@ function htlcFactsFromEsploraTxs(txs, address, opts) {
         spendWitness: spend.witness ?? []
       };
   }
-  const funding = txs.find(
-    (tx) => tx.vout.some((vout) => vout.scriptpubkey_address === address)
-  );
+  const paidSats = (tx) => tx.vout.filter((vout) => vout.scriptpubkey_address === address).reduce((sum, vout) => sum + (vout.value ?? 0), 0);
+  let funding;
+  let fundedSats = 0;
+  for (const tx of txs) {
+    const paid = paidSats(tx);
+    if (paid > fundedSats) {
+      funding = tx;
+      fundedSats = paid;
+    }
+  }
   if (funding) {
-    const fundedSats = funding.vout.filter((vout) => vout.scriptpubkey_address === address).reduce((sum, vout) => sum + (vout.value ?? 0), 0);
     const minConf = opts?.minConfirmations ?? 0;
     let deepEnough;
     if (funding.status?.confirmed) {
@@ -177,7 +183,17 @@ function electrumReader(client, opts) {
       }
       return indices;
     };
-    const funding = txs.find(({ tx }) => outputIndicesPaying(tx).length > 0);
+    let funding;
+    let fundedSats = 0;
+    for (const candidate of txs) {
+      let paid = 0;
+      for (const i of outputIndicesPaying(candidate.tx))
+        paid += Number(candidate.tx.getOutput(i).amount ?? 0n);
+      if (paid > fundedSats) {
+        funding = candidate;
+        fundedSats = paid;
+      }
+    }
     if (!funding) return { funding: "absent", fundedSats: 0 };
     const fundedVouts = outputIndicesPaying(funding.tx);
     for (const { tx } of txs) {
@@ -195,9 +211,6 @@ function electrumReader(client, opts) {
         }
       }
     }
-    let fundedSats = 0;
-    for (const i of fundedVouts)
-      fundedSats += Number(funding.tx.getOutput(i).amount ?? 0n);
     const height = funding.entry.height;
     const isConfirmed = height > 0;
     let deepEnough;
@@ -279,6 +292,7 @@ __export(src_exports, {
   DEFAULT_ESPLORA_URLS: () => DEFAULT_ESPLORA_URLS,
   DEFAULT_EVM_RPCS: () => DEFAULT_EVM_RPCS,
   EvmContractManager: () => EvmContractManager,
+  HintTracker: () => HintTracker,
   SwapTracker: () => SwapTracker,
   SwapWorker: () => SwapWorker,
   WsStatusSource: () => WsStatusSource,
@@ -1491,6 +1505,113 @@ function defaultEvmReaders(overrides) {
   return readers;
 }
 
+// src/hints/hint-tracker.ts
+var HintTracker = class {
+  #fetchStatus;
+  #refreshIntervalMs;
+  #swaps = /* @__PURE__ */ new Map();
+  /** Last server-reported status per swap (seeded from storage, updated by hints). */
+  #statuses = /* @__PURE__ */ new Map();
+  /** Last actions emitted per swap — for dedupe and the subscribe-time snapshot. */
+  #lastActions = /* @__PURE__ */ new Map();
+  #subscribers = /* @__PURE__ */ new Set();
+  #timer;
+  constructor(options) {
+    this.#fetchStatus = options.fetchStatus;
+    this.#refreshIntervalMs = options.refreshIntervalMs ?? 5e3;
+  }
+  /**
+   * Always `true`: with no chain readers there is no reachability constraint.
+   * (Claim/refund execution has its own chain configuration, independent of
+   * tracking.)
+   */
+  canObserve(_swap) {
+    return true;
+  }
+  /** Register the swaps, derive each one's first action from its stored status. */
+  async startTracking(swaps) {
+    for (const swap of swaps) this.#admit(swap);
+    this.#recomputeAll();
+    if (this.#refreshIntervalMs > 0)
+      this.#timer = setInterval(
+        () => this.#recomputeAll(),
+        this.#refreshIntervalMs
+      );
+  }
+  /**
+   * Track one more swap after {@link startTracking}. Idempotent: a swap already
+   * tracked, or one already seen through to a terminal action, is ignored.
+   */
+  async track(swap) {
+    if (this.#swaps.has(swap.swapId) || this.#lastActions.has(swap.swapId))
+      return;
+    this.#admit(swap);
+    this.#recompute(swap);
+  }
+  #admit(swap) {
+    this.#swaps.set(swap.swapId, swap);
+    if (swap.storedStatus !== void 0 && !this.#statuses.has(swap.swapId))
+      this.#statuses.set(swap.swapId, swap.storedStatus);
+  }
+  /** The swap ids currently tracked — e.g. to subscribe them to the hint feed. */
+  trackedSwapIds() {
+    return [...this.#swaps.keys()];
+  }
+  /**
+   * Apply a server status to one swap and recompute its action. A hint that
+   * carries the pushed `status` is applied as-is; without one (the worker's
+   * retry and post-reconnect paths) the status is re-fetched from the server.
+   * A no-op for an untracked swap.
+   */
+  async applyHint(swapId, opts) {
+    const swap = this.#swaps.get(swapId);
+    if (!swap) return;
+    const status = opts?.status ?? await this.#fetchStatus(swapId);
+    if (!this.#swaps.has(swapId)) return;
+    this.#statuses.set(swapId, status);
+    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: drop the tick timer, tracked swaps, and subscribers. */
+  stop() {
+    if (this.#timer) clearInterval(this.#timer);
+    this.#timer = void 0;
+    this.#swaps.clear();
+    this.#subscribers.clear();
+  }
+  #recomputeAll() {
+    for (const swap of this.#swaps.values()) this.#recompute(swap);
+  }
+  #recompute(swap, force = false) {
+    const status = this.#statuses.get(swap.swapId);
+    if (status === void 0) return;
+    const now = Date.now();
+    const actions = deriveSwapActions({
+      status,
+      clientChainNow: now,
+      serverChainNow: now,
+      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.#swaps.delete(swap.swapId);
+      this.#statuses.delete(swap.swapId);
+    }
+  }
+};
+
 // src/hints/swap-worker.ts
 var AUTO_EXECUTABLE = /* @__PURE__ */ new Set([
   "claim"
@@ -1524,8 +1645,8 @@ var SwapWorker = class {
     this.#started = true;
     this.#hintSource.subscribe(this.#tracker.trackedSwapIds());
     this.#unsubs.push(
-      this.#hintSource.onStatus(({ swapId }) => {
-        void this.#tracker.applyHint(swapId).catch((error) => {
+      this.#hintSource.onStatus(({ swapId, status }) => {
+        void this.#tracker.applyHint(swapId, { status }).catch((error) => {
           console.warn(`SwapWorker: applyHint(${swapId}) failed:`, error);
         });
       })
@@ -2079,6 +2200,21 @@ function swapToTracked(stored) {
         // no on-chain client leg
         serverRefundLocktime: ms(r.vhtlc_refund_locktime)
       };
+    // Client funds the Arkade VHTLC (source_amount); the server pays the
+    // Lightning invoice off-chain and claims the VHTLC — no server leg to
+    // watch.
+    case "arkade_to_lightning":
+      return {
+        swapId: r.id,
+        clientHtlc: arkadeLeg(
+          r,
+          r.arkade_vhtlc_address,
+          Number(r.source_amount)
+        ),
+        clientRefundLocktime: ms(r.vhtlc_refund_locktime),
+        serverRefundLocktime: 0
+        // no on-chain server leg
+      };
     default:
       return void 0;
   }
@@ -2605,6 +2741,12 @@ var Client = class {
     );
   }
   /** Delegated to the legacy client (migration checkpoint). */
+  createArkadeToLightningSwap(...args) {
+    return this.#trackAfterCreate(
+      this.#legacy.createArkadeToLightningSwap(...args)
+    );
+  }
+  /** Delegated to the legacy client (migration checkpoint). */
   createEvmToArkadeSwapGeneric(...args) {
     return this.#trackAfterCreate(
       this.#legacy.createEvmToArkadeSwapGeneric(...args)
@@ -2666,8 +2808,11 @@ var Client = class {
   /**
    * 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
+   * Loads stored swaps, maps them to {@link TrackedSwap}s, and derives each
+   * one's actions — by default from the server's status hints alone (TEMP while
+   * the chain monitors are buggy; see
+   * {@link ClientBuilder.withChainVerifiedTracking} to re-enable the per-ledger
+   * chain monitors). Idempotent. Requires
    * the client to have been built with {@link ClientBuilder.withTracking}.
    * Subscribe with {@link subscribeToActions}; release with
    * {@link stopTracking}.
@@ -2687,7 +2832,11 @@ var Client = class {
   }
   async #doStartTracking() {
     try {
-      const tracker = new SwapTracker(await this.#ensureManagers(), {
+      const chainVerified = this.#tracking.chainVerified || this.#tracking.managers !== void 0;
+      const tracker = chainVerified ? new SwapTracker(await this.#ensureManagers(), {
+        refreshIntervalMs: this.#tracking.refreshIntervalMs ?? 5e3
+      }) : new HintTracker({
+        fetchStatus: async (swapId) => (await this.getSwap(swapId, { updateStorage: true })).status,
         refreshIntervalMs: this.#tracking.refreshIntervalMs ?? 5e3
       });
       this.#tracker = tracker;
@@ -2736,7 +2885,9 @@ var Client = class {
     const swaps = await this.listAllSwaps();
     return swaps.filter((s) => !SETTLED_STORED_STATUSES.has(s.response.status)).map((s) => {
       try {
-        return swapToTracked(s);
+        const tracked = swapToTracked(s);
+        if (!tracked) return void 0;
+        return { ...tracked, storedStatus: s.response.status };
       } catch (error) {
         console.warn(
           `Client: skipping untrackable stored swap ${s.response.id}:`,
@@ -2814,7 +2965,7 @@ var Client = class {
    * otherwise it runs observe-only, hints in, no spends.
    */
   #startWorker(tracker) {
-    const serverUrl = this.#tracking.serverUrl;
+    const serverUrl = this.#tracking.serverUrl ?? legacyBaseUrl(this.#legacy);
     if (!serverUrl) return;
     const autoClaim = this.#tracking.autoClaim;
     const hintSource = new WsStatusSource({ serverUrl });
@@ -2912,6 +3063,7 @@ var ClientBuilder = class {
   #evmRpcUrls;
   #managers;
   #autoClaim;
+  #chainVerified = false;
   /**
    * Override the EVM JSON-RPC endpoint per chainId. Optional — tracking uses
    * tested public defaults otherwise; an override is tried first, with the
@@ -2938,6 +3090,16 @@ var ClientBuilder = class {
     this.#trackingEnabled = false;
     return this;
   }
+  /**
+   * Verify swap state against the chain (per-ledger contract managers) instead
+   * of trusting the server's status hints. TEMPORARILY off by default while the
+   * chain monitors are being fixed — without it, tracking derives actions from
+   * the server's pushed status alone, with zero chain access.
+   */
+  withChainVerifiedTracking() {
+    this.#chainVerified = true;
+    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
@@ -3055,10 +3217,18 @@ var ClientBuilder = class {
       bitcoinNetwork: this.#bitcoinNetwork,
       bitcoinMinConfirmations: this.#bitcoinMinConfirmations,
       evmRpcUrls: this.#evmRpcUrls,
-      autoClaim: this.#autoClaim
+      autoClaim: this.#autoClaim,
+      chainVerified: this.#chainVerified
     });
   }
 };
+function legacyBaseUrl(legacy) {
+  try {
+    return legacy.baseUrl;
+  } catch {
+    return void 0;
+  }
+}
 var SETTLED_STORED_STATUSES = /* @__PURE__ */ new Set([
   "serverredeemed",
   "clientrefunded",
@@ -3084,6 +3254,7 @@ init_bitcoin_reader_esplora();
   DEFAULT_ESPLORA_URLS,
   DEFAULT_EVM_RPCS,
   EvmContractManager,
+  HintTracker,
   SwapTracker,
   SwapWorker,
   WsStatusSource,