Expose our "offchain balance" in Balances
#4267
Conversation
`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`.
|
I've assigned @joostjager as a reviewer! |
Codecov Report❌ Patch coverage is
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
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
| 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, |
There was a problem hiding this comment.
Renaming to amount_onchain_satoshis might be helpful to avoid confusion. Or maybe it should be amount_unilateral_close_satoshis?
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
"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.
| /// | ||
| /// 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. |
There was a problem hiding this comment.
What differences in rounding and htlc calculation cause this?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
You could consider describing some of this in the code.
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
Yes not critical to add. Just the question that came to mind when reading the comment.
| balance_candidates.last().map(|balance| balance.amount_offchain_satoshis.unwrap_or(balance.amount_satoshis)).unwrap_or(0) | ||
| } | ||
| }, | ||
| Balance::ClaimableAwaitingConfirmations { amount_satoshis, .. }| |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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...
There was a problem hiding this comment.
Yes, don't know. Maybe 2nd reviewer has inspiration...
| #[derive(Clone, Debug)] | ||
| pub struct CommitmentTransaction { | ||
| commitment_number: u64, | ||
| to_broadcaster_value_offchain_msat: Option<u64>, |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
That the calculation of value_offchain can also be custom you mean?
Right, this. Some "balance" might actually be locked up in some sub-protocol LDK isn't aware of, at least eventually.
There was a problem hiding this comment.
See comment below, and PR #4026 for a potential path to customization of this offchain value.
|
👋 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
force-pushed
the
2025-12-end-user-balances
branch
from
0b0f140 to
4f1abd3
Compare
|
✅ Added second reviewer: @tankyleo |
tankyleo
left a comment
tankyleo
left a comment
There was a problem hiding this comment.
Have you considered exposing this concept in channel instead, via get_available_balances and ChannelDetails ? We've now consolidated and cleaned up a lot of things in channel, so I wonder if calculating this concept there is now straightforward and easier to reason about than in the past. I understand I am missing conversations behind the removal of AvailableBalances::balance_msat, have only read some parts.
In #4026 I give the channel state machine snapshot to TxBuilder and ask it to give me AvailableBalances, so there is still a path to customization if we go the channel direction.
FundedChannel::send_htlc calls get_available_balances to determine whether it can send this new HTLC, so it seems reasonable to me to have get_available_balances also produce the offchain balance.
Part of the reason we dropped it is because we didn't want to have two separate ways to calculate "balance". While I agree this approach would simplify the implementation, it would reintroduce the dual balance APIs, which I'm very much not a fan of. |
Agreed dual-balance API is ugly. I'm also not digesting well sticking an offchain balance in I do like keeping Keeping it as dual-APIs would make it clear to the user, if you want an offchain balance, look in channel, if you want a balance that you can actually claim on-chain, look in channelmonitor. In my experience with ldk-server, I always looked at If we put the @wpaulino would love to hear your thoughts - if you are good with this direction here, I can see it working too. |
|
I'm also not a huge fan of tracking the offchain balance in the monitor. Exposing it in I would actually prefer to see @MaxFangX's suggestion in #4241 to include the amount burned to fees from the offchain state, with either a helper or documentation on how you could arrive at the offchain balance. |
Hmm in #4026 I build the set of HTLCs like this before passing it to let pending_outbound_htlcs = self.pending_outbound_htlcs.iter().map(|htlc| HTLCAmountDirection { amount_msat: htlc.amount_msat, outbound: true });
let pending_inbound_htlcs = self.pending_inbound_htlcs.iter().map(|htlc| HTLCAmountDirection { amount_msat: htlc.amount_msat, outbound: false });
let holding_cell_htlcs = self.holding_cell_htlc_updates.iter().filter_map(|htlc| {
if let &HTLCUpdateAwaitingACK::AddHTLC { amount_msat, .. } = htlc {
Some(HTLCAmountDirection { outbound: true, amount_msat })
} else {
None
}
});
let mut pending_htlcs: Vec<HTLCAmountDirection> = Vec::with_capacity(self.pending_outbound_htlcs.len() + self.pending_inbound_htlcs.len() + self.holding_cell_htlc_updates.len());
pending_htlcs.extend(pending_outbound_htlcs.chain(pending_inbound_htlcs).chain(holding_cell_htlcs));
let dust_exposure_limiting_feerate = self.get_dust_exposure_limiting_feerate(
&fee_estimator, funding.get_channel_type(),
);
let max_dust_htlc_exposure_msat = self.get_max_dust_htlc_exposure_msat(dust_exposure_limiting_feerate);
SpecTxBuilder {}.get_available_balances(
funding.is_outbound(),
funding.get_value_satoshis(),
funding.get_value_to_self_msat(),
&pending_htlcs,
self.feerate_per_kw,
dust_exposure_limiting_feerate,
max_dust_htlc_exposure_msat,
self.get_holder_channel_constraints(funding),
self.get_counterparty_channel_constraints(funding),
funding.get_channel_type(),
) |
Its weird in
This is what we had before, and people just never saw the other balance, used the one in
But this is a totally different concept from the "balance". The Admittedly this is maybe useful, in sum across channels, as the "balance you can send in your next payment over LN", but IMO its wrong to pull this for that as in the future it might well break - the router may get smarter and MPP across a single channel.
This is just two sides of the same coin? Storing the "user balance minus available-to-claim balance" just means doing math when building the |
I agree it's essentially the same, but it maintains the "onchain" theme of the monitor better than just exposing the offchain balance directly since fees are enforceable onchain, and meshes well with the already exposed |
Not opinionated on how LDK how stores the value internally, but just want to note that due to UI / UX reasons we've already had to manually match on We'd love to remove this logic and just use the new |
To clarify your concern - is your view that the If its the first you're really arguing we need to move In terms of internal storage, ultimately the
That's still gonna be funky with reserve values + anchors as values below reserve will still show 0 (at least for inbound channels) and anchors will be excluded from the balance (for outbound channels). I assume that is not what you want? |
Correct. Things like anchors and channel reserves are low-level implementation details that average Joe consumers aren't going to care about once they have some significant amount of funds in the channel. They're going to be more concerned if when testing the wallet they deposit 100 sats and it displays as 0 sats despite a successful payment - they'll think the wallet is a scam, or at minimum think it is broken in some way. |
6 participants
Fixes #4241.