diff --git a/README.md b/README.md index bba6b55..258af15 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,7 @@ 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 | diff --git a/blip-0002.md b/blip-0002.md index 5efcc35..91efa62 100644 --- a/blip-0002.md +++ b/blip-0002.md @@ -44,10 +44,11 @@ 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) | +| 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 | `htlc_endorsement` | This node forwards experimental htlc endorsement signals | N | | [bLIP 4](./blip-004.md) | ### Messages @@ -110,6 +111,15 @@ The following table contains extension tlv fields for the `ping` message: |-------|-----------------------------|--------------------------------| | 65536 | `tlv_field_name` | Link to the corresponding bLIP | +#### `update_add_htlc` + +The following table contains extension tlv fields for the `update_add_htlc` message: + + +| Type | Name | Link | +|--------|-----------------------------|--------------------------------| +| 106822 | `endorsed` | [bLIP 4](./blip-0004.md) | + ## Copyright This bLIP is licensed under the CC0 license. diff --git a/blip-0004.md b/blip-0004.md new file mode 100644 index 0000000..f4e1cdd --- /dev/null +++ b/blip-0004.md @@ -0,0 +1,141 @@ +``` +bLIP: 4 +Title: Experimental Endorsement Signaling +Status: Active +Author: Carla Kirk-Cohen +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: 106822(`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 otherwise. + +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)