Skip to content

blip-0060: trampoline payments to legacy Bolt11 invoices #60

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

blip-0060: trampoline payments to legacy Bolt11 invoices #60

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
18 changes: 10 additions & 8 deletions blip-0002.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down Expand Up @@ -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) |

Expand All @@ -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:
Expand Down
99 changes: 99 additions & 0 deletions blip-0060.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
```
bLIP: 60
Title: Trampoline payments to non-trampoline Bolt11 invoices
Status: Active
Author: Bastien Teinturier <[email protected]>
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: <https://github.com/ACINQ/eclair/pull/2819>
- lightning-kmp: <https://github.com/ACINQ/lightning-kmp/pull/688>

## Copyright

This bLIP is licensed under the CC0 license.