Skip to content

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

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

shubhamkmr04 wants to merge 2 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

  • 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. A plain lack of funds still fails before coin selection.
  • 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

  • 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, without syncing B's wallet between the splice and the bumps:
    • 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.

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`. A plain lack of funds still
fails before coin selection.

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

3 participants