bLIP-0025: Allow forwarding HTLCs that underpay the onion encoded value

Author: valentinewallace

README.md

@@ -25,4 +25,5 @@ For more detail on the process, please read [bLIP-0001](./blip-0001.md) and
 | [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 |
+| [25](./blip-0025.md)     | Forward less than onion value  | Valentine Wallace           | Active |
 | [32](./blip-0032.md)     | Onion Message DNS Resolution   | Matt Corallo                | Active |

blip-0002.md

@@ -103,6 +103,13 @@ The following table contains extension tlv fields for the `payment_onion_payload
 | 7629169     | `podcasting_2_0`            | [bLIP 10](./blip-0010.md)      |
 | 5482373484  | `keysend_preimage`          | [bLIP 3](./blip-0003.md)       |
 
+#### `update_add_htlc`
+
+The following table contains extension tlv fields for the `update_add_htlc` message:
+
+| Type  | Name                        | Link                           |
+|-------|-----------------------------|--------------------------------|
+| 65537 | `extra_fee`                 | [bLIP 25](./blip-0025.md)      |
 
 #### `ping`
 

blip-0025.md

@@ -0,0 +1,63 @@
+```
+bLIP: 25
+Title: Allow forwarding HTLCs with less value than the onion claims to pay
+Status: Draft
+Author: Valentine Wallace <[email protected]>
+Created: 2023-05-22
+License: CC0
+```
+
+## Abstract
+
+Penultimate hops in lightning payment paths may want to take an extra fee from the payee's final
+received value. To do so, they can simply forward less than the amount encoded in the onion by the
+sender, and specify the exact fee they took in a new `update_add_htlc` TLV for the receiver to
+verify.
+
+## Copyright
+
+This bLIP is licensed under the CC0 license.
+
+## Specification
+
+We define a TLV field for `update_add_htlc` that allows a relaying node to
+relay a smaller amount than the amount encoded in the onion:
+
+1. `tlv_stream`: `update_add_htlc_tlvs`
+2. types:
+    1. type: 65537 (`extra_fee`)
+    2. data:
+        - [`u64`:`amount_msat`]
+
+The writer:
+* MUST set `extra_fee` to the amount of extra fee they took from the receiver's final value
+
+The receiver:
+* MUST fail the HTLC if they did not expect an extra fee to be taken or if the extra fee taken is
+  too high
+* MUST either accept or reject the HTLC as if it had received `htlc_value + extra_fee`
+
+## Motivation
+
+For context, it is expected that many lightning users will be connected to the lightning network via
+Lightning Service Providers (LSPs), who are responsible for managing channel liquidity on end users'
+behalf.
+
+Often, users are onboarded to these services via a just-in-time inbound channel when they first
+receive a payment. However, this channel open costs money, and so liquidity providers may want to
+take an extra fee so that users can help bear the cost of this initial on-chain fee.
+
+## Rationale
+
+While it would be possible to avoid the extra TLV record if receivers could be trusted to calculate
+that the fee taken by the penultimate hop is as-expected, in practice this may be tricky to get
+right. If there were a bug in this logic, a sender could exploit it by forwarding less than the
+invoice's expected value, and receive proof-of-payment that they paid the full value.
+
+## Implementation Notes
+See
+<https://github.com/BitcoinAndLightningLayerSpecs/lsp/tree/main/LSPS2#3--invoice-generation>
+for invoice requirements if this feature is being used in the JIT channel context.
+
+## Reference Implementations
+LDK: <https://github.com/lightningdevkit/rust-lightning/pull/2319>