Add `FundingNeeded` event for splicing #4290

jkczyz · 2025-12-18T16:11:08Z

Rather than requiring the user to pass FundingTxInputs when initiating a splice, generate a FundingNeeded event once the channel has become quiescent. This simplifies error handling and UTXO / change address clean-up by consolidating it in SpliceFailed event handling.

Later, this event will be used for opportunistic contributions (i.e., when the counterparty wins quiescence or initiates), dual-funding, and RBF.

Based on #4261.

This is still fairly rough. It does not yet include any code for creating a FundingNegotiationContext from a FundingContribution. The former may need to a dedicated struct instead so that any data needed from ChannelManager or ChannelContext can be produced internally. Alternatively, that data could be included in FundingContribution, but it would need to be serializable.

ldk-reviews-bot · 2025-12-18T16:11:11Z

🎉 This PR is now ready for review!
Please choose at least one reviewer by assigning them on the right bar.
If no reviewers are assigned within 10 minutes, I'll automatically assign one.
Once the first reviewer has submitted a review, a second will be assigned if required.

jkczyz · 2026-01-12T18:03:27Z

@TheBlueMatt @wpaulino Looking for some high-level feedback on the API introduced in the last commit. In summary:

User passes SpliceContribution -- which no longer contains any FundingTxInputs -- to ChannelManager::splice_channel
Upon quiescence LDK generates a FundingNeeded event which contains a FundingTemplate
User calls FundingTemplate::build or FundingTemplate::build_sync with a WalletSource or WalletSourceSync, respectively, to produce a FundingContribution
User passes FundingContribution -- which contains the FundingTxInputs -- to ChannelManager::funding_contributed
LDK validates that the FundingContribution can pay for inputs / outputs, causing LDK to either send splice_init or produce a SpliceFailed event.

The same mechanism can be used later for contributing inputs for counterparty-initiated splices or v2 channel opens since FundingTemplate and FundingContribution contains the context.

Test code still needs to be fixed up, and change_script generation will follow in another commit.

wpaulino

The API design LGTM, though there's one issue with WalletSource. One thing users need to keep in mind now is that from the moment they receive FundingNeeded, they need to act quickly to ensure the counterparty doesn't disconnect due to quiescence taking too long.

wpaulino · 2026-01-12T19:37:10Z

lightning/src/events/bump_transaction/sync.rs

 	fn list_confirmed_utxos(&self) -> Result<Vec<Utxo>, ()>;
+
+	///
+	fn select_confirmed_utxos(


Adding this here now requires implementers to satisfy this method when, in the context of anchor channels, WalletSource is only intended to be used such that we perform coin selection on behalf of the user. Ideally, we also give users the option between choosing WalletSource/CoinSelectionSource when funding channels.

Right, I guess I'm a bit confused why we can't use select_confirmed_utxos as-is? Indeed the claim_id is annoying, but we can make that either an enum across a ClaimId and some unit value describing a splice or just make it an Option. Aside from that it seems to be basically what we want.

Adding this here now requires implementers to satisfy this method when, in the context of anchor channels, WalletSource is only intended to be used such that we perform coin selection on behalf of the user. Ideally, we also give users the option between choosing WalletSource/CoinSelectionSource when funding channels.

Hmm... I see. Would a separate trait be desirable? Also, see my reply to @TheBlueMatt below.

Right, I guess I'm a bit confused why we can't use select_confirmed_utxos as-is? Indeed the claim_id is annoying, but we can make that either an enum across a ClaimId and some unit value describing a splice or just make it an Option. Aside from that it seems to be basically what we want.

The return value also isn't compatible. It contains Utxos but we also need the previous tx and sequence number as part of each FundingTxInput. Though its constructor will give a default sequence number.

We could change CoinSelection to use FundingTxInput instead of Utxo, but that would be odd for use with the anchor context.

Honestly that seems fine to me? We expect ~all of our users to want to use splicing, which implies they need to support the "return coin selection with full transactions" interface. So what if anchors throw away some of that data?

If we feel strongly about it we can add a new trait method that does return the full transactions and provide a default implementation for the current method so that those that really want to avoid always fetching the transaction data can.

Right, I don't have a strong opinion, but note that Wallet's implementation of CoinSelectionSource::select_confirmed_utxos delegates to WalletSource::list_confirmed_utxos. So it might be expensive to use that abstraction. @wpaulino WDYT?

I was thinking of keeping CoinSelectionSource the same (with the full transaction data in the response, or with the default-impl-method described above) but changing WalletSource so that we don't have to fetch all previous-transactions at the start.

Yeah, Wallet wraps a WalletSource and implements CoinSelectionSource by listing all the UTXOs and selecting from them. So WalletSource's interface would remain unchanged while CoinSelection would use FundingTxInput instead of Utxo. Which I guess means FundingTemplate::build should actually take a CoinSelectionSource.

Seems reasonable to require a sequence number in the response for that as well, even for anchors?

Hmm... in WalletSource::list_confirmed_utxos by adding a field to Utxto (and removing it from FundingTxInput)? Or by having the CoinSelectionSource implementation fill it in on FundingTxInput?

So WalletSource's interface would remain unchanged

Wouldn't we need a WalletSource::get_previous_transaction_for_utxo method to fetch the full tx data for the UTXOs we selected?

Hmm... in WalletSource::list_confirmed_utxos by adding a field to Utxto (and removing it from FundingTxInput)? Or by having the CoinSelectionSource implementation fill it in on FundingTxInput?

ISTM we should replace Utxo with FundingTxInput since FundingTxInput has strictly more fields (it contains a Utxo!) and we'd move to returning FundingTxInput from the trait.

Wouldn't we need a WalletSource::get_previous_transaction_for_utxo method to fetch the full tx data for the UTXOs we selected?

Right, we need another method for that.

ISTM we should replace Utxo with FundingTxInput since FundingTxInput has strictly more fields (it contains a Utxo!) and we'd move to returning FundingTxInput from the trait.

The question is more what should be setting Sequence? Either:

(1) Move it to Utxo and have WalletSource::list_confirmed_utxos set it since it returns Vec<Utxo>.
(2) Have CoinSelectionSource::select_confirmed_utxos set it since CoinSelection would now contain Vec<FundingTxInput>

We just can't replace Utxo with FundingTxInput in WalletSource::list_confirmed_utxos since we don't want to return the previous tx there.

(1) Move it to Utxo and have WalletSource::list_confirmed_utxos set it since it returns Vec.

Presumably this. No reason to want it to not be possible in WalletSource.

Done as discussed here and offline. I'm in the middle of updating the tests, but I've pushed an update for now.

TheBlueMatt

Aside from the above which-interface question I think the API is good.

ldk-reviews-bot · 2026-01-15T00:28:47Z

🔔 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 · 2026-01-15T00:28:48Z

🔔 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 · 2026-01-17T00:29:31Z

🔔 2nd 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 · 2026-01-17T00:29:32Z

🔔 2nd 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 · 2026-01-19T00:29:48Z

🔔 3rd 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 · 2026-01-19T00:29:50Z

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

A forthcoming commit will change CoinSelection to include FundingTxInput instead of Utxo, though the former will probably be renamed. This is so CoinSelectionSource can be used when funding a splice. Further updating WalletSource to use FundingTxInput is not desirable, however, as it would result in looking up each confirmed UTXOs previous transaction even if it is not selected. See Wallet's implementation of CoinSelectionSource, which delegates to WalletSource for listing all confirmed UTXOs. This commit moves FundingTxInput::sequence to Utxo, and thus the responsibility for setting it to WalletSource implementations. Doing so will allow Wallet's CoinSelectionSource implementation to delegate looking up previous transactions to WalletSource without having to explicitly set the sequence on any FundingTxInput.

In order to reuse CoinSelectionSource for splicing, the previous transaction of each UTXO is needed. Update CoinSelection to use FundingTxInput (renamed to ConfirmedUtxo) so that it is available. This requires adding a method to WalletSource to look up a previous transaction for a UTXO. Otherwise, Wallet's implementation of CoinSelectionSource would need WalletSource to include the previous transactions when listing confirmed UTXOs to select from. But this would be inefficient since only some UTXOs are selected.

jkczyz · 2026-01-20T19:20:35Z

lightning/src/ln/funding.rs

+			// FIXME: Should claim_id be an Option?
+			let claim_id = ClaimId([0; 32]);


Regarding the CoinSelectionSource API, do we want to make claim_id an Option?

jkczyz · 2026-01-20T19:24:28Z

lightning/src/ln/splicing_tests.rs

-		Amount::from_sat(383)
+		Amount::from_sat(385)
 	} else {
-		Amount::from_sat(384)
+		Amount::from_sat(386)


Seems select_confirmed_utxos_internal might be off on the change calculation because it's using the weight of the change output to compute additional fees instead of re-computing the total fees using the total weight when including a change output.

ldk-reviews-bot · 2026-01-21T00:30:25Z

🔔 4th 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 · 2026-01-21T00:30:27Z

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

Rather than requiring the user to pass FundingTxInputs when initiating a splice, generate a FundingNeeded event once the channel has become quiescent. This simplifies error handling and UTXO / change address clean-up by consolidating it in SpliceFailed event handling. Later, this event will be used for opportunistic contributions (i.e., when the counterparty wins quiescence or initiates), dual-funding, and RBF.

Now that CoinSelection is used to fund a splice funding transaction, use that for determining of a change output should be used. Previously, the initiator could either provide a change script upfront or let LDK generate one using SignerProvider::get_destination_script. Since older versions may have serialized a SpliceInstruction without a change script while waiting on quiescence, LDK must still generate a change output in this case.

codecov · 2026-01-21T19:58:51Z

Codecov Report

❌ Patch coverage is 76.35830% with 161 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.39%. Comparing base (8eb9e70) to head (fcccbac).
⚠️ Report is 15 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning/src/ln/channel.rs	59.23%	61 Missing and 3 partials ⚠️
lightning/src/ln/splicing_tests.rs	0.00%	33 Missing ⚠️
lightning/src/ln/funding.rs	89.74%	17 Missing and 15 partials ⚠️
lightning/src/ln/channelmanager.rs	71.60%	23 Missing ⚠️
lightning/src/events/bump_transaction/mod.rs	90.47%	3 Missing and 1 partial ⚠️
lightning/src/ln/functional_test_utils.rs	40.00%	3 Missing ⚠️
lightning/src/events/mod.rs	87.50%	0 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4290      +/-   ##
==========================================
- Coverage   86.61%   86.39%   -0.23%     
==========================================
  Files         158      158              
  Lines      103067   103469     +402     
  Branches   103067   103469     +402     
==========================================
+ Hits        89275    89394     +119     
- Misses      11366    11654     +288     
+ Partials     2426     2421       -5

Flag	Coverage Δ
fuzzing	`37.02% <42.32%> (-0.05%)`	⬇️
tests	`85.70% <80.09%> (-0.21%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

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

TheBlueMatt

API looks good. some misc comments i noted while skimming it

TheBlueMatt · 2026-01-21T22:21:34Z

lightning/src/events/bump_transaction/mod.rs

 }

+/// An unspent transaction output with at least one confirmation.
+pub type ConfirmedUtxo = FundingTxInput;


lets not rename types with aliases. If we are making a type more general lets rename the type itself.

TheBlueMatt · 2026-01-21T22:30:23Z

lightning/src/events/mod.rs

+	/// Indicates that funding is needed for a channel splice or a dual-funded channel open.
+	///
+	/// The client should build a [`FundingContribution`] from the provided [`FundingTemplate`] and
+	/// pass it to [`ChannelManager::funding_contributed`].


Needs a call-out to what to do if you actually don't want to splice anymore (ie on failure)

Also maybe a note that the channel is hung waiting on our response, so we need to respond quickly.

TheBlueMatt · 2026-01-21T22:39:22Z

lightning/src/ln/funding.rs

+			// FIXME: Should claim_id be an Option?
+			let claim_id = ClaimId([0; 32]);


TheBlueMatt · 2026-01-21T22:40:28Z

lightning/src/ln/funding.rs

+
+	/// Creates a `FundingContribution` from the template by using `wallet` to perform coin
+	/// selection with the given fee rate.
+	pub fn build_sync<W: Deref>(


Can we also have a method for building with a provided set of inputs rather than going through the trait?

TheBlueMatt · 2026-01-21T22:41:10Z

test_cases/chanmon_consistency/any_filename_works

spurious diff?

TheBlueMatt · 2026-01-21T22:47:47Z

lightning/src/ln/channel.rs

+		if self.context.channel_state.is_quiescent() {
+			return Err(APIError::APIMisuseError {
+				err: format!(
+					"Channel {} cannot be spliced as it is already quiescent",


Don't we want to support queuing up the splice to do afterwards?

TheBlueMatt · 2026-01-21T22:50:38Z

lightning/src/ln/channel.rs

+	) -> Result<msgs::SpliceInit, SpliceFundingFailed>
+	where
+		L::Target: Logger,
+	{


presumably we need to check that we're quiescent and its our turn to talk?

TheBlueMatt · 2026-01-21T22:53:51Z

lightning/src/ln/channel.rs

 impl_writeable_tlv_based_enum_upgradable!(QuiescentAction,
 	(0, DoNothing) => {},
-	{1, Splice} => (),
+	{1, LegacySplice} => (),


Needs docs on when we switched so we know when to remove it

jkczyz added this to Weekly Goals Dec 18, 2025

jkczyz self-assigned this Dec 18, 2025

jkczyz force-pushed the 2025-12-new-splice-api branch from f5933e5 to 854e9ca Compare January 12, 2026 17:47

wpaulino reviewed Jan 12, 2026

View reviewed changes

TheBlueMatt reviewed Jan 12, 2026

View reviewed changes

jkczyz requested review from TheBlueMatt and wpaulino January 13, 2026 00:28

jkczyz force-pushed the 2025-12-new-splice-api branch from 854e9ca to 6d78c3f Compare January 14, 2026 17:03

jkczyz force-pushed the 2025-12-new-splice-api branch from 6d78c3f to 94b1aa9 Compare January 15, 2026 17:02

jkczyz mentioned this pull request Jan 16, 2026

Mixed mode splicing #4261

Merged

jkczyz added 3 commits January 20, 2026 13:16

FIXME: Why does handle_channel_close override the witness?

f3eb94e

jkczyz force-pushed the 2025-12-new-splice-api branch from 94b1aa9 to c3f3453 Compare January 20, 2026 19:16

jkczyz commented Jan 20, 2026

View reviewed changes

jkczyz marked this pull request as ready for review January 20, 2026 19:25

jkczyz force-pushed the 2025-12-new-splice-api branch from c3f3453 to 3253a99 Compare January 20, 2026 23:57

jkczyz force-pushed the 2025-12-new-splice-api branch 2 times, most recently from 6b92b77 to f2d9fa5 Compare January 21, 2026 05:59

jkczyz added 2 commits January 21, 2026 12:21

f - fix chanmon_consistency

5e4096c

jkczyz force-pushed the 2025-12-new-splice-api branch from f2d9fa5 to fcccbac Compare January 21, 2026 18:22

TheBlueMatt reviewed Jan 21, 2026

View reviewed changes

		// FIXME: Should claim_id be an Option?
		let claim_id = ClaimId([0; 32]);

Add FundingNeeded event for splicing #4290

Are you sure you want to change the base?

Add FundingNeeded event for splicing #4290

Conversation

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

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

jkczyz commented Jan 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

wpaulino left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TheBlueMatt left a comment

Choose a reason for hiding this comment

Uh oh!

ldk-reviews-bot commented Jan 15, 2026

Uh oh!

ldk-reviews-bot commented Jan 15, 2026

Uh oh!

ldk-reviews-bot commented Jan 17, 2026

Uh oh!

ldk-reviews-bot commented Jan 17, 2026

Uh oh!

ldk-reviews-bot commented Jan 19, 2026

Uh oh!

ldk-reviews-bot commented Jan 19, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ldk-reviews-bot commented Jan 21, 2026

Uh oh!

ldk-reviews-bot commented Jan 21, 2026

Uh oh!

codecov bot commented Jan 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

TheBlueMatt left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Add `FundingNeeded` event for splicing #4290

Add `FundingNeeded` event for splicing #4290

jkczyz commented Dec 18, 2025 •

edited

Loading

ldk-reviews-bot commented Dec 18, 2025 •

edited

Loading

jkczyz commented Jan 12, 2026 •

edited

Loading

codecov bot commented Jan 21, 2026 •

edited

Loading