Skip to content

BOLT 12: feature to allow requests of a bolt11 invoice. #1336

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rustyrussell wants to merge 2 commits into
base: master
Choose a base branch
from
Open

BOLT 12: feature to allow requests of a bolt11 invoice. #1336

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a2c9896
BOLT 12: feature to allow requests of a bolt11 invoice.
rustyrussell May 26, 2026
a1ed8a2
fixup! BOLT 12: feature to allow requests of a bolt11 invoice.
rustyrussell May 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions 04-onion-routing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1658,6 +1658,9 @@ even, of course!).
1. type: 68 (`invoice_error`)
2. data:
* [`tlv_invoice_error`:`inverr`]
1. type: 72 (`bolt11_invoice`)
2. data:
* [`...*utf8`:`bolt11`]

#### Requirements

Expand Down
3 changes: 3 additions & 0 deletions 09-features.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,12 +28,14 @@ The Context column decodes as follows:
* `C-`: presented in the `channel_announcement` message, but always odd (optional).
* `C+`: presented in the `channel_announcement` message, but always even (required).
* `9`: presented in [BOLT 11](11-payment-encoding.md) invoices.
* `2`: presented in [BOLT 12](12-offer-encoding.md) offers.
* `B`: presented in the `allowed_features` field of a blinded path.
* `T`: used in the `channel_type` field [when opening channels](02-peer-protocol.md#the-open_channel-message).

| Bits | Name | Description | Context | Dependencies | Link |
|-------|-----------------------------------|-----------------------------------------------------------|----------|-----------------------------|-----------------------------------------------------------------------|
| 0/1 | `option_data_loss_protect` | ASSUMED | | | |
| 2/3 | `option_bolt11_request` | Invoice request for a bolt11 invoice | 2 | | [BOLT #12][bolt12-bolt11-req] |
| 4/5 | `option_upfront_shutdown_script` | Commits to a shutdown scriptpubkey when opening channel | IN | | [BOLT #2][bolt02-open] |
| 6/7 | `gossip_queries` | Peer has useful gossip to share | | | |
| 8/9 | `var_onion_optin` | ASSUMED | | | |
Expand Down Expand Up @@ -113,4 +115,5 @@ This work is licensed under a [Creative Commons Attribution 4.0 International Li
[bolt04-mpp]: 04-onion-routing.md#basic-multi-part-payments
[bolt04-route-blinding]: 04-onion-routing.md#route-blinding
[bolt04-attributable-errors]: 04-onion-routing.md
[bolt12-bolt11-req]: 12-offer-encoding.md#requrements-for-invoice-requests

@t-bast t-bast Jun 1, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit:

Suggested change
[bolt12-bolt11-req]: 12-offer-encoding.md#requrements-for-invoice-requests
[bolt12-bolt11-req]: 12-offer-encoding.md#requirements-for-invoice-requests

[ml-sighash-single-harmful]: https://lists.linuxfoundation.org/pipermail/lightning-dev/2020-September/002796.html
14 changes: 13 additions & 1 deletion 12-offer-encoding.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -452,6 +452,7 @@ while still allowing signature validation.
* [`name_len*byte`:`name`]
* [`u8`:`domain_len`]
* [`domain_len*byte`:`domain`]
1. type: 92 (`invreq_bolt11`)
1. type: 240 (`signature`)
2. data:
* [`bip340sig`:`sig`]
Expand Down Expand Up @@ -480,6 +481,8 @@ The writer:
- MUST set `invreq_quantity` less than or equal to `offer_quantity_max`.
- otherwise:
- MUST NOT set `invreq_quantity`
- if `offer_features` contains `option_bolt11_request`:

@yyforyongyu yyforyongyu Jun 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Guess these if-else's are a bit difficult to follow😂

Given that, when the offer has offer_quantity_max, the writer (payer) must set invreq_quantity, and may set invreq_bolt11 when option_bolt11_request is found in the offer_features, the payer is allowed to include these in a single request,

  • invreq_bolt11
  • invreq_quantity

which will be rejected by the reader. So we need to add a writer rule: if offer_quantity_max is present, the writer MUST NOT set invreq_bolt11.

- MAY set `invreq_bolt11` to request a bolt11 invoice rather than a bolt12.
- otherwise (not responding to an offer):
- MUST set `offer_description` to a complete description of the purpose of the payment.
- MUST set (or not set) `offer_absolute_expiry` and `offer_issuer` as it would for an offer.
Expand Down Expand Up @@ -537,7 +540,14 @@ The reader:
- MAY reject the invoice request if `invreq_amount`.`msat` greatly exceeds the *expected amount*.
- otherwise (no `offer_amount`):
- MUST reject the invoice request if it does not contain `invreq_amount`.
- SHOULD send an invoice in response using the `onionmsg_tlv` `reply_path`.
- if `invreq_bolt11` is present:
- if `offer_features` does not contain `option_bolt11_request`:
- MUST reject the invoice request.
- if `invreq_quantity` is present:
- MUST reject the invoice request.
- SHOULD create a BOLT 11 invoice and place it in the `bolt11_invoice` field of a response `onionmsg_tlv`, sent using the `onionmsg_tlv` `reply_path`.
- otherwise:
- SHOULD create an invoice and place it in the `invoice` field of a response `onionmsg_tlv`, sent using the `onionmsg_tlv` `reply_path`.
- otherwise (no `offer_issuer_id` or `offer_paths`, not a response to our offer):
- MUST reject the invoice request if any of the following are present:
- `offer_chains`, `offer_features` or `offer_quantity_max`.
Expand Down Expand Up @@ -580,6 +590,8 @@ informative for the payer to know how the sender claims

The requirement to use `offer_paths` if present, ensures a node does not reveal it is the source of an offer if it is asked directly. Similarly, the requirement that the correct path is used for the offer ensures that cannot be made to reveal that it is the same node that created some other offer.

The `option_bolt11_request` field allows a backwards-compatible mechanism for simple offers, to simplify transition.

@yyforyongyu yyforyongyu Jun 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like we missed the part to bind the bolt11 invoice. For a bolt12 invoice there's a cryptographic binding, but for bolt11 invoice there is no proof that it is coming from the offer? Like the payer cannot prove it corresponds to the exact request or offer version.


# Invoices

Invoices are a payment request, and when the payment is made,
Expand Down