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

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.

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.

ldk-reviews-bot · 2025-06-09T00:00:28Z

🔔 1st Reminder

Hey @TheBlueMatt @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-06-09T00:00:30Z

🔔 1st Reminder

Hey @TheBlueMatt @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.

TheBlueMatt · 2025-06-10T00:55:18Z

lightning/src/ln/channel.rs

+					funding, block_hash, height, index_in_block, &mut confirmed_tx, logger,
+				)? {
+					if confirmed_funding_index.is_some() {
+						let err_reason = "splice tx of another pending funding already confirmed";


Should we also check to make sure no other funding is already confirmed?

Added a funding_already_confirmed to track and check.

TheBlueMatt · 2025-06-10T00:59:47Z

lightning/src/ln/channelmanager.rs

+									},
+									#[cfg(splicing)]
+									Some(FundingConfirmedMessage::Splice(splice_locked)) => {
+										if announcement_sigs.is_some() {


Hmm, don't we normally keep all (including non-public) channels in short_to_chan_info? I'd buy that we don't actually need to, but seems weird to end up with different state here than we get on restart/for a normal channel open. (same goes for the inbound-locked case afaict)

Not quite sure if I understand this comment. We use announcement_sigs to determine if we already received splice_locked from our counterparty. If so, the funding is now locked as we are about to send our own splice_locked. Thus, we need to update short_to_chan_info with the new SCID.

We won't have announcement_sigs if the channel is private, so we won't update short_to_chan_info even though we should.

TheBlueMatt · 2025-06-10T01:06:27Z

lightning/src/ln/channel.rs

+					// transaction until it is seen on chain. Set it so that minimum_depth
+					// checks can tell if the coinbase transaction was used.
+					if funding.funding_transaction.is_none() {
+						funding.funding_transaction = Some(tx.clone());


We should be able to remove this line now, right?

TheBlueMatt · 2025-06-10T01:13:02Z

lightning/src/ln/channel.rs

+
+				// Check if we sent splice_locked for the unconfirmed transaction
+				#[cfg(splicing)]
+				if let Some(pending_splice) = &mut self.pending_splice {


This is only called for chain::Confirm listeners, but chain::Listen folks only get best_block_updated calls. We should probably move this hunk to best_block_updated (with appropriate changes).

Added a fixup. Let me know if it looks sane.

ldk-reviews-bot · 2025-06-11T00:01:12Z

🔔 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.

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 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.

wpaulino · 2025-06-11T23:12:53Z

lightning/src/ln/channel.rs

+			// Note that transaction_unconfirmed may have reset funding_tx_confirmation_height
+			// to zero if it has been reorged out, however in either case, our state flags
+			// indicate we've already sent a channel_ready
+			let funding_tx_confirmations = self.funding.get_funding_tx_confirmations(height);


To keep things consistent with the splicing case, maybe we should also reset the confirmation height to 0 in do_best_block_updated for the current scope so we don't have to do it in transaction_unconfirmed. Though keep in mind that we should reset it regardless of whether we've sent ChannelReady.

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 5 commits June 6, 2025 17:26

f - add logging to maybe_promote_splice_funding

d4d7cb3

f - update minimum_depth docs

bcc9d7f

f - preemptive rustfmt nit

2cd8496

jkczyz force-pushed the 2025-04-splice-locked branch from bff123e to 2129d53 Compare June 6, 2025 22:44

jkczyz requested review from TheBlueMatt and wpaulino June 6, 2025 22:48

TheBlueMatt reviewed Jun 10, 2025

View reviewed changes

jkczyz added 16 commits June 11, 2025 14:51

f - drop setting funding_transaction

fac36c3

f - funding_already_confirmed check

32af1d7

f - bug fix

e4903bd

Move check_funding_meets_minimum_depth to FundedChannel

49adc1a

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

Check unconfirmation of pending funding transactions

d6be3ee

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

f - fix CI

b4eb865

f - add logging to transaction_unconfirmed

a354008

f - correctly check for unconfirmed splice funding tx

47793d8

Check all FundingScopes in get_relevant_txids

42f7ee2

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

0f33fba

f - add logging to splice_locked

d5e1468

Emit SpliceLocked event

e58b540

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

6a0fb94

jkczyz force-pushed the 2025-04-splice-locked branch from 2129d53 to 6a0fb94 Compare June 11, 2025 22:43

wpaulino reviewed Jun 11, 2025

View reviewed changes

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!

Choose a reason for hiding this comment

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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!

ldk-reviews-bot commented Jun 9, 2025

Uh oh!

ldk-reviews-bot commented Jun 9, 2025

Uh oh!

Choose a reason for hiding this comment

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