From 1bad9b214ade5d60cf2e28c84a91162f234c44c3 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 | 63 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 71 insertions(+) create mode 100644 blip-0025.md diff --git a/README.md b/README.md index ffc79ec..602b3c7 100644 --- a/README.md +++ b/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 | diff --git a/blip-0002.md b/blip-0002.md index 15ad52f..14b104c 100644 --- a/blip-0002.md +++ b/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` diff --git a/blip-0025.md b/blip-0025.md new file mode 100644 index 0000000..a306ba4 --- /dev/null +++ b/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 +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 + +for invoice requirements if this feature is being used in the JIT channel context. + +## Reference Implementations +LDK: