BOLT 12 Offers message handling support (offers, onion messages)

Host: dunxen  -  PR author: jkczyz


BOLT 12 offers essentially provide a way for a merchant to receive payments through the use of a static identifier (they can be long-lived). Offers do not replace the need for something like invoices, in fact, they work in tandem. Readers of an offer will be able to request invoices via onion messages using a blinded path to the merchant. This provides recipient privacy. In fact, any onion messages, not just for offers, can use a blinded path.

PR #2294 introduces onion message handling for offers so that LDK can interpret offer payloads. It also adds support for actually replying to onion messages via reply paths in general which is an essential part of the offer protocol and other uses of onion messages. The reader of an offer would create an InvoiceRequest payload to send to the merchant (to a blinded path provided in the offer contents) who would then reply with an Invoice requesting payment or an InvoiceError. If an Invoice is received, the payer can then pay the invoice (also to a blinded path) or respond with an InvoiceError.

         A successful flow
 β”Œβ”€β”€β”€β”€β”€β”                   β”Œβ”€β”€β”€β”€β”€β”
 β”‚     β”‚  InvoiceRequest   β”‚  M  β”‚
 β”‚     β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Ί(BP)──►│  E  β”‚
 β”‚  P  β”‚                   β”‚  R  β”‚
 β”‚  A  β”‚     Invoice       β”‚  C  β”‚
 β”‚  Y  │◄─(BP)──────────────  H  β”‚
 β”‚  E  β”‚   (reply path)    β”‚  A  β”‚
 β”‚  R  β”‚                   β”‚  N  β”‚
 β”‚     β”‚     payment       β”‚  T  β”‚
 β”‚     β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Ί(BP)───►│     β”‚
 β””β”€β”€β”€β”€β”€β”˜                   β””β”€β”€β”€β”€β”€β”˜

* BP: Blinded Path

The PR adds the OffersMessageHandler trait where implementors handle incoming OnionMessages containing an offer message as payload. ChannelManager implements this trait, but it remains a stub for this PR.


  1. Did you review the PR? Concept ACK, approach ACK, tested ACK, or NACK?
  2. The PR introduces the MessageRouter trait for finding routes for onion messages. MessageRoute::find_route implementations must return a Vec<PublicKey> when provided a sender PublicKey and a Destination. What is a Destination in the onion messages context and which PublicKeys should an implementor be returning from find_route. Is find_route a good name? Any other ideas for a name?
  3. To support replies, onion message handlers were modified to return an optional response message. How does a recipient know where a reply should be sent? When replying do we ever know the original sender (the reply’s recipient) node ID/pubkey?
  4. Currently a BOLT 11 invoice exposes the payee’s node ID explicitly or via signature recovery. Without BOLT 12 (and blinded paths) and currently doable on the Lightning Network, is there any possible way to gain any level of privacy in this regard, or would the payer always know the payee’s pubkey? How could we at the very least try make the effective payee not seem like the final recipient of the payment?
  5. We’ve generally covered one kind of payment flow scenario up to now. What other payment flow does BOLT 12 enable and how does this differ to the one we’ve discussed?