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.

jkczyz · 2025-06-03T22:44:39Z

Feel free to squash. Would also like to see some more logging whenever we've made substantial progress towards splice_locked. Some initial logs to include: splice confirmation/unconfirmation, splice_locked sent/received/mismatch, funding promotion.

Added logging though I couldn't find logging of the initial funding confirmation, so I left out logging splice funding confirmation. Let me know if you think we should include both.

ldk-reviews-bot · 2025-06-04T00:02:33Z

🔔 9th Reminder

Hey @TheBlueMatt! 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-04T15:25:12Z

lightning/src/ln/channel.rs

+		}
+
+		let funding_tx_confirmations = height as i64 - funding.funding_tx_confirmation_height as i64 + 1;
+		if funding_tx_confirmations < minimum_depth.unwrap_or(0) as i64 {


Looks like docs weren't updated?

TheBlueMatt · 2025-06-04T17:20:28Z

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());


Honestly I'm not a fan of adding the funding transaction to the Channel when we don't need it. They can be nontrivially big and writing it every time in the ChannelManager is gonna really bloat our IO. We used to remove them but it looks like we don't even do that anymore (which we should fix!). If we had some strong reason to want it fine but just to limit the confirmation rate it seems pretty weird - if the channel opens with a coinbase tx, setting it to require 100 confs is cheap, and we never actually need to check splice txn for being a coinbase tx. That would just leave splices on channels originally opened with coinbase txn waiting for 100 blocks to confirm, but maybe we can more easily fix that by coping the original block count and keeping that separate from the limit in the funding context (which would let us give different limits for splices anyway, which we may want to do eventually).

We actually need the transaction when splicing, since it is needed in tx_add_input for the prevtx field.

prevtx is the serialized transaction that contains the output this input spends. Used to verify that the input is non-malleable.

https://github.com/lightning/bolts/blob/2822a528491b5bb72336e2c450028beb0a380552/02-peer-protocol.md?plain=1#L251-L252

We were just talking about this today since we won't have this for inbound V1 channels that have already confirmed. See: lightning/bolts#1160 (comment)

Related discussion on the spec regarding number of confirmations: lightning/bolts#1160 (comment)

Ugh yea would good to get that fixed in the spec, there's no reason to provide that for the commitment transaction...

Yeah, though note that it isn't a TLV. I guess we could set prevtx_len to 0 though.

Yeah, based on the spec conversation, looks like we need prevtx to be an Option in TxAddInput. It would be None if prevtx_len is 0.

prevtx_out, too? Hmmm... maybe an enum for these two and shared_input_txid? Left some comments on the spec.

prevtx_out could be made optional as well, but we always have enough information to set it, just not prevtx.

Ended up adding a minimum_depth_override field to FundingScope, which if set will take precedence over ChannelContext::minimum_depth. The original places where we overrode minimum_depth with COINBASE_MATURITY now sets that field.

TheBlueMatt · 2025-06-04T19:18:56Z

lightning/src/ln/channelmanager.rs

+
+			// Remove any scids used by older funding transactions
+			if let Some(current_scid) = channel.funding.get_short_channel_id() {
+				let historical_scids = &mut channel.context.historical_scids;


Oof, please push this logic down into channel.rs vs exposing the Mutex publicly.

There's no mutex on historical_scids.

wpaulino · 2025-06-05T17:51:21Z

Added logging though I couldn't find logging of the initial funding confirmation, so I left out logging splice funding confirmation. Let me know if you think we should include both.

Yeah I think those would be helpful. We can make the initial funding/splice confirmation and the FundingScope promotion logs info level, with anything in between at debug/warn.

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

optout21 mentioned this pull request Jun 3, 2025

[Splicing] Tx negotiation during splicing #3736

Open

jkczyz force-pushed the 2025-04-splice-locked branch from 2094737 to 750515c Compare June 3, 2025 22:43

TheBlueMatt reviewed Jun 4, 2025

View reviewed changes

jkczyz force-pushed the 2025-04-splice-locked branch from 750515c to bff123e Compare June 4, 2025 20:54

jkczyz added 20 commits June 6, 2025 17:26

s - FundingScope::minimum_depth_override

59b4d7f

Add FundingScope::get_funding_txid helper

98de23d

f - add logging to maybe_promote_splice_funding

d4d7cb3

f - update minimum_depth docs

bcc9d7f

f - preemptive rustfmt nit

2cd8496

Move check_funding_meets_minimum_depth to FundedChannel

abf38c4

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

Check unconfirmation of pending funding transactions

75b16c2

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

245de24

f - add logging to transaction_unconfirmed

1b095ea

Check all FundingScopes in get_relevant_txids

4fa0ff4

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

f9e084b

f - add logging to splice_locked

d0e95c5

Emit SpliceLocked event

2fe76d5

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

2129d53

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

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

jkczyz commented Jun 3, 2025

Uh oh!

ldk-reviews-bot commented Jun 4, 2025

Uh oh!

Choose a reason for hiding this comment

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