Skip to content

LSPS2: Support splice-in for JIT provisioning #65

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

LSPS2: Support splice-in for JIT provisioning #65

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
61 changes: 50 additions & 11 deletions blip-0052.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -159,8 +159,9 @@ Overview:
* The client hands the invoice to whoever it will receive funds from.
* The payment is forwarded to the LSP.
* The LSP recognizes the next hop SCID as being a JIT channel request,
and opens a 0-confirmation channel to the client, which must be
connected to the LSP at that time.
and either opens a 0-confirmation channel to the client or performs a
splice-in on an existing channel. The client must be connected to the LSP
during this step.
* The LSP forwards the payment to the client, deducting the channel
opening fee.
* The client claims the payment.
Expand Down Expand Up @@ -809,20 +810,23 @@ where the next hop is `jit_channel_scid`, before
* MUST check that `opening_fee + htlc_minimum_msat <= htlc_value_msat`,
and if that fails, MUST fail with `unknown_next_peer`.

### 5. Channel Opening And Forwarding
### 5. Channel Provisioning And Forwarding

The LSP requests a channel open to the client via standard
[BOLT2 Channel Establishment][] flow.
The LSP requests a channel open to the client or negotiates a splice-in on
an existing channel with the client, via standard [BOLT2 Channel Establishment][]
or [Splicing][] flows.

[BOLT2 Channel Establishment]: https://github.com/lightning/bolts/blob/c4c5a8e5fb30b1b99fa5bb0aba7d0b6b4c831ee5/02-peer-protocol.md#channel-establishment
[Splicing]: https://github.com/lightning/bolts/pull/1160/files

The LSP selects the channel size.
The LSP MUST ensure the channel is large enough to transmit the
`payment_size_msat - opening_fee`, plus any reserve needed on the LSP
side.
The LSP determines the funding delta and resulting channel balances.
The LSP MUST ensure the resulting channel balances allow forwarding at least
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we discussed this elsewhere, but I do think it would be easier in terms of backwards compat., "no surprisees", etc, if we mandate that the LSP always splices in at least payment_size_msat. I.e., the open_channel flow would be untouched, and if the LSP splices it's required to add exactly the same liquidity to the channel as if it was opening a new channel.

You already solve this with the paragraph below, but here, we also need to clarify the new balance should be at least old_balance + payment_size_msat - opening_fee.

`payment_size_msat - opening_fee`, plus any reserve needed on the LSP side.

The LSP and client MUST negotiate these options and parameters in
their [BOLT2 Channel Establishment][] flow:
The LSP MAY choose to splice-in instead of open a new channel.

If opening a new channel, the LSP and client MUST negotiate the following in their
[BOLT2 Channel Establishment][] flow:

* `option_scid_alias` is set.
* `announce_channel` is `false`.
Expand All @@ -835,6 +839,41 @@ their [BOLT2 Channel Establishment][] flow:
>
> `option_scid_alias` requires that `announce_channel` be `false`.

Splicing Option:

* If the LSP and client already share a channel that supports splicing (i.e.,
splicing was negotiated for that specific channel per [Splicing][]),
the LSP MAY satisfy an LSPS2 buy by performing a splice-in instead of opening
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SHOULD?

a new channel. This choice does not change any LSPS2 messages or parameters
and is transparent to the client.
* When choosing splicing, the LSP SHOULD splice-in the full amount of the
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's make this SHOULD a MUST, otherwise it might become very confusing to the client how to track balances/what to expect. If the LSP can use previously-paid liquidity to forward the payment, the client would either be doulby charged or would need to have a way to learn about this beforehand to be able to reevaluate which fee rate offering they deem acceptable. To keep it simple, we need to require splicing to be 1:1 the same contract as opening a new channel.

incoming payment (subject to the same fee deductions defined in this bLIP),
so the client can receive the entire payment without additional steps.

> **Rationale** LSPS2 aims to provision enough inbound liquidity for the
> incoming payment. Whether this is done via a new channel or a splice-in is
> an implementation choice with no changes to LSPS2 messages or parameters.
> Allowing splice-in avoids unnecessary new channels and improves liquidity
> management.

When forwarding after splicing:

* If satisfying an LSPS2 buy via splice-in, the LSP MUST forward only after the
channel is no longer quiescent, i.e., after both peers have exchanged the
`tx_signatures` message for the splice transaction per [Splicing][]. The LSP
MUST NOT require the `splice_locked` message before forwarding.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm why MUST NOT here?

* If the client disconnects or the splice negotiation fails before `tx_signatures`
are exchanged, the LSP MUST fail the incoming payment parts with
`temporary_channel_failure`.

Timeouts and fallback:

* The `opening_fee_params.valid_until` also applies to splice negotiation. If a
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we also need to clarify how the min_lifetime of the channel is changed during splice-in?

Note this might be an issue where we get to the limits of what is easily expressible with LSPS2: if the client already is close to the end of the lifetime of the original channel, the LSP probably doesn't want to renew the full channel for the opening fee of the new incoming payment.

So the LSP has three options:

  1. Price-in the TLV of the previously-provisioned liquidity into the offering for the new payment (although that is race-y, given the valid_until periods could overlap). That in turn means that the client sees higher rates from their LSP, without explicitly knowing why/what they're getting into.
  2. Still default to open_channel to keep the two flows independent.
  3. Decidedly splice-out the original balance some time after the min_lifetime. Maybe we should clarify that this is an option for the LSP here, which makes it all the more important that they MUST add the full payment_size_msat on top rather than 'merging' the channel balances.

splice cannot complete before `valid_until`, the LSP MAY fail the buy or fall
back to opening a new channel.
* If splicing cannot be negotiated or no splicing-capable channel exists with
the client, the LSP MAY open a new channel instead.

Clients MAY reject the channel open attempt if any other
parameters or options are not desired by the client (for example,
it MAY reject non-zero channel reserve requirements imposed on
Expand Down