Deprecate AvailableBalances::balance_msat

[dunxen]

The ChannelMonitor::get_claimable_balances method provides a more straightforward approach to the balance of a channel, which satisfies most use cases. The computation of AvailableBalances::balance_msat is complex and originally had a different purpose that is not applicable anymore. We deprecate AvailableBalances::balance_msat now and will remove it in a following release by #3243.

See #3243 for context/motivation.

[codecov]

Codecov Report

Attention: Patch coverage is 98.01980% with 2 lines in your changes missing coverage. Please review.

Project coverage is 89.84%. Comparing base (680d399) to head (0a1adeb).
Report is 9 commits behind head on main.

Files	Patch %	Lines
lightning/src/ln/channel_state.rs	98.98%	0 Missing and 1 partial ⚠️
lightning/src/routing/router.rs	50.00%	1 Missing ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #3247 +/- ##
==========================================
+ Coverage 89.71% 89.84% +0.12% 
==========================================
Files 125 125 Lines 102801 103009 +208 Branches 102801 103009 +208 ==========================================
+ Hits 92226 92545 +319 + Misses 7865 7754 -111 
Partials 2710 2710 

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[vincenzopalazzo]

It looks like the CI is complaining about something, probably we should relax the check for this deprecated field?

warning: build failed, waiting for other jobs to finish...
error: use of deprecated field `ln::channel_state::ChannelDetails::balance_msat`: use [`ChannelMonitor::get_claimable_balances`] instead
--> lightning/src/routing/router.rs:3605:4
|
3605 | balance_msat: 0,
| ^^^^^^^^^^^^^^^
error: use of deprecated field `ln::channel_state::ChannelDetails::balance_msat`: use [`ChannelMonitor::get_claimable_balances`] instead
--> lightning/src/routing/router.rs:8880:4
|
8880 | balance_msat: 10_000_000_000,
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
error: could not compile `lightning` due to 7 previous errors

[dunxen]

It looks like the CI is complaining about something, probably we should relax the check for this deprecated field?

warning: build failed, waiting for other jobs to finish...
error: use of deprecated field `ln::channel_state::ChannelDetails::balance_msat`: use [`ChannelMonitor::get_claimable_balances`] instead
--> lightning/src/routing/router.rs:3605:4
|
3605 | balance_msat: 0,
| ^^^^^^^^^^^^^^^
error: use of deprecated field `ln::channel_state::ChannelDetails::balance_msat`: use [`ChannelMonitor::get_claimable_balances`] instead
--> lightning/src/routing/router.rs:8880:4
|
8880 | balance_msat: 10_000_000_000,
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
error: could not compile `lightning` due to 7 previous errors

Yip, I'll ignore it for our usage.

[TheBlueMatt]

I don't think we need to deprecate this, its internal-only and not exported.

[TheBlueMatt]

I guess we can deprecate it to avoid new uses internally from creeping in causing us pain to remove this later.

[TheBlueMatt]

I guess we can deprecate it to avoid new uses internally from creeping in causing us pain to remove this later.

[TheBlueMatt]

Should we link to ChainMonitor::get_claimable_balances instead, since that's more directly usable?

[valentinewallace]

LGTM after Matt's comment

[dunxen]

Latest changes

diff --git a/lightning/src/ln/channel.rs b/lightning/src/ln/channel.rs
index 0b15151c..731b203f 100644
--- a/lightning/src/ln/channel.rs+++ b/lightning/src/ln/channel.rs@@ -82,3 +82,3 @@ pub struct AvailableBalances {
/// The amount that would go to us if we close the channel, ignoring any on-chain fees.
-	#[deprecated(since = "0.0.124", note = "use [`ChannelMonitor::get_claimable_balances`] instead")]+	#[deprecated(since = "0.0.124", note = "use [`ChainMonitor::get_claimable_balances`] instead")]
pub balance_msat: u64,
diff --git a/lightning/src/ln/channel_state.rs b/lightning/src/ln/channel_state.rs
index f21822cd..7a9bbf9b 100644
--- a/lightning/src/ln/channel_state.rs+++ b/lightning/src/ln/channel_state.rs@@ -371,6 +371,3 @@ pub struct ChannelDetails {
/// See also [`ChannelDetails::outbound_capacity_msat`]
-	#[deprecated(- since = "0.0.124",- note = "use [`ChannelMonitor::get_claimable_balances`] instead"-	)]+	#[deprecated(since = "0.0.124", note = "use [`ChainMonitor::get_claimable_balances`] instead")]
pub balance_msat: u64,
diff --git a/pending_changelog/3247-deprecate-balance_msat.txt b/pending_changelog/3247-deprecate-balance_msat.txt
index 1f0eebd5..662eb3de 100644
--- a/pending_changelog/3247-deprecate-balance_msat.txt+++ b/pending_changelog/3247-deprecate-balance_msat.txt@@ -1 +1 @@-* The `AvailableBalances::balance_msat` field has been deprecated in favor of `ChannelMonitor::get_claimable_balances`. `AvailableBalances::balance_msat` will be removed in an upcoming release (#3247).+* The `AvailableBalances::balance_msat` field has been deprecated in favor of `ChainMonitor::get_claimable_balances`. `AvailableBalances::balance_msat` will be removed in an upcoming release (#3247).