Enum Balance 

pub enum Balance {
    ClaimableOnChannelClose {
        balance_candidates: Vec<HolderCommitmentTransactionBalance>,
        confirmed_balance_candidate_index: usize,
        outbound_payment_htlc_rounded_msat: u64,
        outbound_forwarded_htlc_rounded_msat: u64,
        inbound_claiming_htlc_rounded_msat: u64,
        inbound_htlc_rounded_msat: u64,
    },
    ClaimableAwaitingConfirmations {
        amount_satoshis: u64,
        confirmation_height: u32,
        source: BalanceSource,
    },
    ContentiousClaimable {
        amount_satoshis: u64,
        timeout_height: u32,
        payment_hash: PaymentHash,
        payment_preimage: PaymentPreimage,
    },
    MaybeTimeoutClaimableHTLC {
        amount_satoshis: u64,
        claimable_height: u32,
        payment_hash: PaymentHash,
        outbound_payment: bool,
    },
    MaybePreimageClaimableHTLC {
        amount_satoshis: u64,
        expiry_height: u32,
        payment_hash: PaymentHash,
    },
    CounterpartyRevokedOutputClaimable {
        amount_satoshis: u64,
    },
}

Details about the balance(s) available for spending once the channel appears on chain.

See ChannelMonitor::get_claimable_balances for more details on when these will or will not be provided.

Variants

ClaimableOnChannelClose

The channel is not yet closed (or the commitment or closing transaction has not yet appeared in a block).

Fields

balance_candidates: Vec<HolderCommitmentTransactionBalance>

A list of balance candidates based on the latest set of valid holder commitment transactions that can hit the chain. Typically, a channel only has one valid holder commitment transaction that spends the current funding output. As soon as a channel is spliced, an alternative holder commitment transaction exists spending the new funding output. More alternative holder commitment transactions can exist as the splice remains pending and RBF attempts are made.

The candidates are sorted by the order in which the holder commitment transactions were negotiated. When only one candidate exists, the channel does not have a splice pending. When multiple candidates exist, the last one reflects the balance of the latest splice/RBF attempt, while the first reflects the balance prior to the splice occurring.

Entries remain in this vec until the pending splice has reached ANTI_REORG_DELAY confirmations, at which point any conflicts will be removed. Once a splice confirms Self::ClaimableOnChannelClose::confirmed_balance_candidate_index will point to the confirmed entry, even if it has fewer than ANTI_REORG_DELAY confirmations.

confirmed_balance_candidate_index: usize

The index within Balance::ClaimableOnChannelClose::balance_candidates for the balance according to the current onchain state of the channel. This can be helpful when wanting to determine the claimable amount when the holder commitment transaction for the current funding transaction is broadcast and/or confirms.

outbound_payment_htlc_rounded_msat: u64

The amount of millisatoshis which has been burned to fees from HTLCs which are outbound from us and are related to a payment which was sent by us. This is the sum of the millisatoshis part of all HTLCs which are otherwise represented by Balance::MaybeTimeoutClaimableHTLC with their Balance::MaybeTimeoutClaimableHTLC::outbound_payment flag set, as well as any dust HTLCs which would otherwise be represented the same.

This amount (rounded up to a whole satoshi value) will not be included in amount_satoshis.

outbound_forwarded_htlc_rounded_msat: u64

The amount of millisatoshis which has been burned to fees from HTLCs which are outbound from us and are related to a forwarded HTLC. This is the sum of the millisatoshis part of all HTLCs which are otherwise represented by Balance::MaybeTimeoutClaimableHTLC with their Balance::MaybeTimeoutClaimableHTLC::outbound_payment flag not set, as well as any dust HTLCs which would otherwise be represented the same.

This amount (rounded up to a whole satoshi value) will not be included in amount_satoshis.

inbound_claiming_htlc_rounded_msat: u64

The amount of millisatoshis which has been burned to fees from HTLCs which are inbound to us and for which we know the preimage. This is the sum of the millisatoshis part of all HTLCs which would be represented by Balance::ContentiousClaimable on channel close, but whose current value is included in HolderCommitmentTransactionBalance::amount_satoshis, as well as any dust HTLCs which would otherwise be represented the same.

This amount (rounded up to a whole satoshi value) will not be included in the counterparty’s amount_satoshis.

inbound_htlc_rounded_msat: u64

The amount of millisatoshis which has been burned to fees from HTLCs which are inbound to us and for which we do not know the preimage. This is the sum of the millisatoshis part of all HTLCs which would be represented by Balance::MaybePreimageClaimableHTLC on channel close, as well as any dust HTLCs which would otherwise be represented the same.

This amount (rounded up to a whole satoshi value) will not be included in the counterparty’s amount_satoshis.

ClaimableAwaitingConfirmations

The channel has been closed, and the given balance is ours but awaiting confirmations until we consider it spendable.

Fields

amount_satoshis: u64

The amount available to claim, in satoshis, possibly excluding the on-chain fees which were spent in broadcasting the transaction.

confirmation_height: u32

The height at which an Event::SpendableOutputs event will be generated for this amount.

source: BalanceSource

Whether this balance is a result of cooperative close, a force-close, or an HTLC.

ContentiousClaimable

The channel has been closed, and the given balance should be ours but awaiting spending transaction confirmation. If the spending transaction does not confirm in time, it is possible our counterparty can take the funds by broadcasting an HTLC timeout on-chain.

Once the spending transaction confirms, before it has reached enough confirmations to be considered safe from chain reorganizations, the balance will instead be provided via Balance::ClaimableAwaitingConfirmations.

Fields

amount_satoshis: u64

The amount available to claim, in satoshis, excluding the on-chain fees which will be required to do so.

timeout_height: u32

The height at which the counterparty may be able to claim the balance if we have not done so.

payment_hash: PaymentHash

The payment hash that locks this HTLC.

payment_preimage: PaymentPreimage

The preimage that can be used to claim this HTLC.

MaybeTimeoutClaimableHTLC

HTLCs which we sent to our counterparty which are claimable after a timeout (less on-chain fees) if the counterparty does not know the preimage for the HTLCs. These are somewhat likely to be claimed by our counterparty before we do.

Fields

amount_satoshis: u64

The amount potentially available to claim, in satoshis, excluding the on-chain fees which will be required to do so.

claimable_height: u32

The height at which we will be able to claim the balance if our counterparty has not done so.

payment_hash: PaymentHash

The payment hash whose preimage our counterparty needs to claim this HTLC.

outbound_payment: bool

Whether this HTLC represents a payment which was sent outbound from us. Otherwise it represents an HTLC which was forwarded (and should, thus, have a corresponding inbound edge on another channel).

MaybePreimageClaimableHTLC

HTLCs which we received from our counterparty which are claimable with a preimage which we do not currently have. This will only be claimable if we receive the preimage from the node to which we forwarded this HTLC before the timeout.

Fields

amount_satoshis: u64

The amount potentially available to claim, in satoshis, excluding the on-chain fees which will be required to do so.

expiry_height: u32

The height at which our counterparty will be able to claim the balance if we have not yet received the preimage and claimed it ourselves.

payment_hash: PaymentHash

The payment hash whose preimage we need to claim this HTLC.

CounterpartyRevokedOutputClaimable

The channel has been closed, and our counterparty broadcasted a revoked commitment transaction.

Thus, we’re able to claim all outputs in the commitment transaction, one of which has the following amount.

Fields

amount_satoshis: u64

The amount, in satoshis, of the output which we can claim.

Note that for outputs from HTLC balances this may be excluding some on-chain fees that were already spent.

Implementations

impl Balance

pub fn claimable_amount_satoshis(&self) -> u64

The amount claimable, in satoshis.

When the channel has yet to close, this returns the balance we expect to claim from the channel. This may change throughout the lifetime of the channel due to payments, but also due to splicing. If there’s a pending splice, this will return the balance we expect to have assuming the latest negotiated splice confirms. However, if one of the negotiated splice transactions has already confirmed but is not yet locked, this reports the corresponding balance for said splice transaction instead.

For outbound payments, this excludes the balance from the possible HTLC timeout.

For forwarded payments, this includes the balance from the possible HTLC timeout as (to be conservative) that balance does not include routing fees we’d earn if we’d claim the balance from a preimage in a successful forward.

For more information on these balances see Balance::MaybeTimeoutClaimableHTLC and Balance::MaybePreimageClaimableHTLC.

On-chain fees required to claim the balance are not included in this amount.

Trait Implementations

impl Clone for Balance

fn clone(&self) -> Balance

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Balance

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for Balance

fn eq(&self, other: &Balance) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for Balance

impl StructuralPartialEq for Balance