Skip to content

Commit db9e618

Browse files
carlaKCcarlaKC
committed
blip-0004: add experimental HTLC endorsement signaling
1 parent b273c85 commit db9e618

File tree

3 files changed

+158
-4
lines changed

3 files changed

+158
-4
lines changed

‎README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ For more detail on the process, please read [bLIP-0001](./blip-0001.md) and
2222
| [1](./blip-0001.md) | bLIP Process | Ryan Gentry | Active |
2323
| [2](./blip-0002.md) | Reserved Values | Bastien Teinturier | Active |
2424
| [3](./blip-0003.md) | Keysend | Valentine Wallace | Active |
25+
| [4](./blip-0004.md) | Experimental Endorsement | Carla Kirk-Cohen | Active |
2526
| [10](./blip-0010.md) | Podcasting 2.0 | Satoshis Stream | Active |
2627
| [11](./blip-0011.md) | NameDesc | Hampus Sjöberg | Active |
2728
| [17](./blip-0017.md) | Hosted Channels | Anton Kumaigorodskiy | Active |

‎blip-0002.md

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -44,10 +44,11 @@ Custom feature bits used in the `I` [Bolt 11](https://github.com/lightning/bolts
4444

4545
bLIPs may reserve feature bits by adding them to the following table:
4646

47-
| Bits | Name | Description | Context | Dependencies | Link |
48-
| --------- | ---------------------- | ------------------------------------------------- | ---------------- | -------------------------------- | -------------------------------- |
49-
| 54/55 | `keysend` | A form of spontaneous payment | N | `var_onion_optin` | [bLIP 3](./blip-0003.md) |
50-
| 256/257 | `hosted_channels` | This node accepts requests for hosted channels | IN | | [bLIP 17](./blip-0017.md) |
47+
| Bits | Name | Description | Context | Dependencies | Link |
48+
| --------- | ---------------------- | ----------------------------------------------------------- | ---------------- | -------------------------------- | -------------------------------- |
49+
| 54/55 | `keysend` | A form of spontaneous payment | N | `var_onion_optin` | [bLIP 3](./blip-0003.md) |
50+
| 256/257 | `hosted_channels` | This node accepts requests for hosted channels | IN | | [bLIP 17](./blip-0017.md) |
51+
| 258/259 | `htlc_endorsement | This node forwards experimental htlc endorsement signals | N | | [bLIP 4](./blip-004.md) |
5152

5253
### Messages
5354

@@ -110,6 +111,15 @@ The following table contains extension tlv fields for the `ping` message:
110111
|-------|-----------------------------|--------------------------------|
111112
| 65536 | `tlv_field_name` | Link to the corresponding bLIP |
112113

114+
#### `update_add_htlc`
115+
116+
The following table contains extension tlv fields for the `update_add_htlc` message:
117+
118+
119+
| Type | Name | Link |
120+
|-------|-----------------------------|--------------------------------|
121+
| 65555 | `endorsed` | [bLIP 4](./blip-0004.md) |
122+
113123
## Copyright
114124

115125
This bLIP is licensed under the CC0 license.

‎blip-0004.md

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
```
2+
bLIP: 4
3+
Title: Experimental Endorsement Signaling
4+
Status: Active
5+
Author: Carla Kirk-Cohen <[email protected]>
6+
Created: 2024-01-12
7+
License: CC0
8+
```
9+
10+
## Abstract
11+
12+
HTLC endorsement signaling is a [proposed](https://github.com/lightning/bolts/pull/1071)
13+
component of a [hybrid approach](https://research.chaincode.com/2022/11/15/unjamming-lightning)
14+
to addressing [channel jamming attacks](https://bitcoinops.org/en/topics/channel-jamming-attacks)
15+
against the Lightning Network. This bLIP outlines a proposal to deploy an
16+
experimental endorsement TLV to the network to provide real world data to
17+
inform specification of reputation algorithms.
18+
19+
## Copyright
20+
21+
This bLIP is licensed under the CC0 license.
22+
23+
## Specification
24+
25+
Experiment Parameters:
26+
* `experiment_start`: [TODO]
27+
* `experiment_end`: [TODO]
28+
29+
### Adding an HTLC: `update_add_htlc`:
30+
31+
1. `tlv_stream`: `update_add_htlc_tlvs`
32+
1. type: 65555 (`endorsed`)
33+
2. data:
34+
* [`byte`:`endorsed`]
35+
36+
Sender:
37+
* If the current time is greater than or equal to `experiment_start` and less
38+
than `experiment_end`:
39+
* if it is the original source of the HTLC:
40+
* if it does not expect immediate fulfillment upon receipt by the
41+
final destination:
42+
* SHOULD set `endorsed` to `0`.
43+
* otherwise:
44+
* SHOULD set `endorsed` to `1`.
45+
* MAY choose to set `endorsed` to `0` for some percentage of payments to
46+
prevent leaking its identity as the original sender.
47+
48+
Receiver:
49+
* If the current time is less than `experiment_end`:
50+
* if running an experimental reputation algorithm:
51+
* SHOULD set `endorsed` at its discretion.
52+
* otherwise:
53+
* if `endorsed` is present and non-zero in the `update_add_htlc`:
54+
* SHOULD set `endorsed` to `1`.
55+
* otherwise:
56+
* SHOULD set `endorsed` to `0`.
57+
58+
## Deployment and Deprecation
59+
60+
### Deployment
61+
62+
Forwarding nodes can upgrade and being to set `endorsed` signals immediately,
63+
as there is no privacy risk associated with propagating zero values. Feature
64+
bit signaling and a flag day are used to allow senders to set `endorsed` to `1`
65+
without leaking their identity as the original sender of the HTLC.
66+
67+
1. Nodes on the network upgrade to support forwarding `endorsed` signals.
68+
2. Choose a `experiment_start` parameter based on deployment of the
69+
`htlc_endorsed` signal on the network.
70+
3. After `experiment_start` has passed, sending nodes start to set `endorsed`
71+
to `1` as described above.
72+
4. When `experiment_end` is reached, sending node on the network stop setting
73+
the experimental `endorsed` field and intermediate nodes will stop
74+
relaying it, so the signal will cease to propagate through the network.
75+
76+
### Deprecation
77+
78+
If `endorsement` is merged to the BOLTs, the experimental signal can be
79+
deprecated in favor of the protocol-range field. If it is not, the signal
80+
will simply expire when `experiment_end` is reached.
81+
82+
1. Upgrade to protocol-range field:
83+
84+
Once nodes are updated to use the protocol-range field, they can stop
85+
advertising the experimental `htlc_endorsed` feature bit.
86+
87+
Sender:
88+
* MUST set the same value for experimental and protocol-range field.
89+
90+
Receiver:
91+
* if the protocol-range TLV is present:
92+
* MUST interpret its value as the `endorsed` signal for the HTLC.
93+
otherwise, if the experimental TLV is present:
94+
* SHOULD interpret the experimental value as the `endorsed` signal
95+
for the HTLC.
96+
97+
2. When `experiment_end` is reached, the experimental field can be deprecated,
98+
and the TLV number / feature bit can be released into the available pool:
99+
Sender:
100+
* MUST set the protocol-range field.
101+
* MUST NOT set the experimental range field.
102+
103+
Receiver:
104+
* MUST interpret the protocol-range field as the `endorsed` value for the HTLC.
105+
106+
## Motivation
107+
108+
The emergent properties of network-wide changes to Lightning are difficult to
109+
fully grasp without gathering real world data. This bLIP outlines a lightweight
110+
and reversible mechanism to assess the impact of this change so that we can
111+
direct further specification in an informed manner.
112+
113+
## Rationale
114+
115+
Endorsement signals are copied from the incoming `update_add_htlc` to allow
116+
positive signals to propagate through the network. Nodes wishing to participate
117+
in active experimentation may set this signal according to their local
118+
reputation algorithm, and this signal will be passively propagated by the
119+
remainder of the route that is simply copying incoming values.
120+
121+
A flag day is included to mitigate privacy concerns that setting the
122+
endorsement signal on payments will expose the identity of the original sender.
123+
Nodes participating in the experiment will signal the `htlc_endorsed` feature
124+
in their node announcement to help chose an appropriate `experiment_start`.
125+
Once a sufficient portion of the network is upgraded to relay these signals, the
126+
presence of positive endorsement does not expose the sender as the original
127+
source of the HTLC. Senders are also advised to only set a positive endorsement
128+
signal for some percentage of payments to further protect sender privacy.
129+
130+
The `endorsed` TLV is encoded as a single `byte` rather than a boolean to allow
131+
flexible experimentation. HTLCs that are not endorsed include a TLV with a zero
132+
value byte so that they can be distinguished from those with no endorsement
133+
signal, which can be filtered out of experimental data as null values.
134+
135+
This experiment is opened as a bLIP because it is not intended to be a
136+
permanent part of the lightning specification. Should endorsement signaling be
137+
accepted to the BOLTs, the network can cleanly upgrade by setting the same
138+
value for the protocol and experimental range TLV, and deprecate the
139+
experimental TLV.
140+
141+
## Reference Implementations
142+
143+
* [LND](https://github.com/lightningnetwork/lnd/pull/8390)

0 commit comments

Comments
 (0)