Skip to content

Commit 5ea2017

Browse files
carlaKCcarlaKC
authored
blip-0004: add experimental HTLC endorsement signaling (#27)
1 parent 43d18b5 commit 5ea2017

File tree

3 files changed

+157
-5
lines changed

3 files changed

+157
-5
lines changed

‎README.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,10 @@ 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 |
2829
| [25](./blip-0025.md) | Forward less than onion value | Valentine Wallace | Active |
2930
| [32](./blip-0032.md) | Onion Message DNS Resolution | Matt Corallo | Active |
31+

‎blip-0002.md

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

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

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

5455
### Messages
5556

@@ -128,6 +129,14 @@ The following table contains tlv fields for use in onion messages as the payload
128129
| 65536 | `dnssec_query` | [bLIP 32](./blip-0032.md) |
129130
| 65538 | `dnssec_proof` | [bLIP 32](./blip-0032.md) |
130131

132+
#### `update_add_htlc`
133+
134+
The following table contains extension tlv fields for the `update_add_htlc` message:
135+
136+
| Type | Name | Link |
137+
|--------|-----------------------------|--------------------------------|
138+
| 106823 | `endorsed` | [bLIP 4](./blip-0004.md) |
139+
131140
## Copyright
132141

133142
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, expressed as unix time (seconds):
26+
* `experiment_start`: TODO: set once feature bit is widely deployed
27+
* `experiment_end`: 1767225600
28+
29+
### Adding an HTLC: `update_add_htlc`:
30+
31+
1. `tlv_stream`: `update_add_htlc_tlvs`
32+
1. type: 106823(`endorsed`)
33+
2. data:
34+
* [`byte`:`endorsed`]
35+
36+
The 3 least significant bits of the endorsement TLV are used to represent an
37+
endorsement value. A HTLC is considered to be endorsed if it is received
38+
with `endorsed`=7 and unendorsed if `endorsed=0`.
39+
40+
Sender:
41+
* If the current time is less than `experiment_end`:
42+
* if it is the original source of the HTLC:
43+
* if the current time is greater than or equal to `experiment_start`:
44+
* if it does not expect immediate fulfillment upon receipt by the
45+
final destination:
46+
* SHOULD set `endorsed` to `0`.
47+
* otherwise:
48+
* SHOULD set `endorsed` to `7`.
49+
* otherwise:
50+
* SHOULD set `endorsed` to `0`
51+
* MAY choose to set `endorsed` to `0` for some percentage of payments to
52+
prevent leaking its identity as the original sender.
53+
54+
Receiver:
55+
* If the current time is less than `experiment_end`:
56+
* if running an experimental reputation algorithm:
57+
* SHOULD set `endorsed` at its discretion.
58+
* otherwise:
59+
* if `endorsed`=7 in the incoming `update_add_htlc`:
60+
* SHOULD set `endorsed`=7 on its outgoing `update_add_htlc`
61+
* otherwise:
62+
* SHOULD set `endorsed` to `0`.
63+
* MUST NOT use the experimental `endorsed` field in resource allocation
64+
decisions.
65+
66+
## Deployment and Deprecation
67+
68+
### Deployment
69+
70+
Forwarding nodes can upgrade and begin to set `endorsed` signals immediately,
71+
as there is no privacy risk associated with propagating zero values. Feature
72+
bit signaling and a flag day are used to allow senders to set `endorsed` to `7`
73+
without leaking their identity as the original sender of the HTLC.
74+
75+
1. Nodes on the network upgrade to support sending and forwarding zero value
76+
`endorsed` signals.
77+
2. Choose a `experiment_start` parameter based on deployment of the
78+
`htlc_endorsed` signal on the network.
79+
3. After `experiment_start` has passed, sending nodes start to set `endorsed`
80+
to `7` as described above.
81+
4. When `experiment_end` is reached, sending node on the network stop setting
82+
the experimental `endorsed` field and intermediate nodes will stop
83+
relaying it, so the signal will cease to propagate through the network.
84+
85+
### Deprecation
86+
87+
If `endorsement` is merged to the BOLTs, the experimental field will naturally
88+
be deprecated when `experiment_end` is reached.
89+
90+
1. Nodes on the network may freely use an endorsement signal defined by the
91+
BOLTs, even if `experiment_end` has not yet been reached, as the experimental
92+
signal described in this bLIP is distinct from one outlined in the BOLTs.
93+
2. Once `experiment_end` has been reached, all nodes will stop relaying the
94+
experimental signal.
95+
3. In the next release, experimental code can safely be removed as it has been
96+
deprecated across the network.
97+
98+
## Motivation
99+
100+
The emergent properties of network-wide changes to Lightning are difficult to
101+
fully grasp without gathering real world data. This bLIP outlines a lightweight
102+
and reversible mechanism to assess various reputation algorithms in a read-only
103+
setting so that we can direct further specification in an informed manner.
104+
105+
## Rationale
106+
107+
Endorsement signals are copied from the incoming `update_add_htlc` to allow
108+
positive signals to propagate through the network. Nodes wishing to participate
109+
in active experimentation may set this signal according to their local
110+
reputation algorithm, and this signal will be passively propagated by the
111+
upgraded portion of the route. This experimental signal is used to observe
112+
the behavior of reputation algorithms under real-world conditions, but is not
113+
used to allocate resources so that the experiment does not impact payment
114+
traffic.
115+
116+
A flag day is included to mitigate privacy concerns that setting the
117+
endorsement signal on payments will expose the identity of the original sender.
118+
Nodes participating in the experiment will signal the `htlc_endorsed` feature
119+
in their node announcement to help chose an appropriate `experiment_start`.
120+
Once a sufficient portion of the network is upgraded to relay these signals, the
121+
presence of positive endorsement does not expose the sender as the original
122+
source of the HTLC. Senders are also advised to only set a positive endorsement
123+
signal for some percentage of payments to further protect sender privacy.
124+
125+
The `endorsed` TLV is encoded as a single `byte` rather than a boolean to allow
126+
flexible experimentation. Three bits of information are used to represent
127+
endorsement to allow for the future possibility of experimentation that relies
128+
on a range of endorsement values. HTLCs that are not endorsed include a TLV
129+
with a zero value byte so that they can be distinguished from those with no
130+
endorsement signal, which can be filtered out of experimental data as null
131+
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. If a BOLT with endorsement
135+
signaling is merged to the BOLTs, the two signals can be handled independently
136+
and the experimental signal described in this bLIP can be removed after the
137+
end of the experimental period.
138+
139+
## Reference Implementations
140+
141+
* [LND](https://github.com/lightningnetwork/lnd/pull/8390)

0 commit comments

Comments
 (0)