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

blip-0002.md

@@ -101,6 +101,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,61 @@
+```
+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
+
+Penultimate hop on the path:
+* In their outbound `update_add_htlc` message, MUST include a TLV record keyed by type 65537 with a
+  TLV value of `u64` containing the amount of extra fee they took from the receiver's final received
+  value, in millisatoshis
+
+Receiver:
+* MUST fail the HTLC if they did not expect an extra fee to be taken
+* MUST either accept or reject the HTLC as if it had received `htlc_value + extra_fee`
+* MUST reject the HTLC if the extra fee taken is too high
+
+## 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.
+
+In the JIT channel context, MPP should be disallowed unless the receiver can communicate to the LSP
+when all MPP parts have been aggregated, because otherwise the LSP may be at risk of wastefully
+opening a new channel for each MPP part.
+
+## Implementation notes
+If this feature is being used in the context of the penultimate hop opening a just-in-time channel
+to the receiver, MPP should be disabled in the invoice unless the recipient has a way to communicate
+to the penultimate hop when all MPP parts have been received. See
+<https://github.com/BitcoinAndLightningLayerSpecs/lsp/pull/22> "Invoice Generation" section.
+
+## Reference Implementations
+LDK: <https://github.com/lightningdevkit/rust-lightning/pull/2319>