Skip to content

Commit c4c5a8e

Browse files
t-bastt-bast
committed
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.
1 parent 58d8047 commit c4c5a8e

File tree

7 files changed

+608
-130
lines changed

7 files changed

+608
-130
lines changed

‎.aspell.en.pws‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -391,3 +391,5 @@ griefing
391391
unspendable
392392
pkh
393393
kB
394+
unblind
395+
unblinded

‎02-peer-protocol.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -990,6 +990,12 @@ is destined, is described in [BOLT #4](04-onion-routing.md).
990990
* [`u32`:`cltv_expiry`]
991991
* [`1366*byte`:`onion_routing_packet`]
992992

993+
1. `tlv_stream`: `update_add_htlc_tlvs`
994+
2. types:
995+
1. type: 0 (`blinding_point`)
996+
2. data:
997+
* [`point`:`blinding`]
998+
993999
#### Requirements
9941000

9951001
A sending node:
@@ -1025,6 +1031,8 @@ A sending node:
10251031
- for the first HTLC it offers:
10261032
- MUST set `id` to 0.
10271033
- MUST increase the value of `id` by 1 for each successive offer.
1034+
- if it is relaying a payment inside a blinded route:
1035+
- MUST set `blinding_point` (see [Route Blinding](04-onion-routing.md#route-blinding))
10281036

10291037
`id` MUST NOT be reset to 0 after the update is complete (i.e. after `revoke_and_ack` has
10301038
been received). It MUST continue incrementing instead.
@@ -1049,6 +1057,8 @@ A receiving node:
10491057
- if other `id` violations occur:
10501058
- MAY send a `warning` and close the connection, or send an
10511059
`error` and fail the channel.
1060+
- if `blinding_point` is provided:
1061+
- MUST use the corresponding blinded private key to decrypt the `onion_routing_packet` (see [Route Blinding](04-onion-routing.md#route-blinding))
10521062

10531063
The `onion_routing_packet` contains an obfuscated list of hops and instructions for each hop along the path.
10541064
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:
11311141
commitment transactions:
11321142
- MUST NOT send an `update_fulfill_htlc`, `update_fail_htlc`, or
11331143
`update_fail_malformed_htlc`.
1144+
- When failing an incoming HTLC:
1145+
- If `current_blinding_point` is set in the onion payload and it is not the
1146+
final node:
1147+
- MUST send an `update_fail_htlc` error using the
1148+
`invalid_onion_blinding` failure code with the `sha256_of_onion`
1149+
of the onion it received, for any local or downstream errors.
1150+
- SHOULD add a random delay before sending `update_fail_htlc`.
1151+
- If `blinding_point` is set in the incoming `update_add_htlc`:
1152+
- MUST send an `update_fail_malformed_htlc` error using the
1153+
`invalid_onion_blinding` failure code with the `sha256_of_onion`
1154+
of the onion it received, for any local or downstream errors.
11341155

11351156
A receiving node:
11361157
- 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,
11701191
it won't know whether the error was its own or the remote's; so
11711192
such detection is left as an option.
11721193

1194+
Nodes inside a blinded route must use `invalid_onion_blinding` to avoid
1195+
leaking information to senders trying to probe the blinded route.
1196+
11731197
### Committing Updates So Far: `commitment_signed`
11741198

11751199
When a node has changes for the remote commitment, it can apply them,

‎04-onion-routing.md‎

Lines changed: 184 additions & 69 deletions
Large diffs are not rendered by default.

‎09-features.md‎

Lines changed: 24 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -19,32 +19,35 @@ for use of the channel, so the presentation of those features depends
1919
on the feature itself.
2020

2121
The Context column decodes as follows:
22+
2223
* `I`: presented in the `init` message.
2324
* `N`: presented in the `node_announcement` messages
2425
* `C`: presented in the `channel_announcement` message.
2526
* `C-`: presented in the `channel_announcement` message, but always odd (optional).
2627
* `C+`: presented in the `channel_announcement` message, but always even (required).
2728
* `9`: presented in [BOLT 11](11-payment-encoding.md) invoices.
28-
29-
| Bits | Name | Description | Context | Dependencies | Link |
30-
|-------|----------------------------------|-----------------------------------------------------------|----------|-------------------|---------------------------------------|
31-
| 0/1 | `option_data_loss_protect` | Requires or supports extra `channel_reestablish` fields | IN | | [BOLT #2][bolt02-retransmit] |
32-
| 3 | `initial_routing_sync` | Sending node needs a complete routing information dump | I | | [BOLT #7][bolt07-sync] |
33-
| 4/5 | `option_upfront_shutdown_script` | Commits to a shutdown scriptpubkey when opening channel | IN | | [BOLT #2][bolt02-open] |
34-
| 6/7 | `gossip_queries` | More sophisticated gossip control | IN | | [BOLT #7][bolt07-query] |
35-
| 8/9 | `var_onion_optin` | Requires/supports variable-length routing onion payloads | IN9 | | [Routing Onion Specification][bolt04] |
36-
| 10/11 | `gossip_queries_ex` | Gossip queries can include additional information | IN | `gossip_queries` | [BOLT #7][bolt07-query] |
37-
| 12/13 | `option_static_remotekey` | Static key for remote output | IN | | [BOLT #3](03-transactions.md) |
38-
| 14/15 | `payment_secret` | Node supports `payment_secret` field | IN9 | `var_onion_optin` | [Routing Onion Specification][bolt04] |
39-
| 16/17 | `basic_mpp` | Node can receive basic multi-part payments | IN9 | `payment_secret` | [BOLT #4][bolt04-mpp] |
40-
| 18/19 | `option_support_large_channel` | Can create large channels | IN | | [BOLT #2](02-peer-protocol.md#the-open_channel-message) |
41-
| 20/21 | `option_anchor_outputs` | Anchor outputs | IN | `option_static_remotekey` | [BOLT #3](03-transactions.md) |
42-
| 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]|
43-
| 26/27 | `option_shutdown_anysegwit` | Future segwit versions allowed in `shutdown` | IN | | [BOLT #2][bolt02-shutdown] |
44-
| 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) |
45-
| 46/47 | `option_scid_alias` | Supply channel aliases for routing | IN | | [BOLT #2][bolt02-channel-ready] |
46-
| 48/49 | `option_payment_metadata` | Payment metadata in tlv record | 9 | | [BOLT #11](11-payment-encoding.md#tagged-fields)
47-
| 50/51 | `option_zeroconf` | Understands zeroconf channel types | IN | `option_scid_alias` | [BOLT #2][bolt02-channel-ready] |
29+
* `B`: presented in the `allowed_features` field of a blinded path.
30+
31+
| Bits | Name | Description | Context | Dependencies | Link |
32+
|-------|-----------------------------------|-----------------------------------------------------------|----------|---------------------------|-----------------------------------------------------------------------|
33+
| 0/1 | `option_data_loss_protect` | Requires or supports extra `channel_reestablish` fields | IN | | [BOLT #2][bolt02-retransmit] |
34+
| 3 | `initial_routing_sync` | Sending node needs a complete routing information dump | I | | [BOLT #7][bolt07-sync] |
35+
| 4/5 | `option_upfront_shutdown_script` | Commits to a shutdown scriptpubkey when opening channel | IN | | [BOLT #2][bolt02-open] |
36+
| 6/7 | `gossip_queries` | More sophisticated gossip control | IN | | [BOLT #7][bolt07-query] |
37+
| 8/9 | `var_onion_optin` | Requires/supports variable-length routing onion payloads | IN9 | | [Routing Onion Specification][bolt04] |
38+
| 10/11 | `gossip_queries_ex` | Gossip queries can include additional information | IN | `gossip_queries` | [BOLT #7][bolt07-query] |
39+
| 12/13 | `option_static_remotekey` | Static key for remote output | IN | | [BOLT #3](03-transactions.md) |
40+
| 14/15 | `payment_secret` | Node supports `payment_secret` field | IN9 | `var_onion_optin` | [Routing Onion Specification][bolt04] |
41+
| 16/17 | `basic_mpp` | Node can receive basic multi-part payments | IN9 | `payment_secret` | [BOLT #4][bolt04-mpp] |
42+
| 18/19 | `option_support_large_channel` | Can create large channels | IN | | [BOLT #2](02-peer-protocol.md#the-open_channel-message) |
43+
| 20/21 | `option_anchor_outputs` | Anchor outputs | IN | `option_static_remotekey` | [BOLT #3](03-transactions.md) |
44+
| 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] |
45+
| 24/25 | `option_route_blinding` | Node supports blinded paths | IN9 | `var_onion_optin` | [BOLT #4](bolt04-route-blinding) |
46+
| 26/27 | `option_shutdown_anysegwit` | Future segwit versions allowed in `shutdown` | IN | | [BOLT #2][bolt02-shutdown] |
47+
| 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) |
48+
| 46/47 | `option_scid_alias` | Supply channel aliases for routing | IN | | [BOLT #2][bolt02-channel-ready] |
49+
| 48/49 | `option_payment_metadata` | Payment metadata in tlv record | 9 | | [BOLT #11](11-payment-encoding.md#tagged-fields) |
50+
| 50/51 | `option_zeroconf` | Understands zeroconf channel types | IN | `option_scid_alias` | [BOLT #2][bolt02-channel-ready] |
4851

4952
## Definitions
5053

@@ -100,4 +103,5 @@ This work is licensed under a [Creative Commons Attribution 4.0 International Li
100103
[bolt07-sync]: 07-routing-gossip.md#initial-sync
101104
[bolt07-query]: 07-routing-gossip.md#query-messages
102105
[bolt04-mpp]: 04-onion-routing.md#basic-multi-part-payments
106+
[bolt04-route-blinding]: 04-onion-routing.md#route-blinding
103107
[ml-sighash-single-harmful]: https://lists.linuxfoundation.org/pipermail/lightning-dev/2020-September/002796.html

0 commit comments

Comments
 (0)