lightning-blips/blip-0004.md

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 component of a hybrid approach to addressing 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