thunder-bridge 0.8.0 → 0.8.2

package/dist/index.js

@@ -34,10 +34,13 @@ var ProblemError = class extends Error {
     this.detail = problem.detail ?? null;
   }
 };
-var NO_WALLET_AVAILABLE = "urn:problem-type:thunder-bridge-direct:no-wallet-available";
-var REQUEST_IN_FLIGHT = "urn:problem-type:thunder-bridge-direct:request-in-flight";
-var IDEMPOTENCY_KEY_REUSED = "urn:problem-type:thunder-bridge-direct:idempotency-key-reused";
-var PAYMENT_ALREADY_WATCHED = "urn:problem-type:thunder-bridge-direct:payment-already-watched";
+function isProblemType(problem, type) {
+  return problem.type === type;
+}
+var NO_WALLET_AVAILABLE = "urn:problem-type:thunder-bridge:no-wallet-available";
+var REQUEST_IN_FLIGHT = "urn:problem-type:thunder-bridge:request-in-flight";
+var IDEMPOTENCY_KEY_REUSED = "urn:problem-type:thunder-bridge:idempotency-key-reused";
+var PAYMENT_ALREADY_WATCHED = "urn:problem-type:thunder-bridge:payment-already-watched";
 var IdempotencyConflictError = class extends ProblemError {
   conflict;
   constructor(problem, conflict) {
@@ -68,8 +71,8 @@ function hexToBytes(hex) {
   }
   return bytes;
 }
-function isHex(text2) {
-  return /^[0-9a-f]+$/i.test(text2) && text2.length % 2 === 0;
+function isHex(text3) {
+  return /^[0-9a-f]+$/i.test(text3) && text3.length % 2 === 0;
 }
 
 // ../core/sha256.ts
@@ -163,8 +166,8 @@ function sha256(bytes) {
   }
   return asBytes(state);
 }
-function sha256Hex(text2) {
-  return bytesToHex(sha256(new TextEncoder().encode(text2)));
+function sha256Hex(text3) {
+  return bytesToHex(sha256(new TextEncoder().encode(text3)));
 }
 function withPadding(bytes) {
   const padded = new Uint8Array(
@@ -343,10 +346,13 @@ function sameOrigin(one, other) {
     return false;
   }
 }
+function publicAddress(literal) {
+  return literal.includes(":") ? ipv6IsGlobal(literal) : ipv4IsGlobal(literal);
+}
 function hostIsPublic(host) {
-  if (host.startsWith("[")) return ipv6IsGlobal(host.slice(1, -1));
+  if (host.startsWith("[")) return publicAddress(host.slice(1, -1));
   const name = host.replace(/\.$/, "");
-  if (/^\d+\.\d+\.\d+\.\d+$/.test(name)) return ipv4IsGlobal(name);
+  if (/^\d+\.\d+\.\d+\.\d+$/.test(name)) return publicAddress(name);
   const labels = name.split(".");
   if (labels.length < 2 || labels.some((label) => label === "")) return false;
   return !PRIVATE_SUFFIXES.includes(labels[labels.length - 1]);
@@ -489,10 +495,10 @@ function quoteFromWire(body) {
   const minMsat = msatFrom(wire["min_amount"], 0);
   const maxMsat = msatFrom(wire["max_amount"], 0);
   const metadata = text(wire["metadata"]);
-  const refusals2 = refusalsFrom(wire["refusals"]);
+  const refusals3 = refusalsFrom(wire["refusals"]);
   if (lnAddress === null || amountMsat === null || feeMsat === null) return null;
-  if (minMsat === null || maxMsat === null || metadata === null || refusals2 === null) return null;
-  return { lnAddress, amountMsat, feeMsat, minMsat, maxMsat, metadata, refusals: refusals2 };
+  if (minMsat === null || maxMsat === null || metadata === null || refusals3 === null) return null;
+  return { lnAddress, amountMsat, feeMsat, minMsat, maxMsat, metadata, refusals: refusals3 };
 }
 function paymentFromWire(body) {
   const wire = asObject(body);
@@ -587,15 +593,15 @@ function msatFrom(value, least) {
 }
 function refusalsFrom(value) {
   if (!Array.isArray(value)) return null;
-  const refusals2 = [];
+  const refusals3 = [];
   for (const entry of value) {
     const failure = asObject(entry);
     const address = failure === null ? null : text(failure["address"]);
     const reason = failure?.["reason"];
     if (address === null || typeof reason !== "string" || !REASONS.has(reason)) return null;
-    refusals2.push({ address, reason });
+    refusals3.push({ address, reason });
   }
-  return refusals2;
+  return refusals3;
 }
 function secondsFrom(value) {
   if (typeof value !== "string") return null;
@@ -611,6 +617,16 @@ var TERMINAL = /* @__PURE__ */ new Set(["paid", "expired"]);
 var RECONNECT_DELAY_MS = 3e3;
 var RECONNECT_CAP_MS = 3e4;
 var UNANSWERED_ATTEMPTS = 5;
+var TRIGGER_MIN_CHARS = 16;
+var STRANGER_PROBE = "is-this-gateway-yours";
+function unguessable(trigger) {
+  if (trigger.length < TRIGGER_MIN_CHARS) {
+    throw new Error(
+      `a trigger secret is the only thing guarding its stream, and nothing rate limits a guess at it, so it has to be at least ${TRIGGER_MIN_CHARS} characters nobody can predict`
+    );
+  }
+  return trigger;
+}
 function backoffMs(firstDelay, attempt) {
   const grown = Math.min(firstDelay * 2 ** (attempt - 1), RECONNECT_CAP_MS);
   return Math.round(grown * (0.5 + Math.random() / 2));
@@ -619,11 +635,35 @@ var ThunderBridge = class {
   baseUrl;
   verify;
   token;
+  strangers = null;
   constructor(baseUrl, options) {
     this.baseUrl = baseUrl.replace(/\/+$/, "");
     this.verify = options?.verify ?? true;
     this.token = options?.token ?? null;
   }
+  /**
+   * Whether a token was given, which is what makes an instance yours: a gateway
+   * started with `GATEWAY_TOKEN` answers nobody else, so anything you hand it
+   * stays between you and it
+   */
+  get isPrivate() {
+    return this.token !== null;
+  }
+  /**
+   * Whether the gateway turns away a caller carrying no token, asked by making
+   * one unauthenticated read it would have to refuse. `isPrivate` answers only
+   * whether you configured a token, which is your side of the arrangement and
+   * says nothing about the gateway's, so a made-up token against a public
+   * instance reads as private and is not. Asked once and remembered, because an
+   * instance does not change its mind. Anything other than a refusal counts as
+   * open, so an unreachable gateway fails closed
+   */
+  async refusesStrangers() {
+    this.strangers ??= fetch(`${this.baseUrl}/incoming-payments/${STRANGER_PROBE}`, {
+      headers: { accept: "application/json" }
+    }).then((answer) => answer.status === 401).catch(() => false);
+    return await this.strangers;
+  }
   /**
    * Ask the gateway for an invoice payable to the first address on your list
    * that can issue a provable one, throws `NoWalletAvailableError` when none can
@@ -635,7 +675,10 @@ var ThunderBridge = class {
     const response = await fetch(`${this.baseUrl}/incoming-payments`, {
       method: "POST",
       headers,
-      body: createRequestBody(params, options?.trigger ? sha256Hex(options.trigger) : null)
+      body: createRequestBody(
+        params,
+        options?.trigger ? sha256Hex(unguessable(options.trigger)) : null
+      )
     });
     if (!response.ok) throw await problemFrom(response);
     const payment = await paymentFrom(response);
@@ -674,6 +717,26 @@ var ThunderBridge = class {
     if (!response.ok) throw await problemFrom(response);
     return this.checked(await paymentFrom(response));
   }
+  /**
+   * Read back a payment the gateway is only watching, null when it has never
+   * heard of it. A watched payment carries no address, amount or invoice, so
+   * `getPayment` refuses it and this reads the shape both rails share
+   */
+  async getWatched(id) {
+    const response = await fetch(`${this.baseUrl}/incoming-payments/${encodeURIComponent(id)}`, {
+      headers: this.reading()
+    });
+    if (response.status === 404) return null;
+    if (!response.ok) throw await problemFrom(response);
+    const watched = triggerEventFromWire(await response.json().catch(() => null));
+    if (watched === null) {
+      throw new ProblemError({
+        status: response.status,
+        title: "The gateway answered with something that is not a payment"
+      });
+    }
+    return this.proven(watched);
+  }
   /**
    * List what this gateway is watching, newest first. Only a gateway started
    * with `GATEWAY_TOKEN` serves this, because on a shared one it would hand
@@ -705,7 +768,36 @@ var ThunderBridge = class {
    * one that has answered is followed until its own expiry, so the wait always
    * ends by itself
    */
-  waitForPayment(id, options) {
+  async waitForPayment(id, options) {
+    const payment = paymentFromWire(await this.followed(id, options));
+    if (payment === null) {
+      throw new ProblemError({
+        status: 200,
+        title: `payment ${id} is watched rather than minted here, read it with waitForWatched`
+      });
+    }
+    return this.checked(payment);
+  }
+  /**
+   * Follow a payment the gateway is only watching, one it did not mint, until it
+   * is paid or expired.
+   *
+   * A watched payment carries no address, no amount and no invoice, because the
+   * gateway was told none of them, so it reads back as the shape a trigger
+   * streams rather than as a `Payment`. That is every bank transfer, and every
+   * Lightning invoice registered with `watchPayment` instead of `createPayment`.
+   */
+  async waitForWatched(id, options) {
+    const watched = triggerEventFromWire(await this.followed(id, options));
+    if (watched === null) {
+      throw new ProblemError({
+        status: 200,
+        title: "The gateway answered with something that is not a payment"
+      });
+    }
+    return this.proven(watched);
+  }
+  followed(id, options) {
     const base = this.baseUrl.replace(/^http/, "ws");
     const direct = `${base}/ws/incoming-payments/${encodeURIComponent(id)}`;
     return new Promise((resolve2, reject) => {
@@ -758,13 +850,13 @@ var ThunderBridge = class {
         socket = opened;
         opened.onmessage = (event) => {
           try {
-            const payment = paymentFromWire(JSON.parse(String(event.data)));
-            if (payment === null) return;
-            expiresAt = payment.expiresAt;
+            const frame = JSON.parse(String(event.data));
+            const watched = triggerEventFromWire(frame);
+            if (watched === null) return;
+            expiresAt = watched.expiresAt;
             attempt = 1;
-            if (!TERMINAL.has(payment.status)) return;
-            const checked = this.checked(payment);
-            settle(() => resolve2(checked));
+            if (!TERMINAL.has(watched.status)) return;
+            settle(() => resolve2(frame));
           } catch (refused) {
             settle(() => reject(refused));
           }
@@ -775,6 +867,49 @@ var ThunderBridge = class {
       void connect();
     });
   }
+  /**
+   * Wait on several payments and keep the first one that is really paid, then stop
+   * waiting on the losers, which closes their sockets.
+   *
+   * This is how one order offers two rails. A Lightning invoice and a bank
+   * transfer for the same thing are two payments here, and the payer picks one, so
+   * what you want is the one that arrives and nothing further from the other.
+   *
+   * A leg that expires is a loser, not a winner, which is the whole reason this is
+   * not a race: `waitForPayment` ends on `paid` and on `expired` alike, and a
+   * Lightning invoice expires in an hour while a bank transfer takes days. `null`
+   * means every leg ended without being paid.
+   *
+   * Stopping the wait is not revoking the invoice. Nobody can revoke one, because
+   * the recipient's own wallet minted it, so a payer who pays the loser afterwards
+   * really does pay twice and that shows up on `followTrigger` as a second
+   * settlement to refund.
+   */
+  async firstToSettle(ids, options) {
+    if (ids.length === 0) return null;
+    const stopLosers = new AbortController();
+    const signal = options?.signal ? AbortSignal.any([stopLosers.signal, options.signal]) : stopLosers.signal;
+    let refused = null;
+    try {
+      const winner = await new Promise((resolve2) => {
+        let waiting = ids.length;
+        const lost = () => {
+          waiting -= 1;
+          if (waiting === 0) resolve2(null);
+        };
+        for (const id of ids) {
+          this.waitForWatched(id, { ...options, signal }).then((watched) => watched.status === "paid" ? resolve2(watched) : lost()).catch((failure) => {
+            refused ??= failure;
+            lost();
+          });
+        }
+      });
+      if (winner === null && refused !== null) throw refused;
+      return winner;
+    } finally {
+      stopLosers.abort();
+    }
+  }
   /**
    * Hand over an invoice you obtained yourself so the gateway watches it without
    * being told the address or the amount. It can then only refuse everyone
@@ -785,7 +920,10 @@ var ThunderBridge = class {
     const response = await fetch(`${this.baseUrl}/watched-payments`, {
       method: "POST",
       headers: this.sending(),
-      body: watchRequestBody(params, params.trigger ? sha256Hex(params.trigger) : null)
+      body: watchRequestBody(
+        params,
+        params.trigger ? sha256Hex(unguessable(params.trigger)) : null
+      )
     });
     if (!response.ok) throw await problemFrom(response);
     const watched = triggerEventFromWire(await response.json().catch(() => null));
@@ -804,7 +942,7 @@ var ThunderBridge = class {
    */
   followTrigger(secret, options) {
     const base = this.baseUrl.replace(/^http/, "ws");
-    const direct = `${base}/ws/triggers/${encodeURIComponent(secret)}`;
+    const direct = `${base}/ws/triggers/${encodeURIComponent(unguessable(secret))}`;
     const firstDelay = options.reconnectDelayMs ?? RECONNECT_DELAY_MS;
     let socket = null;
     let retry;
@@ -899,13 +1037,13 @@ async function paymentFrom(response) {
 async function problemFrom(response) {
   const problem = await response.json().catch(() => ({}));
   const document = { ...problem, status: response.status };
-  if (problem.type === NO_WALLET_AVAILABLE) {
+  if (isProblemType(problem, NO_WALLET_AVAILABLE)) {
     return new NoWalletAvailableError(document, refusals(problem.wallets));
   }
-  if (problem.type === REQUEST_IN_FLIGHT) {
+  if (isProblemType(problem, REQUEST_IN_FLIGHT)) {
     return new IdempotencyConflictError(document, "request-in-flight");
   }
-  if (problem.type === IDEMPOTENCY_KEY_REUSED) {
+  if (isProblemType(problem, IDEMPOTENCY_KEY_REUSED)) {
     return new IdempotencyConflictError(document, "key-reused");
   }
   return new ProblemError(document);
@@ -922,7 +1060,7 @@ var VERSION = "v1";
 var IV_BYTES = 12;
 var MIN_SECRET_CHARS = 32;
 var MAX_PLAIN_BYTES = 3e3;
-var INFO = new TextEncoder().encode("thunder-bridge-direct/sealed");
+var INFO = new TextEncoder().encode("thunder-bridge/sealed");
 async function seal(secret, plaintext) {
   const body = new TextEncoder().encode(plaintext);
   if (body.length > MAX_PLAIN_BYTES) {
@@ -976,10 +1114,10 @@ function toBase64Url(bytes) {
   for (const byte of bytes) binary += String.fromCharCode(byte);
   return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
-function fromBase64Url(text2) {
-  if (text2.length === 0 || !/^[A-Za-z0-9_-]+$/.test(text2)) return null;
+function fromBase64Url(text3) {
+  if (text3.length === 0 || !/^[A-Za-z0-9_-]+$/.test(text3)) return null;
   try {
-    const binary = atob(text2.replace(/-/g, "+").replace(/_/g, "/"));
+    const binary = atob(text3.replace(/-/g, "+").replace(/_/g, "/"));
     const bytes = new Uint8Array(binary.length);
     for (let at = 0; at < bytes.length; at++) bytes[at] = binary.charCodeAt(at);
     return bytes;
@@ -1011,6 +1149,87 @@ function asBuffer(bytes) {
   return bytes instanceof Uint8Array && bytes.buffer instanceof ArrayBuffer ? bytes : new Uint8Array(bytes);
 }
 
+// ../core/outbound.ts
+import { lookup } from "dns/promises";
+import { setTimeout as sleep } from "timers/promises";
+var HTTP_TIMEOUT_MS2 = 15e3;
+var LOOKUP_TIMEOUT_MS = 5e3;
+var HOPS_FOLLOWED = 2;
+var REDIRECTS = [301, 302, 303, 307, 308];
+var KEEPS_THE_METHOD = [307, 308];
+var CREDENTIALS = ["authorization", "cookie", "proxy-authorization"];
+var BODY_LIMIT_BYTES = 262144;
+async function ask(url, sent = {}) {
+  const capped = AbortSignal.timeout(HTTP_TIMEOUT_MS2);
+  const signal = sent.deadline ? AbortSignal.any([sent.deadline, capped]) : capped;
+  let target = url;
+  let carried = sent;
+  for (let hop = 0; hop <= HOPS_FOLLOWED; hop += 1) {
+    await refuseUnlessPublic(target);
+    const response = await fetch(target, {
+      method: carried.method ?? "GET",
+      headers: carried.headers ?? {},
+      body: carried.body,
+      redirect: "manual",
+      signal
+    });
+    if (!REDIRECTS.includes(response.status)) return await answerOf(response);
+    const location = response.headers.get("location");
+    if (location === null) {
+      throw new Error(`${target} answered ${response.status} without saying where to`);
+    }
+    await response.body?.cancel();
+    const next = new URL(location, target).toString();
+    carried = KEEPS_THE_METHOD.includes(response.status) ? carried : withoutBody(carried);
+    carried = sameOrigin(target, next) ? carried : withoutCredentials(carried);
+    target = next;
+  }
+  throw new Error(`${url} redirected more than ${HOPS_FOLLOWED} times`);
+}
+async function resolvesNothingPrivate(url) {
+  const host = new URL(url).hostname.replace(/^\[|]$/g, "");
+  const found = await Promise.race([
+    lookup(host, { all: true, verbatim: true }).catch(() => []),
+    sleep(LOOKUP_TIMEOUT_MS, null, { ref: false })
+  ]);
+  return found !== null && found.every((one) => publicAddress(one.address));
+}
+async function refuseUnlessPublic(url) {
+  if (!publicHttps(url)) throw new Error(`${url} is not a public https URL`);
+  if (!await resolvesNothingPrivate(url)) throw new Error(`${url} resolves to an address we do not reach`);
+}
+async function answerOf(response) {
+  const { status, ok } = response;
+  const reader = response.body?.getReader();
+  if (!reader) return { status, ok, body: "", truncated: false };
+  const read = [];
+  let bytes = 0;
+  while (bytes <= BODY_LIMIT_BYTES) {
+    const { done, value } = await reader.read();
+    if (done) return { status, ok, body: text2(read), truncated: false };
+    read.push(value);
+    bytes += value.length;
+  }
+  await reader.cancel();
+  return { status, ok, body: text2(read), truncated: true };
+}
+function withoutBody(sent) {
+  const headers = { ...sent.headers };
+  delete headers["content-type"];
+  return { ...sent, method: "GET", headers, body: void 0 };
+}
+function withoutCredentials(sent) {
+  const headers = { ...sent.headers };
+  for (const named of CREDENTIALS) delete headers[named];
+  return { ...sent, headers };
+}
+function text2(chunks) {
+  const decoder = new TextDecoder();
+  let decoded = "";
+  for (const chunk of chunks) decoded += decoder.decode(chunk, { stream: true });
+  return decoded + decoder.decode();
+}
+
 // ../core/refusal.ts
 var WalletRefused = class extends Error {
   reason;
@@ -1029,7 +1248,6 @@ var NoWalletAvailable = class extends Error {
 
 // ../core/lnurl.ts
 var VERIFY_WITHOUT_PREIMAGE = ["zeuspay.com", "zeusnuts.com", "ecash.love"];
-var HTTP_TIMEOUT_MS2 = 15e3;
 var BECH32_CHARSET2 = "qpzry9x8gf2tvdw0s3jn54khce6mua7l";
 var BECH32_GENERATOR = [996825010, 642813549, 513874426, 1027748829, 705979059];
 var CHECKSUM_SLOTS = [0, 1, 2, 3, 4, 5];
@@ -1044,18 +1262,18 @@ async function resolve(addresses, amountMsat) {
 }
 async function firstThatServes(addresses, attempt) {
   const deadline = AbortSignal.timeout(RESOLVE_TIMEOUT_MS);
-  const refusals2 = [];
+  const refusals3 = [];
   for (const address of addresses) {
     if (deadline.aborted) break;
     try {
-      return { won: await attempt(address, deadline), refusals: refusals2 };
+      return { won: await attempt(address, deadline), refusals: refusals3 };
     } catch (refusal) {
       if (!(refusal instanceof WalletRefused)) throw refusal;
       console.warn(`wallet ${address} refused, ${refusal.reason}: ${refusal.message}`);
-      refusals2.push({ address, reason: refusal.reason });
+      refusals3.push({ address, reason: refusal.reason });
     }
   }
-  throw new NoWalletAvailable(refusals2);
+  throw new NoWalletAvailable(refusals3);
 }
 async function probe(address, amountMsat, deadline) {
   const [user, domain] = splitAddress(address);
@@ -1194,14 +1412,12 @@ function splitAddress(address) {
   return [user, domain];
 }
 async function fetchJson(url, deadline) {
-  if (!publicHttps(url)) throw new Error(`${url} is not a public https URL`);
-  const capped = AbortSignal.timeout(HTTP_TIMEOUT_MS2);
-  const response = await fetch(url, {
-    signal: deadline ? AbortSignal.any([deadline, capped]) : capped,
-    headers: { accept: "application/json" }
-  });
-  if (!response.ok) throw new Error(`${url} answered ${response.status}`);
-  return await response.json();
+  const answer = await ask(url, { headers: { accept: "application/json" }, deadline });
+  if (!answer.ok) throw new Error(`${url} answered ${answer.status}`);
+  if (answer.truncated) {
+    throw new Error(`${url} answered with more than the ${BODY_LIMIT_BYTES} bytes we read`);
+  }
+  return JSON.parse(answer.body);
 }
 
 // src/trigger.ts
@@ -1280,7 +1496,7 @@ async function mintBlind(config, address, amountMsat) {
   return { bolt11: resolved.bolt11, verifyUrl: resolved.verifyUrl };
 }
 function alreadyWatched(refused) {
-  return refused instanceof ProblemError && refused.type === PAYMENT_ALREADY_WATCHED;
+  return refused instanceof ProblemError && isProblemType(refused, PAYMENT_ALREADY_WATCHED);
 }
 function sign(secret, address, amountMsat, nonce) {
   return hmacHex(secret, `${address}|${amountMsat}|${nonce}`);
@@ -1295,6 +1511,249 @@ function refuse(reason) {
   return Response.json({ status: "ERROR", reason });
 }
 
+// src/currency.ts
+var ISO_4217_MINOR_UNITS = {
+  BHD: 3,
+  BIF: 0,
+  CLP: 0,
+  CZK: 2,
+  DJF: 0,
+  EUR: 2,
+  GBP: 2,
+  ISK: 0,
+  IQD: 3,
+  JOD: 3,
+  JPY: 0,
+  KRW: 0,
+  KWD: 3,
+  LYD: 3,
+  OMR: 3,
+  PLN: 2,
+  PYG: 0,
+  RWF: 0,
+  TND: 3,
+  UGX: 0,
+  USD: 2,
+  VND: 0,
+  VUV: 0,
+  XAF: 0,
+  XOF: 0,
+  XPF: 0
+};
+function minorUnitsOf(currency) {
+  const digits = ISO_4217_MINOR_UNITS[currency.toUpperCase()];
+  if (digits === void 0) {
+    throw new Error(
+      `${currency.toUpperCase()} is not a currency this knows the ISO 4217 minor unit of`
+    );
+  }
+  return digits;
+}
+function minorScaleOf(currency) {
+  return 10 ** minorUnitsOf(currency);
+}
+
+// src/bank.ts
+var DEFAULT_CURRENCY = "CZK";
+var DEFAULT_LOOK_BACK_SECS = 7 * 24 * 60 * 60;
+var IBAN = /^[A-Z]{2}[0-9]{2}[0-9A-Z]{8,30}$/;
+var FORBIDDEN_IN_SPD = "*";
+async function bankTransfer(params) {
+  const currency = params.currency ?? DEFAULT_CURRENCY;
+  refuseUnusable(params, currency);
+  await refuseAnOpenGateway(params);
+  const spd = shortPaymentDescriptor(params, currency);
+  const subject = subjectOf(params.reference, params.amountMinor, currency);
+  const polling = new URL(params.verifyUrl);
+  polling.searchParams.set("ref", params.reference);
+  polling.searchParams.set("minor", String(params.amountMinor));
+  polling.searchParams.set("cc", currency);
+  polling.searchParams.set("sig", await hmacHex(params.secret, `verify|${subject}`));
+  const verifyUrl = polling.toString();
+  const watched = await params.gateway.watchPayment({
+    paymentHash: hashOf(await hmacHex(params.secret, `preimage|${subject}`)),
+    verifyUrl,
+    expiresAt: params.expiresAt,
+    trigger: params.trigger,
+    sealed: params.sealed
+  });
+  return { id: watched.id, paymentHash: watched.paymentHash, verifyUrl, spd };
+}
+function bankVerifyEndpoint(config) {
+  return async (request) => {
+    const asked = readQuery(new URL(request.url));
+    if (asked === null) return Response.json({ settled: false }, { status: 400 });
+    const subject = subjectOf(asked.reference, asked.amountMinor, asked.currency);
+    const expected = await hmacHex(config.secret, `verify|${subject}`);
+    if (!equalInConstantTime(asked.signature, expected)) {
+      return Response.json({ settled: false }, { status: 403 });
+    }
+    const since = unixNow() - (config.lookBackSecs ?? DEFAULT_LOOK_BACK_SECS);
+    const landed = (await config.statement(since)).some((credit) => pays(credit, asked));
+    if (!landed) return Response.json({ settled: false });
+    return Response.json({
+      settled: true,
+      preimage: await hmacHex(config.secret, `preimage|${subject}`)
+    });
+  };
+}
+function readQuery(url) {
+  const reference = url.searchParams.get("ref");
+  const minor = Number(url.searchParams.get("minor"));
+  const currency = url.searchParams.get("cc");
+  const signature = url.searchParams.get("sig");
+  if (!reference || !currency || !signature) return null;
+  if (!Number.isInteger(minor) || minor <= 0) return null;
+  return { reference, amountMinor: minor, currency, signature };
+}
+function pays(credit, asked) {
+  return credit.amountMinor === asked.amountMinor && credit.currency.toUpperCase() === asked.currency.toUpperCase() && credit.reference.toUpperCase().includes(asked.reference.toUpperCase());
+}
+function subjectOf(reference, amountMinor, currency) {
+  return `${reference}|${amountMinor}|${currency.toUpperCase()}`;
+}
+function hashOf(preimage) {
+  return bytesToHex(sha256(hexToBytes(preimage)));
+}
+function shortPaymentDescriptor(params, currency) {
+  const fields = [
+    `ACC:${params.iban}`,
+    `AM:${major(params.amountMinor, currency)}`,
+    `CC:${currency.toUpperCase()}`,
+    `MSG:${params.reference}`
+  ];
+  if (params.variableSymbol) fields.push(`X-VS:${params.variableSymbol}`);
+  return `SPD*1.0*${fields.join("*")}`;
+}
+function major(amountMinor, currency) {
+  return (amountMinor / minorScaleOf(currency)).toFixed(minorUnitsOf(currency));
+}
+async function refuseAnOpenGateway(params) {
+  if (params.allowPublicGateway === true) return;
+  if (await params.gateway.refusesStrangers()) return;
+  throw new Error(
+    "this gateway serves callers with no token, so it is not yours, and its operator would read the amount and the reference off every verify URL. Point at one that answers 401 to a stranger, or say allowPublicGateway"
+  );
+}
+function refuseUnusable(params, currency) {
+  if (!IBAN.test(params.iban)) throw new Error(`${params.iban} is not an IBAN`);
+  if (!Number.isInteger(params.amountMinor) || params.amountMinor <= 0) {
+    throw new Error("amountMinor must be a whole number of minor units above zero");
+  }
+  if (params.reference.length === 0) {
+    throw new Error("a transfer with no reference cannot be found");
+  }
+  if (params.reference.includes(FORBIDDEN_IN_SPD)) {
+    throw new Error("a reference cannot contain an asterisk, it separates the QR fields");
+  }
+  if (params.variableSymbol && !/^[0-9]{1,10}$/.test(params.variableSymbol)) {
+    throw new Error("a variable symbol is up to ten digits");
+  }
+}
+function unixNow() {
+  return Math.floor(Date.now() / 1e3);
+}
+
+// src/fio.ts
+var BASE_URL = "https://fioapi.fio.cz/v1/rest";
+var MINOR_UNITS = 100;
+var MILLIS = 1e3;
+var DATE_CHARS = "2026-08-04".length;
+var DEFAULT_MIN_INTERVAL_SECS = 30;
+var TOO_SOON = 409;
+var BOOKED_AT = "column0";
+var AMOUNT = "column1";
+var CURRENCY = "column14";
+var VARIABLE_SYMBOL = "column5";
+var USER_IDENTIFICATION = "column7";
+var MESSAGE_FOR_RECIPIENT = "column16";
+var PAYER_REFERENCE = "column27";
+var WHERE_A_PAYER_WRITES = [
+  MESSAGE_FOR_RECIPIENT,
+  VARIABLE_SYMBOL,
+  USER_IDENTIFICATION,
+  PAYER_REFERENCE
+];
+var UTC_OFFSET = /^[+-]\d{4}$/;
+function fioStatement(config) {
+  const named = typeof config.token === "string" ? [config.token] : config.token;
+  if (named.length === 0) throw new Error("fioStatement needs at least one token to read with");
+  const usedAt = new Map(named.map((token) => [token, Number.NEGATIVE_INFINITY]));
+  const tokenWindowMs = (config.minIntervalSecs ?? DEFAULT_MIN_INTERVAL_SECS) * MILLIS;
+  const paceMs = tokenWindowMs / usedAt.size;
+  let lastRead = Number.NEGATIVE_INFINITY;
+  let credits = [];
+  return async (sinceUnix) => {
+    const now = Date.now();
+    if (now - lastRead < paceMs) return credits;
+    const idlest = longestUnused(usedAt);
+    if (now - idlest.usedAt < tokenWindowMs) return credits;
+    usedAt.set(idlest.token, now);
+    lastRead = now;
+    const url = [
+      config.baseUrl ?? BASE_URL,
+      "periods",
+      idlest.token,
+      asDate(sinceUnix),
+      asDate(Math.floor(now / MILLIS)),
+      "transactions.json"
+    ].join("/");
+    const answer = await fetch(url, { headers: { accept: "application/json" } });
+    if (answer.status === TOO_SOON) {
+      throw new Error("fio refuses a second read of this token inside its 30 second window");
+    }
+    if (!answer.ok) throw new Error(`fio answered ${answer.status} reading the statement`);
+    const read = await answer.json();
+    credits = (read.accountStatement?.transactionList?.transaction ?? []).filter(isCredit).map(asCredit);
+    return credits;
+  };
+}
+function longestUnused(usedAt) {
+  let token = "";
+  let idleSince = Number.POSITIVE_INFINITY;
+  for (const [candidate, at] of usedAt) {
+    if (at < idleSince) {
+      token = candidate;
+      idleSince = at;
+    }
+  }
+  return { token, usedAt: idleSince };
+}
+function isCredit(transaction) {
+  return numberIn(transaction[AMOUNT]) > 0;
+}
+function asCredit(transaction) {
+  return {
+    amountMinor: Math.round(numberIn(transaction[AMOUNT]) * MINOR_UNITS),
+    currency: textIn(transaction[CURRENCY]),
+    reference: WHERE_A_PAYER_WRITES.map((column) => textIn(transaction[column])).filter((written) => written.length > 0).join(" "),
+    bookedAt: bookedAtIn(transaction[BOOKED_AT])
+  };
+}
+function bookedAtIn(cell) {
+  const value = cell?.value;
+  if (typeof value === "number") return Math.floor(value / MILLIS);
+  const at = Date.parse(asIso8601(textIn(cell)));
+  return Number.isFinite(at) ? Math.floor(at / MILLIS) : 0;
+}
+function asIso8601(booked) {
+  const day = booked.slice(0, DATE_CHARS);
+  const zone = booked.slice(DATE_CHARS);
+  if (!UTC_OFFSET.test(zone)) return `${day}T00:00:00Z`;
+  return `${day}T00:00:00${zone.slice(0, 3)}:${zone.slice(3)}`;
+}
+function numberIn(cell) {
+  const value = Number(cell?.value ?? Number.NaN);
+  return Number.isFinite(value) ? value : 0;
+}
+function textIn(cell) {
+  const value = cell?.value;
+  return value === null || value === void 0 ? "" : String(value).trim();
+}
+function asDate(unix) {
+  return new Date(unix * MILLIS).toISOString().slice(0, DATE_CHARS);
+}
+
 // src/qr.ts
 import { encode } from "uqr";
 var SAFE_COLOR = /^#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$|^rgba?\([\d.,%/\s]+\)$|^[a-z]+$/i;
@@ -1314,6 +1773,18 @@ function lnurlToSvg(endpoint, options) {
 function lnurlToDataUrl(endpoint, options) {
   return asDataUrl(lnurlToSvg(endpoint, options));
 }
+function spdToSvg(spd, options) {
+  return svgOf(spd, options);
+}
+function spdToDataUrl(spd, options) {
+  return asDataUrl(spdToSvg(spd, options));
+}
+function qrToSvg(payload, options) {
+  return svgOf(payload, options);
+}
+function qrToDataUrl(payload, options) {
+  return asDataUrl(qrToSvg(payload, options));
+}
 function svgOf(scanned, options) {
   const size = options?.size ?? 256;
   const color = options?.color ?? "#000";
@@ -1347,6 +1818,207 @@ function renderSvg(content, size, color) {
   ].join("");
 }
 
+// src/rail.ts
+var BANK = "bank";
+var LIGHTNING = "lightning";
+function bankRail(config) {
+  return async (order) => {
+    const expiresAt = config.expiresAt(order);
+    const transfer = await bankTransfer({
+      gateway: config.gateway,
+      secret: config.secret,
+      iban: config.iban,
+      verifyUrl: config.verifyUrl,
+      reference: order.reference,
+      amountMinor: order.amountMinor,
+      currency: order.currency,
+      expiresAt,
+      trigger: config.trigger,
+      sealed: await config.sealed?.(order),
+      variableSymbol: config.variableSymbol?.(order),
+      allowPublicGateway: config.allowPublicGateway
+    });
+    return {
+      id: transfer.id,
+      rail: config.name ?? BANK,
+      scan: transfer.spd,
+      qr: transfer.spd,
+      expiresAt
+    };
+  };
+}
+function lightningRail(config) {
+  return async (order) => {
+    const payment = await config.gateway.createPayment(
+      {
+        lnAddresses: config.lnAddresses,
+        amountMsat: await config.amountMsat(order),
+        webhookUrl: config.webhookUrl,
+        webhookSecret: config.webhookSecret
+      },
+      { idempotencyKey: config.idempotencyKey?.(order), trigger: config.trigger }
+    );
+    return {
+      id: payment.id,
+      rail: config.name ?? LIGHTNING,
+      scan: payment.bolt11,
+      qr: encodeForQr(payment.bolt11),
+      expiresAt: payment.expiresAt
+    };
+  };
+}
+function blindLightningRail(config) {
+  return async (order) => {
+    const resolved = await invoiceFrom(config.lnAddresses, await config.amountMsat(order));
+    const watched = await config.gateway.watchPayment({
+      paymentHash: resolved.paymentHash,
+      verifyUrl: resolved.verifyUrl,
+      expiresAt: resolved.expiresAt,
+      trigger: config.trigger,
+      sealed: await config.sealed?.(order)
+    });
+    return {
+      id: watched.id,
+      rail: config.name ?? LIGHTNING,
+      scan: resolved.bolt11,
+      qr: encodeForQr(resolved.bolt11),
+      expiresAt: resolved.expiresAt
+    };
+  };
+}
+async function invoiceFrom(lnAddresses, amountMsat) {
+  try {
+    return await resolve(lnAddresses, amountMsat);
+  } catch (refused) {
+    if (refused instanceof NoWalletAvailable) {
+      throw new NoWalletAvailableError({ title: refused.message }, refused.wallets);
+    }
+    throw refused;
+  }
+}
+
+// src/price.ts
+var MSAT_PER_BTC2 = 1e11;
+var BASIS_POINTS = 1e4;
+var DEFAULT_HOLD_SECS = 60;
+var DEFAULT_MIN_VENUES = 2;
+var DEFAULT_MAX_SPREAD_BPS = 200;
+var MILLIS2 = 1e3;
+function coinbase(baseUrl = "https://api.coinbase.com") {
+  return async (currency) => {
+    const asked = currency.toUpperCase();
+    const answer = await asJson(`${baseUrl}/v2/prices/BTC-${asked}/spot`, "coinbase");
+    const quoted = answer.data;
+    if (quoted?.currency !== asked) {
+      throw new Error(`coinbase quoted ${quoted?.currency} when asked for ${asked}`);
+    }
+    return asMinor(quoted.amount, "coinbase", asked);
+  };
+}
+function kraken(baseUrl = "https://api.kraken.com") {
+  return async (currency) => {
+    const asked = currency.toUpperCase();
+    const answer = await asJson(`${baseUrl}/0/public/Ticker?pair=XBT${asked}`, "kraken");
+    if (answer.error?.length) throw new Error(`kraken refused XBT${asked}: ${answer.error[0]}`);
+    const pairs = Object.values(answer.result ?? {});
+    if (pairs.length !== 1) {
+      throw new Error(`kraken answered ${pairs.length} pairs for XBT${asked}`);
+    }
+    return asMinor(pairs[0]?.c?.[0], "kraken", asked);
+  };
+}
+function bitstamp(baseUrl = "https://www.bitstamp.net") {
+  return async (currency) => {
+    const pair = `btc${currency.toLowerCase()}`;
+    const answer = await asJson(`${baseUrl}/api/v2/ticker/${pair}/`, "bitstamp");
+    if (Array.isArray(answer)) throw new Error(`bitstamp has no ${pair} pair`);
+    return asMinor(answer.last, "bitstamp", currency);
+  };
+}
+function coinmate(baseUrl = "https://coinmate.io") {
+  return async (currency) => {
+    const pair = `BTC_${currency.toUpperCase()}`;
+    const answer = await asJson(`${baseUrl}/api/ticker?currencyPair=${pair}`, "coinmate");
+    if (answer.error !== false) {
+      throw new Error(`coinmate refused ${pair}: ${answer.errorMessage ?? "no reason"}`);
+    }
+    return asMinor(answer.data?.last, "coinmate", currency);
+  };
+}
+function medianOf(tickers = [coinbase(), kraken(), bitstamp(), coinmate()], options = {}) {
+  const holdFor = (options.holdForSecs ?? DEFAULT_HOLD_SECS) * MILLIS2;
+  const minVenues = options.minVenues ?? DEFAULT_MIN_VENUES;
+  const maxSpread = options.maxSpreadBps ?? DEFAULT_MAX_SPREAD_BPS;
+  const held = /* @__PURE__ */ new Map();
+  return async (currency) => {
+    const asked = currency.toUpperCase();
+    const remembered = held.get(asked);
+    if (remembered && Date.now() - remembered.at < holdFor) return remembered.price;
+    const answers = await Promise.allSettled(tickers.map((ticker) => ticker(asked)));
+    const quoted = answers.filter((answer) => answer.status === "fulfilled").map((answer) => answer.value).sort((one, other) => one - other);
+    if (quoted.length < minVenues) {
+      throw new Error(
+        `${quoted.length} of ${tickers.length} venues quoted ${asked}, ${minVenues} wanted: ${refusals2(answers)}`
+      );
+    }
+    const spread = spreadBpsOf(quoted);
+    if (spread > maxSpread) {
+      throw new Error(
+        `venues disagree on ${asked} by ${Math.round(spread)} bps, more than the ${maxSpread} allowed: ${quoted.join(", ")}`
+      );
+    }
+    const price = middleOf(quoted);
+    held.set(asked, { at: Date.now(), price });
+    return price;
+  };
+}
+function msatFor(amountMinor, priceMinorPerBtc, options = {}) {
+  if (!Number.isInteger(amountMinor) || amountMinor <= 0) {
+    throw new Error("amountMinor must be a whole number of minor units above zero");
+  }
+  if (!Number.isFinite(priceMinorPerBtc) || priceMinorPerBtc <= 0) {
+    throw new Error(`${priceMinorPerBtc} is not a usable price`);
+  }
+  const spreadBps = options.spreadBps ?? 0;
+  if (!Number.isInteger(spreadBps) || spreadBps < 0) {
+    throw new Error("spreadBps must be a whole number of basis points, none or more");
+  }
+  const wanted = BigInt(amountMinor) * BigInt(MSAT_PER_BTC2) * BigInt(BASIS_POINTS + spreadBps);
+  const per = BigInt(Math.round(priceMinorPerBtc)) * BigInt(BASIS_POINTS);
+  const msat = (wanted + per - 1n) / per;
+  if (msat > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new Error(`${amountMinor} at ${priceMinorPerBtc} is more millisatoshi than exist`);
+  }
+  return Number(msat);
+}
+async function asJson(url, venue) {
+  const answer = await fetch(url, { headers: { accept: "application/json" } });
+  if (!answer.ok) throw new Error(`${venue} answered ${answer.status}`);
+  return answer.json();
+}
+function asMinor(quoted, venue, currency) {
+  const major2 = Number(quoted);
+  if (!Number.isFinite(major2) || major2 <= 0) {
+    throw new Error(`${venue} quoted ${String(quoted)} for ${currency.toUpperCase()}`);
+  }
+  return Math.round(major2 * minorScaleOf(currency));
+}
+function spreadBpsOf(sorted) {
+  const lowest = sorted[0] ?? 0;
+  const highest = sorted[sorted.length - 1] ?? 0;
+  return lowest === 0 ? Number.POSITIVE_INFINITY : (highest - lowest) / lowest * BASIS_POINTS;
+}
+function middleOf(sorted) {
+  const middle = Math.floor(sorted.length / 2);
+  if (sorted.length % 2 === 1) return sorted[middle] ?? 0;
+  return Math.round(((sorted[middle - 1] ?? 0) + (sorted[middle] ?? 0)) / 2);
+}
+function refusals2(answers) {
+  return answers.filter((answer) => answer.status === "rejected").map(
+    (answer) => answer.reason instanceof Error ? answer.reason.message : String(answer.reason)
+  ).join("; ");
+}
+
 // src/webhook.ts
 var SIGNATURE_HEADER = "x-signature";
 var TIMESTAMP_HEADER = "x-timestamp";
@@ -1359,9 +2031,9 @@ async function verifyWebhookSignature(body, signature, secret, timestamp, option
 }
 async function parseWebhook(body, signature, secret, timestamp, options = {}) {
   if (!await verifyWebhookSignature(body, signature, secret, timestamp, options)) return null;
-  const text2 = typeof body === "string" ? body : new TextDecoder().decode(body);
+  const text3 = typeof body === "string" ? body : new TextDecoder().decode(body);
   try {
-    return paymentFromWire(JSON.parse(text2));
+    return paymentFromWire(JSON.parse(text3));
   } catch {
     return null;
   }
@@ -1400,19 +2072,38 @@ export {
   REQUEST_IN_FLIGHT,
   ThunderBridge,
   UnverifiedRecipientError,
+  bankRail,
+  bankTransfer,
+  bankVerifyEndpoint,
+  bitstamp,
+  blindLightningRail,
+  coinbase,
+  coinmate,
   decodeInvoice,
+  fioStatement,
   invoiceToDataUrl,
   invoiceToSvg,
+  isProblemType,
   isProvablyPaid,
+  kraken,
+  lightningRail,
   lnurlPayEndpoint,
   lnurlToDataUrl,
   lnurlToSvg,
+  medianOf,
+  minorScaleOf,
+  minorUnitsOf,
+  msatFor,
   parseWebhook,
   parseWebhookRequest,
   preimageMatchesHash,
   proveOrigin,
   proveSettlement,
+  qrToDataUrl,
+  qrToSvg,
   seal,
+  spdToDataUrl,
+  spdToSvg,
   toLnurl,
   unseal,
   verifyWebhookSignature