thunder-bridge 0.8.0 → 0.8.1

package/README.md

@@ -1,29 +1,25 @@
 # thunder-bridge
 
-A JavaScript client for a Thunder Bridge gateway. You give it a priority list of
-Lightning addresses and an amount, it walks the list, asks each address's own
-LNURL-pay endpoint for an invoice, and hands back the first one it could get.
-The gateway mints nothing, holds nothing and forwards nothing. The payer pays
-the recipient's own invoice.
-
-None of that would be worth much if you had to take the gateway's word for it,
-so this package does not. Before `createPayment` returns, the invoice is proven
-against the recipient's own server: it is the invoice that address issued, it is
-for the amount you asked for rather than the amount the gateway echoed back, and
-the settlement proof url belongs to the recipient rather than to the gateway.
-Two fetches, both straight at the recipient's domain, neither of them back to
-the gateway. A gateway that substitutes an invoice is caught by the caller that
-asked for it, before a payer ever sees a QR code.
-
-Whether the money then arrived is a separate question with its own call.
-`proveSettlement` asks the recipient's own server and returns the preimage that
-server released. Everything else you can read about a payment is the gateway's
-own account of it, and this package is deliberate about which of its functions
-are proofs and which are only sanity checks.
+A JavaScript client for a Thunder Bridge gateway. Give it a priority list of
+lightning addresses and an amount, and it hands back an invoice minted by the
+recipient's own wallet. The gateway mints nothing, holds nothing and forwards
+nothing.
+
+None of that would be worth much if you had to take the gateway's word for it, so
+this package does not. Before `createPayment` returns, the invoice is proven
+against the recipient's own server: it is the invoice that address issued, for the
+amount you asked for rather than the amount the gateway echoed back, and its
+settlement proof url belongs to the recipient. A gateway that substitutes an
+invoice is caught before a payer sees a QR code.
+
+Lightning is the rail it was built for, not the only one it can prove.
+`bankTransfer` derives a preimage and hands the gateway its hash, which puts money
+landing in a bank account behind the same watch and the same proof. `Statement` is
+the seam a bank plugs into and `fioStatement` is the first one.
 
 It touches only `fetch`, `crypto.subtle`, `URL` and `WebSocket`, so it runs in
-Node, Bun, Deno, Cloudflare Workers and the browser. The service it talks to lives in the same repository, one level up from this
-package.
+Node, Bun, Deno, Cloudflare Workers and the browser. The gateway it talks to is
+one level up in [this repository](../README.md).
 
 ## Install
 
@@ -35,7 +31,7 @@ npm install thunder-bridge
 
 A page can run the whole flow with no backend of its own. The gateway answers
 every origin, and coinos, Alby and Stacker News serve their LNURL endpoints with
-CORS open, so the verification fetches work from a browser too.
+CORS open, so the proof fetches work from a browser too.
 
 ```ts
 import { ThunderBridge, invoiceToSvg, type CreatePaymentParams } from "thunder-bridge";
@@ -53,10 +49,8 @@ const target = document.querySelector("#qr");
 if (target) target.innerHTML = invoiceToSvg(payment.bolt11);
 ```
 
-By the time that resolves, the invoice has been checked against whichever
-address won, so it is safe to put in front of a payer. Keep the `request`
-object. Every proof in this package takes it, because what you asked for is the
-one side of each comparison the gateway did not supply.
+Keep the `request` object. Every proof takes it, because what you asked for is the
+side of each comparison the gateway did not supply.
 
 ```ts
 import { proveSettlement } from "thunder-bridge";
@@ -71,625 +65,128 @@ if (settled.status === "paid") {
 }
 ```
 
-`waitForPayment` tells you what the gateway says, and rejects a `paid` frame
-whose numbers do not hold together. `proveSettlement` goes to the recipient's
-own server and comes back with the preimage that server released, or `null` if
-it has released none. Only the second is evidence the money arrived.
+`waitForPayment` tells you what the gateway says. `proveSettlement` goes to the
+recipient's own server. Only the second is evidence the money arrived.
 
-## API
+## What is exported
 
-Everything below is exported from the package root. There are no subpaths.
+Everything comes from the package root, there are no subpaths. Signatures and the
+caveats on each export are in the TSDoc on the export itself, so your editor has
+them and this table does not repeat them.
 
-### `new ThunderBridge(baseUrl, options?)`
+**The gateway** - [`src/client.ts`](src/client.ts)
 
-```ts
-const gateway = new ThunderBridge("https://gateway.example");
-const unchecked = new ThunderBridge("https://gateway.example", { verify: false });
-```
-
-```ts
-const mine = new ThunderBridge("https://gateway.example", { token: process.env.GATEWAY_TOKEN });
-```
-
-A trailing slash on `baseUrl` is stripped. `verify` defaults to `true`, and
-setting it to `false` turns off both halves of the checking the client does for
-you: the origin proof on
-`createPayment`, and the `isProvablyPaid` consistency check on every `paid`
-payment read back. Turn it off only when you are running the checks yourself.
-
-`token` is sent as `Authorization: Bearer` and is what a gateway started with
-`GATEWAY_TOKEN` requires on every call. That is a lock for a gateway you host
-yourself, not a per-user login: it keeps strangers out of your instance. On a
-shared gateway a token someone else issues you is a thing they can revoke, which
-is the dependency this project exists to remove, so there is no account system
-here and none is planned.
-
-The token covers the WebSocket handshake too, and a socket without it is refused
-with a 401 rather than upgraded. No browser can put a header on a socket, so
-setting `token` also makes `waitForPayment` and `followTrigger` mint a
-short-lived ticket per connection and open `/ws/tickets/...` with that. Nothing
-to configure, and `tickets: true` stays there for the public gateway where you
-want the same on purpose.
-
-### `gateway.listPayments(limit?)`
-
-```ts
-const { payments, scanned } = await gateway.listPayments(50);
-```
-
-Lists what the gateway is watching, newest first. Only a gateway with a token
-serves it, because a list on a shared one would hand every caller everyone
-else's payments. A public gateway answers 404 and this throws `ProblemError`.
-
-`scanned` is how many settled records were read to build the page. Settled
-payments older than that window are not in the answer. Entries are
-`TriggerEvent`, so `lnAddress` and `amountMsat` are `null` for anything
-registered blind through `watchPayment`.
-
-### `gateway.createPayment(params)`
-
-```ts
-const payment = await gateway.createPayment({
-  lnAddresses: ["alice@coinos.io", "alice@getalby.com"],
-  amountMsat: 21_000,
-  webhookUrl: "https://myapp.example/hooks/paid",
-  webhookSecret: process.env.WEBHOOK_SECRET,
-});
-```
-
-| Field | Type | Meaning |
-|---|---|---|
-| `lnAddresses` | `string[]` | priority list, tried strictly in order, the first one that can issue a provable invoice wins |
-| `amountMsat` | `number` | amount in millisatoshi |
-| `webhookUrl` | `string?` | POSTed once the payment is paid, must be a public https URL |
-| `webhookSecret` | `string?` | HMAC-SHA256 key for the `x-signature` header |
-
-Resolves to a `Payment`, having run `proveOrigin(payment, params)` against it
-first unless `verify` is off. The object you pass is the object the proof is run
-against, so keep it if you intend to prove anything later. Throws
-`NoWalletAvailableError` when no address on the list could serve one,
-`GatewayCheatError` when the invoice returned is not the recipient's,
-`UnverifiedRecipientError` when the recipient's server could not be reached to
-find out, and `ProblemError` for everything else the gateway answered, including
-a 2xx whose body is not a JSON object.
-
-A second argument makes the call safe to retry:
-
-```ts
-const payment = await gateway.createPayment(params, { idempotencyKey: orderId });
-```
-
-The key is claimed before any wallet is contacted, so the retry a client fires
-when its own timeout expires does not mint a second invoice. Repeating a finished
-request replays its payment, repeating one that is still resolving throws
-`IdempotencyConflictError` with `conflict: "request-in-flight"`, and sending the
-same key for different addresses, a different amount or a different webhook
-throws it with `conflict: "key-reused"`. Keys are held for 24 hours, which is
-shorter than a payment lives, so a replay naming a payment the gateway has since
-pruned throws a plain `ProblemError` with status 410 rather than minting again.
-The replayed payment is verified exactly as a fresh one is.
-
-### `gateway.createQuote(params)`
-
-```ts
-const quote = await gateway.createQuote({
-  lnAddresses: ["alice@coinos.io", "alice@getalby.com"],
-  amountMsat: 21_000,
-});
-```
-
-Asks which address would serve an amount without minting anything. It fetches
-each address's LNURL-pay endpoint in order and returns the first that answers and
-accepts the amount, never calling the callback, so nothing is charged to the
-recipient's wallet and no invoice exists afterwards.
-
-Resolves to a `Quote`. `feeMsat` is always zero: the payer pays the recipient's
-own invoice and the gateway is never in the money's path, so it has nothing to
-charge for. `refusals` lists the addresses ahead of the winner and why each was
-passed over. Throws `NoWalletAvailableError` when none would take the amount.
-
-A quote is a probe, not a promise. Whether a wallet returns a *provable* invoice
-cannot be known without asking it for one, and asking mints it, so the LUD-21 and
-description-hash checks only run at create time. An address that quotes cleanly
-can still be refused by `createPayment`.
-
-`metadata` is the LUD-06 metadata string that wallet serves, verbatim. You need
-it if you put your own LNURL-pay endpoint in front of the address, which is what
-`lnurlPayEndpoint` does for you.
-
-### `gateway.followTrigger(secret, options)`
-
-```ts
-const stop = gateway.followTrigger(process.env.WATCH_SECRET, {
-  onPayment: (payment) => overlay.show(payment.amountMsat),
-});
-```
-
-Follows every payment made to one trigger rather than one payment. On connect the
-gateway replays the trigger's recent settlements, then streams each new one. It
-reconnects on its own until you call the returned function, because a trigger has
-no terminal state to stop at. A `paid` event whose preimage does not hash to its
-payment hash goes to `onError` and is never handed to `onPayment`.
-
-Events are `TriggerEvent`, not `Payment`. `lnAddress` and `amountMsat` are `null`
-when the payment was registered with `watchPayment`, because the gateway was
-never told them. What the watcher needs in that case arrives in `sealed`.
-
-### `gateway.watchPayment(params)`
-
-```ts
-await gateway.watchPayment({
-  paymentHash: resolved.paymentHash,
-  verifyUrl: resolved.verifyUrl,
-  expiresAt: resolved.expiresAt,
-  trigger: process.env.WATCH_SECRET,
-  sealed: await encrypt({ amountMsat }),
-});
-```
-
-Hands over an invoice you obtained yourself. The gateway polls its `verify_url`
-and checks preimages against `paymentHash` exactly as it does for one it minted,
-but it is given no address and no amount.
-
-That difference is the point. Creating a payment tells the gateway who is being
-paid and how much, and a gateway that knows can refuse one recipient rather than
-all of them. Told only a hash and a URL, the only refusal left to it is refusing
-everyone, which is visible and is what makes leaving cheap.
-
-Be exact about what is hidden and what is not. The verify URL still carries the
-recipient's **domain**, so the gateway knows the provider, just not which account
-there and not the amount. `sealed` is stored and handed back untouched, so
-anything the watcher needs but the gateway should not know goes there.
-
-### `seal(secret, plaintext)` and `unseal(secret, sealed)`
-
-```ts
-const sealed = await seal(process.env.SEALING_SECRET, JSON.stringify({ amountMsat }));
-const back = await unseal(process.env.SEALING_SECRET, sealed);
-```
-
-AES-GCM through WebCrypto, so no dependency and it runs wherever the rest does.
-`unseal` returns `null` for a blob sealed with another secret, edited on the way,
-or simply not one of ours. It throws only when your own secret is unusable,
-because that is your bug rather than someone else's input.
-
-The secret needs **32 characters of randomness, not a passphrase**, and a shorter
-one is refused rather than quietly making a weak key. Every watcher of one
-trigger holds the same secret: there is no rotation and no per-watcher key.
-
-Plaintext is capped at 3000 bytes, which is what fits the wire's 4096 once
-encrypted and encoded, so an oversized payload fails here with a readable message
-instead of as a 400 from the gateway.
-
-Do not hand-roll this. A `sealed` value the gateway can read is a fact you told
-it, and blind mode exists to not tell it.
-
-Nothing is verified on your behalf here, because there is nothing to verify
-against. You resolved the address, so running `proveOrigin` was yours to do.
-
-A hash already watched throws `ProblemError` with status 409 and
-`type === PAYMENT_ALREADY_WATCHED`. That is a disclosure control, not
-bookkeeping: the payment id is an HMAC of the payment hash and that id is the
-read capability, so handing back the stored record would turn a value every payer
-holds into a key. Repeating your own registration byte for byte still succeeds,
-so a retry after a timeout is fine. `lnurlPayEndpoint` under `blind: true`
-already treats it as success, because either way the invoice is being watched.
-
-Pass `tickets: true` and the client mints a short-lived ticket per connection and
-puts that in the socket URL instead of the secret. A socket URL gets logged, by
-the gateway, by proxies and by the browser, and a POST body does not, so this is
-how you keep the secret out of logs. It costs one request before each connect. A
-`token` turns it on by itself, because there the ticket is the only way in.
-
-Leave it off for a microcontroller. One hardcoded `wss://` URL and a dumb
-reconnect loop is the right shape for an ESP32, where a POST and a JSON parse
-before every reconnect is more to go wrong rather than less, and against a
-private gateway it can send the bearer as a header the way a browser cannot.
-Turn it on for a browser overlay and for anything where the logs matter.
-
-This is the piece a long-lived consumer needs: an OBS overlay, a microcontroller,
-a game server. Note it needs a process that stays alive, so it is the one part of
-this package that does not fit a serverless function. The serverless answer is
-`parseWebhookRequest`.
-
-### `lnurlPayEndpoint(config)`
-
-```ts
-export default {
-  fetch: lnurlPayEndpoint({
-    gateway: new ThunderBridge("https://gateway.example.net"),
-    lnAddresses: ["alice@coinos.io", "alice@getalby.com"],
-    amountMsat: () => 21_000,
-    secret: process.env.CALLBACK_SECRET,
-    watchSecret: process.env.WATCH_SECRET,
-  }),
-};
-```
-
-A whole LNURL-pay endpoint as one Fetch handler, so a static QR can point at your
-own domain instead of at a gateway. It runs anywhere `Request` and `Response` do:
-Deno Deploy, Cloudflare Workers, Hono, Next, Node. It holds no state, so there is
-nothing to provision.
-
-`amountMsat` is a plain function called once per payRequest, which is where a
-fiat peg or a time-of-day rule goes. The price is published as
-`minSendable === maxSendable`, so the payer's wallet has no amount to choose.
-
-Both halves of the flow live on one path: a bare request is the payRequest, a
-signed one is the callback. `secret` signs the callback URL, and without it
-anyone could call your callback and have it mint invoices on wallets of their
-choosing. `watchSecret` groups the payments so `followTrigger` can watch them,
-and only its sha256 ever reaches the gateway.
-
-**Why the recipient is pinned at payRequest.** LUD-06 makes the payer's wallet
-check the invoice's description hash against the sha256 of the metadata it was
-served. The invoice is minted by the recipient's own wallet, so that metadata has
-to be the recipient's. If the address list were walked again at callback time and
-a different address won, the hashes would differ and the wallet would refuse the
-payment. So the winner is quoted at payRequest and pinned into the callback URL.
-
-The cost of that is real and worth knowing: once pinned, a recipient that goes
-down before the callback fails that payment, with no fallback behind it.
-
-Pass `blind: true` and the endpoint resolves the address itself and registers the
-result with `watchPayment` instead of asking the gateway to mint. The gateway
-then never learns the address or the amount. It costs one more round trip and
-gives up the gateway's CORS proxying, which a server does not need.
-
-```ts
-sealed: {
-  secret: process.env.SEALING_SECRET,
-  data: (minted) => ({ amountMsat: minted.amountMsat }),
-},
-```
-
-`data` says what the watcher needs and `secret` encrypts it, so there is no way
-to hand the gateway something it can read. If you want your own crypto instead,
-skip this handler and call `gateway.watchPayment({ ..., sealed })` directly,
-where `sealed` is still just a string.
-
-For the same reason the description shown in the payer's wallet is always the
-recipient's, never yours. Only the amount is yours to set.
-
-### `gateway.getPayment(id)`
-
-```ts
-const payment = await gateway.getPayment(id);
-if (payment === null) return;
-```
-
-Reads a payment back. `null` when the gateway has never heard of that id, rather
-than a throw. A `paid` payment that fails `isProvablyPaid` throws
-`GatewayCheatError` with code `preimage_mismatch`. That is a consistency check on
-the gateway's own report and not a proof of payment. The origin proof is not
-re-run here, since it was run when the payment was created, so a payment this
-process did not create has been proven against nothing at all.
-
-### `gateway.waitForPayment(id, options?)`
-
-```ts
-const settled = await gateway.waitForPayment(id, {
-  signal: AbortSignal.timeout(600_000),
-});
-```
-
-Opens a WebSocket and resolves with the payment the first time its status leaves
-`pending`, so the result is always `paid` or `expired`. Same `isProvablyPaid`
-check as `getPayment`, and the same limit: the frame that arrives is the
-gateway's account of the payment, checked only against itself.
-
-A dropped connection is not the end of the wait. The gateway sends the current
-state on connect, so a settlement during an outage arrives as the first frame of
-the next attempt and nothing is missed. What ends the wait by itself is the
-payment: once a frame has arrived its `expires_at` is known, and reconnecting
-stops there. Before any frame has arrived there is nothing to bound it, so a few
-tries decide it, which is also what keeps a wrong id from becoming a loop. Waits
-grow from 3 seconds and are jittered, and a gateway that answers the ticket mint
-with a refusal is final rather than retried.
-
-Rejects if the signal aborts, if a frame is not JSON, if a `paid` frame does not
-hold together, if nothing ever answered, or if the payment passed its expiry
-unreported. There is no default timeout, pass a signal if you want one.
-
-It follows a payment this gateway minted. One registered blind through
-`watchPayment` has no address, amount or invoice, so it does not fit the
-`Payment` shape this reads, and `followTrigger` is what watches those.
-
-### `proveOrigin(payment, request)`
-
-```ts
-import { proveOrigin } from "thunder-bridge";
-
-await proveOrigin(payment, request);
-```
-
-The whole trust argument of this package, spelled out under
-[The verification chain](#the-verification-chain). The second argument is the
-same `CreatePaymentParams` you handed to `createPayment`, never the gateway's
-echo of it, so on every comparison at least one side is a value the gateway did
-not choose. Resolves when every check passed, throws `GatewayCheatError` on the
-first one that failed and `UnverifiedRecipientError` when a check could not be
-run at all. Call it directly when you built the payment some other way, for
-example from a webhook body or from your own `fetch` against the gateway.
-
-### `proveSettlement(payment, request)`
-
-```ts
-import { proveSettlement } from "thunder-bridge";
-
-const preimage = await proveSettlement(payment, request);
-if (preimage !== null) {
-  fulfil(payment.id);
-}
-```
-
-The only call here that is evidence the money arrived. It runs the full origin
-proof first, because a `verifyUrl` the gateway made up would otherwise be
-answering for itself, and then reads `settled` and `preimage` from that url,
-which check 4 has just pinned to the recipient's own callback origin.
-
-Returns the preimage when the recipient's server reports the invoice settled and
-releases one. Returns `null` when the server answers without reporting a settled
-invoice and a preimage, which is the ordinary answer for an invoice nobody has
-paid yet, so it is safe to call on a timer. Throws
-`GatewayCheatError("preimage_mismatch")` when the released preimage does not
-hash to the payment hash, and anything `proveOrigin` throws, since it runs
-`proveOrigin` first. Three fetches per call, all of them at the recipient's
-domain, and nothing is cached between calls.
-
-### `isProvablyPaid(payment)`
-
-```ts
-if (!isProvablyPaid(webhookPayment)) {
-  report(`payment ${webhookPayment.id} does not even agree with itself`);
-}
-```
-
-A sanity check, not a proof, and the name is older than the distinction. True
-when the payment says `paid`, carries a preimage, its `bolt11` carries the
-payment hash the record claims, and that preimage hashes to it. Synchronous, no
-network, and every value it compares came out of the same gateway message. A
-gateway willing to invent a preimage, hash it, and mint an invoice around that
-hash passes.
-
-It is worth running: it rejects a status flipped to `paid` without a preimage
-that fits, a truncated preimage, and a record whose `bolt11` was swapped for
-another. It is not worth acting on. Decide to ship goods on `proveSettlement`,
-which asks the recipient rather than the gateway. This is what the client runs
-for you on `getPayment` and `waitForPayment`, and it is the limit of what those
-two can promise.
-
-### `preimageMatchesHash(preimage, paymentHash)`
-
-```ts
-preimageMatchesHash(settled.preimage ?? "", settled.paymentHash);
-```
-
-True when `preimage` is the secret behind `paymentHash`. Non-hex or odd-length
-input is false rather than a throw. Both arguments are compared
-case-insensitively.
-
-### `decodeInvoice(bolt11)`
-
-```ts
-const invoice = decodeInvoice(payment.bolt11);
-```
-
-Returns `{ paymentHash, descriptionHash, amountMsat }`, every field `string | null`
-except `amountMsat` which is `number | null`. Hand-rolled bech32, no library, no
-signature recovery. Anything it cannot read, including a BOLT12 offer, comes back
-with all three fields null rather than throwing, so check for null before
-comparing.
-
-### `invoiceToSvg(destination, options?)`
-
-```ts
-const svg = invoiceToSvg(payment.bolt11, { size: 320, color: "#1a1a2e" });
-const jar = invoiceToSvg("iamfatik@blink.sv");
-```
-
-An SVG string, no canvas and no DOM required. `size` defaults to 256 and `color`
-to `#000`. An invoice is encoded as `LIGHTNING:` plus the uppercased invoice,
-which is what wallets expect and what lets the QR use alphanumeric mode. A
-lightning address keeps the case it was given, because the part before the
-at-sign is case sensitive and the at-sign is outside the alphanumeric set
-anyway, so uppercasing one would only risk breaking it. A
-`color` that is not a hex literal, an `rgb()` or `rgba()` value, or a bare colour
-name throws, because it would otherwise be written straight into the markup.
-Each alternative in that pattern is anchored at both ends, so a value that is a
-legal colour followed by more markup, such as `rgba(0)" onload="alert(1)`, is
-refused rather than allowed to close the `fill` attribute early.
-
-### `invoiceToDataUrl(destination, options?)`
-
-```ts
-const src = invoiceToDataUrl(payment.bolt11);
-```
-
-The same SVG, percent-encoded as a `data:image/svg+xml,` URL for an `<img>` tag.
-
-### `lnurlToSvg(endpoint, options?)` and `lnurlToDataUrl(endpoint, options?)`
-
-```ts
-const svg = lnurlToSvg("https://agora.gripe/tip", { size: 320 });
-```
+| Export | What it does |
+|---|---|
+| `new ThunderBridge(baseUrl, options?)` | a gateway handle. `{ verify: false }` turns off the automatic proof, `{ token }` makes the instance yours |
+| `gateway.createPayment(params, options?)` | mint an invoice on the first address that can prove one, and prove it before returning |
+| `gateway.createQuote(params)` | ask which address would take an amount without minting anything |
+| `gateway.getPayment(id)` | read a payment back, `null` when the gateway never heard of it |
+| `gateway.getWatched(id)` | the same for one the gateway only watches, which carries no address, amount or invoice |
+| `gateway.listPayments(limit?)` | what this gateway is watching, newest first. Needs a token |
+| `gateway.waitForPayment(id, options?)` | follow one payment over WebSocket until it is paid or expired |
+| `gateway.waitForWatched(id, options?)` | the same for a watched one, answering the shape both rails share |
+| `gateway.firstToSettle(ids, options?)` | wait on several legs, keep the first really paid, drop the losers |
+| `gateway.watchPayment(params)` | hand over an invoice you obtained yourself, without the address or the amount |
+| `gateway.followTrigger(secret, options)` | stream every payment carrying one trigger, reconnecting on its own |
+| `gateway.isPrivate` | whether a token was given |
+
+**Proving it** - [`src/verify.ts`](src/verify.ts)
+
+| Export | What it does |
+|---|---|
+| `proveOrigin(payment, request)` | the five checks below, against the recipient's own server |
+| `proveSettlement(payment, request)` | ask the recipient whether it settled, returns the preimage or `null` |
+| `isProvablyPaid(payment)` | whether the gateway's own report is self-consistent. A sanity check, not a proof |
+| `preimageMatchesHash(preimage, hash)` | one sha256 comparison |
+| `decodeInvoice(bolt11)` | the invoice's own amount, payment hash and description hash |
 
-The QR for a trigger, meaning the URL you mounted `lnurlPayEndpoint` on. It
-carries no invoice and nothing in it expires, so this is the code a tip jar
-prints once and an overlay leaves on screen all stream. The endpoint is bech32
-encoded as the `LNURL1` string LUD-01 defines and uppercased, which is the form
-that spec asks a QR to carry and the one every LNURL wallet has read for years.
-An input that is not an http or https URL throws rather than becoming a QR
-nobody can pay.
+**Serving your own endpoint** - [`src/trigger.ts`](src/trigger.ts), [`src/bank.ts`](src/bank.ts), [`src/fio.ts`](src/fio.ts)
 
-`toLnurl(endpoint)` is the same encoding on its own, for a `lightning:` link or a
-page that renders its own codes.
+| Export | What it does |
+|---|---|
+| `lnurlPayEndpoint(config)` | a whole LNURL-pay endpoint as one Fetch handler, so a static QR points at your domain |
+| `bankTransfer(params)` | register a Czech QR platba as a watched payment. Refuses a gateway with no token |
+| `bankVerifyEndpoint(config)` | the other half, the LUD-21 shape backed by your own statement |
+| `fioStatement(config)` | a `Statement` reading a Fio account, several tokens used strictly in turn |
+| `seal(secret, plaintext)`, `unseal` | the blob the gateway stores and cannot read |
+| `toLnurl(url)` | bech32-encode an endpoint url |
 
-LUD-17 would let you write `lnurlp://agora.gripe/tip` instead, and its own text
-calls bech32 a mistake, but wallet support for it is recent enough that the
-bech32 form is still what scans everywhere. If your trigger sits at
-`/.well-known/lnurlp/<name>` then it is also a lightning address, and
-`invoiceToSvg("<name>@yourdomain")` gives a QR people can read and type.
+`Statement` is a plain `(sinceUnix) => Promise<Credit[]>`, so another bank is
+another function of that shape and persistence wraps it from outside rather than
+living inside it. Nothing above it changes, and the package stays ignorant of
+whatever runtime you keep state in.
 
-### `parseWebhookRequest(request, secret)`
+**Pricing a fiat order** - [`src/price.ts`](src/price.ts), [`src/currency.ts`](src/currency.ts)
 
-```ts
-const payment = await parseWebhookRequest(request, secret);
-```
+| Export | What it does |
+|---|---|
+| `medianOf(tickers?, options?)` | ask several venues, take the middle, refuse the lot when they disagree too much |
+| `coinbase`, `kraken`, `bitstamp`, `coinmate` | the four MiCA authorised venues, every one replaceable |
+| `msatFor(amountMinor, priceMinorPerBtc, options?)` | exact BigInt arithmetic from fiat to millisatoshi |
+| `minorUnitsOf(currency)`, `minorScaleOf` | what ISO 4217 says the currency's minor unit is |
 
-Takes a Fetch API `Request`, reads the `x-signature` header, verifies it against
-the raw body and parses. `null` on a missing signature, on a bad signature, and
-on a correctly signed body that is not JSON, so `null` always means do not trust
-this and never means this was fine but empty. Use it in Hono, Next, SvelteKit,
-Cloudflare Workers, Deno and Bun.
+**QR codes** - [`src/qr.ts`](src/qr.ts)
 
-### `parseWebhook(body, signature, secret)`
+Every renderer returns a string, so they work on a server, in a worker and in a
+browser with no canvas involved. `invoiceToSvg` takes an invoice or a lightning
+address, `lnurlToSvg` takes your own endpoint url, `spdToSvg` takes the `spd` from
+`bankTransfer`. Each has a `…ToDataUrl` twin for an `<img>` `src`. A BOLT12 offer
+is not handled, because this gateway never returns one.
 
 ```ts
-const payment = await parseWebhook(rawBody, signature, secret);
-```
+import { invoiceToSvg, lnurlToSvg } from "thunder-bridge";
 
-The same thing for frameworks that hand you a raw body and headers separately,
-with the same three ways of returning `null`. `body` is a `string` or a
-`Uint8Array`, and it must be the bytes as received. Parsed and re-serialised JSON
-will not verify.
-
-### `verifyWebhookSignature(body, signature, secret)`
-
-```ts
-if (!(await verifyWebhookSignature(rawBody, signature, secret))) return;
+const toPay = invoiceToSvg(payment.bolt11, { size: 320, color: "#1a1a2e" });
+const tipJar = lnurlToSvg("https://agora.gripe/tip");
 ```
 
-The signature check on its own, for when you want to parse the body yourself.
-The `sha256=` prefix is optional and the comparison is constant time.
+**Webhooks** - [`src/webhook.ts`](src/webhook.ts): `parseWebhookRequest`,
+`parseWebhook`, `verifyWebhookSignature`. See [Webhooks](#webhooks).
 
-### Errors
+**Errors** - [`src/errors.ts`](src/errors.ts): `ProblemError`,
+`NoWalletAvailableError`, `GatewayCheatError`, `UnverifiedRecipientError`,
+`IdempotencyConflictError`, `isProblemType`. See [Errors](#errors).
 
-`GatewayCheatError` carries `code: GatewayCheatCode` and `paymentId`.
-`UnverifiedRecipientError` carries `lnAddress` and `paymentId`. `ProblemError`
-carries `type`, `title`, `status` and `detail`, and `status` is always the HTTP
-status of the response: a problem document naming a different one does not
-override it. `NoWalletAvailableError` extends `ProblemError` and adds
-`wallets: WalletFailure[]`, always an array and empty when the gateway sent
-something that is not one, so test for it before you test for `ProblemError`.
-`IdempotencyConflictError` also extends `ProblemError` and adds
-`conflict: IdempotencyConflict`, so test for it first too.
+## The proof
 
-### Types
-
-`Payment`, `PaymentStatus`, `CreatePaymentParams`, `Quote`, `CreateQuoteParams`,
-`WalletFailure`, `WalletReason`, `GatewayCheatCode`, `IdempotencyConflict`,
-`Invoice`, `QrOptions`, `ThunderBridgeOptions`, `CreateOptions`, `FollowOptions`,
-`TriggerConfig`, `TriggerEvent`, `WatchPaymentParams`, `Minted` and `WaitOptions`
-are all exported as types.
-
-```ts
-interface Payment {
-  id: string;
-  lnAddress: string;
-  amountMsat: number;
-  status: "pending" | "paid" | "expired";
-  paymentHash: string;
-  bolt11: string;
-  preimage: string | null;
-  expiresAt: number;
-  createdAt: number;
-  verifyUrl: string;
-}
-```
+`proveOrigin(payment, request)` runs five checks in order and stops at the first
+failure. The first two need no network. The rest go to the recipient's own domain,
+never back to the gateway, which is the point: a gateway cannot witness its own
+honesty.
 
-`lnAddress` is the one address out of your list that actually served the
-invoice. `expiresAt` and `createdAt` are unix seconds. `preimage` is non-null
-only once the status is `paid`.
+| # | Check | Rules out | Fails with |
+|---|---|---|---|
+| 1 | the chosen address is one you listed, compared case-insensitively | the gateway paying an address you never named, its own included | `address_not_requested` |
+| 2 | the invoice decodes to the amount you asked for and the payment hash the record reports | being billed more than you asked, or a record describing one invoice while carrying another | `amount_mismatch`, `hash_mismatch` |
+| 3 | the invoice's description hash equals the sha256 of the `metadata` that address serves, under LUD-06 | an invoice minted by a different account on the same custodial domain | `description_hash_mismatch` |
+| 4 | `verifyUrl` shares an origin with the `callback` that endpoint publishes | a settlement proof pointed anywhere the gateway controls | `verify_url_foreign` |
+| 5 | a GET to `verifyUrl` echoes `pr`, and it equals `bolt11` byte for byte | everything the earlier checks could still miss, because the answer now comes from the recipient | `invoice_not_issued` |
 
-```ts
-interface Quote {
-  lnAddress: string;
-  amountMsat: number;
-  feeMsat: number;
-  minMsat: number;
-  maxMsat: number;
-  metadata: string;
-  refusals: WalletFailure[];
-}
-```
+Check 1 also builds the url the rest of the chain uses: your `user@domain` becomes
+`https://domain/.well-known/lnurlp/user` under LUD-16, with the domain lowercased
+and the local part left exactly as you wrote it. The gateway's spelling is used to
+find the match and never to build the url, so it cannot aim the proof at a
+different account on a provider that treats the local part as case-sensitive.
 
-`minMsat` and `maxMsat` are the range that wallet accepts, so a quote also tells
-you what else you could have asked it for.
+### Origin is not settlement
 
-## The verification chain
+Those five checks are about an invoice. They prove that what you are putting in
+front of a payer is the recipient's own invoice for the right amount. They say
+nothing about whether anybody paid it, and the two answers to that are not the
+same answer.
 
-`proveOrigin(payment, request)` runs five checks in order and stops at the first
-failure. The first two need no network at all. The rest go to the recipient's own
-domain, never back to the gateway, which is the point: a gateway cannot be the
-witness to its own honesty. `request` is your own `CreatePaymentParams`, so
-every comparison below has your value on one side of it.
-
-**1. The chosen address is one you listed.** `payment.lnAddress` must appear in
-`request.lnAddresses`, compared case-insensitively. Rules out the gateway paying
-an address you never named, its own included. The entry that matched is then the
-one the rest of the chain is run against: your `user@domain` becomes
-`https://domain/.well-known/lnurlp/user` under LUD-16, with the domain lowercased
-because host names are case-insensitive and the local part left exactly as you
-wrote it. The gateway's spelling of the address is used to find the match and
-never to build the url, so a gateway cannot aim the proof at a different account
-on a provider that treats the local part as case-sensitive. Fails with
-`address_not_requested`. No network.
-
-**2. The invoice is for the amount you asked, and it is the invoice the record
-describes.** Three local comparisons in order. `payment.amountMsat` must equal
-`request.amountMsat`, so the gateway's own summary matches your order. The BOLT11
-is then decoded in-package, and its payment hash must equal
-`payment.paymentHash`. Its amount must equal `request.amountMsat`, your figure
-again and not the gateway's. The hash check rules out a record that describes one
-invoice while the `bolt11` field carries another, which would otherwise let a
-later preimage check pass against a hash nobody paid. The amount checks rule out
-being billed more than you asked for by a payment that is perfectly consistent
-with itself, being shown a receipt for one figure and a QR code for another, and
-an amountless invoice that a payer's wallet would let them fill in themselves.
-Fails with `amount_mismatch` or `hash_mismatch`. No network.
-
-**3. The invoice's description hash pins it to that user.** The well-known url
-built in check 1 is fetched, and the sha256 of the `metadata` it serves must
-equal the invoice's description hash under LUD-06. Rules out an invoice minted by
-a different account on the same custodial domain, which is the substitution a
-node id alone cannot see: on a shared custodian every account sits behind one
-node. Fails with `description_hash_mismatch`, or with
-`UnverifiedRecipientError` when the endpoint served no usable payRequest.
-
-**4. The proof url belongs to the recipient.** `payment.verifyUrl` must share an
-origin with the `callback` that same endpoint publishes. Rules out a settlement
-proof pointed at the gateway or anywhere else it controls, which would let it
-sign off on its own payments. Fails with `verify_url_foreign`.
-
-**5. The recipient's own server says it issued this invoice.** A GET to
-`verifyUrl` under LUD-21 echoes `pr`, and it must equal `payment.bolt11` byte for
-byte, case aside. Rules out everything the earlier checks could still miss,
-because the answer now comes from the recipient's server rather than from the
-gateway. Fails with `invoice_not_issued`.
-
-### Proving the money arrived
-
-Those five checks are about an invoice, not about a payment. They prove that what
-you are putting in front of a payer is the recipient's own invoice for the right
-amount. They say nothing about whether anybody paid it, and the two answers to
-that question are not the same answer.
-
-`isProvablyPaid`, which the client runs for you on `getPayment` and
-`waitForPayment`, asks whether the gateway's report contradicts itself: a `paid`
+`isProvablyPaid` asks whether the gateway's report contradicts itself: a `paid`
 status, a preimage, and a `bolt11` whose payment hash that preimage opens. All
-three values arrive from the gateway in one message, so the check is internal
-consistency and nothing more. A gateway that generates a preimage, hashes it, and
+three values arrive from the gateway in one message, so this is internal
+consistency and nothing more. A gateway that generates a preimage, hashes it and
 builds an invoice around that hash passes it. It catches breakage and
 carelessness, not an operator who means it.
 
 `proveSettlement` asks the recipient. It re-runs the origin proof, which is what
-ties `verifyUrl` to the recipient's own callback origin instead of to somewhere
-the gateway picked, then reads that url. Under LUD-21 the recipient's server
-releases the preimage once the invoice has actually been claimed, so a preimage
-from there was released by the party that got paid, and it is checked against the
-payment hash before you see it. `null` means the recipient's own server is not
-claiming the money arrived, whatever the gateway says.
+ties `verifyUrl` to the recipient's own callback origin, then reads that url.
+`null` means the recipient's own server is not claiming the money arrived,
+whatever the gateway says.
 
 Use `isProvablyPaid` to throw out a record that is obviously wrong. Use
 `proveSettlement` before you part with anything.
@@ -698,132 +195,79 @@ Use `isProvablyPaid` to throw out a record that is obviously wrong. Use
 
 Every outbound url in the chain must be public https. The guard refuses loopback,
 link-local, the RFC 1918 ranges, carrier-grade NAT, unique local addresses, and
-IPv4-mapped IPv6 that unwraps into any of those IPv4 ranges. It also refuses a
-host with no dot in it such as `nas`, the
-trailing-dot form `localhost.`, and anything whose last label is `local`,
-`internal`, `lan`, `arpa`, `test` or `invalid`. A lightning address pointing at
-your own network is never fetched, and neither is a `verifyUrl` on a private host
-that the recipient's own callback vouches for.
+IPv4-mapped IPv6 unwrapping into any of those. It also refuses a host with no dot
+such as `nas`, the trailing-dot `localhost.`, and anything whose last label is
+`local`, `internal`, `lan`, `arpa`, `test` or `invalid`.
 
-It vets the first hop only. See [What is still trusted](#what-is-still-trusted).
+It vets the first hop only. See below.
 
 ## What is still trusted
 
-Short, and worth saying out loud rather than burying.
-
-**The gateway chooses which of your addresses gets paid.** It is supposed to
-take the first that works, and nothing here can tell a genuine failure of the
-first from a preference for the third. What it cannot do is pick an address that
-is not on the list, so the money still lands somewhere you named.
-
-**The gateway can refuse you.** Availability is not provable. It can answer 503,
-answer nothing, or serve one caller and not another. Every check in this package
-is about an invoice you were given, none is about an invoice you were not.
-
-**The gateway sees your request.** The address list, the amount, the webhook url
-and the webhook secret all pass through it, because it has to make the calls.
-Treat the secret as shared with the gateway, and treat the address list as
-public. Nothing here is a privacy layer, and the payer sees the recipient's real
-invoice and node either way.
-
-**Everything the gateway says about a settlement, until you ask the recipient.**
-The status, the preimage and the body a webhook delivers are the gateway's own
-account. `isProvablyPaid` only asks whether that account holds together, and a
-gateway that fabricates the whole record passes it. `proveSettlement` is the one
-call that goes and asks somebody else. If a payment matters, ask.
-
-**The host guard vets the first hop and no further.** Both fetches use the
-runtime's default redirect handling, so a public https host that answers a
-request with a 302 to a private address is followed there. The guard runs on the
-url the package is about to request, not on where that request ends up. If a
-request into your own network would matter, keep the egress control outside this
-package: a proxy, a network policy, or a `fetch` of your own that refuses
-redirects.
-
-**A colluding custodian defeats all of it.** The proof is the recipient's
-server's word, made cryptographic. If the recipient's wallet provider and the
-gateway are the same party, or are cooperating, then the party holding the money
-is also the party serving the metadata, publishing the callback and answering the
-verify requests. Every check would pass, `proveSettlement` included, and nothing
-here would help. This protects a payer against the gateway, not against the
-recipient's own custodian.
-
-**TLS and DNS for the recipient's domain.** The whole chain hangs off reaching
-the real `domain`, so whoever can forge a certificate for it can forge the proof.
-
-**An address is not a person.** This proves an invoice belongs to an address. It
-never proves the address belongs to whoever you think. Vouching for the address
-stays with whoever published it.
-
-**A payment read cold is only as pinned as its creation.** `getPayment` and
-`waitForPayment` check the preimage against the `paymentHash` in the same record.
-It is `proveOrigin` at creation, against the request you wrote, that tied that
-hash to an invoice the recipient issued. If you fetch a payment id you never
-created and never proved, you are checking the gateway's numbers against each
-other and nothing more. Run `proveOrigin` with the request that created it, or
-`proveSettlement` if you also need to know it was paid, which means storing the
-request alongside the payment id.
+- **The gateway chooses which of your addresses gets paid.** Nothing here can
+  tell a genuine failure of the first from a preference for the third. What it
+  cannot do is pick an address off your list.
+- **The gateway can refuse you.** Availability is not provable. Every check here
+  is about an invoice you were given, none about one you were not.
+- **The gateway sees your request.** The address list, the amount and the webhook
+  secret pass through it, because it has to make the calls. Treat the secret as
+  shared with it and the address list as public.
+- **Everything it says about a settlement, until you ask the recipient.**
+  `isProvablyPaid` only asks whether that account holds together. If a payment
+  matters, ask.
+- **The host guard vets the first hop and no further.** Both fetches use the
+  runtime's default redirect handling, so a public https host answering with a 302
+  to a private address is followed there. Keep egress control outside this
+  package if that matters.
+- **A colluding custodian defeats all of it.** If the recipient's wallet provider
+  and the gateway are the same party, then the party holding the money is also the
+  one serving the metadata and answering the verify requests. Every check would
+  pass. This protects a payer against the gateway, not against the recipient's own
+  custodian.
+- **TLS and DNS for the recipient's domain**, and an address is not a person. This
+  proves an invoice belongs to an address, never that the address belongs to
+  whoever you think.
+- **A payment read cold is only as pinned as its creation.** `getPayment` checks
+  the preimage against the `paymentHash` in the same record. It was `proveOrigin`
+  at creation, against the request you wrote, that tied that hash to an invoice
+  the recipient issued. So store the request alongside the payment id, or you are
+  checking the gateway's numbers against each other and nothing more.
 
 ## Errors
 
-Every failure from the gateway is an RFC 9457 problem document served as
-`application/problem+json`. Branch on `type`, never on prose. One type maps to
-its own class, the rest arrive as `ProblemError` with `type` intact.
-
-| `type` | Status | Class | When |
-|---|---|---|---|
-| `urn:problem-type:thunder-bridge-direct:invalid-request` | 400 | `ProblemError` | the body or one of its fields could not be read, `detail` names the field |
-| `urn:problem-type:thunder-bridge-direct:no-wallet-available` | 400, 422, 502 | `NoWalletAvailableError` | the list was walked and nothing served, `wallets` says why each one failed |
-| `about:blank` | 404 | none | unknown payment, `getPayment` returns `null` instead of throwing |
-| `about:blank` | 503 | `ProblemError` | the instance is watching as many payments as it can |
-| `about:blank` | 500 | `ProblemError` | the gateway broke |
+Every failure from the gateway is an RFC 9457 problem document. Branch on `type`,
+never on prose. `error.status` is what the transport carried, and a document
+naming a different status in its own body does not override it.
 
-The `Status` column is what the transport carried, and it is what `error.status`
-reports. A document that names a different status in its own body does not get to
-override it.
+| `type` | Status | Class |
+|---|---|---|
+| `…:invalid-request` | 400 | `ProblemError`, `detail` names the field |
+| `…:no-wallet-available` | 400, 422, 502 | `NoWalletAvailableError`, `wallets` says why each failed |
+| `about:blank` | 404 | none, `getPayment` returns `null` |
+| `about:blank` | 503 | `ProblemError`, the instance is at capacity |
+| `about:blank` | 500 | `ProblemError` |
 
 The status on `no-wallet-available` follows the worst wallet, so a retry is never
-advised in vain: 502 if any wallet was merely unreachable, else 422 if any
-refused permanently, else 400.
-
-Each entry in `wallets` is a `WalletFailure` with an `address` and a `reason`,
-in the order the addresses were tried. The array is empty rather than absent when
-the gateway sends a `wallets` field that is not a list.
+advised in vain: 502 if any was merely unreachable, else 422 if any refused
+permanently, else 400. Each entry in `wallets` is a `WalletFailure` in the order
+the addresses were tried, and every reason is enumerated in
+[`openapi.yaml`](../openapi.yaml).
 
-| `reason` | What it means | Do |
-|---|---|---|
-| `address-unusable` | not a lightning address, or its domain is not a public https host | fix the address |
-| `unreachable` | no usable payRequest or invoice came back, which also covers an unknown user | retry, or check the wallet |
-| `amount-not-accepted` | the amount is outside that wallet's min and max | change the amount |
-| `cannot-prove-delivery` | no LUD-21 `verify` url, or a provider known never to release a preimage | use another provider |
-| `invoice-refused` | it answered with an invoice the gateway will not accept: wrong amount, unbound metadata, or undecodable | report it, use another wallet |
-
-`GatewayCheatError` is different in kind. It does not report a request that
-failed, it reports a gateway that demonstrably misbehaved, and `code` names the
-check that caught it.
+`GatewayCheatError` is different in kind. It reports a gateway that demonstrably
+misbehaved, and `code` names the check that caught it: the five in the table above
+plus `preimage_mismatch`, a reported `paid` whose preimage does not open the
+invoice.
 
-| `code` | The gateway did this |
-|---|---|
-| `address_not_requested` | returned an address that was not on the list you passed |
-| `hash_mismatch` | the `bolt11` does not carry the `paymentHash` it reports |
-| `amount_mismatch` | reported, or invoiced, an amount other than the `amountMsat` you asked for |
-| `description_hash_mismatch` | the invoice is not bound to that user's LNURL metadata |
-| `verify_url_foreign` | the `verifyUrl` is not on the recipient's callback origin |
-| `invoice_not_issued` | the recipient's own server does not echo this invoice |
-| `preimage_mismatch` | reported `paid` with a preimage that does not open the invoice, or the recipient released one that does not |
-
-`UnverifiedRecipientError` is deliberately not in that table. It means a check
-could not be run, because the recipient's server was down, timed out, answered
-with something unreadable, or the browser was blocked by CORS. It is not an
-accusation, and it is also not a clean bill of health. Decide what you want to
-do with an unproven invoice, and decide it explicitly.
+`UnverifiedRecipientError` is deliberately neither. It means a check could not be
+run, because the recipient's server was down, timed out, answered something
+unreadable, or the browser was blocked by CORS. Not an accusation, and not a clean
+bill of health either. Decide what you want to do with an unproven invoice, and
+decide it explicitly.
 
 ```ts
 import {
   GatewayCheatError,
   NoWalletAvailableError,
   ProblemError,
-  ThunderBridge,
   UnverifiedRecipientError,
 } from "thunder-bridge";
 
@@ -849,9 +293,10 @@ try {
 
 Pass `webhookUrl` and optionally `webhookSecret` when you create a payment. Once
 it reaches `paid` the gateway POSTs the same JSON the API returns, so the body is
-a `Payment`. With a secret set it carries `x-signature: sha256=<hmac>` over the
-raw body, HMAC-SHA256. Three attempts, five seconds apart, then it gives up. An
-invoice that expires fires nothing.
+a `Payment`. Every delivery carries `x-timestamp`, and with a secret set
+`x-signature: sha256=<hmac>` over `<timestamp>.<body>` rather than the body alone,
+so a captured delivery cannot be replayed at you later. Six attempts on a widening
+backoff, then it parks. An invoice that expires fires nothing.
 
 Delivery is at-least-once, so deduplicate on `id`.
 
@@ -870,77 +315,46 @@ app.post("/hooks/paid", async (context) => {
 });
 ```
 
-The signature proves the body came from someone holding your secret. It does not
-prove the payment happened, since the gateway holds that secret too. Neither does
-`isProvablyPaid`: the gateway wrote every field in that body, so all the check
-can say is that the body does not contradict itself. The proof is
-`proveSettlement`, and it needs the request you originally sent, which is why
-`requestFor` above is your own lookup from a payment id back to the
-`CreatePaymentParams` you stored when you created it.
+`parseWebhookRequest` refuses anything more than five minutes out of date,
+adjustable with `toleranceSecs`. The signature proves the body came from someone
+holding your secret. It does not prove the payment happened, since the gateway
+holds that secret too. The proof is `proveSettlement`, and it needs the request you
+originally sent, which is why `requestFor` above is your own lookup from a payment
+id back to the `CreatePaymentParams` you stored.
 
 For a framework that hands you the raw body and headers separately, use
-`parseWebhook`. The body must be the bytes as received, so mount a raw body
-parser on that route and not a JSON one. The settlement proof belongs here too,
-and is left out only to keep the raw body point visible.
+`parseWebhook`. The body must be the bytes as received, so mount a raw body parser
+on that route and not a JSON one.
 
 ```ts
 import express from "express";
 import { parseWebhook } from "thunder-bridge";
 
 app.post("/hooks/paid", express.raw({ type: "application/json" }), async (request, response) => {
-  const payment = await parseWebhook(request.body, request.get("x-signature") ?? "", secret);
-  if (payment === null) {
-    response.sendStatus(401);
-    return;
-  }
-  response.sendStatus(200);
+  const payment = await parseWebhook(
+    request.body,
+    request.get("x-signature") ?? "",
+    secret,
+    request.get("x-timestamp") ?? "",
+  );
+  response.sendStatus(payment === null ? 401 : 200);
 });
 ```
 
-## QR codes
-
-`invoiceToSvg` returns a string, so it works on a server, in a worker and in a
-browser with no canvas involved.
-
-```ts
-import { invoiceToDataUrl, invoiceToSvg } from "thunder-bridge";
-
-const markup = invoiceToSvg(payment.bolt11, { size: 320, color: "#1a1a2e" });
-const source = invoiceToDataUrl(payment.bolt11);
-```
-
-Both encode the invoice as `LIGHTNING:` followed by the uppercased BOLT11, per
-BIP 21 and the BOLT 11 QR section. Uppercase is not cosmetic, it lets the encoder
-use alphanumeric mode, which fits the same invoice into a visibly smaller and
-more scannable code.
-
-Only BOLT11 is handled. This gateway never returns a BOLT12 offer, and the
-`lightning:` scheme is BOLT11-specific anyway: wrapping an offer in it makes
-wallets that recognise the scheme parse the body as BOLT11 and reject it.
-
 ## Requirements
 
-Node 22 or newer. `waitForPayment` and `followTrigger` use the global
-`WebSocket`, which Node only exposes from 22 onwards, and there is no fallback
-and no optional dependency to install. Everything else in the package works on
-any runtime with `fetch` and `crypto.subtle`, so an older Node can still create
-payments, quote them, verify them, poll `getPayment`, serve `lnurlPayEndpoint`
-and handle webhooks.
-
-On a serverless runtime, treat the two sockets as unavailable whatever the
-platform supports: an invocation ends when it answers, and a payment can live for
-weeks. `lnurlPayEndpoint` is built for that world and holds no state, and
-`parseWebhookRequest` is how settlement reaches you there.
-
-TypeScript is bundled. The package ships ESM and CJS builds with types for both.
+Node 22 or newer. `waitForPayment` and `followTrigger` use the global `WebSocket`,
+which Node only exposes from 22 onwards, and there is no fallback and no optional
+dependency to install. Everything else works on any runtime with `fetch` and
+`crypto.subtle`, so an older Node can still create payments, quote them, verify
+them, poll `getPayment`, serve `lnurlPayEndpoint` and handle webhooks.
 
 ## Development
 
-`npm test` runs the vitest suite. `npm run typecheck` type-checks `src` against
-`tsconfig.json` and then `src` and `test` together against `tsconfig.test.json`,
-so a test file that stops compiling fails the same gate the library does.
-`npm run build` emits ESM, CJS and the two declaration flavours with tsup.
-
-## License
+```bash
+npm install
+npm test
+npm run build
+```
 
-MIT
+MIT.