blip-0004: add experimental HTLC endorsement signaling

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 |

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.

blip-0004.md

@@ -0,0 +1,141 @@
+```
+bLIP: 4
+Title: Experimental Endorsement Signaling
+Status: Active
+Author: Carla Kirk-Cohen <[email protected]>
+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)