Remove AvailableBalances::balance_msat

The ChannelMonitor::get_claimable_balances and ChainMonitor::get_claimable_balances
methods provide 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.

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

Author: dunxen

fuzz/src/router.rs

@@ -242,7 +242,6 @@ pub fn do_test<Out: test_logger::Output>(data: &[u8], out: Out) {
 							is_channel_ready: true,
 							is_usable: true,
 							is_public: true,
-							balance_msat: 0,
 							outbound_capacity_msat: capacity.saturating_mul(1000),
 							next_outbound_htlc_limit_msat: capacity.saturating_mul(1000),
 							next_outbound_htlc_minimum_msat: 0,

lightning/src/ln/channel.rs

@@ -79,9 +79,6 @@ 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 [`ChainMonitor::get_claimable_balances`] instead")]
-	pub balance_msat: u64,
 	/// Total amount available for our counterparty to send to us.
 	pub inbound_capacity_msat: u64,
 	/// Total amount available for us to send to our counterparty.
@@ -3077,14 +3074,6 @@ impl<SP: Deref> ChannelContext<SP> where SP::Target: SignerProvider  {
 		let dust_exposure_limiting_feerate = self.get_dust_exposure_limiting_feerate(&fee_estimator);
 		let htlc_stats = context.get_pending_htlc_stats(None, dust_exposure_limiting_feerate);
 
-		let mut balance_msat = context.value_to_self_msat;
-		for ref htlc in context.pending_inbound_htlcs.iter() {
-			if let InboundHTLCState::LocalRemoved(InboundHTLCRemovalReason::Fulfill(_)) = htlc.state {
-				balance_msat += htlc.amount_msat;
-			}
-		}
-		balance_msat -= htlc_stats.pending_outbound_htlcs_value_msat;
-
 		let outbound_capacity_msat = context.value_to_self_msat
 				.saturating_sub(htlc_stats.pending_outbound_htlcs_value_msat)
 				.saturating_sub(
@@ -3226,7 +3215,6 @@ impl<SP: Deref> ChannelContext<SP> where SP::Target: SignerProvider  {
 			outbound_capacity_msat,
 			next_outbound_htlc_limit_msat: available_capacity_msat,
 			next_outbound_htlc_minimum_msat,
-			balance_msat,
 		}
 	}
 

lightning/src/ln/channel_state.rs

@@ -359,25 +359,11 @@ pub struct ChannelDetails {
 	///
 	/// This value will be `None` for objects serialized with LDK versions prior to 0.0.115.
 	pub feerate_sat_per_1000_weight: Option<u32>,
-	/// Our total balance.  This is the amount we would get if we close the channel.
-	/// This value is not exact. Due to various in-flight changes and feerate changes, exactly this
-	/// amount is not likely to be recoverable on close.
-	///
-	/// This does not include any pending HTLCs which are not yet fully resolved (and, thus, whose
-	/// balance is not available for inclusion in new outbound HTLCs). This further does not include
-	/// any pending outgoing HTLCs which are awaiting some other resolution to be sent.
-	/// This does not consider any on-chain fees.
-	///
-	/// See also [`ChannelDetails::outbound_capacity_msat`]
-	#[deprecated(since = "0.0.124", note = "use [`ChainMonitor::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
 	/// available for inclusion in new outbound HTLCs). This further does not include any pending
 	/// outgoing HTLCs which are awaiting some other resolution to be sent.
 	///
-	/// See also [`ChannelDetails::balance_msat`]
-	///
 	/// This value is not exact. Due to various in-flight changes, feerate changes, and our
 	/// conflict-avoidance policy, exactly this amount is not likely to be spendable. However, we
 	/// should be able to spend nearly this amount.
@@ -387,8 +373,8 @@ pub struct ChannelDetails {
 	/// the current state and per-HTLC limit(s). This is intended for use when routing, allowing us
 	/// to use a limit as close as possible to the HTLC limit we can currently send.
 	///
-	/// See also [`ChannelDetails::next_outbound_htlc_minimum_msat`],
-	/// [`ChannelDetails::balance_msat`], and [`ChannelDetails::outbound_capacity_msat`].
+	/// See also [`ChannelDetails::next_outbound_htlc_minimum_msat`] and
+	/// [`ChannelDetails::outbound_capacity_msat`].
 	pub next_outbound_htlc_limit_msat: u64,
 	/// The minimum value for sending a single HTLC to the remote peer. This is the equivalent of
 	/// [`ChannelDetails::next_outbound_htlc_limit_msat`] but represents a lower-bound, rather than
@@ -540,7 +526,6 @@ impl ChannelDetails {
 			channel_value_satoshis: context.get_value_satoshis(),
 			feerate_sat_per_1000_weight: Some(context.get_feerate_sat_per_1000_weight()),
 			unspendable_punishment_reserve: to_self_reserve_satoshis,
-			balance_msat: balance.balance_msat,
 			inbound_capacity_msat: balance.inbound_capacity_msat,
 			outbound_capacity_msat: balance.outbound_capacity_msat,
 			next_outbound_htlc_limit_msat: balance.next_outbound_htlc_limit_msat,
@@ -569,41 +554,38 @@ impl Writeable for ChannelDetails {
 		// versions prior to 0.0.113, the u128 is serialized as two separate u64 values.
 		let user_channel_id_low = self.user_channel_id as u64;
 		let user_channel_id_high_opt = Some((self.user_channel_id >> 64) as u64);
-		#[allow(deprecated)] // TODO: Remove once balance_msat is removed.
-		{
-			write_tlv_fields!(writer, {
-				(1, self.inbound_scid_alias, option),
-				(2, self.channel_id, required),
-				(3, self.channel_type, option),
-				(4, self.counterparty, required),
-				(5, self.outbound_scid_alias, option),
-				(6, self.funding_txo, option),
-				(7, self.config, option),
-				(8, self.short_channel_id, option),
-				(9, self.confirmations, option),
-				(10, self.channel_value_satoshis, required),
-				(12, self.unspendable_punishment_reserve, option),
-				(14, user_channel_id_low, required),
-				(16, self.balance_msat, required),
-				(18, self.outbound_capacity_msat, required),
-				(19, self.next_outbound_htlc_limit_msat, required),
-				(20, self.inbound_capacity_msat, required),
-				(21, self.next_outbound_htlc_minimum_msat, required),
-				(22, self.confirmations_required, option),
-				(24, self.force_close_spend_delay, option),
-				(26, self.is_outbound, required),
-				(28, self.is_channel_ready, required),
-				(30, self.is_usable, required),
-				(32, self.is_public, required),
-				(33, self.inbound_htlc_minimum_msat, option),
-				(35, self.inbound_htlc_maximum_msat, option),
-				(37, user_channel_id_high_opt, option),
-				(39, self.feerate_sat_per_1000_weight, option),
-				(41, self.channel_shutdown_state, option),
-				(43, self.pending_inbound_htlcs, optional_vec),
-				(45, self.pending_outbound_htlcs, optional_vec),
-			});
-		}
+		write_tlv_fields!(writer, {
+			(1, self.inbound_scid_alias, option),
+			(2, self.channel_id, required),
+			(3, self.channel_type, option),
+			(4, self.counterparty, required),
+			(5, self.outbound_scid_alias, option),
+			(6, self.funding_txo, option),
+			(7, self.config, option),
+			(8, self.short_channel_id, option),
+			(9, self.confirmations, option),
+			(10, self.channel_value_satoshis, required),
+			(12, self.unspendable_punishment_reserve, option),
+			(14, user_channel_id_low, required),
+			(16, self.next_outbound_htlc_limit_msat, required), // Forwards compatibility for removed balance_msat field.
+			(18, self.outbound_capacity_msat, required),
+			(19, self.next_outbound_htlc_limit_msat, required),
+			(20, self.inbound_capacity_msat, required),
+			(21, self.next_outbound_htlc_minimum_msat, required),
+			(22, self.confirmations_required, option),
+			(24, self.force_close_spend_delay, option),
+			(26, self.is_outbound, required),
+			(28, self.is_channel_ready, required),
+			(30, self.is_usable, required),
+			(32, self.is_public, required),
+			(33, self.inbound_htlc_minimum_msat, option),
+			(35, self.inbound_htlc_maximum_msat, option),
+			(37, user_channel_id_high_opt, option),
+			(39, self.feerate_sat_per_1000_weight, option),
+			(41, self.channel_shutdown_state, option),
+			(43, self.pending_inbound_htlcs, optional_vec),
+			(45, self.pending_outbound_htlcs, optional_vec),
+		});
 		Ok(())
 	}
 }
@@ -623,7 +605,7 @@ impl Readable for ChannelDetails {
 			(10, channel_value_satoshis, required),
 			(12, unspendable_punishment_reserve, option),
 			(14, user_channel_id_low, required),
-			(16, balance_msat, required),
+			(16, _balance_msat, option), // Backwards compatibility for removed balance_msat field.
 			(18, outbound_capacity_msat, required),
 			// Note that by the time we get past the required read above, outbound_capacity_msat will be
 			// filled in, so we can safely unwrap it here.
@@ -651,7 +633,8 @@ impl Readable for ChannelDetails {
 		let user_channel_id = user_channel_id_low as u128
 			+ ((user_channel_id_high_opt.unwrap_or(0 as u64) as u128) << 64);
 
-		#[allow(deprecated)] // TODO: Remove once balance_msat is removed.
+		let _balance_msat: Option<u64> = _balance_msat;
+
 		Ok(Self {
 			inbound_scid_alias,
 			channel_id: channel_id.0.unwrap(),
@@ -664,7 +647,6 @@ impl Readable for ChannelDetails {
 			channel_value_satoshis: channel_value_satoshis.0.unwrap(),
 			unspendable_punishment_reserve,
 			user_channel_id,
-			balance_msat: balance_msat.0.unwrap(),
 			outbound_capacity_msat: outbound_capacity_msat.0.unwrap(),
 			next_outbound_htlc_limit_msat: next_outbound_htlc_limit_msat.0.unwrap(),
 			next_outbound_htlc_minimum_msat: next_outbound_htlc_minimum_msat.0.unwrap(),
@@ -762,7 +744,6 @@ mod tests {
 			inbound_scid_alias: None,
 			channel_value_satoshis: 50_100,
 			user_channel_id: (u64::MAX as u128) + 1, // Gets us into the high bytes
-			balance_msat: 23_100,
 			outbound_capacity_msat: 24_300,
 			next_outbound_htlc_limit_msat: 20_000,
 			next_outbound_htlc_minimum_msat: 132,

lightning/src/routing/router.rs

@@ -3609,7 +3609,6 @@ mod tests {
 			inbound_scid_alias: None,
 			channel_value_satoshis: 0,
 			user_channel_id: 0,
-			balance_msat: 0,
 			outbound_capacity_msat,
 			next_outbound_htlc_limit_msat: outbound_capacity_msat,
 			next_outbound_htlc_minimum_msat: 0,
@@ -8797,7 +8796,6 @@ pub(crate) mod bench_utils {
 			outbound_scid_alias: None,
 			channel_value_satoshis: 10_000_000_000,
 			user_channel_id: 0,
-			balance_msat: 10_000_000_000,
 			outbound_capacity_msat: 10_000_000_000,
 			next_outbound_htlc_minimum_msat: 0,
 			next_outbound_htlc_limit_msat: 10_000_000_000,

pending_changelog/3243-remove-balance_msat.txt

@@ -0,0 +1 @@
+* The `AvailableBalances::balance_msat` field has been removed in favor of `ChainMonitor::get_claimable_balances`. `ChannelDetails` serialized with versions of LDK >= 0.0.125 will have their `balance_msat` field set to `next_outbound_htlc_limit_msat` when read by versions of LDK prior to 0.0.125 (#3243).