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                           |
+|-------|-----------------------------|--------------------------------|
+| 65555 | `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 <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:
+* `flag_day`: [TODO]
+
+
+### Adding an HTLC: `update_add_htlc`:
+
+1. `tlv_stream`: `update_add_htlc_tlvs`
+    1. type: 65555 (`endorsed`)
+    2. data:
+        * [`byte`:`endorsed`]
+
+Sender:
+* if it is the original source of the HTLC and `flag_day` has passed:
+  * if it does not expect immediate fulfillment upon receipt by the 
+    final destination: 
+    * SHOULD set `endorsed` to `0`.
+  * otherwise:  
+    * SHOULD set `endorsed` to `1`.
+* MAY choose to set `endorsed` to `0` for some percentage of payments to 
+  prevent leaking its identity as the original sender.
+
+Receiver:
+* if `endorsed` is present and non-zero in the `update_add_htlc`:
+  * if running an experimental reputation algorithm:
+      * SHOULD set `endorsed` as specified by the algorithm.
+    otherwise:
+      * SHOULD set `endorsed` to `1`.
+* otherwise: 
+  * SHOULD set `endorsed` to `0`.
+
+## Deployment and Deprecation
+
+### Deployment 
+
+Forwarding nodes can upgrade and being 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 `1`
+without leaking their identity as the original sender of the HTLC.
+
+1. Nodes on the network upgrade to support forwarding `endorsed` signals. 
+2. Choose a `flag_day` parameter based on deployment of the `htlc_endorsed` 
+   signal on the network.
+3. After `flag_day` has passed, sending nodes start to set `endorsed` to `1` 
+   as described above.
+
+### Deprecation
+
+If `endorsement` is merged to the BOLTs, the experimental signal can be 
+deprecated in favor of the protocol-range field. If it is not, the signal 
+can simply be deleted with no deprecation period.
+
+1. Upgrade to protocol-range field: 
+
+  Once nodes are updated to use the protocol-range field, they can stop
+  advertising the experimental `htlc_endorsed` feature bit.
+
+  Sender:
+  * MUST set the same value for experimental and protocol-range field.
+
+  Receiver:
+  * if the protocol-range TLV is present: 
+    * MUST interpret its value as the `endorsed` signal for the HTLC.
+    otherwise, if the experimental TLV is present: 
+    * SHOULD interpret the experimental value as the `endorsed` signal 
+      for the HTLC.
+
+2. Wait until the `htlc_endorsed` feature is no longer widely signaled on the 
+   network, and implementations have gone through a release cycle to provide 
+   the upgrade.
+
+3. Deprecate use of experimental field.
+
+  Sender: 
+  * MUST set the protocol-range field.
+  * MUST NOT set the experimental range field.
+
+  Receiver: 
+  * MUST interpret the protocol-range field as the `endorsed` value for the HTLC.
+
+## 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 the impact of this change 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 
+remainder of the route that is simply copying incoming values.
+
+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 `flag_day`. 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. 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. Should endorsement signaling be 
+accepted to the BOLTs, the network can cleanly upgrade by setting the same 
+value for the protocol and experimental range TLV, and deprecate the 
+experimental TLV over time.
+
+## Reference Implementations
+
+* [LND](https://github.com/lightningnetwork/lnd/pull/8390)