Skip to content

Count the funding fee in the anchor reserve check for splice-ins and fee bumps - #1223

Open
shubhamkmr04 wants to merge 3 commits into
lightningdevkit:mainfrom
shubhamkmr04:splice-in-reserve-fees
Open

shubhamkmr04 wants to merge 3 commits into
lightningdevkit:mainfrom
shubhamkmr04:splice-in-reserve-fees

Conversation

@shubhamkmr04

@shubhamkmr04 shubhamkmr04 commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

Part of #1166.

When splicing in an exact amount, we checked that our on-chain funds cover the amount on top of the anchor reserve. We didn't check the fee for our contribution, which is paid from the same funds, or that LDK may raise that fee later, up to the contribution's maximum feerate, paying the difference from our change. Coin selection doesn't keep the reserve aside, so the fee could come out of it.

bump_channel_funding_fee had no reserve check at all. A bump of an exact splice-in pays the higher fee from our wallet: LDK shrinks the pending contribution's change or, past its maximum feerate, re-runs coin selection. A bump of a splice-out whose channel balance can't cover the higher fee falls back to funding the whole withdrawal and fees from our wallet, as discussed in #1181.

Changes

  • Prefactor: test_funding_contribution_with_parts takes a max_feerate, for unit tests of how much a contribution's fee may still rise.
  • check_sufficient_onchain_funds_for_contribution, run once LDK has built a contribution:
    • What a contribution may take at most: its inputs, less the least change it may return. LDK may still raise its fee up to its max_feerate out of the change, when our contribution joins a splice the counterparty initiated or the RBF minimum feerate rises. It drops the change if less than dust would be left. max_wallet_spend_sats bounds this from the contribution's estimated_fee, feerate and max_feerate.
    • What it's checked against: that amount must leave the anchor reserve of our confirmed, unlocked funds, plus the inputs of the contribution being replaced, which are ours again unless the replacement spends them too. The funds are read before coin selection, which locks the inputs it picks.
    • Replacements: one that takes no more than the contribution it replaces passes, so bumps of splice_in_with_all and splice-out bumps the channel pays for keep working when the wallet holds less than the reserve.
    • On rejection: it releases what LDK's reserved_inputs and reserved_outputs report, never what the contribution inherited from a pending splice, and fails with InsufficientFunds.
    • Independent of wallet sync: unconfirmed change is left out, via the new Wallet::get_confirmed_unlocked_amount_sats. So the result doesn't depend on whether wallet sync has seen a pending splice's transaction, or only an earlier round of it.
  • Exact splice_in: runs the check with no prior contribution. The amount's pre-check in check_sufficient_onchain_funds now uses the same confirmed, unlocked funds for splice-ins, so a plain lack of funds still fails before coin selection. Channel opens are unchanged.
  • bump_channel_funding_fee: runs the check against the pending contribution. Bumps of splice_in_with_all that rebuild the splice are unaffected, as they already keep the reserve as their own output (Build splice_in_with_all from manually selected inputs #1176).
  • Docs for splice_in, bump_channel_funding_fee and splice_out_max, and CHANGELOG entries.

Testing

  • Unit tests for max_wallet_spend_sats: no change, the rounded-up room for a higher fee, no room to raise the feerate, change left exactly at the dust limit and one sat below it, and change too small to cover the higher fee.
  • splice_in_fee_does_not_spend_anchor_reserve: node B holds 1,000,000 sats with a 25,000 sat anchor reserve.
    • At 50 sat/vB (fee about 12,500 sats), splicing in 970,000 fails with InsufficientFunds: the fee alone would come out of the reserve.
    • Splicing in 959,500 fails too: the fee fits, but paying up to 1.5 times the feerate doesn't.
    • B's spendable balance is unchanged after each failure.
    • The 970,000 at the regtest estimate splices in and keeps the reserve on-chain.
  • splice_in_bump_fee_does_not_spend_anchor_reserve, on Esplora and without syncing B's wallet between the splice and the bumps, so they run before the wallet has seen the splice transaction:
    • B splices in at 50 sat/vB, leaving room for paying up to 1.5 times that feerate.
    • A bump to 1.5 times the feerate, which may in turn pay up to 1.5 times its own, fails with InsufficientFunds.
    • A bump at the original feerate, raised to the RBF minimum, succeeds in place, on the same inputs.
  • splice_out_bump_fee_does_not_spend_anchor_reserve:
    • Node A withdraws its full splice-out maximum, so a bump has to be funded from its wallet. The wallet holds the withdrawal plus fees only together with half of the reserve.
    • The bump fails with InsufficientFunds, and the inputs coin selection locked are released.
    • Another coin then confirms while the splice stays in the mempool. The same bump now succeeds, with the withdrawal output unchanged.

Open question

Locked inputs while a replacement is pending. When a bump of a splice-in re-runs coin selection, the replacement can't reuse the pending splice's inputs, and those stay locked until one candidate confirms. The check makes sure the reserve holds whichever candidate confirms, but until then part of it can be tied up in those locked inputs. Should we hold back for that too, or is the window acceptable?

With this, the cases in #1166 are covered, apart from the question above.

This change was developed with the assistance of Claude Code.

@ldk-reviews-bot

ldk-reviews-bot commented Nov 8, 2026 •

Copy link
Copy Markdown

👋 Thanks for assigning @jkczyz 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.

@ldk-reviews-bot
ldk-reviews-bot requested a review from tnull November 8, 2026 06:49
@shubhamkmr04
shubhamkmr04 force-pushed the splice-in-reserve-fees branch 2 times, most recently from afede9a to 39ef2ad Compare November 11, 2026 08:57
@shubhamkmr04
shubhamkmr04 force-pushed the splice-in-reserve-fees branch from 39ef2ad to 0c1cba9 Compare November 17, 2026 12:15
@tnull tnull added this to the 0.8 milestone Nov 17, 2026

@tnull tnull left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please rebase now #1204 is in.

@shubhamkmr04
shubhamkmr04 force-pushed the splice-in-reserve-fees branch 2 times, most recently from 0689499 to 915b7dd Compare November 17, 2026 13:40
@shubhamkmr04
shubhamkmr04 requested a review from tnull November 17, 2026 15:35

@tnull tnull left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some Claude review:

  1. A fee bump of an exact splice-in can still pay from the reserve (src/lib.rs:2505)
  • bump_channel_funding_fee rebuilds a coin-selected contribution through rbf_prior_contribution(...) with the wallet and goes straight to funding_contributed.
  • Nothing on that path checks the anchor reserve.
  • So splice_in at a low fee rate followed by a bump at a high one reaches the state this PR is meant to prevent.
  • The commit says "Part of #1166", so this may be a planned follow-up. If so, the changelog entry is fine as scoped, but it is worth confirming with the author.
  1. The check uses feerate, but the contribution may pay up to max_feerate (src/lib.rs:1972-1976, question for the author)
  • The splice_in docs say we may pay up to 1.5 times the feerate when the counterparty initiates a splice concurrently and our contribution is added to theirs.
  • If LDK takes that extra fee from our change output, the reserve can be undercut by the difference after this check has passed.
  • I did not verify how LDK adjusts the contribution in that case, as the LDK sources are not in the local cargo cache.
  • If it does reduce change, checking against the fee at max_feerate would close the gap.

Seems we'd need to at the very least also do the check in bump_channel_funding_fee.

@shubhamkmr04
shubhamkmr04 force-pushed the splice-in-reserve-fees branch from 915b7dd to dd9b622 Compare November 18, 2026 09:36
@shubhamkmr04 shubhamkmr04 changed the title Count the funding fee in the anchor reserve check for splice-ins Count the funding fee in the anchor reserve check for splice-ins and fee bumps Nov 18, 2026
@shubhamkmr04

Copy link
Copy Markdown
Contributor Author

Thanks!

  1. Agreed, it's added here now. bump_channel_funding_fee checks what the replacement takes from our wallet beyond the pending contribution against the spendable balance, like the on-chain bump_fee_rbf does. That covers both a splice-in bump paid from its change or new coins and a splice-out bump that falls back to the wallet. These are the last two commits, which I'd first opened separately as Check the anchor reserve when fee-bumping a splice #1246 (now closed).

  2. Yes, LDK does take the difference from our change. For a coin-selected contribution, compute_feerate_adjustment shrinks the change, up to the contribution's max_feerate.

    • As acceptor, we don't pay for the common fields or the shared input and output. So even at 1.5x, our fee only exceeds what we checked once the contribution has about four or more inputs.
    • As initiator, it takes the RBF minimum rising between building the contribution and LDK using it, since splice_in_inner already builds at the current RBF minimum.

    Checking the fee at max_feerate up front would close the gap, but it would hold back 50% more fee than needed in the common case. Happy to add it if you'd prefer the stricter check.

@shubhamkmr04
shubhamkmr04 requested a review from tnull November 18, 2026 09:54

@tnull tnull left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we rearrange the commits so we don't first add logic that we then extract into a helper? Seems we can get rid of commit 3 if we just add the logic to the helper directly?

Also claude has some feedback:

  1. A bump before the wallet has synced the pending splice can be rejected for no reason (src/lib.rs:2530-2533)
  • The delta check is exact once the wallet has seen the pending splice transaction: the prior inputs are spent and the prior change counts as spendable.
  • Before that sync, the prior inputs are only locked. The spendable balance then excludes them and has no change to credit, so it understates by the prior change.
  • Example: a single 1,000,000 sat UTXO, splice_in of 100,000, then an immediate bump. Spendable reads 0, so any bump fails with InsufficientFunds although about 875,000 sats are free.
  • This errs on the safe side and clears with the next wallet sync. On Esplora or Electrum, though, that leaves a window in which a bump is refused.
  • Both new tests, and every existing bump test I checked, call sync_wallets() between the splice and the bump, so none covers this.
  • Options: credit the prior change when the prior inputs are still locked and unspent, or document that a bump needs a wallet sync first. Either way, a test that bumps without syncing would pin the behaviour.
  1. The check still uses the selected feerate, not max_feerate (src/lib.rs:1667-1676, carried over)
  • LDK can raise the contribution's fee up to max_feerate out of its change when the counterparty initiates concurrently or the RBF minimum has moved.
  • The reserve can therefore still be undercut by up to half the fee after the check passes.
  • This applies to both splice_in and the bump. Adding estimated_fee * (max_feerate - feerate) / feerate as headroom would close it; otherwise the docs should say so.

@shubhamkmr04
shubhamkmr04 force-pushed the splice-in-reserve-fees branch from dd9b622 to 1f5c87a Compare November 18, 2026 13:13
@shubhamkmr04

Copy link
Copy Markdown
Contributor Author

Thanks, reworked:

  • Commits: the splice-in commit now adds check_sufficient_onchain_funds_for_contribution directly, so nothing is added and then extracted. The prefactor that made check_sufficient_onchain_funds return the spendable balance is gone too, since the new check no longer uses it. That leaves two commits: the splice-in, then the bump.
  • Bump before the wallet has synced the pending splice (1):
    • The check now uses our confirmed, unlocked funds, read before coin selection, and credits the pending contribution's inputs, which are ours again once the replacement confirms unless it spends them too. Neither depends on what wallet sync has seen, so an immediate bump is no longer refused.
    • This also closes a gap in the other direction. With two bumps between syncs, the wallet still counted the first round's larger change, so it overstated our funds by the first bump's extra fee.
    • The bump test now bumps without syncing.
  • max_feerate (2): added as headroom.
    • A contribution may take at most its inputs, less the least change left after LDK raises its fee up to max_feerate, or drops the change once less than dust would remain. The extra fee is bounded by estimated_fee * (max_feerate - feerate) / feerate, rounded up.
    • This applies to both splice_in and bumps, and is documented.
    • A bump that takes no more than the pending contribution still passes, so bumps of splice_in_with_all, and splice-out bumps the channel pays for, keep working when the wallet holds less than the reserve.

@tnull tnull left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good, tagging @jkczyz to see if he has further thoughts on this.

@tnull
tnull requested a review from jkczyz November 18, 2026 13:21

@jkczyz jkczyz left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some comments and a Claude review.

Comment thread src/lib.rs
Comment on lines +1661 to +1664
fn check_sufficient_onchain_funds_for_contribution(
&self, contribution: FundingContribution, prior_contribution: Option<&FundingContribution>,
confirmed_unlocked_sats: u64,
) -> Result<FundingContribution, Error> {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you document that contribution is released via release_inputs_and_outputs on error?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done, added it to the doc.

Comment thread tests/integration_tests_rust.rs Outdated
expect_channel_ready_event!(node_b, node_a.node_id());

let anchor_reserve_sat = 25_000;
assert_eq!(node_a.list_balances().total_anchor_channels_reserve_sats, anchor_reserve_sat);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 This fails on CI with left: 24999, right: 25000, and it will on every run: open_channel_with_all leaves 24,999 on-chain, and list_balances caps the reported reserve at the on-chain balance. open_channel_variants_reserve_funds_for_anchor_peers already expects anchor_reserve_sat - 1 here (L9334-9335).

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch, fixed. It now expects anchor_reserve_sat - 1, same as open_channel_variants_reserve_funds_for_anchor_peers.

Comment thread src/lib.rs
})?,
FundingAmount::Exact { amount_sats } => {
// Coin selection locks the inputs it picks, so read our funds before it.
let confirmed_unlocked_sats = self.wallet.get_confirmed_unlocked_amount_sats();

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 The pre-check in check_sufficient_onchain_funds counts unconfirmed change, but this one doesn't. So with unconfirmed change from an on-chain send, spendable_onchain_balance_sats can cover the splice and it still fails with InsufficientFunds after coin selection. That seems defensible since anchor bumping only spends confirmed outputs, but is it intended? If so, should the pre-check use the same funds so it fails before coin selection?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, intended, since splices only spend confirmed outputs. Agreed on the pre-check though: for splice-ins it now uses the same confirmed funds, so a plain lack of funds fails before coin selection again.

Comment thread src/lib.rs
e
);
}
Err(Error::InsufficientFunds)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@tnull When should we return InsufficientFunds vs ChannelSplicingFailed? InsufficientFunds here matches on-chain sends whose coin selection fails, while splice_out returns ChannelSplicingFailed when the channel balance can't cover the amount. But when a splice's coin selection fails, at L2033 and in the bump at L2559, we return ChannelSplicingFailed.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess ChannelSplicingFailed makes more sense then to keep it generic for now? Maybe this is an indication that going forward we'll need more specific/descriptive error types for the different error cases, but that's probably out-of-scope here?

Comment thread tests/integration_tests_rust.rs Outdated
"{change_sat} sats of change after a splice fee of {fee_sat} sats"
);

// We don't sync node_b's wallet before bumping, so it may not have seen the splice transaction

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 With a bitcoind chain source, the node polls the mempool every 2 seconds, so the wallet may have seen the splice by the time we bump. Only Esplora and Electrum keep it unsynced. Could this test pin one of those so the unsynced case is always covered?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Makes sense, pinned it to Esplora.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, generally we try to keep all tests on random_chain_source to make sure to get coverage independently of chain source. Do we see a straightforward alternative that would allow us to test this in a robust way without pinning one specific chain source?

Comment thread src/lib.rs

let dust_limit_sats = change_output.script_pubkey.minimal_non_dust().to_sat();
let min_change_sats = match change_output.value.to_sat().checked_sub(max_fee_increase_sats) {
Some(change_sats) if change_sats >= dust_limit_sats => change_sats,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 No test drops the change below dust here. test_funding_contribution_with_parts in pending_payment_store.rs could build the contribution for a unit test, though it sets max_feerate to feerate, so it would need a parameter for that.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added unit tests for max_wallet_spend_sats, including change landing exactly on the dust limit and one sat below it. The max_feerate parameter went into a small prefactor commit.

The helper used the input-selection feerate as the contribution's
maximum feerate too. Tests of how much a contribution's fee may still
rise need the two to differ, so take the maximum as its own parameter.
The existing callers pass their feerate, as before.

Part of lightningdevkit#1166.

Developed with assistance from Claude Code.
Splicing in an exact amount only checked that our on-chain funds cover
the amount on top of the anchor reserve. The fee for our contribution to
the splice transaction is paid from the same funds, though, and coin
selection doesn't keep the reserve aside, so the fee could be taken
from it. LDK may also raise that fee later, up to the contribution's
maximum feerate, when our contribution joins a splice the counterparty
initiated or the RBF minimum feerate rises. It pays the difference from
our change.

Once the contribution is built, check in
`check_sufficient_onchain_funds_for_contribution` that the most it may
take from our wallet, its inputs less the least change it may return,
leaves the anchor reserve of our confirmed funds that aren't locked for
a pending funding. These are read before coin selection, which locks
the inputs it picks. Unconfirmed change is left out, so the check
doesn't depend on whether wallet sync has seen a pending splice's
transaction yet. If the contribution doesn't fit, release what it
reserved and fail with `InsufficientFunds`.

Splices only spend confirmed outputs, so check the amount alone against
the same confirmed funds too, before coin selection. A plain lack of
funds still fails there.

The method takes the contribution being replaced as
`prior_contribution`, for the fee bump check that follows: its inputs
are ours again unless the replacement spends them, and a replacement
that takes no more than it is fine.

Part of lightningdevkit#1166.

Developed with assistance from Claude Code.
`bump_channel_funding_fee` didn't check the anchor reserve at all. A
bump of an exact splice-in pays the higher fee from our wallet: LDK
shrinks the pending contribution's change or, past its maximum
feerate, re-runs coin selection. A bump of a splice-out whose channel
balance can't cover the higher fee falls back to funding the whole
withdrawal and fees from our wallet. Neither keeps the reserve aside.

Read our confirmed, unlocked funds before LDK builds the replacement,
and check it with `check_sufficient_onchain_funds_for_contribution`
against the pending contribution. Once the replacement confirms, the
pending contribution's inputs are ours again unless the replacement
spends them too, and the most the replacement may take has to leave the
anchor reserve of all that. A replacement that takes no more than the
pending contribution may still passes. That keeps bumps of
`splice_in_with_all`, and splice-out bumps the channel pays for,
working when the wallet holds less than the reserve. If the check
fails, release what the replacement reserved and fail with
`InsufficientFunds`.

The check leaves out unconfirmed change, so it gives the same result
whether wallet sync has seen the pending splice's transaction, only an
earlier round of it, or neither.

Part of lightningdevkit#1166.

Developed with assistance from Claude Code.
@shubhamkmr04
shubhamkmr04 force-pushed the splice-in-reserve-fees branch from 1f5c87a to 30ec67f Compare November 19, 2026 06:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants