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.

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

wpaulino · 2025-04-21T19:04:07Z

lightning/src/ln/channel.rs

+
+		match pending_splice.sent_funding_txid {
+			Some(sent_funding_txid) if confirmed_funding_txid == sent_funding_txid => {
+				debug_assert!(false);


We may need to replay splice_locked if a disconnect happened before they were able to process it. Unclear if we'd want to use this same code path for it or not.

By this do you mean for channel_reestablish?

Yeah, I assume there is a similar retransmission case we need to handle there, like with channel_ready.

Gonna leave this for a follow-up, if that's ok.

Sure, probably better to wait for #3637 to land anyway.

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

jkczyz · 2025-04-29T19:13:35Z

lightning/src/ln/channel.rs

+
+		match pending_splice.sent_funding_txid {
+			Some(sent_funding_txid) if confirmed_funding_txid == sent_funding_txid => {
+				debug_assert!(false);


By this do you mean for channel_reestablish?

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.

TheBlueMatt · 2025-04-30T19:53:37Z

lightning/src/ln/channelmanager.rs

@@ -11639,7 +11639,7 @@ where
 			for chan in peer_state.channel_by_id.values().filter_map(Channel::as_funded) {
 				let txid_opt = chan.funding.get_funding_txo();
 				let height_opt = chan.context.get_funding_tx_confirmation_height();
-				let hash_opt = chan.context.get_funding_tx_confirmed_in();
+				let hash_opt = chan.funding.get_funding_tx_confirmed_in();


Can we avoid new references to Channel::funding in ChannelManager? I thought we wanted to remove that?

I was able to get rid of this one by moving get_funding_tx_confirmed_in to FundedChannel since this is the only use.

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.

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.

The minimum_depth of a channel is overridden to COINBASE_MATURITY if the funding transaction is the coinbase transaction. However, if this is to be reused for a splice's minimum_depth, it would be a problem since sending splice_locked would be unnecessarily delayed. Now that FundingScope contains the funding transaction, use this to check if it is a coinbase transaction instead of overriding minimum_depth.

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.

jkczyz · 2025-05-16T15:07:34Z

Squashed and rebased as discussed offline. Still need address latest comments.

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

Now that ChannelContext::minimum_depth is not overridden with COINBASE_MATURITY when the funding transaction is the coinbase transaction, so do instead in the identically named 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 funded 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 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.

ldk-reviews-bot · 2025-05-17T00:00:50Z

🔔 5th 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-17T00:00:53Z

🔔 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-17T00:00:54Z

🔔 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-19T00:01:18Z

🔔 6th 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-19T00:01:21Z

🔔 2nd 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-19T00:01:23Z

🔔 2nd 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 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 added 10 commits May 16, 2025 09:55

Move ChannelContext::funding_tx_confirmed_in to FundingScope

d590e2a

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

11027f4

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

51e300c

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

682c459

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

44671ae

jkczyz force-pushed the 2025-04-splice-locked branch from 66fa294 to 6f1f50f Compare May 16, 2025 15:06

jkczyz added 11 commits May 16, 2025 12:58

f - error when pending_splice is None

ba4e98d

f - add docs

22da134

Move check_funding_meets_minimum_depth to FundedChannel

e26ff16

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

Check unconfirmation of pending funding transactions

cd33154

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

d4a6612

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

b3453b7

f - proper return values

e9f4f35

Emit SpliceLocked event

60e21ac

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

jkczyz force-pushed the 2025-04-splice-locked branch from 6f1f50f to c6e3515 Compare May 16, 2025 21:28

Exchange splice_locked messages #3741

Are you sure you want to change the base?

Exchange splice_locked messages #3741

Conversation

jkczyz commented Apr 16, 2025 • edited Loading

ldk-reviews-bot commented Apr 16, 2025 • edited Loading

jkczyz commented Apr 16, 2025

jkczyz commented Apr 18, 2025

codecov bot commented Apr 18, 2025 • edited Loading

Codecov Report

ldk-reviews-bot commented Apr 19, 2025

optout21 left a comment

Choose a reason for hiding this comment

ldk-reviews-bot commented Apr 21, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jkczyz left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jkczyz commented Apr 30, 2025

wpaulino commented Apr 30, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jkczyz Apr 30, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jkczyz commented May 1, 2025

jkczyz commented May 1, 2025

jkczyz commented May 7, 2025

jkczyz commented May 7, 2025

ldk-reviews-bot commented May 7, 2025

ldk-reviews-bot commented May 8, 2025

jkczyz commented May 16, 2025

ldk-reviews-bot commented May 17, 2025

ldk-reviews-bot commented May 17, 2025

ldk-reviews-bot commented May 17, 2025

ldk-reviews-bot commented May 19, 2025

ldk-reviews-bot commented May 19, 2025

ldk-reviews-bot commented May 19, 2025

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