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

@@ -110,6 +110,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,92 @@
+```
+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`]
+
+If an `update_add_htlc` irrevocably committed after `flag_day`:
+
+Sender:
+* if it is the original source of the HTLC:
+  * 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`.
+
+## 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. 
+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
+
+* TODO