Deprecate AvailableBalances::balance_msat

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.

Co-authored-by: Willem Van Lint <[email protected]>

Author: dunxen

lightning/src/chain/chainmonitor.rs

@@ -394,8 +394,7 @@ where C::Target: chain::Filter,
 	/// claims which are awaiting confirmation.
 	///
 	/// Includes the balances from each [`ChannelMonitor`] *except* those included in
-	/// `ignored_channels`, allowing you to filter out balances from channels which are still open
-	/// (and whose balance should likely be pulled from the [`ChannelDetails`]).
+	/// `ignored_channels`.
 	///
 	/// See [`ChannelMonitor::get_claimable_balances`] for more details on the exact criteria for
 	/// inclusion in the return value.

lightning/src/ln/channel.rs

@@ -80,6 +80,7 @@ pub struct ChannelValueStat {
 
 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")]
 	pub balance_msat: u64,
 	/// Total amount available for our counterparty to send to us.
 	pub inbound_capacity_msat: u64,

lightning/src/ln/channel_state.rs

@@ -273,8 +273,14 @@ impl_writeable_tlv_based!(ChannelCounterparty, {
 
 /// Details of a channel, as returned by [`ChannelManager::list_channels`] and [`ChannelManager::list_usable_channels`]
 ///
+/// Balances of a channel are available through [`ChainMonitor::get_claimable_balances`] and
+/// [`ChannelMonitor::get_claimable_balances`], calculated with respect to the corresponding on-chain
+/// transactions.
+///
 /// [`ChannelManager::list_channels`]: crate::ln::channelmanager::ChannelManager::list_channels
 /// [`ChannelManager::list_usable_channels`]: crate::ln::channelmanager::ChannelManager::list_usable_channels
+/// [`ChainMonitor::get_claimable_balances`]: crate::chain::chainmonitor::ChainMonitor::get_claimable_balances
+/// [`ChannelMonitor::get_claimable_balances`]: crate::chain::channelmonitor::ChannelMonitor::get_claimable_balances
 #[derive(Clone, Debug, PartialEq)]
 pub struct ChannelDetails {
 	/// The channel's ID (prior to funding transaction generation, this is a random 32 bytes,
@@ -363,6 +369,10 @@ pub struct ChannelDetails {
 	/// This does not consider any on-chain fees.
 	///
 	/// See also [`ChannelDetails::outbound_capacity_msat`]
+	#[deprecated(
+		since = "0.0.124",
+		note = "use [`ChannelMonitor::get_claimable_balances`] instead"
+	)]
 	pub balance_msat: u64,
 	/// The available outbound capacity for sending HTLCs to the remote peer. This does not include
 	/// any pending HTLCs which are not yet fully resolved (and, thus, whose balance is not

pending_changelog/3247-deprecate-balance_msat.txt

@@ -0,0 +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).