Channel Splicing (feature 62/63)

[t-bast]

Splicing allows spending the current funding transaction to replace it with a new one that changes the capacity of the channel, allowing both peers to add or remove funds to/from their channel balance.

Splicing takes place while a channel is quiescent, to ensure that both peers have the same view of the current commitments.

We don't want channels to be unusable while waiting for transactions to confirm, so channel operation returns to normal once the splice transaction has been signed and we're waiting for it to confirm. The channel can then be used for payments, as long as those payments are valid for every pending splice transactions. Splice transactions can be RBF-ed to speed up confirmation.

Once one of the pending splice transactions confirms and reaches acceptable depth, peers exchange splice_locked to discard the other pending splice transactions and the previous funding transaction. The confirmed splice transaction becomes the channel funding transaction.

Nodes then advertise this spliced channel to the network, so that nodes keep routing payments through it without any downtime.

This PR replaces #863 which contains a lot of legacy mechanisms for early versions of splicing, which didn't work in some edge cases (detailed in the test vectors provided in this PR). It can be very helpful to read the protocol flows described in the test vector: they give a better intuition of how splicing works, and how it deals with message concurrency and disconnections.

This PR requires the quiescence feature (#869) to start negotiating a splice.

Credits to @rustyrussell and @ddustin will be added in the commit messages once we're ready to merge this PR.

[ProofOfKeags]

Can I suggest we do this as an extension BOLT rather than layering it in with the existing BOLT2 text? It makes it easier to implement when all of the requirements deltas are in a single document than when it is inlined into the original spec. Otherwise, the PR/branch-diff itself is the only way to see the diff and that can get very messy during the review process as people's commentary comes in. While there are other ways to get at this diff without the commentary, it would make the UX of getting at this diff rather straightforward.

Given that the change is gated behind a feature bit anyway it also makes it easier for a new implementation to bootstrap itself without the splice feature by just reading the main BOLTs as is.

At some point in the future when splicing support becomes standard across the network we can consolidate the extension BOLT into the main BOLTs if people still prefer.

[t-bast]

Why not, if others also feel that it would be better as an extension bolt. I prefer it directly in Bolt 2, because of the following reasons:

• Most of it is self contained in its own section(s) anyway.
• It's an important part of the channel lifecycle: channels are opened, then during normal operation payments are relayed and splices happen, then the channel eventually closes. It is nicely reflected in the architecture of the Bolt 2 sections right now.
• The few additions to existing message TLVs (commit_sig, tx_add_input, tx_signatures) should not be in a separate document when merging, because otherwise different features may use the same TLV tags without realizing it, with a risk of inadvertently shipping incompatible code. I think it's important that all TLVs for a given message are listed in that message's section, this way you know you don't have to randomly search the BOLTs for another place where TLVs may be defined.

But if I'm the only one thinking this is better, I'll move it to a separate document!

One thing to note is that we already have two implementations (eclair and cln), and maybe a 3rd one (LDK) who are very close to code-complete and have had months of experience on mainnet, which means the spec is almost final and we should be able to to merge it to the BOLTs in the not-so-distant future (:crossed_fingers:).

[ddustin]

One thing I've been thinking about is with large splices across many nodes, if some node fails to send signatures (likely because two nodes in the cluster demand to sign last) than splice will hang one tx_signatures.

I believe we need two things to address this:

1. Timeout logic where splices are aborted
2. Being lax about having sent our tx_signatures but getting nothing back

Currently CLN fails the channel in this case as taking signatures and not responding is rather rude but this is bad because it could lead to clusters of splice channels being closed.

The unfortunate side effect of this is we have to be comfortable sending out signatures with no recourse for not getting any back.

I believe long term the solution is to maintain a signature-sending reputation for each peer and eventually blacklist peers from doing splices and / or fail your channels with that peer.

A reputation system may be beyond the needs of the spec but what to do with hanging tx_signatures (timeout etc) should be in the spec with a note about this problem.

[t-bast]

1. Timeout logic where splices are aborted

This is already covered at the quiescence level: quiescence will timeout if the splice doesn't complete (e.g. because we haven't received tx_signatures).

2. Being lax about having sent our tx_signatures but getting nothing back

I don't think this is necessary, and I think we should really require people to send tx_signatures when it is owed, to ensure that we get to a clean state on both peers.

if some node fails to send signatures (likely because two nodes in the cluster demand to sign last)

It seems like we've discussed this many times already: this simply cannot happen because ordering based on contributed amount fixes this? Can you detail a concrete scenario where tx_signatures ordering leads to a deadlock?

[ProofOfKeags]

What does it mean to have a channel reserve to "match the new channel capacity". AFAICT the channel_reserve is specified in satoshis and reading the negotiation process of this proposal doesn't seem to indicate that there is any change happening to that parameter during negotiation.

[t-bast]

AFAICT the channel_reserve is specified in satoshis

Not with dual-funding, where the channel reserve is 1% of the channel capacity. That's why this is potentially changing "automatically" when splicing on top of a dual-funded channel if we want to keep using 1%.

But you're right to highlight this: the channel reserve behavior is very loosely specified for now, and there were a lot of previous discussions with @morehouse regarding what we should do when splicing. Another edge case that we must better specify is what happens when splicing on top of a non-dual-funded channel, where the channel reserve was indeed a static value instead of a proportional one!

The channel reserve behavior is IMO the only missing piece of this specification, that we should discuss, thanks for bringing it up!

[ddustin]

Could be a good thing to discuss in Tokyo!

Also worth stepping back and double checking the reserve requirement makes sense in its current form generally 👀.

[t-bast]

What do you think of the following behavior for handling channel reserves:

• Whenever a splice happens, the channel is automatically enrolled into the 1% reserve policy, even if it wasn't initially a dual-funded channel (unless 0-reserve is used of course, see Add option_zero_reserve (FEATURE 64/65) #1140)
• Splice-out is not allowed if you end up below your pre-splice reserve (your peer will reject that splice with tx_abort)
• Otherwise, it's ok if one side ends up below the channel reserve after a splice: this is the same behavior as when a new channel is created. If we get into that state, the peer that is below the channel reserve:
  • is not allowed to send outgoing HTLCs
  • is allowed to receive incoming HTLCs
  • if it is paying the commit fees, it is allowed to dip further into its channel reserve to receive HTLCs (because of the added weight of the HTLC output), because we must be able to move liquidity to their side to get them above their reserve
• When there are multiple unconfirmed splices, we use the highest channel reserve of all pending splices (ie requirements must be satisfied for all pending splice transactions)

As discussed during yesterday's meeting, there are subtle edge cases due to concurrent updates: this is inherent to the current commitment protocol, but will eventually become much simpler with #867

@ddustin @ProofOfKeags @rustyrussell @ziggie1984 @morehouse

[ziggie1984]

related: ACINQ/eclair#2899 (comment), tries to specify the concurrent edge cases and also the requirement when we would already (without splicing) allow the peer paying the fees being dipped below its reserve.

[morehouse]

@t-bast

That all seems reasonable to me. The one part where we could get into trouble is:

if it is paying the commit fees, it is allowed to dip further into its channel reserve to receive HTLCs (because of the added weight of the HTLC output), because we must be able to move liquidity to their side to get them above their reserve

This allows the reserve to be violated, potentially all the way down to 0. In that situation, there is ~zero incentive to broadcast the latest commitment on force close.

That said, I know the implementation details are hairy to do things completely safely. And we can also look forward to zero-fee commitments with TRUC and ephemeral anchors, which would obsolete the "dip-into-reserve to pay fees" exception entirely.

[t-bast]

This allows the reserve to be violated, potentially all the way down to 0. In that situation, there is ~zero incentive to broadcast the latest commitment on force close.

Since we only allow this to happen when the node paying the fee receives HTLCs, the other node sending that HTLC can limit the exposure by controlling how many HTLCs they send in a batch (or keep pending the commit tx) when we're in this state.

There are unfortunately cases where even a single HTLC would make the node paying the fee have no output (small channels with high feerate), but when that happens you really don't have any other option, the channel is otherwise unusable, so your only other option is to force-close anyway which isn't great...

And we can also look forward to zero-fee commitments with TRUC and ephemeral anchors, which would obsolete the "dip-into-reserve to pay fees" exception entirely.

Exactly, this is coming together (look at this beautiful 0-fee commitment transaction: https://mempool.space/testnet4/tx/85f2256c8d6d61498c074d53912d1f0ef907ee508bb06f5701f3826432ba53b8) which will finally get rid of this kind of mess: I'm fine with using an imperfect but simple work-around in the meantime!

[ziggie1984]

I wonder if this requirement would solely be used for the splicing case, allowing HTLC which dip the opener into its reserve or should we make this an overall requirement. If so there is the problem with backwards compatibility, because older nodes (speaking for LND nodes) will force close if the opener dips below its reserve. So maybe it makes sense to only activate it for splicing use cases so that we don't run into the backwards compatibility issues ?

[t-bast]

Good idea!

[ddustin]

I added a PR to fix the spec for short_channel_id post-splice: t-bast#3

[ddustin]

@t-bast asked me to put together a summary for Richard on how to implement the short_channel_id changes for splice_locked. The process is fairly straight forward but I'll write out some contextual information around it that might be helpful:

1. When receiving splice_locked, mark that it was received in a variable, and call check_splice_locked
2. When splice seen on chain at depth, send splice_locked, mark that it was sent in a variable, save the txid of the locked transaction into splice_locked_txid, and call check_splice_locked
3. When reconnecting without a pending splice but peer expects one (rules as in spec), resend splice_locked
4. When check_splice_locked is called; If sent and receive variables are set, then:
   a) Clear send & receive variables
   b) Find the splice inflight that matches splice_locked_txid
   c) Set the channel's short_channel_id according to the locked tx
   d) Update channel funding amounts according to the confirmed splice
   e) Save it all to disk and clear all splice inflights and reset channel allsplice state variables to neutral

[t-bast]

@ddustin I've added more details for the announcement/gossip part in adf968c and finished implementing it in eclair. You can grab the last version of ACINQ/eclair#2887 for your cross-compatibility tests which should contain everything!

[t-bast]

Rebased to fix conflicts and squashed commits. Please carefully read the reconnection requirements, especially around handling of next_commitment_number: I have applied the same logic as #1214 to use next_commitment_number to indicate when we'd like commitment_signed to be retransmitted.

[optout21]

nit: I suggest funding_feerate_per_kw for consistency (in existing places it is already used as per_kw, not perkw).

[ddustin]

This should be changed to

    - if `next_funding_txid` matches the latest funding transaction
      or the matching splice transaction has reached acceptable depth:

This is because certain splice_locked disconnect flows result in neither side locking the splice into the latest funding transaction but splice_locked still needs to be resent during reestablish.

More discussion on this issue is in this thread: ddustin/lightning#6 (comment)