Skip to content

Commit 0c62229

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

File tree

3 files changed

+156
-4
lines changed

3 files changed

+156
-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: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
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+
* `flag_day`: [TODO]
27+
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 it is the original source of the HTLC and `flag_day` has passed:
38+
* if it does not expect immediate fulfillment upon receipt by the
39+
final destination:
40+
* SHOULD set `endorsed` to `0`.
41+
* otherwise:
42+
* SHOULD set `endorsed` to `1`.
43+
* MAY choose to set `endorsed` to `0` for some percentage of payments to
44+
prevent leaking its identity as the original sender.
45+
46+
Receiver:
47+
* if `endorsed` is present and non-zero in the `update_add_htlc`:
48+
* if running an experimental reputation algorithm:
49+
* SHOULD set `endorsed` as specified by the algorithm.
50+
otherwise:
51+
* SHOULD set `endorsed` to `1`.
52+
* otherwise:
53+
* SHOULD set `endorsed` to `0`.
54+
55+
## Deployment and Deprecation
56+
57+
### Deployment
58+
59+
Forwarding nodes can upgrade and being to set `endorsed` signals immediately,
60+
as there is no privacy risk associated with propagating zero values. Feature
61+
bit signaling and a flag day are used to allow senders to set `endorsed` to `1`
62+
without leaking their identity as the original sender of the HTLC.
63+
64+
1. Nodes on the network upgrade to support forwarding `endorsed` signals.
65+
2. Choose a `flag_day` parameter based on deployment of the `htlc_endorsed`
66+
signal on the network.
67+
3. After `flag_day` has passed, sending nodes start to set `endorsed` to `1`
68+
as described above.
69+
70+
### Deprecation
71+
72+
If `endorsement` is merged to the BOLTs, the experimental signal can be
73+
deprecated in favor of the protocol-range field. If it is not, the signal
74+
can simply be deleted with no deprecation period.
75+
76+
1. Upgrade to protocol-range field:
77+
78+
Once nodes are updated to use the protocol-range field, they can stop
79+
advertising the experimental `htlc_endorsed` feature bit.
80+
81+
Sender:
82+
* MUST set the same value for experimental and protocol-range field.
83+
84+
Receiver:
85+
* if the protocol-range TLV is present:
86+
* MUST interpret its value as the `endorsed` signal for the HTLC.
87+
otherwise, if the experimental TLV is present:
88+
* SHOULD interpret the experimental value as the `endorsed` signal
89+
for the HTLC.
90+
91+
2. Wait until the `htlc_endorsed` feature is no longer widely signaled on the
92+
network, and implementations have gone through a release cycle to provide
93+
the upgrade.
94+
95+
3. Deprecate use of experimental field.
96+
97+
Sender:
98+
* MUST set the protocol-range field.
99+
* MUST NOT set the experimental range field.
100+
101+
Receiver:
102+
* MUST interpret the protocol-range field as the `endorsed` value for the HTLC.
103+
104+
## Motivation
105+
106+
The emergent properties of network-wide changes to Lightning are difficult to
107+
fully grasp without gathering real world data. This bLIP outlines a lightweight
108+
and reversible mechanism to assess the impact of this change so that we can
109+
direct further specification in an informed manner.
110+
111+
## Rationale
112+
113+
Endorsement signals are copied from the incoming `update_add_htlc` to allow
114+
positive signals to propagate through the network. Nodes wishing to participate
115+
in active experimentation may set this signal according to their local
116+
reputation algorithm, and this signal will be passively propagated by the
117+
remainder of the route that is simply copying incoming values.
118+
119+
A flag day is included to mitigate privacy concerns that setting the
120+
endorsement signal on payments will expose the identity of the original sender.
121+
Nodes participating in the experiment will signal the `htlc_endorsed` feature
122+
in their node announcement to help chose an appropriate `flag_day`. Once a
123+
sufficient portion of the network is upgraded to relay these signals, the
124+
presence of positive endorsement does not expose the sender as the original
125+
source of the HTLC. Senders are also advised to only set a positive endorsement
126+
signal for some percentage of payments to further protect sender privacy.
127+
128+
The `endorsed` TLV is encoded as a single `byte` rather than a boolean to allow
129+
flexible experimentation. HTLCs that are not endorsed include a TLV with a zero
130+
value byte so that they can be distinguished from those with no endorsement
131+
signal, which can be filtered out of experimental data as null values.
132+
133+
This experiment is opened as a bLIP because it is not intended to be a
134+
permanent part of the lightning specification. Should endorsement signaling be
135+
accepted to the BOLTs, the network can cleanly upgrade by setting the same
136+
value for the protocol and experimental range TLV, and deprecate the
137+
experimental TLV over time.
138+
139+
## Reference Implementations
140+
141+
* [LND](https://github.com/lightningnetwork/lnd/pull/8390)

0 commit comments

Comments
 (0)