mirrors/lightning-blips
1
0
Fork 0
mirror of https://github.com/lightning/blips.git synced 2024-11-19 00:50:02 +01:00
Code Issues Projects Releases Wiki Activity

blip-0004: add experimental HTLC endorsement signaling (#27)

Browse Source
This commit is contained in:
Carla Kirk-Cohen 2024-08-08 02:43:14 -04:00 committed by GitHub
parent 43d18b5116
commit 5ea2017bfe
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 157 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@ -22,8 +22,10 @@ For more detail on the process, please read [bLIP-0001](./blip-0001.md) and
| [1](./blip-0001.md) | bLIP Process | Ryan Gentry | Active |
| [2](./blip-0002.md) | Reserved Values | Bastien Teinturier | Active |
| [3](./blip-0003.md) | Keysend | Valentine Wallace | Active |
| [4](./blip-0004.md) | Experimental Endorsement | Carla Kirk-Cohen | Active |
| [10](./blip-0010.md) | Podcasting 2.0 | Satoshis Stream | Active |
| [11](./blip-0011.md) | NameDesc | Hampus Sjöberg | Active |
| [17](./blip-0017.md) | Hosted Channels | Anton Kumaigorodskiy | Active |
| [25](./blip-0025.md) | Forward less than onion value | Valentine Wallace | Active |
| [32](./blip-0032.md) | Onion Message DNS Resolution | Matt Corallo | Active |

19
blip-0002.md
View File

@ -45,11 +45,12 @@ Custom feature bits used in the `I` [Bolt 11](https://github.com/lightning/bolts
bLIPs may reserve feature bits by adding them to the following table:
| Bits | Name | Description | Context | Dependencies | Link |
| --------- | ---------------------- | ------------------------------------------------- | ---------------- | -------------------------------- | -------------------------------- |
| 54/55 | `keysend` | A form of spontaneous payment | N | `var_onion_optin` | [bLIP 3](./blip-0003.md) |
| 256/257 | `hosted_channels` | This node accepts requests for hosted channels | IN | | [bLIP 17](./blip-0017.md) |
| 258/259 | `dns_resolver` | This node accepts DNSSEC proof requests | N | | [bLIP 32](./blip-0032.md) |
| Bits | Name | Description | Context | Dependencies | Link |
| --------- | ---------------------- | ----------------------------------------------------------- | ---------------- | -------------------------------- | -------------------------------- |
| 54/55 | `keysend` | A form of spontaneous payment | N | `var_onion_optin` | [bLIP 3](./blip-0003.md) |
| 256/257 | `hosted_channels` | This node accepts requests for hosted channels | IN | | [bLIP 17](./blip-0017.md) |
| 258/259 | `dns_resolver` | This node accepts DNSSEC proof requests | N | | [bLIP 32](./blip-0032.md) |
| 260/261 | `htlc_endorsement` | This node forwards experimental htlc endorsement signals | N | | [bLIP 4](./blip-004.md) |
### Messages
@ -128,6 +129,14 @@ The following table contains tlv fields for use in onion messages as the payload
| 65536 | `dnssec_query` | [bLIP 32](./blip-0032.md) |
| 65538 | `dnssec_proof` | [bLIP 32](./blip-0032.md) |
#### `update_add_htlc`
The following table contains extension tlv fields for the `update_add_htlc` message:
| Type | Name | Link |
|--------|-----------------------------|--------------------------------|
| 106823 | `endorsed` | [bLIP 4](./blip-0004.md) |
## Copyright
This bLIP is licensed under the CC0 license.

141
blip-0004.md Normal file
View File

@ -0,0 +1,141 @@
```
bLIP: 4
Title: Experimental Endorsement Signaling
Status: Active
Author: Carla Kirk-Cohen <carla@chaincode.com>
Created: 2024-01-12
License: CC0
```
## Abstract
HTLC endorsement signaling is a [proposed](https://github.com/lightning/bolts/pull/1071)
component of a [hybrid approach](https://research.chaincode.com/2022/11/15/unjamming-lightning)
to addressing [channel jamming attacks](https://bitcoinops.org/en/topics/channel-jamming-attacks)
against the Lightning Network. This bLIP outlines a proposal to deploy an
experimental endorsement TLV to the network to provide real world data to
inform specification of reputation algorithms.
## Copyright
This bLIP is licensed under the CC0 license.
## Specification
Experiment Parameters, expressed as unix time (seconds):
* `experiment_start`: TODO: set once feature bit is widely deployed
* `experiment_end`: 1767225600
### Adding an HTLC: `update_add_htlc`:
1. `tlv_stream`: `update_add_htlc_tlvs`
1. type: 106823(`endorsed`)
2. data:
* [`byte`:`endorsed`]
The 3 least significant bits of the endorsement TLV are used to represent an
endorsement value. A HTLC is considered to be endorsed if it is received
with `endorsed`=7 and unendorsed if `endorsed=0`.
Sender:
* If the current time is less than `experiment_end`:
* if it is the original source of the HTLC:
* if the current time is greater than or equal to `experiment_start`:
* if it does not expect immediate fulfillment upon receipt by the
final destination:
* SHOULD set `endorsed` to `0`.
* otherwise:
* SHOULD set `endorsed` to `7`.
* otherwise:
* SHOULD set `endorsed` to `0`
* MAY choose to set `endorsed` to `0` for some percentage of payments to
prevent leaking its identity as the original sender.
Receiver:
* If the current time is less than `experiment_end`:
* if running an experimental reputation algorithm:
* SHOULD set `endorsed` at its discretion.
* otherwise:
* if `endorsed`=7 in the incoming `update_add_htlc`:
* SHOULD set `endorsed`=7 on its outgoing `update_add_htlc`
* otherwise:
* SHOULD set `endorsed` to `0`.
* MUST NOT use the experimental `endorsed` field in resource allocation
decisions.
## Deployment and Deprecation
### Deployment
Forwarding nodes can upgrade and begin to set `endorsed` signals immediately,
as there is no privacy risk associated with propagating zero values. Feature
bit signaling and a flag day are used to allow senders to set `endorsed` to `7`
without leaking their identity as the original sender of the HTLC.
1. Nodes on the network upgrade to support sending and forwarding zero value
`endorsed` signals.
2. Choose a `experiment_start` parameter based on deployment of the
`htlc_endorsed` signal on the network.
3. After `experiment_start` has passed, sending nodes start to set `endorsed`
to `7` as described above.
4. When `experiment_end` is reached, sending node on the network stop setting
the experimental `endorsed` field and intermediate nodes will stop
relaying it, so the signal will cease to propagate through the network.
### Deprecation
If `endorsement` is merged to the BOLTs, the experimental field will naturally
be deprecated when `experiment_end` is reached.
1. Nodes on the network may freely use an endorsement signal defined by the
BOLTs, even if `experiment_end` has not yet been reached, as the experimental
signal described in this bLIP is distinct from one outlined in the BOLTs.
2. Once `experiment_end` has been reached, all nodes will stop relaying the
experimental signal.
3. In the next release, experimental code can safely be removed as it has been
deprecated across the network.
## Motivation
The emergent properties of network-wide changes to Lightning are difficult to
fully grasp without gathering real world data. This bLIP outlines a lightweight
and reversible mechanism to assess various reputation algorithms in a read-only
setting so that we can direct further specification in an informed manner.
## Rationale
Endorsement signals are copied from the incoming `update_add_htlc` to allow
positive signals to propagate through the network. Nodes wishing to participate
in active experimentation may set this signal according to their local
reputation algorithm, and this signal will be passively propagated by the
upgraded portion of the route. This experimental signal is used to observe
the behavior of reputation algorithms under real-world conditions, but is not
used to allocate resources so that the experiment does not impact payment
traffic.
A flag day is included to mitigate privacy concerns that setting the
endorsement signal on payments will expose the identity of the original sender.
Nodes participating in the experiment will signal the `htlc_endorsed` feature
in their node announcement to help chose an appropriate `experiment_start`.
Once a sufficient portion of the network is upgraded to relay these signals, the
presence of positive endorsement does not expose the sender as the original
source of the HTLC. Senders are also advised to only set a positive endorsement
signal for some percentage of payments to further protect sender privacy.
The `endorsed` TLV is encoded as a single `byte` rather than a boolean to allow
flexible experimentation. Three bits of information are used to represent
endorsement to allow for the future possibility of experimentation that relies
on a range of endorsement values. HTLCs that are not endorsed include a TLV
with a zero value byte so that they can be distinguished from those with no
endorsement signal, which can be filtered out of experimental data as null
values.
This experiment is opened as a bLIP because it is not intended to be a
permanent part of the lightning specification. If a BOLT with endorsement
signaling is merged to the BOLTs, the two signals can be handled independently
and the experimental signal described in this bLIP can be removed after the
end of the experimental period.
## Reference Implementations
* [LND](https://github.com/lightningnetwork/lnd/pull/8390)