From eb4684bb58c4b2fe3c82cde9afe06ab5d3a6c9e5 Mon Sep 17 00:00:00 2001 From: t-bast Date: Thu, 27 Mar 2025 16:35:56 +0100 Subject: [PATCH] blip-0060: trampoline payments to legacy Bolt11 invoices [Trampoline routing](https://github.com/lightning/bolts/pull/836) allows nodes to send payments with limited access to the network graph, by relying on trampoline nodes to compute the missing parts of the route. The BOLTs only specify how such payments can be made to recipients who either support the trampoline feature or use Bolt12 with a blinded path. This leaves a gap when paying legacy nodes that don't support any of those features. This bLIP provides a mechanism to pay such legacy invoices, by revealing some of the invoice data to the last trampoline node, who converts the trampoline payment to a standard payment. --- README.md | 1 + blip-0002.md | 18 +++++----- blip-0060.md | 99 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 110 insertions(+), 8 deletions(-) create mode 100644 blip-0060.md diff --git a/README.md b/README.md index f2f8313..855c203 100644 --- a/README.md +++ b/README.md @@ -31,3 +31,4 @@ For more detail on the process, please read [bLIP-0001](./blip-0001.md) and | [50](./blip-0050.md) | LSPS0: LSP Spec Transport Layer | ZmnSCPxj jxPCSnmZ | Active | | [51](./blip-0051.md) | LSPS1: Channel Requests | Severin Bühler | Active | | [52](./blip-0052.md) | LSPS2: JIT Channel Negotiation | ZmnSCPxj jxPCSnmZ | Active | +| [60](./blip-0060.md) | Trampoline to legacy Bolt11 | Bastien Teinturier | Active | diff --git a/blip-0002.md b/blip-0002.md index f0e2937..2b315f8 100644 --- a/blip-0002.md +++ b/blip-0002.md @@ -33,6 +33,7 @@ network split. * [TLV fields in BOLT messages](#tlv-fields-in-bolt-messages) * [`init`](#init) * [`ping`](#ping) + * [`payment_onion_payload`](#payment_onion_payload) * [`update_add_htlc`](#update_add_htlc) * [Onion Messages](#onion-messages) @@ -98,12 +99,21 @@ The following table contains extension tlv fields for the `init` message: |-------|-----------------------------|--------------------------------| | 65536 | `tlv_field_name` | Link to the corresponding bLIP | +#### `ping` + +The following table contains extension tlv fields for the `ping` message: + +| Type | Name | Link | +|-------|-----------------------------|--------------------------------| +| 65536 | `tlv_field_name` | Link to the corresponding bLIP | + #### `payment_onion_payload` The following table contains extension tlv fields for the `payment_onion_payload` message: | Type | Name | Link | |-------------|-----------------------------|--------------------------------| +| 66099 | `bolt11_additional_routes` | [bLIP 60](./blip-0060.md) | | 7629169 | `podcasting_2_0` | [bLIP 10](./blip-0010.md) | | 5482373484 | `keysend_preimage` | [bLIP 3](./blip-0003.md) | @@ -116,14 +126,6 @@ The following table contains extension tlv fields for the `update_add_htlc` mess | 106823 | `endorsed` | [bLIP 4](./blip-0004.md) | | 65537 | `extra_fee` | [bLIP 25](./blip-0025.md) | -#### `ping` - -The following table contains extension tlv fields for the `ping` message: - -| Type | Name | Link | -|-------|-----------------------------|--------------------------------| -| 65536 | `tlv_field_name` | Link to the corresponding bLIP | - ### Onion Messages The following table contains tlv fields for use in onion messages as the payload type: diff --git a/blip-0060.md b/blip-0060.md new file mode 100644 index 0000000..eaf1dd8 --- /dev/null +++ b/blip-0060.md @@ -0,0 +1,99 @@ +``` +bLIP: 60 +Title: Trampoline payments to non-trampoline Bolt11 invoices +Status: Active +Author: Bastien Teinturier +Created: 2025-03-27 +License: CC0 +``` + +## Abstract + +[Trampoline routing](https://github.com/lightning/bolts/pull/836) allows nodes to send payments +with limited access to the network graph, by relying on trampoline nodes to compute the missing +parts of the route. The BOLTs only specify how such payments can be made to recipients who either +support the trampoline feature or use Bolt12 with a blinded path. This leaves a gap when paying +legacy nodes that don't support any of those features. + +This bLIP provides a mechanism to pay such legacy invoices, by revealing some of the invoice data +to the last trampoline node, who converts the trampoline payment to a standard payment. + +## Motivation + +This is a bLIP rather than a BOLT, because it's an imperfect solution that leaks details of the +payment to the trampoline node, and allows stealing funds from the payer when it overpays the +invoice amount (or if the invoice doesn't specify an amount). + +This should only be used to ensure a smooth transition to trampoline and Bolt12, at which point +we can retire this bLIP and rely on the official trampoline feature alone. + +## Specification + +### The `bolt11_additional_routes` TLV field + +We define a TLV field that can be included in payment onions and contains Bolt11 routing hints +(`r` fields from Bolt 11 invoices). + +1. `tlv_stream`: `payload` +2. types: + 1. type: 66099 (`bolt11_additional_routes`) + 2. data: + * [`...*bolt11_additional_route`:`routes`] + +1. subtype: `bolt11_additional_route` +2. data: + * [`u8`:`hops_count`] + * [`len*bolt11_route_hop`:`route`] + +1. subtype: `bolt11_route_hop` +2. data: + * [`point`:`node_id`] + * [`u64`:`short_channel_id`] + * [`u32`:`fee_base_msat`] + * [`u32`:`fee_proportional_millionths`] + * [`u16`:`cltv_expiry_delta`] + +#### Requirements + +When using trampoline to pay a Bolt11 invoice that does NOT have the `trampoline_routing` feature +bit set, in the onion payload for the last trampoline node in the `trampoline_onion_packet`, the +sending node: + +* MUST set `outgoing_node_id` to the `node_id` of the Bolt11 invoice. +* MUST set `amt_to_forward` to the amount that should be forwarded to this `node_id`. +* MUST set `outgoing_cltv_value` to the CLTV expiry that this `node_id` should receive. +* MUST set `payment_data` using the `payment_secret` from the invoice. +* If the Bolt11 invoice contains a `payment_metadata`: + * MUST set `payment_metadata` using the value from the invoice. +* MUST set `recipient_features` to match the feature of the invoice. +* If the invoice contains `r` fields, which are routes from a public node to the recipient: + * MUST set `bolt11_additional_routes`. + * SHOULD include as many routes from the invoice as possible, without overflowing the onion. + +The receiving node: + +* If it is the final hop of the `trampoline_onion_packet` and the trampoline onion payload + contains an `outgoing_node_id` that is different from the node itself: + * MUST send an outgoing payment to the `outgoing_node_id` provided. + * MUST NOT include a `trampoline_onion_packet`. + * MUST include the `payment_data` it received. + * MUST include the `payment_metadata` it received, if any. + * If `bolt11_additional_routes` is provided: + * SHOULD use those routing hints when finding routes to the recipient. + +## Note about 0-amount invoices + +If the Bolt11 invoice didn't contain an amount, the trampoline node can steal the intended +payment by sending a minimal amount to the recipient, who will accept it and reveal the +preimage, not knowing the amount that the payer really intended to send. The payer will not +be able to detect this, unless they communicate with the recipient out-of-band. Wallets may +display a warning when paying such invoices using this scheme. + +## Reference Implementations + +- eclair: +- lightning-kmp: + +## Copyright + +This bLIP is licensed under the CC0 license.