Support repeating an invoice_request in payment onions.

This field may be useful for often-offline recipients who did not receive the invreq when it was originally sent, due to another node providing a static invoice on their behalf. Recipients may want to verify the invreq or be provided some other relevant data about the payment while remaining stateless until an HTLC is actually received.
lightning · Jun 3, 2024 · dc6599f · dc6599f
1 parent edc93aa
commit dc6599f
Show file tree

Hide file tree

Showing 3 changed files with 27 additions and 6 deletions.
diff --git a/04-onion-routing.md b/04-onion-routing.md
@@ -188,6 +188,9 @@ This is formatted according to the Type-Length-Value format defined in [BOLT #1]
 
 1. `tlv_stream`: `payload`
 2. types:
+    1. type: 1 (`invoice_request`)
+    2. data:
+        * [`...*byte`:`invoice_request_tlv_stream`]
     1. type: 2 (`amt_to_forward`)
     2. data:
         * [`tu64`:`amt_to_forward`]
@@ -242,8 +245,10 @@ The requirements ensure consistency in responding to an unexpected
 `outgoing_cltv_value`, whether it is the final node or not, to avoid
 leaking its position in the route.
 
-`sender_provided_payment_preimage` is set in the case that the recipient is 
-often-offline and another node provided a static BOLT 12 invoice on their behalf.
+`sender_provided_payment_preimage` and `invoice_request` are set in the case 
+that the recipient is often-offline and another node provided a static BOLT 12 
+invoice on their behalf, where `invoice_request` is the sender's originl 
+invoice request corresponding to this HTLC.
 
 ### Requirements
 
@@ -279,6 +284,10 @@ The writer of the TLV `payload`:
         - MUST set `sender_provided_payment_preimage` to randomly generated unique bytes.
         - MUST set `update_add_htlc.payment_hash` to match the SHA256 hash of
           `sender_provided_payment_preimage`.
+        - if the `payment_onion_invreq` feature is set in the invoice:
+          - MUST or MAY set `invoice_request` to the BOLT 12 invoice request
+            corresponding to this HTLC, based on whether `payment_onion_invreq`
+            is optional or compulsory.
       - otherwise:
         - MUST NOT set `sender_provided_payment_preimage`.
     - MUST NOT include any other tlv field.

diff --git a/09-features.md b/09-features.md
@@ -28,6 +28,7 @@ The Context column decodes as follows:
 * `9`: presented in [BOLT 11](11-payment-encoding.md) invoices.
 * `B`: presented in the `allowed_features` field of a blinded path.
 * `R`: presented in [BOLT 12](12-offers.md) invoice requests.
+* `V`: presented in [BOLT 12](12-offers.md) invoices.
 
 | Bits  | Name                              | Description                                               | Context  | Dependencies              | Link                                                                  |
 |-------|-----------------------------------|-----------------------------------------------------------|----------|---------------------------|-----------------------------------------------------------------------|
@@ -54,6 +55,7 @@ The Context column decodes as follows:
 | 52/53 | `option_htlc_hold`               | Hold HTLCs and forward on receipt of an onion message     | IN       | `option_onion_messages`                                   |
 | 56/57 | `option_om_mailbox`               | Store-and-forward onion messages for often-offline peers  | IN       | `option_onion_messages`   | [BOLT #12](bolt12-offers.md)                                          |
 | 59    | `static_invoice_pay`              | Supports paying BOLT 12 static invoices                   | R        | `option_onion_messages`   | [BOLT #12](bolt12-offers.md)                                          |
+| 60/61 | `payment_onion_invreq`            | Include `invoice_request` in payment onion                | V        |                           | [BOLT #12](bolt12-offers.md)                                          |
 
 ## Definitions
 

diff --git a/12-offer-encoding.md b/12-offer-encoding.md
@@ -670,10 +670,20 @@ the `onion_message` `invoice` field.
 
 ## Invoice Features
 
-| Bits | Description                      | Name           |
-|------|----------------------------------|----------------|
-| 16   | Multi-part-payment support       | MPP/compulsory |
-| 17   | Multi-part-payment support       | MPP/optional   |
+| Bits | Description                                | Name                            |
+|------|--------------------------------------------|---------------------------------|
+| 16   | Multi-part-payment support                 | MPP/compulsory                  |
+| 17   | Multi-part-payment support                 | MPP/optional                    |
+| 60   | Include `invoice_request` in payment onion | payment_onion_invreq/compulsory |
+| 61   | Include `invoice_request` in payment onion | payment_onion_invreq/optional   |
+
+The `payment_onion_invreq` feature indicates that the payer MUST (0) or MAY (1)
+repeat their invoice request in the `update_add_htlc` payment onion.
+
+Often-offline receivers may not have received the payer's invoice request
+originally if another node replied with a keysend invoice on their behalf.
+Providing it to the receiver separately may be useful for verification purposes
+or to supply some other data relevant to the payment.
 
 The 'MPP support' invoice feature indicates that the payer MUST (16) or
 MAY (17) use multiple part payments to pay the invoice.