Bolt 4: add blinded payments

Add specification requirements for using route blinding to make payments while preserving recipient anonymity. Implementers must ensure they understand all those requirements, there are subtle attacks that could let malicious senders deanonymize the route if incompletely implemented.
lightning · Mar 28, 2023 · c4c5a8e · c4c5a8e
1 parent 58d8047
commit c4c5a8e
Show file tree

Hide file tree

Showing 7 changed files with 608 additions and 130 deletions.
diff --git a/.aspell.en.pws b/.aspell.en.pws
@@ -391,3 +391,5 @@ griefing
 unspendable
 pkh
 kB
+unblind
+unblinded
diff --git a/02-peer-protocol.md b/02-peer-protocol.md
@@ -990,6 +990,12 @@ is destined, is described in [BOLT #4](04-onion-routing.md).
    * [`u32`:`cltv_expiry`]
    * [`1366*byte`:`onion_routing_packet`]
 
+1. `tlv_stream`: `update_add_htlc_tlvs`
+2. types:
+    1. type: 0 (`blinding_point`)
+    2. data:
+        * [`point`:`blinding`]
+
 #### Requirements
 
 A sending node:
@@ -1025,6 +1031,8 @@ A sending node:
   - for the first HTLC it offers:
     - MUST set `id` to 0.
   - MUST increase the value of `id` by 1 for each successive offer.
+  - if it is relaying a payment inside a blinded route:
+    - MUST set `blinding_point` (see [Route Blinding](04-onion-routing.md#route-blinding))
 
 `id` MUST NOT be reset to 0 after the update is complete (i.e. after `revoke_and_ack` has
 been received). It MUST continue incrementing instead.
@@ -1049,6 +1057,8 @@ A receiving node:
   - if other `id` violations occur:
     - MAY send a `warning` and close the connection, or send an
       `error` and fail the channel.
+  - if `blinding_point` is provided:
+    - MUST use the corresponding blinded private key to decrypt the `onion_routing_packet` (see [Route Blinding](04-onion-routing.md#route-blinding))
 
 The `onion_routing_packet` contains an obfuscated list of hops and instructions for each hop along the path.
 It commits to the HTLC by setting the `payment_hash` as associated data, i.e. includes the `payment_hash` in the computation of HMACs.
@@ -1131,6 +1141,17 @@ A node:
   commitment transactions:
     - MUST NOT send an `update_fulfill_htlc`, `update_fail_htlc`, or
 `update_fail_malformed_htlc`.
+  - When failing an incoming HTLC:
+    - If `current_blinding_point` is set in the onion payload and it is not the
+      final node:
+      - MUST send an `update_fail_htlc` error using the
+        `invalid_onion_blinding` failure code with the `sha256_of_onion`
+        of the onion it received, for any local or downstream errors.
+      - SHOULD add a random delay before sending `update_fail_htlc`.
+    - If `blinding_point` is set in the incoming `update_add_htlc`:
+      - MUST send an `update_fail_malformed_htlc` error using the
+        `invalid_onion_blinding` failure code with the `sha256_of_onion`
+        of the onion it received, for any local or downstream errors.
 
 A receiving node:
   - if the `id` does not correspond to an HTLC in its current commitment transaction:
@@ -1170,6 +1191,9 @@ errors. However, without re-checking the actual encrypted packet sent,
 it won't know whether the error was its own or the remote's; so
 such detection is left as an option.
 
+Nodes inside a blinded route must use `invalid_onion_blinding` to avoid
+leaking information to senders trying to probe the blinded route.
+
 ### Committing Updates So Far: `commitment_signed`
 
 When a node has changes for the remote commitment, it can apply them,

diff --git a/04-onion-routing.md b/04-onion-routing.md
diff --git a/09-features.md b/09-features.md
@@ -19,32 +19,35 @@ for use of the channel, so the presentation of those features depends
 on the feature itself.
 
 The Context column decodes as follows:
+
 * `I`: presented in the `init` message.
 * `N`: presented in the `node_announcement` messages
 * `C`: presented in the `channel_announcement` message.
 * `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.
-
-| Bits  | Name                             | Description                                               | Context  | Dependencies      | Link                                  |
-|-------|----------------------------------|-----------------------------------------------------------|----------|-------------------|---------------------------------------|
-| 0/1   | `option_data_loss_protect`       | Requires or supports extra `channel_reestablish` fields   | IN       |                   | [BOLT #2][bolt02-retransmit]          |
-| 3     | `initial_routing_sync`           | Sending node needs a complete routing information dump    | I        |                   | [BOLT #7][bolt07-sync]                |
-| 4/5   | `option_upfront_shutdown_script` | Commits to a shutdown scriptpubkey when opening channel   | IN       |                   | [BOLT #2][bolt02-open]                |
-| 6/7   | `gossip_queries`                 | More sophisticated gossip control                         | IN       |                   | [BOLT #7][bolt07-query]               |
-| 8/9   | `var_onion_optin`                | Requires/supports variable-length routing onion payloads  | IN9      |                   | [Routing Onion Specification][bolt04] |
-| 10/11 | `gossip_queries_ex`              | Gossip queries can include additional information         | IN       | `gossip_queries`  | [BOLT #7][bolt07-query]               |
-| 12/13 | `option_static_remotekey`        | Static key for remote output                              | IN       |                   | [BOLT #3](03-transactions.md)         |
-| 14/15 | `payment_secret`                 | Node supports `payment_secret` field                      | IN9      | `var_onion_optin` | [Routing Onion Specification][bolt04] |
-| 16/17 | `basic_mpp`                      | Node can receive basic multi-part payments                | IN9      | `payment_secret`  | [BOLT #4][bolt04-mpp]                 |
-| 18/19 | `option_support_large_channel`   | Can create large channels                                 | IN       |                   | [BOLT #2](02-peer-protocol.md#the-open_channel-message) |
-| 20/21 | `option_anchor_outputs`          | Anchor outputs                                            | IN       | `option_static_remotekey` | [BOLT #3](03-transactions.md)         |
-| 22/23 | `option_anchors_zero_fee_htlc_tx` | Anchor commitment type with zero fee HTLC transactions   | IN       | `option_static_remotekey` | [BOLT #3][bolt03-htlc-tx], [lightning-dev][ml-sighash-single-harmful]|
-| 26/27 | `option_shutdown_anysegwit`         | Future segwit versions allowed in `shutdown`              | IN       |                   | [BOLT #2][bolt02-shutdown]   |
-| 44/45 | `option_channel_type`            | Node supports the `channel_type` field in open/accept     | IN       |                   | [BOLT #2](02-peer-protocol.md#the-open_channel-message) |
-| 46/47 | `option_scid_alias`              | Supply channel aliases for routing                        | IN       |                   | [BOLT #2][bolt02-channel-ready]   |
-| 48/49 | `option_payment_metadata` | Payment metadata in tlv record | 9 | | [BOLT #11](11-payment-encoding.md#tagged-fields)
-| 50/51 | `option_zeroconf`                | Understands zeroconf channel types                        | IN       | `option_scid_alias` | [BOLT #2][bolt02-channel-ready]   |
+* `B`: presented in the `allowed_features` field of a blinded path.
+
+| Bits  | Name                              | Description                                               | Context  | Dependencies              | Link                                                                  |
+|-------|-----------------------------------|-----------------------------------------------------------|----------|---------------------------|-----------------------------------------------------------------------|
+| 0/1   | `option_data_loss_protect`        | Requires or supports extra `channel_reestablish` fields   | IN       |                           | [BOLT #2][bolt02-retransmit]                                          |
+| 3     | `initial_routing_sync`            | Sending node needs a complete routing information dump    | I        |                           | [BOLT #7][bolt07-sync]                                                |
+| 4/5   | `option_upfront_shutdown_script`  | Commits to a shutdown scriptpubkey when opening channel   | IN       |                           | [BOLT #2][bolt02-open]                                                |
+| 6/7   | `gossip_queries`                  | More sophisticated gossip control                         | IN       |                           | [BOLT #7][bolt07-query]                                               |
+| 8/9   | `var_onion_optin`                 | Requires/supports variable-length routing onion payloads  | IN9      |                           | [Routing Onion Specification][bolt04]                                 |
+| 10/11 | `gossip_queries_ex`               | Gossip queries can include additional information         | IN       | `gossip_queries`          | [BOLT #7][bolt07-query]                                               |
+| 12/13 | `option_static_remotekey`         | Static key for remote output                              | IN       |                           | [BOLT #3](03-transactions.md)                                         |
+| 14/15 | `payment_secret`                  | Node supports `payment_secret` field                      | IN9      | `var_onion_optin`         | [Routing Onion Specification][bolt04]                                 |
+| 16/17 | `basic_mpp`                       | Node can receive basic multi-part payments                | IN9      | `payment_secret`          | [BOLT #4][bolt04-mpp]                                                 |
+| 18/19 | `option_support_large_channel`    | Can create large channels                                 | IN       |                           | [BOLT #2](02-peer-protocol.md#the-open_channel-message)               |
+| 20/21 | `option_anchor_outputs`           | Anchor outputs                                            | IN       | `option_static_remotekey` | [BOLT #3](03-transactions.md)                                         |
+| 22/23 | `option_anchors_zero_fee_htlc_tx` | Anchor commitment type with zero fee HTLC transactions    | IN       | `option_static_remotekey` | [BOLT #3][bolt03-htlc-tx], [lightning-dev][ml-sighash-single-harmful] |
+| 24/25 | `option_route_blinding`           | Node supports blinded paths                               | IN9      | `var_onion_optin`         | [BOLT #4](bolt04-route-blinding)                                      |
+| 26/27 | `option_shutdown_anysegwit`       | Future segwit versions allowed in `shutdown`              | IN       |                           | [BOLT #2][bolt02-shutdown]                                            |
+| 44/45 | `option_channel_type`             | Node supports the `channel_type` field in open/accept     | IN       |                           | [BOLT #2](02-peer-protocol.md#the-open_channel-message)               |
+| 46/47 | `option_scid_alias`               | Supply channel aliases for routing                        | IN       |                           | [BOLT #2][bolt02-channel-ready]                                       |
+| 48/49 | `option_payment_metadata`         | Payment metadata in tlv record                            | 9        |                           | [BOLT #11](11-payment-encoding.md#tagged-fields)                      |
+| 50/51 | `option_zeroconf`                 | Understands zeroconf channel types                        | IN       | `option_scid_alias`       | [BOLT #2][bolt02-channel-ready]                                       |
 
 ## Definitions
 
@@ -100,4 +103,5 @@ This work is licensed under a [Creative Commons Attribution 4.0 International Li
 [bolt07-sync]: 07-routing-gossip.md#initial-sync
 [bolt07-query]: 07-routing-gossip.md#query-messages
 [bolt04-mpp]: 04-onion-routing.md#basic-multi-part-payments
+[bolt04-route-blinding]: 04-onion-routing.md#route-blinding
 [ml-sighash-single-harmful]: https://lists.linuxfoundation.org/pipermail/lightning-dev/2020-September/002796.html