Exchange `splice_locked` messages #3741

jkczyz · 2025-04-16T17:11:41Z

After a splice has been negotiated, each party must send a splice_locked message to the other party once the splice transaction has had an acceptable number of confirmations. Update the logic for processing newly confirmed transactions and updated best block to send splice_locked when appropriate.

Likewise, handle splice_locked and promote the channel's FundingScope once both splice_locked messages have been exchanged. At this point, a ChannelReady event is emitted to indicate that the new funding is ready for use.

ldk-reviews-bot · 2025-04-16T17:11:44Z

👋 Thanks for assigning @wpaulino as a reviewer!
I'll wait for their review and will help manage the review process.
Once they submit their review, I'll check if a second reviewer would be helpful.

jkczyz · 2025-04-16T17:13:51Z

The logic around determining if the splice_locked messages have been exchanged is still a work in progress. It may need to be re-considered to work with chained 0-conf splices. See lightning/bolts#1160 (comment).

jkczyz · 2025-04-18T23:17:53Z

@wpaulino Ok, this is in better shape for a high-level look. I don't believe it correctly handles unconfirmed splice transactions yet. Also, doesn't yet re-send splice_locked on channel reestablishment, thought that may come in a follow-up.

codecov · 2025-04-18T23:24:11Z

Codecov Report

Attention: Patch coverage is 86.16505% with 57 lines in your changes missing coverage. Please review.

Project coverage is 90.34%. Comparing base (7b45811) to head (ef048e6).
Report is 82 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning/src/ln/channel.rs	90.24%	27 Missing and 5 partials ⚠️
lightning/src/events/mod.rs	0.00%	23 Missing ⚠️
lightning/src/ln/channelmanager.rs	96.15%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3741      +/-   ##
==========================================
+ Coverage   89.10%   90.34%   +1.24%     
==========================================
  Files         156      158       +2     
  Lines      123431   135603   +12172     
  Branches   123431   135603   +12172     
==========================================
+ Hits       109985   122515   +12530     
+ Misses      10760    10568     -192     
+ Partials     2686     2520     -166

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

ldk-reviews-bot · 2025-04-19T00:00:14Z

🔔 1st Reminder

Hey @wpaulino! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

optout21

LGTM. The preparational changes are very clear. The WIP part also makes sense so far.

lightning/src/ln/channelmanager.rs

lightning/src/ln/channel.rs

ldk-reviews-bot · 2025-04-21T00:00:36Z

🔔 2nd Reminder

Hey @wpaulino! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

lightning/src/ln/channel.rs

jkczyz

Addressed most comments other than adding an event and for re-sending splice_locked. See comment replies for open questions.

Also, added code to insert the new scid in short_to_chan_info. Should we remove the old one?

lightning/src/ln/channel.rs

lightning/src/ln/channelmanager.rs

jkczyz · 2025-04-30T17:32:04Z

Squashed fixups

wpaulino · 2025-04-30T18:23:22Z

An offline discussion we had around DiscardFunding: we still need to emit one for splices if we negotiated one but it cannot confirm due to the channel closing via a commitment broadcast of the pre-splice FundingScope or a co-op close. Easiest way to handle this may be in transactions_confirmed where we already check for spending transactions of the channel to consider it closed.

TheBlueMatt · 2025-04-30T19:52:59Z

lightning/src/ln/channelmanager.rs

@@ -3026,7 +3026,7 @@ macro_rules! locked_close_channel {
 		// into the map (which prevents the `PeerState` from being cleaned up) for channels that
 		// never even got confirmations (which would open us up to DoS attacks).
 		let update_id = $channel_context.get_latest_monitor_update_id();
-		if $channel_context.get_funding_tx_confirmation_height().is_some() || $channel_context.minimum_depth() == Some(0) || update_id > 1 {
+		if $channel_funding.get_funding_tx_confirmation_height().is_some() || $channel_context.minimum_depth() == Some(0) || update_id > 1 {


I thought we agreed to try to keep the concept of funding scopes outside of ChannelManager? I think for this we can move to a is_funding_confirmed_or_0conf call or something?

This macro doesn't have access to the channel, only the context which doesn't have reference to the funding scope. So it would require much more re-work than I'd like to do in this PR.

Instead, I'd rather make a separate PR after all the changes needed for FundingScope are complete. Hopefully in a couple PRs.

Oh, also forgot to drop these two commits since one reverts the previous one. But the general idea still stands for other occurrences.

Tried to avoid this but the problem is that locked_close_channel is called throughout the file including by convert_channel_err, which likewise is called throughout. Additionally, convert_channel_err has a rule that expects a FundedChannel so that it can pass it to get_channel_update_for_broadcast.

Might be a way to refactor this but I think it should wait for a follow-up given it's not going to be straightforward.

lightning/src/ln/channelmanager.rs

TheBlueMatt · 2025-04-30T19:54:00Z

lightning/src/ln/channelmanager.rs

@@ -3031,7 +3031,7 @@ macro_rules! locked_close_channel {
 			$peer_state.closed_channel_monitor_update_ids.insert(chan_id, update_id);
 		}
 		let mut short_to_chan_info = $self.short_to_chan_info.write().unwrap();
-		if let Some(short_id) = $channel_context.get_short_channel_id() {
+		if let Some(short_id) = $channel_funding.get_short_channel_id() {


Same here, can we avoid this change?

Similarly, we'd need this to take a Channel instead of a ChannelContext, but the problem is that convert_channel_err needs a FundedChannel for one rule as mentioned in another comment. Maybe we eventually just add any methods called from those macros on both Channel and each sub-struct so that it can be used either way?

jkczyz · 2025-05-01T16:28:39Z

An offline discussion we had around DiscardFunding: we still need to emit one for splices if we negotiated one but it cannot confirm due to the channel closing via a commitment broadcast of the pre-splice FundingScope or a co-op close. Easiest way to handle this may be in transactions_confirmed where we already check for spending transactions of the channel to consider it closed.

Separate but related to this, I'm wondering now which FundingScope should be used to populate ShutdownResult when we see the commitment transaction of a pending splice confirm presumably in the same block that the splice funding confirmed.

Currently, we use the pre-splice FundingScope since the flow is:

ChannelManager::do_chain_event calls
FundedChannel::transactions_confirmed which returns ClosureReason to
ChannelManager::do_chain_event which calls
ChannelContext::force_shutdown with the ClosureReason and FundedChannel::funding and returns a ShutdownResult

After that locked_close_channel! is called with the ShutdownResult and FundedChannel::funding. Then ChannelManager::get_channel_update_for_broadcast which uses the pre-splice FundingScope. Then finally ChannelManager::finish_close_channel is called with the ShutdownResult.

So in the scenario described above, should we transition to the pending FundingScope that was just confirmed and spent -- before calling ChannelContext::force_shutdown -- so that it is reflected in ShutdownResult? We may need to also generate an Event::SpliceLocked, too.

Then that way for Event::DiscardFunding we simply include info for any pending funding scopes in ShutdownResult in order to produce that event. And in the case of transitioning to a pending FundingScope first, we'd avoid producing Event::DiscardFunding since it would not be desired in that situation.

Related discussion: #3592 (comment)

jkczyz · 2025-05-01T22:07:40Z

An offline discussion we had around DiscardFunding: we still need to emit one for splices if we negotiated one but it cannot confirm due to the channel closing via a commitment broadcast of the pre-splice FundingScope or a co-op close. Easiest way to handle this may be in transactions_confirmed where we already check for spending transactions of the channel to consider it closed.

Separate but related to this, I'm wondering now which FundingScope should be used to populate ShutdownResult when we see the commitment transaction of a pending splice confirm presumably in the same block that the splice funding confirmed.

Discussed offline with @TheBlueMatt and @wpaulino. The two scenarios are closing while funding negotiation takes place and while waiting for the splice to confirm. For the latter, it would be better to a have general approach in ChannelMonitor for determining if an Event::DiscardFunding should be emitted. So no changes necessary in this PR.

For the former, we won't have a ChannelMonitor so we will need to emit the event in ChannelManager whenever the user has contributed inputs. I'd imagine we need to keep track of this in PendingSplice and return it to ChannelManager somehow. Also, since we won't have a funding transaction or a funding txo during negotiation, we'd need a new FundingInfo variant for the contributed inputs to use in Event::DiscardFunding, IIUC. (cc: @optout21 @dunxen)

jkczyz · 2025-05-07T16:29:00Z

Pushed some fixups to hopefully fix CI. Also, updated the WIP commit message.

jkczyz · 2025-05-07T16:51:20Z

One more fixup...

ldk-reviews-bot · 2025-05-07T18:27:17Z

🔔 1st Reminder

Hey @TheBlueMatt @dunxen @wpaulino! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-05-08T20:55:29Z

🔔 1st Reminder

Hey @TheBlueMatt @dunxen @wpaulino! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

jkczyz · 2025-06-12T22:53:49Z

Squashed! Rebase incoming...

jkczyz · 2025-06-12T23:09:44Z

Rebased. Will likely need to rustfmt some methods that were added (or add a skip).

When processing confirmed transactions and updates to the best block, ChannelManager may be instructed to send a channel_ready message when a channel's funding transaction has confirmed and has met the required number of confirmations. A similar action is needed for sending splice_locked once splice transaction has confirmed with required number of confirmations. Generalize do_chain_event signature to allow for either scenario.

When processing confirmed transactions, if the funding transaction is found then information about it in the ChannelContext is updated. In preparation for splicing, move this data to FundingScope.

When checking if channel_ready should be sent, the funding transaction must reach minimum_depth confirmations. The same logic is needed for splicing a channel, so refactor it into a helper method.

When a channel is funded using the coinbase transaction, the minimum depth must be at least COINBASE_MATURITY. Instead of overriding it in ChannelContext, add FundingScope::minimum_depth_override for this purpose. Otherwise, if the overridden minimum_depth were reused in a splice's minimum dpeth, then sending splice_locked would be unnecessarily delayed. Later, this can be used to override the minimum depth needed for a splice.

FundingScope::funding_tx_confirmation_height is reset as part of calling ChannelContext::check_funding_meets_minimum_depth via FundedChannel::check_get_channel_ready. This side effect requires using mutable references to self when otherwise it would not be needed. Instead of reseting funding_tx_confirmation_height there, do so when unconfirming the funding transaction.

0-conf channels always meet the funding minimum depth once accepted. Special case this in check_funding_meets_minimum_depth such that it isn't implicit in later calculations. Since a minimum depth is always set when the channel is accepted, expect this to be the case in the method since it should only be called on a ChannelContext in a FundedChannel.

When transactions confirm or the best block is updated, check if any pending splice funding transactions have confirmed to an acceptable depth. If so, send a splice_locked message to the counterparty and -- if the counterparty has exchanged a splice_locked message for the same funding txid -- promote the corresponding FundingScope such that the new funding can be utilized.

This method is only applicable for FundedChannel, so it shouldn't be accessible from ChannelContext.

Now that FundedScope::minimum_depth_override is used to override the minimum depth with COINBASE_MATURITY when the funding transaction is the coinbase transaction, use this in ChannelContext::minimum_depth method. Also, add a minimum_depth to Channel. The one on ChannelContext can become private once FudningScope doesn't need to be accessed directly from a ChannelManager macro. This fixes ChannelDetails showing an incorrect minimum depth when the coinbase transaction is used to fund the channel.

When a splice funding transaction is unconfirmed, update the corresponding FundingScope just as is done when the initial funding transaction is unconfirmed.

Pending funding transactions for splices should be monitored for appearance on chain. Include these in ChannelManager::get_relevant_txids so that they can be watched.

When receiving a splice_locked message from a counterparty, promote the corresponding FundingScope if the funding txid matches the one sent by us in splice_locked.

When a splice is locked, the SCID from the previous funding transaction needs to be remembered so that pending HTLCs can be handled properly. Additionally, when they need to be cleaned up once they should no longer be used. Track these SCIDs as splices are locked and clean any up as blocks are connected.

Once both parties have exchanged splice_locked messages, the splice funding is ready for use. Emit an event to the user indicating as much.

A ChannelReady event is used for both channel establishment and splicing to indicate that the funding transaction is confirmed to an acceptable depth and thus the channel can be used with the funding. An upcoming SplicePending event will be emitted for each pending splice (i.e., both the initial splice attempt and any RBF attempts). Thus, when a ChannelReady event is emitted, the funding_txo must be included to differentiate between which ChannelPending -- which also contains the funding_txo -- that the event corresponds to.

jkczyz · 2025-06-13T14:28:06Z

Had to rebase again since channel.rs was updated to use #[rustfmt::skip] on methods.

jkczyz requested a review from wpaulino April 16, 2025 17:11

jkczyz force-pushed the 2025-04-splice-locked branch from dfbc04e to e4c0566 Compare April 18, 2025 23:15

optout21 reviewed Apr 19, 2025

View reviewed changes

lightning/src/ln/channelmanager.rs Show resolved Hide resolved

lightning/src/ln/channel.rs Show resolved Hide resolved

lightning/src/ln/channel.rs Outdated Show resolved Hide resolved

wpaulino reviewed Apr 21, 2025

View reviewed changes

jkczyz force-pushed the 2025-04-splice-locked branch from e4c0566 to 49f8ef6 Compare April 29, 2025 19:55

jkczyz commented Apr 29, 2025

View reviewed changes

jkczyz marked this pull request as ready for review April 30, 2025 16:20

ldk-reviews-bot requested a review from TheBlueMatt April 30, 2025 16:20

jkczyz added the weekly goal Someone wants to land this this week label Apr 30, 2025

jkczyz force-pushed the 2025-04-splice-locked branch from ef048e6 to f3b0989 Compare April 30, 2025 17:31

TheBlueMatt reviewed Apr 30, 2025

View reviewed changes

jkczyz force-pushed the 2025-04-splice-locked branch from f3b0989 to bd1a788 Compare May 1, 2025 21:51

dunxen self-requested a review May 5, 2025 18:26

jkczyz requested review from wpaulino and TheBlueMatt May 6, 2025 20:54

jkczyz force-pushed the 2025-04-splice-locked branch from b4e2b1a to a57c034 Compare May 7, 2025 16:27

jkczyz force-pushed the 2025-04-splice-locked branch 2 times, most recently from 49ea5fa to bbceb09 Compare June 12, 2025 22:53

jkczyz force-pushed the 2025-04-splice-locked branch from bbceb09 to cd4dc73 Compare June 12, 2025 23:09

jkczyz force-pushed the 2025-04-splice-locked branch from cd4dc73 to db2c5e8 Compare June 13, 2025 03:37

jkczyz added 19 commits June 13, 2025 08:33

Move ChannelContext::funding_tx_confirmed_in to FundingScope

39667e3

When processing confirmed transactions, if the funding transaction is found then information about it in the ChannelContext is updated. In preparation for splicing, move this data to FundingScope.

Move ChannelContext::funding_tx_confirmation_height to FundingScope

0eca1e5

When processing confirmed transactions, if the funding transaction is found then information about it in the ChannelContext is updated. In preparation for splicing, move this data to FundingScope.

Move ChannelContext::short_channel_id to FundingScope

dbd677b

When processing confirmed transactions, if the funding transaction is found then information about it in the ChannelContext is updated. In preparation for splicing, move this data to FundingScope.

Refactor funding tx confirmation check into helper

a3bf741

When checking if channel_ready should be sent, the funding transaction must reach minimum_depth confirmations. The same logic is needed for splicing a channel, so refactor it into a helper method.

Add FundingScope::get_funding_txid helper

b38d28d

Move check_funding_meets_minimum_depth to FundedChannel

8adfa9b

This method is only applicable for FundedChannel, so it shouldn't be accessible from ChannelContext.

Check unconfirmation of pending funding transactions

2aae372

When a splice funding transaction is unconfirmed, update the corresponding FundingScope just as is done when the initial funding transaction is unconfirmed.

Check all FundingScopes in get_relevant_txids

8c921d3

Pending funding transactions for splices should be monitored for appearance on chain. Include these in ChannelManager::get_relevant_txids so that they can be watched.

Handle splice_locked message

96d4e80

When receiving a splice_locked message from a counterparty, promote the corresponding FundingScope if the funding txid matches the one sent by us in splice_locked.

Emit SpliceLocked event

3f1fa35

Once both parties have exchanged splice_locked messages, the splice funding is ready for use. Emit an event to the user indicating as much.

Log confirmation of channel funding transaction

417698f

jkczyz force-pushed the 2025-04-splice-locked branch from db2c5e8 to 417698f Compare June 13, 2025 14:26

jkczyz requested a review from TheBlueMatt June 13, 2025 17:39

wpaulino approved these changes Jun 13, 2025

View reviewed changes

TheBlueMatt linked an issue Jun 13, 2025 that may be closed by this pull request

Allow non-strict forwarding for spliced/closed channels #3821

Open

Exchange splice_locked messages #3741

Are you sure you want to change the base?

Exchange splice_locked messages #3741

Uh oh!

Conversation

jkczyz commented Apr 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ldk-reviews-bot commented Apr 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jkczyz commented Apr 16, 2025

Uh oh!

jkczyz commented Apr 18, 2025

Uh oh!

codecov bot commented Apr 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

ldk-reviews-bot commented Apr 19, 2025

Uh oh!

optout21 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ldk-reviews-bot commented Apr 21, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jkczyz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jkczyz commented Apr 30, 2025

Uh oh!

wpaulino commented Apr 30, 2025

Uh oh!

TheBlueMatt Apr 30, 2025

Choose a reason for hiding this comment

Uh oh!

jkczyz Apr 30, 2025

Choose a reason for hiding this comment

Uh oh!

jkczyz Apr 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jkczyz May 1, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

TheBlueMatt Apr 30, 2025

Choose a reason for hiding this comment

Uh oh!

jkczyz May 1, 2025

Choose a reason for hiding this comment

Uh oh!

jkczyz commented May 1, 2025

Uh oh!

jkczyz commented May 1, 2025

Uh oh!

jkczyz commented May 7, 2025

Uh oh!

jkczyz commented May 7, 2025

Uh oh!

ldk-reviews-bot commented May 7, 2025

Uh oh!

ldk-reviews-bot commented May 8, 2025

Uh oh!

Exchange `splice_locked` messages #3741

Exchange `splice_locked` messages #3741

jkczyz commented Apr 16, 2025 •

edited

Loading

ldk-reviews-bot commented Apr 16, 2025 •

edited

Loading

codecov bot commented Apr 18, 2025 •

edited

Loading

jkczyz Apr 30, 2025 •

edited

Loading