Expose our "offchain balance" in `Balance`s #4267

TheBlueMatt · 2025-12-08T22:00:00Z

`Balance` seeks to expose our balance accurate based on what we
would get, less fees, if we were to force-close right now. This is
great, but for an end-user wallet its not really what you want to
display as the "balance" of the wallet.

Instead, you want to give a balance which matches the sum of HTLCs
received over time, which is only possible when balance information
is avilable which ignores things like dust, anchors, fees, and
reserve values.

Here we provide such a balance - a new "offchain balance" in
`HolderCommitmentTransactionBalance`.

Fixes #4241.

`Balance` seeks to expose our balance accurate based on what we would get, less fees, if we were to force-close right now. This is great, but for an end-user wallet its not really what you want to display as the "balance" of the wallet. Instead, you want to give a balance which matches the sum of HTLCs received over time, which is only possible when balance information is avilable which ignores things like dust, anchors, fees, and reserve values. Here we provide such a balance - a new "offchain balance" in `HolderCommitmentTransactionBalance`.

ldk-reviews-bot · 2025-12-08T22:00:03Z

I've assigned @joostjager 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.

codecov · 2025-12-08T23:29:15Z

Codecov Report

❌ Patch coverage is 83.57143% with 23 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.32%. Comparing base (fbf0c61) to head (4f1abd3).
⚠️ Report is 5 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning/src/chain/channelmonitor.rs	47.72%	23 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff            @@
##             main    #4267    +/-   ##
========================================
  Coverage   89.32%   89.32%            
========================================
  Files         180      180            
  Lines      139267   139410   +143     
  Branches   139267   139410   +143     
========================================
+ Hits       124402   124530   +128     
- Misses      12235    12254    +19     
+ Partials     2630     2626     -4

Flag	Coverage Δ
fuzzing	`35.09% <67.52%> (+0.10%)`	⬆️
tests	`88.67% <83.57%> (-0.02%)`	⬇️

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.

lightning/src/chain/channelmonitor.rs

joostjager · 2025-12-09T12:41:01Z

lightning/src/chain/channelmonitor.rs

 pub struct HolderCommitmentTransactionBalance {
 	/// The amount available to claim, in satoshis, excluding the on-chain fees which will be
 	/// required to do so.
 	pub amount_satoshis: u64,


Renaming to amount_onchain_satoshis might be helpful to avoid confusion. Or maybe it should be amount_unilateral_close_satoshis?

Hmm, good point. What about amount_claimable_satoshis? Initially I thought that might be confusing as there's a somewhat separate concept of "claimable" between on-chain and off-chain, but actually they're pretty related - the amount we're allowed to send off-chain is, basically, the amount we're able to claim on-chain in an FC, with the one exception being dust, but that only applies for channels with 0 reserve (which are mostly end-user channels and probably use the amount_offchain_satoshis. Its also a part of Balance::ClaimableOnChannelClose which makes it align better I think?

"Claimable" as the unilaterally recoverable balance does seem like an improvement. And it often remains hard to capture the full meaning in a name when dealing with lightning concepts.

joostjager · 2025-12-09T12:43:25Z

lightning/src/chain/channelmonitor.rs

+	///
+	/// This is generally roughly equal to [`Self::amount_satoshis`] +
+	/// [`Self::transaction_fee_satoshis`] + any anchor outputs in the current commitment
+	/// transaction. It might differ slightly due to differences in rounding and HTLC calculation.


What differences in rounding and htlc calculation cause this?

The fee is calculated by just totaling the transaction fee (funding amount minus sum of all the outputs). The amount-offchain is the actual channel balance minus HTLCs pending outbound (in msats) plus inbound HTLCs we have the preimage for.

The HTLC difference is the fees on outputs for inbound HTLCs we have the preimages for, rounding is totally different as well.

You could consider describing some of this in the code.

Hmm, spent a minute fighting with it but not sure how to add it such that its actually useful information. It shouldn't differ by more than a few sats, so going into detail about how its all calculated seems kinda overkill?

Yes not critical to add. Just the question that came to mind when reading the comment.

lightning/src/chain/channelmonitor.rs

joostjager · 2025-12-09T13:14:58Z

lightning/src/chain/channelmonitor.rs

+					balance_candidates.last().map(|balance| balance.amount_offchain_satoshis.unwrap_or(balance.amount_satoshis)).unwrap_or(0)
+				}
+			},
+			Balance::ClaimableAwaitingConfirmations { amount_satoshis, .. }|


Shouldn't offchain_amount_satoshis be undefined if the channel is no longer offchain? Maybe this indicates that the name isn't fully covering the meaning of the value.

Yea, maybe the name could use some workshopping. My intended use here is really "balance that an end-user wallet might care about" which obviously includes funds which we're in the process of claiming on-chain, but until we close its not really anything corresponding to anything "on-chain". I'm definitely open to a better name, if you have any thoughts.

user_balance maybe? That is quite indirect though, but maybe it is good to steer away from onchain/offchain because there are nuances to that.

Hmm, I don't want to imply that our devs should prefer this as the "balance". Its really not - the claimable amount is closer to the "balance" IMO, though of course its a bit misleading as well...

Yes, don't know. Maybe 2nd reviewer has inspiration...

lightning/src/ln/chan_utils.rs

joostjager · 2025-12-09T14:12:32Z

lightning/src/ln/chan_utils.rs

 #[derive(Clone, Debug)]
 pub struct CommitmentTransaction {
 	commitment_number: u64,
+	to_broadcaster_value_offchain_msat: Option<u64>,


Were there other data structures that could have stored this value? The field looks a bit out of place between all the on-chain properties.

We could put it directly in the ChannelMonitorUpdateStep::LatestCounterpartyCommitment but it doesn't really feel like it belongs there any more. The nice thing about being in the CommitmentTransaction is it will (eventually) go through the custom commitment transaction API, which I think feels right?

LatestCounterpartyCommitment does have some additional non-on-chain info like htlc sources already. But not sure how those two options compare.

The nice thing about being in the CommitmentTransaction is it will (eventually) go through the custom commitment transaction API

Can you elaborate a bit more on what it brings to have to_broadcaster_value_offchain_msat go through the custom commit tx API? That the calculation of value_offchain can also be custom you mean?

ldk-reviews-bot · 2025-12-09T14:13:47Z

👋 The first review has been submitted!

Do you think this PR is ready for a second reviewer? If so, click here to assign a second reviewer.

In a previous commit we introduced the concept of the "offchain balance" to `HolderCommitmentTransactionBalance` to better capture the type of balance that end-user walets likely wish to expose. Here we expose an accessor on `Balance` to fetch that concept across difference `Balance` variants easily. Fixes lightningdevkit#4241

TheBlueMatt added this to the 0.3 milestone Dec 8, 2025

ldk-reviews-bot requested a review from joostjager December 8, 2025 22:10

joostjager reviewed Dec 9, 2025

View reviewed changes

TheBlueMatt added 6 commits December 9, 2025 15:45

f rename

83a5102

f drop extra crap

b006a82

Run rustfmt on CommitmentTransaction's builder

16f1ab8

f is the sum, not close to

ec72e56

Run rustfmt on Balance methods

4f1abd3

TheBlueMatt force-pushed the 2025-12-end-user-balances branch from 0b0f140 to 4f1abd3 Compare December 9, 2025 15:45

Expose our "offchain balance" in Balances #4267

Are you sure you want to change the base?

Expose our "offchain balance" in Balances #4267

Uh oh!

Conversation

TheBlueMatt commented Dec 8, 2025

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Codecov Report

Uh oh!

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!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joostjager Dec 9, 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!

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!

Choose a reason for hiding this comment

Uh oh!

ldk-reviews-bot commented Dec 9, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Expose our "offchain balance" in `Balance`s #4267

Expose our "offchain balance" in `Balance`s #4267

ldk-reviews-bot commented Dec 8, 2025 •

edited

Loading

codecov bot commented Dec 8, 2025 •

edited

Loading

joostjager Dec 9, 2025 •

edited

Loading