thunder-bridge 1.5.0 → 2.2.0

package/README.md

@@ -34,7 +34,7 @@ so the same wallet on another domain can answer differently.
 A refusal happens at creation rather than leaving a payment pending until a
 watcher gives up, so a recipient finds out before a payer sees a QR code.
 
-If your recipient is on a refused name, `nwcRail` from `thunder-bridge/nwc` is the way round it: your own
+If your recipient is on a refused name, `gateway.rails.nwc` is the way round it: your own
 wallet answers over NIP-47 instead of over an address, and the gateway watches the
 hash exactly the same. [docs/lud21-coverage.md](../docs/lud21-coverage.md) is the
 measured list rather than a reading of changelogs, last surveyed 2026-08-12. Read
@@ -137,16 +137,16 @@ preimage, and which side does the checking.
 | the gateway is told | a hash, an expiry and your URL, with the wallet's sealed inside |
 | the invoice is checked by | nobody needs to, you resolved the address yourself |
 | the gateway probes first | `speaksVerify`: a GET on the URL, then a signed POST nonce it must echo |
-| the gateway polls | your `serve.verify` endpoint, once `relayThrough` is set. Leave it off and the gateway polls the wallet directly, as on the minted rail |
+| the gateway polls | your `serve.lightningVerify` endpoint, once `relayThrough` is set. Leave it off and the gateway polls the wallet directly, as on the minted rail |
 | `settled` comes from | your endpoint, which unseals, asks the wallet and relays the answer |
 | the pace is set by | you, `pollEverySecs` |
 
-| `nwcRail` | your own wallet mints it, over NIP-47 `make_invoice` |
+| `rails.nwc` | your own wallet mints it, over NIP-47 `make_invoice` |
 |---|---|
 | the gateway is told | a hash and your URL, with the hash sealed inside |
 | the invoice is checked by | nobody, it is your wallet |
 | the gateway probes first | the same GET and signed nonce |
-| the gateway polls | your `nwcVerifyEndpoint` |
+| the gateway polls | your `serve.nwcVerify` endpoint |
 | `settled` comes from | `lookup_invoice`, refused unless the wallet's own key signed it |
 | the pace is set by | you, `pollEverySecs` |
 
@@ -203,7 +203,7 @@ without saying whether either invoice was paid.
   concluding the invoice went unpaid. The body still reads `settled: false`, and the
   status is what separates "could not ask" from "asked, and no"
 
-**`nwcRail`**
+**`rails.nwc`**
 
 - an NWC connection to your own wallet, and the nostr relays behind it
 - **scope the connection to `make_invoice` and `lookup_invoice`, never
@@ -252,21 +252,23 @@ Four sharp edges, worth reading before you build:
   metadata and answers the verify requests. Every check passes. This protects a
   payer against the operator, never against the recipient's own custodian.
 - **The two proof fetches vet the first hop and no further.** `proveOrigin` and
-  `proveSettlement` use the runtime's default redirect handling, so a public https
-  host answering `302` to a private address is followed there. `invoiceFrom` is not
-  like this: it resolves through the outbound guard, which sets `redirect: "manual"`
-  and re-vets every hop. Keep egress control outside this package if that matters.
+  `proveSettlement` use the runtime's redirect handling, so a public https host
+  answering `302` to a private address on its own origin is followed there, while a
+  redirect off the recipient's origin fails the proof. `invoiceFrom` is not like
+  this: it resolves through the outbound guard, which sets `redirect: "manual"` and
+  re-vets every hop. Keep egress control outside this package if that matters.
 - **A payment read cold is only as pinned as its creation.** `payment` checks
-  the preimage against the `paymentHash` in the same record, and it was
-  `proveOrigin` at creation, against the request you wrote, that tied that hash to
-  an invoice the recipient issued. Store the request alongside the payment id, or a
-  cold read is checking the gateway's numbers against each other and nothing more.
+  the report against the `paymentHash` you hand it, and it was `proveOrigin` at
+  creation, against the request you wrote, that tied that hash to an invoice the
+  recipient issued. Store the hash you proved alongside the payment id, and never a
+  hash a later read handed back, or a cold read is checking the gateway's numbers
+  against each other and nothing more.
 - **Availability is not provable, and an address is not a person.** Every check
   here is about an invoice you were given, none about one you were refused, and
   proving an invoice belongs to an address never proves the address belongs to
   whoever you think it does.
 
-`carriesProof` is the one to be careful with: it asks only whether a report holds
+`agreesWithItself` is the one to be careful with: it asks only whether a report holds
 together, so a gateway that generates a preimage, hashes it and builds an invoice
 around that hash passes it. If a payment matters, ask the recipient with
 `prove` on the payment request or with `proveSettlement`. The full argument, including the five
@@ -291,7 +293,7 @@ const gateway = new ThunderBridge("https://public.thunder-bridge.agora.gripe", {
 });
 
 const asked = await gateway.requestPayment({ paidTo: "iamfatik@blink.sv", amount: sats(21) });
-const read = await gateway.payment(asked.id);
+const read = await gateway.payment(asked);
 const quoted = await gateway.quote({ paidTo: "iamfatik@blink.sv", amount: sats(21) });
 
 const lnurl = gateway.serve.lnurlPay({
@@ -306,13 +308,16 @@ const rail = gateway.rails.lightning({ paidTo: "iamfatik@blink.sv", amount: () =
   `payments`, `settled`, `firstSettled`, `follow`, `ticket`, `nameFor` and
   `webhookKey`, all on the instance
 - **what you mount** is on `gateway.serve`: an LNURL-pay endpoint, the two ticket
-  endpoints, the verify endpoints for Lightning and for a bank, the webhook route,
-  and the readers under it
+  endpoints, the verify endpoints `lightningVerify`, `bankVerify` and `nwcVerify`, the
+  webhook route, and the readers under it
 - **one call per sale** is on `gateway.rails`: `lightning`, `blindLightning`,
-  `bank`, and `transfer` for a bank transfer on its own
+  `bank`, `nwc`, and `transfer` for a bank transfer on its own. What the NWC rail
+  needs to reach your wallet, `nwcConnection` and the wallet calls, stays in
+  `thunder-bridge/nwc`
 - **the proofs** are free functions, deliberately, because a proof you cannot run
   without the thing being audited is not a proof: `proveOrigin`, `proveSettlement`,
-  `proveWrapped`, `carriesProof`, `decodeInvoice`, `preimageMatchesHash`
+  `proveWrapped`, `decodeInvoice`, `preimageMatchesHash`. `agreesWithItself` sits
+  beside them and proves less, as the table below says
 - **a payment reads without an assertion.** `Payment` is `MintedPayment |
   WatchedPayment`, so checking `kind` is what makes the address, the amount and the
   invoice non-null. The gateway writes those three together or writes none of them,
@@ -322,6 +327,20 @@ const rail = gateway.rails.lightning({ paidTo: "iamfatik@blink.sv", amount: () =
 What your service answers once those handlers are mounted is written out in
 [`openapi.yaml`](openapi.yaml), shipped with this package.
 
+### Which call checks what
+
+There are several ways to hear that a payment settled because there are several
+places to hear it from. They do not check the same thing, and the difference is
+what you may act on without asking anyone else.
+
+| You hear it through | What the claim is checked against |
+| --- | --- |
+| `payment`, `settled`, `firstSettled`, `paid()` on a `requestPayment`, and `Gateways.settled` | the `{ id, paymentHash }` you hold. Another payment, another hash, or a preimage that does not hash to yours throws `GatewayCheatError` |
+| `serve.webhook`, `serve.readSettlement`, `serve.readPayment` | the gateway's key, the timestamp, the URL it was sent to, and the preimage against the hash in the same body. Find your order by that hash before you act, which is what makes a pair the gateway invented find nothing |
+| `payments`, `follow` | the report itself. An entry claiming paid whose preimage does not hash to its own hash is left out of `payments` and reaches `follow`'s `onError` rather than `onPayment` |
+| `agreesWithItself` | the report itself, and nothing you hold, so a gateway that invents a preimage and names its hash passes it |
+| `proveSettlement` | the recipient's own verify URL, after the origin proof, so the gateway is not asked at all |
+
 ## Errors
 
 Every failure from the gateway is an RFC 9457 problem document. Branch on `type`,
@@ -398,10 +417,16 @@ try {
 
 Pass `webhookUrl` when you create a payment, or on any rail. There is no webhook
 secret: a gateway holds nothing of yours, and sending one is refused rather than
-ignored. Every delivery is signed `ed25519=<signature>` with the key the gateway
-publishes at `/webhook-key`, over `<x-timestamp>.<raw body>` rather than the body
-alone, so a captured delivery cannot be replayed at you later. Delivery is
-at-least-once, so deduplicate on `id`.
+ignored. Every delivery carries `x-signature-v2: ed25519=<signature>` with the key
+the gateway publishes at `/webhook-key`, over the URL it was sent to, `<x-timestamp>`
+and the raw body, so a delivery made for somebody else's endpoint proves nothing at
+yours and a captured one cannot be replayed at you later. Behind a proxy that hands
+the request on under another host or scheme, pass the URL you registered as `url`.
+Until then
+`serve.webhook` acts on each settlement once, answering a replay `200` without
+calling you again. Delivery is still at-least-once: a retry after that window, or
+one reaching another instance of your server, calls you again, so fulfil
+idempotently on `id`.
 
 Your handler answers one challenge before any of that. The gateway POSTs
 `{"type":"webhook-challenge","nonce":"..."}` to the URL while the create is still
@@ -429,7 +454,7 @@ that proves nothing gets a `202` and no callback, because acting on an unproven
 claim is the one thing this refuses to do. Pass `onUnproven` when an expiry is news
 you want.
 
-`onSettled` is handed a `Proven<Settlement>`, so the preimage is a `string` rather
+`onSettled` is handed a `SelfConsistent<Settlement>`, so the preimage is a `string` rather
 than something to coerce: the check the route already ran is what narrows it.
 
 `gateway.serve.readSettlement` and `gateway.serve.readPayment` are the same checks