Skip to content

Commit

Permalink
Deprecate AvailableBalances::balance_msat
Browse files Browse the repository at this point in the history 
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]>
  • Loading branch information
@dunxen @wvanlint
dunxen and wvanlint committed Aug 20, 2024
1 parent 680d399 commit 70762f9
Show file tree
Hide file tree
Showing 5 changed files with 50 additions and 34 deletions.
3 changes: 1 addition & 2 deletions lightning/src/chain/chainmonitor.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 2 additions & 0 deletions lightning/src/ln/channel.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 [`ChainMonitor::get_claimable_balances`] instead")]
pub balance_msat: u64,
/// Total amount available for our counterparty to send to us.
pub inbound_capacity_msat: u64,
Expand Down Expand Up @@ -3215,6 +3216,7 @@ impl<SP: Deref> ChannelContext<SP> where SP::Target: SignerProvider {
available_capacity_msat = 0;
}

#[allow(deprecated)] // TODO: Remove once balance_msat is removed.
AvailableBalances {
inbound_capacity_msat: cmp::max(context.channel_value_satoshis as i64 * 1000
- context.value_to_self_msat as i64
Expand Down
76 changes: 44 additions & 32 deletions lightning/src/ln/channel_state.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -363,6 +369,7 @@ pub struct ChannelDetails {
/// 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
Expand Down Expand Up @@ -495,6 +502,7 @@ impl ChannelDetails {
let balance = context.get_available_balances(fee_estimator);
let (to_remote_reserve_satoshis, to_self_reserve_satoshis) =
context.get_holder_counterparty_selected_channel_reserve_satoshis();
#[allow(deprecated)] // TODO: Remove once balance_msat is removed.
ChannelDetails {
channel_id: context.channel_id(),
counterparty: ChannelCounterparty {
Expand Down Expand Up @@ -561,38 +569,41 @@ 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);
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),
});
#[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),
});
}
Ok(())
}
}
Expand Down Expand Up @@ -640,6 +651,7 @@ 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.
Ok(Self {
inbound_scid_alias,
channel_id: channel_id.0.unwrap(),
Expand Down
2 changes: 2 additions & 0 deletions lightning/src/routing/router.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3591,6 +3591,7 @@ mod tests {

fn get_channel_details(short_channel_id: Option<u64>, node_id: PublicKey,
features: InitFeatures, outbound_capacity_msat: u64) -> ChannelDetails {
#[allow(deprecated)] // TODO: Remove once balance_msat is removed.
ChannelDetails {
channel_id: ChannelId::new_zero(),
counterparty: ChannelCounterparty {
Expand Down Expand Up @@ -8776,6 +8777,7 @@ pub(crate) mod bench_utils {

#[inline]
pub(crate) fn first_hop(node_id: PublicKey) -> ChannelDetails {
#[allow(deprecated)] // TODO: Remove once balance_msat is removed.
ChannelDetails {
channel_id: ChannelId::new_zero(),
counterparty: ChannelCounterparty {
Expand Down
1 change: 1 addition & 0 deletions pending_changelog/3247-deprecate-balance_msat.txt
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
* 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).

0 comments on commit 70762f9

Please sign in to comment.