From 99b5fa1f69f397d3ee5128353fe4ac068eaa6991 Mon Sep 17 00:00:00 2001 From: Valentine Wallace Date: Mon, 22 May 2023 14:51:08 -0400 Subject: [PATCH] bLIP-0025: Allow forwarding HTLCs that underpay the onion encoded value --- README.md | 1 + blip-0002.md | 7 +++++++ blip-0025.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 64 insertions(+) create mode 100644 blip-0025.md diff --git a/README.md b/README.md index bba6b55..2f8096a 100644 --- a/README.md +++ b/README.md @@ -25,3 +25,4 @@ 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 | Valentine Wallace | Active | diff --git a/blip-0002.md b/blip-0002.md index 5efcc35..947527b 100644 --- a/blip-0002.md +++ b/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` diff --git a/blip-0025.md b/blip-0025.md new file mode 100644 index 0000000..3f032d7 --- /dev/null +++ b/blip-0025.md @@ -0,0 +1,56 @@ +``` +bLIP: 25 +Title: Allow forwarding HTLCs with less value than the onion claims to pay +Status: Draft +Author: Valentine Wallace +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 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 + +for invoice requirements if this feature is being used in the JIT channel context. + +## Reference Implementations +LDK: