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.