@satora/swap 0.2.0 → 0.3.1

package/README.md

@@ -16,6 +16,10 @@ New code should import `@satora/swap`.
 npm install @satora/swap
 ```
 
+## Compatibility headers
+
+API requests include `X-Lendaswap-Client: <sdk-name>/<semver>` and `x-satora-server-version: <server-api-semver>`. The server-version header declares the server/API version this SDK was built against; the API logs it for diagnostics and does not enforce compatibility yet.
+
 ## Supported swaps
 
 | Direction | Source                      | Target                      |

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

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

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

@@ -1,5 +1,5 @@
 // src/contracts/bitcoin-reader-esplora.ts
-function htlcFactsFromEsploraTxs(txs, address) {
+function htlcFactsFromEsploraTxs(txs, address, opts) {
   for (const tx of txs) {
     const spend = tx.vin.find(
       (vin) => vin.prevout?.scriptpubkey_address === address
@@ -17,8 +17,15 @@ function htlcFactsFromEsploraTxs(txs, address) {
   );
   if (funding) {
     const fundedSats = funding.vout.filter((vout) => vout.scriptpubkey_address === address).reduce((sum, vout) => sum + (vout.value ?? 0), 0);
+    const minConf = opts?.minConfirmations ?? 0;
+    let deepEnough;
+    if (funding.status?.confirmed) {
+      deepEnough = minConf <= 1 || opts?.tipHeight !== void 0 && funding.status.block_height !== void 0 && opts.tipHeight - funding.status.block_height + 1 >= minConf;
+    } else {
+      deepEnough = minConf === 0;
+    }
     return {
-      funding: funding.status?.confirmed ? "confirmed" : "mempool",
+      funding: deepEnough ? "confirmed" : "mempool",
       fundedSats
     };
   }
@@ -28,13 +35,15 @@ var DEFAULT_ESPLORA_URLS = [
   "https://mempool.space/api",
   "https://blockstream.info/api"
 ];
-function esploraReader(esploraUrls, fetchImpl = fetch) {
+function esploraReader(esploraUrls, fetchImpl = fetch, policy) {
   const bases = (Array.isArray(esploraUrls) ? esploraUrls : [esploraUrls]).map(
     (url) => url.replace(/\/+$/, "")
   );
+  const minConf = policy?.minConfirmations ?? 0;
   let start = 0;
   return {
-    async getHtlcFacts(address) {
+    async getHtlcFacts(address, minConfirmations) {
+      const required = minConfirmations ?? minConf;
       const from = start++ % bases.length;
       let lastError;
       for (let i = 0; i < bases.length; i++) {
@@ -44,10 +53,17 @@ function esploraReader(esploraUrls, fetchImpl = fetch) {
             `${base}/address/${encodeURIComponent(address)}/txs`
           );
           if (!res.ok) throw new Error(`esplora ${res.status} at ${base}`);
-          return htlcFactsFromEsploraTxs(
-            await res.json(),
-            address
-          );
+          const txs = await res.json();
+          let tipHeight;
+          if (required > 1) {
+            const tip = await fetchImpl(`${base}/blocks/tip/height`);
+            if (!tip.ok) throw new Error(`esplora ${tip.status} at ${base}`);
+            tipHeight = Number(await tip.text());
+          }
+          return htlcFactsFromEsploraTxs(txs, address, {
+            minConfirmations: required,
+            tipHeight
+          });
         } catch (error) {
           lastError = error;
         }
@@ -62,4 +78,4 @@ export {
   DEFAULT_ESPLORA_URLS,
   esploraReader
 };
-//# sourceMappingURL=chunk-J35RZBDW.js.map
+//# sourceMappingURL=chunk-EIWELJJK.js.map

package/dist/chunk-EIWELJJK.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  const funding = txs.find((tx) =>\n    tx.vout.some((vout) => vout.scriptpubkey_address === address),\n  );\n  if (funding) {\n    const fundedSats = funding.vout\n      .filter((vout) => vout.scriptpubkey_address === address)\n      .reduce((sum, vout) => sum + (vout.value ?? 0), 0);\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;AACA,QAAM,UAAU,IAAI;AAAA,IAAK,CAAC,OACxB,GAAG,KAAK,KAAK,CAAC,SAAS,KAAK,yBAAyB,OAAO;AAAA,EAC9D;AACA,MAAI,SAAS;AACX,UAAM,aAAa,QAAQ,KACxB,OAAO,CAAC,SAAS,KAAK,yBAAyB,OAAO,EACtD,OAAO,CAAC,KAAK,SAAS,OAAO,KAAK,SAAS,IAAI,CAAC;AACnD,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":[]}