mirrors/rust-lightning
1
0
Fork 0
mirror of https://github.com/lightningdevkit/rust-lightning.git synced 2025-02-24 15:02:20 +01:00
Code Issues Projects Releases Packages Wiki Activity

Merge pull request #3089 from TheBlueMatt/2024-06-channel_state-module

Browse source 
Move the public channel state API into a new module
This commit is contained in:
Elias Rohrer 2024-06-04 16:28:39 +02:00 • committed by GitHub
commit 15c709d747
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
16 changed files with 594 additions and 542 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
fuzz/src/chanmon_consistency.rs
View file

@ -45,7 +45,8 @@ use lightning::sign::{KeyMaterial, InMemorySigner, Recipient, EntropySource, Nod
use lightning::events;
use lightning::events::MessageSendEventsProvider;
use lightning::ln::{ChannelId, PaymentHash, PaymentPreimage, PaymentSecret};
use lightning::ln::channelmanager::{ChainParameters, ChannelDetails, ChannelManager, PaymentSendFailure, ChannelManagerReadArgs, PaymentId, RecipientOnionFields};
use lightning::ln::channel_state::ChannelDetails;
use lightning::ln::channelmanager::{ChainParameters,ChannelManager, PaymentSendFailure, ChannelManagerReadArgs, PaymentId, RecipientOnionFields};
use lightning::ln::channel::FEE_SPIKE_BUFFER_FEE_INCREASE_MULTIPLE;
use lightning::ln::msgs::{self, CommitmentUpdate, ChannelMessageHandler, DecodeError, UpdateAddHTLC, Init};
use lightning::ln::script::ShutdownScript;

3
fuzz/src/full_stack.rs
View file

@ -41,7 +41,8 @@ use lightning::chain::transaction::OutPoint;
use lightning::sign::{InMemorySigner, Recipient, KeyMaterial, EntropySource, NodeSigner, SignerProvider};
use lightning::events::Event;
use lightning::ln::{ChannelId, PaymentHash, PaymentPreimage, PaymentSecret};
use lightning::ln::channelmanager::{ChainParameters, ChannelDetails, ChannelManager, PaymentId, RecipientOnionFields, Retry, InterceptId};
use lightning::ln::channel_state::ChannelDetails;
use lightning::ln::channelmanager::{ChainParameters, ChannelManager, PaymentId, RecipientOnionFields, Retry, InterceptId};
use lightning::ln::peer_handler::{MessageHandler,PeerManager,SocketDescriptor,IgnoringMessageHandler};
use lightning::ln::msgs::{self, DecodeError};
use lightning::ln::script::ShutdownScript;

2
fuzz/src/msg_targets/gen_target.sh
View file

@ -45,7 +45,7 @@ GEN_TEST lightning::ln::msgs::ErrorMessage test_msg_hole ", 32, 2"
GEN_TEST lightning::ln::msgs::WarningMessage test_msg_hole ", 32, 2"
GEN_TEST lightning::ln::msgs::ChannelUpdate test_msg_hole ", 108, 1"
GEN_TEST lightning::ln::channelmanager::ChannelDetails test_msg_simple ""
GEN_TEST lightning::ln::channel_state::ChannelDetails test_msg_simple ""
GEN_TEST lightning::ln::msgs::OpenChannelV2 test_msg_simple ""
GEN_TEST lightning::ln::msgs::AcceptChannelV2 test_msg_simple ""

4
fuzz/src/msg_targets/msg_channel_details.rs
View file

@ -15,11 +15,11 @@ use crate::utils::test_logger;
#[inline]
pub fn msg_channel_details_test<Out: test_logger::Output>(data: &[u8], _out: Out) {
test_msg_simple!(lightning::ln::channelmanager::ChannelDetails, data);
test_msg_simple!(lightning::ln::channel_state::ChannelDetails, data);
}
#[no_mangle]
pub extern "C" fn msg_channel_details_run(data: *const u8, datalen: usize) {
let data = unsafe { std::slice::from_raw_parts(data, datalen) };
test_msg_simple!(lightning::ln::channelmanager::ChannelDetails, data);
test_msg_simple!(lightning::ln::channel_state::ChannelDetails, data);
}

5
fuzz/src/router.rs
View file

@ -15,7 +15,8 @@ use bitcoin::blockdata::transaction::TxOut;
use lightning::blinded_path::{BlindedHop, BlindedPath, IntroductionNode};
use lightning::chain::transaction::OutPoint;
use lightning::ln::ChannelId;
use lightning::ln::channelmanager::{self, ChannelDetails, ChannelCounterparty};
use lightning::ln::channel_state::{ChannelDetails, ChannelCounterparty, ChannelShutdownState};
use lightning::ln::channelmanager;
use lightning::ln::features::{BlindedHopFeatures, Bolt12InvoiceFeatures};
use lightning::ln::msgs;
use lightning::offers::invoice::BlindedPayInfo;
@ -244,7 +245,7 @@ pub fn do_test<Out: test_logger::Output>(data: &[u8], out: Out) {
inbound_htlc_maximum_msat: None,
config: None,
feerate_sat_per_1000_weight: None,
channel_shutdown_state: Some(channelmanager::ChannelShutdownState::NotShuttingDown),
channel_shutdown_state: Some(ChannelShutdownState::NotShuttingDown),
pending_inbound_htlcs: Vec::new(),
pending_outbound_htlcs: Vec::new(),
});

3
lightning-invoice/src/utils.rs
View file

@ -9,7 +9,8 @@ use lightning::chain;
use lightning::chain::chaininterface::{BroadcasterInterface, FeeEstimator};
use lightning::sign::{Recipient, NodeSigner, SignerProvider, EntropySource};
use lightning::ln::types::{PaymentHash, PaymentSecret};
use lightning::ln::channelmanager::{ChannelDetails, ChannelManager, MIN_FINAL_CLTV_EXPIRY_DELTA};
use lightning::ln::channel_state::ChannelDetails;
use lightning::ln::channelmanager::{ChannelManager, MIN_FINAL_CLTV_EXPIRY_DELTA};
use lightning::ln::channelmanager::{PhantomRouteHints, MIN_CLTV_EXPIRY_DELTA};
use lightning::ln::inbound_payment::{create, create_from_hash, ExpandedKey};
use lightning::routing::gossip::RoutingFees;

2
lightning/src/blinded_path/payment.rs
View file

@ -17,7 +17,7 @@ use crate::blinded_path::BlindedHop;
use crate::blinded_path::utils;
use crate::io;
use crate::ln::types::PaymentSecret;
use crate::ln::channelmanager::CounterpartyForwardingInfo;
use crate::ln::channel_state::CounterpartyForwardingInfo;
use crate::ln::features::BlindedHopFeatures;
use crate::ln::msgs::DecodeError;
use crate::offers::invoice::BlindedPayInfo;

2
lightning/src/chain/chainmonitor.rs
View file

@ -38,7 +38,7 @@ use crate::events::{Event, EventHandler};
use crate::util::logger::{Logger, WithContext};
use crate::util::errors::APIError;
use crate::util::wakers::{Future, Notifier};
use crate::ln::channelmanager::ChannelDetails;
use crate::ln::channel_state::ChannelDetails;
use crate::prelude::*;
use crate::sync::{RwLock, RwLockReadGuard, Mutex, MutexGuard};

191
lightning/src/ln/channel.rs
View file

@ -30,7 +30,8 @@ use crate::ln::features::{ChannelTypeFeatures, InitFeatures};
use crate::ln::msgs;
use crate::ln::msgs::DecodeError;
use crate::ln::script::{self, ShutdownScript};
use crate::ln::channelmanager::{self, CounterpartyForwardingInfo, PendingHTLCStatus, HTLCSource, SentHTLCId, HTLCFailureMsg, PendingHTLCInfo, RAACommitmentOrder, BREAKDOWN_TIMEOUT, MIN_CLTV_EXPIRY_DELTA, MAX_LOCAL_BREAKDOWN_TIMEOUT, ChannelShutdownState};
use crate::ln::channel_state::{ChannelShutdownState, CounterpartyForwardingInfo, InboundHTLCDetails, InboundHTLCStateDetails, OutboundHTLCDetails, OutboundHTLCStateDetails};
use crate::ln::channelmanager::{self, PendingHTLCStatus, HTLCSource, SentHTLCId, HTLCFailureMsg, PendingHTLCInfo, RAACommitmentOrder, BREAKDOWN_TIMEOUT, MIN_CLTV_EXPIRY_DELTA, MAX_LOCAL_BREAKDOWN_TIMEOUT};
use crate::ln::chan_utils::{CounterpartyCommitmentSecrets, TxCreationKeys, HTLCOutputInCommitment, htlc_success_tx_weight, htlc_timeout_tx_weight, make_funding_redeemscript, ChannelPublicKeys, CommitmentTransaction, HolderCommitmentTransaction, ChannelTransactionParameters, CounterpartyChannelTransactionParameters, MAX_HTLCS, get_commitment_transaction_number_obscure_factor, ClosingTransaction};
use crate::ln::chan_utils;
use crate::ln::onion_utils::HTLCFailReason;
@ -186,45 +187,6 @@ enum InboundHTLCState {
LocalRemoved(InboundHTLCRemovalReason),
}
/// Exposes the state of pending inbound HTLCs.
///
/// At a high level, an HTLC being forwarded from one Lightning node to another Lightning node goes
/// through the following states in the state machine:
/// - Announced for addition by the originating node through the update_add_htlc message.
/// - Added to the commitment transaction of the receiving node and originating node in turn
/// through the exchange of commitment_signed and revoke_and_ack messages.
/// - Announced for resolution (fulfillment or failure) by the receiving node through either one of
/// the update_fulfill_htlc, update_fail_htlc, and update_fail_malformed_htlc messages.
/// - Removed from the commitment transaction of the originating node and receiving node in turn
/// through the exchange of commitment_signed and revoke_and_ack messages.
///
/// This can be used to inspect what next message an HTLC is waiting for to advance its state.
#[derive(Clone, Debug, PartialEq)]
pub enum InboundHTLCStateDetails {
/// We have added this HTLC in our commitment transaction by receiving commitment_signed and
/// returning revoke_and_ack. We are awaiting the appropriate revoke_and_ack's from the remote
/// before this HTLC is included on the remote commitment transaction.
AwaitingRemoteRevokeToAdd,
/// This HTLC has been included in the commitment_signed and revoke_and_ack messages on both sides
/// and is included in both commitment transactions.
///
/// This HTLC is now safe to either forward or be claimed as a payment by us. The HTLC will
/// remain in this state until the forwarded upstream HTLC has been resolved and we resolve this
/// HTLC correspondingly, or until we claim it as a payment. If it is part of a multipart
/// payment, it will only be claimed together with other required parts.
Committed,
/// We have received the preimage for this HTLC and it is being removed by fulfilling it with
/// update_fulfill_htlc. This HTLC is still on both commitment transactions, but we are awaiting
/// the appropriate revoke_and_ack's from the remote before this HTLC is removed from the remote
/// commitment transaction after update_fulfill_htlc.
AwaitingRemoteRevokeToRemoveFulfill,
/// The HTLC is being removed by failing it with update_fail_htlc or update_fail_malformed_htlc.
/// This HTLC is still on both commitment transactions, but we are awaiting the appropriate
/// revoke_and_ack's from the remote before this HTLC is removed from the remote commitment
/// transaction.
AwaitingRemoteRevokeToRemoveFail,
}
impl From<&InboundHTLCState> for Option<InboundHTLCStateDetails> {
fn from(state: &InboundHTLCState) -> Option<InboundHTLCStateDetails> {
match state {
@ -245,13 +207,6 @@ impl From<&InboundHTLCState> for Option<InboundHTLCStateDetails> {
}
}
impl_writeable_tlv_based_enum_upgradable!(InboundHTLCStateDetails,
(0, AwaitingRemoteRevokeToAdd) => {},
(2, Committed) => {},
(4, AwaitingRemoteRevokeToRemoveFulfill) => {},
(6, AwaitingRemoteRevokeToRemoveFail) => {};
);
struct InboundHTLCOutput {
htlc_id: u64,
amount_msat: u64,
@ -260,53 +215,6 @@ struct InboundHTLCOutput {
state: InboundHTLCState,
}
/// Exposes details around pending inbound HTLCs.
#[derive(Clone, Debug, PartialEq)]
pub struct InboundHTLCDetails {
/// The HTLC ID.
/// The IDs are incremented by 1 starting from 0 for each offered HTLC.
/// They are unique per channel and inbound/outbound direction, unless an HTLC was only announced
/// and not part of any commitment transaction.
pub htlc_id: u64,
/// The amount in msat.
pub amount_msat: u64,
/// The block height at which this HTLC expires.
pub cltv_expiry: u32,
/// The payment hash.
pub payment_hash: PaymentHash,
/// The state of the HTLC in the state machine.
///
/// Determines on which commitment transactions the HTLC is included and what message the HTLC is
/// waiting for to advance to the next state.
///
/// See [`InboundHTLCStateDetails`] for information on the specific states.
///
/// LDK will always fill this field in, but when downgrading to prior versions of LDK, new
/// states may result in `None` here.
pub state: Option<InboundHTLCStateDetails>,
/// Whether the HTLC has an output below the local dust limit. If so, the output will be trimmed
/// from the local commitment transaction and added to the commitment transaction fee.
/// For non-anchor channels, this takes into account the cost of the second-stage HTLC
/// transactions as well.
///
/// When the local commitment transaction is broadcasted as part of a unilateral closure,
/// the value of this HTLC will therefore not be claimable but instead burned as a transaction
/// fee.
///
/// Note that dust limits are specific to each party. An HTLC can be dust for the local
/// commitment transaction but not for the counterparty's commitment transaction and vice versa.
pub is_dust: bool,
}
impl_writeable_tlv_based!(InboundHTLCDetails, {
(0, htlc_id, required),
(2, amount_msat, required),
(4, cltv_expiry, required),
(6, payment_hash, required),
(7, state, upgradable_option),
(8, is_dust, required),
});
#[cfg_attr(test, derive(Clone, Debug, PartialEq))]
enum OutboundHTLCState {
/// Added by us and included in a commitment_signed (if we were AwaitingRemoteRevoke when we
@ -340,42 +248,6 @@ enum OutboundHTLCState {
AwaitingRemovedRemoteRevoke(OutboundHTLCOutcome),
}
/// Exposes the state of pending outbound HTLCs.
///
/// At a high level, an HTLC being forwarded from one Lightning node to another Lightning node goes
/// through the following states in the state machine:
/// - Announced for addition by the originating node through the update_add_htlc message.
/// - Added to the commitment transaction of the receiving node and originating node in turn
/// through the exchange of commitment_signed and revoke_and_ack messages.
/// - Announced for resolution (fulfillment or failure) by the receiving node through either one of
/// the update_fulfill_htlc, update_fail_htlc, and update_fail_malformed_htlc messages.
/// - Removed from the commitment transaction of the originating node and receiving node in turn
/// through the exchange of commitment_signed and revoke_and_ack messages.
///
/// This can be used to inspect what next message an HTLC is waiting for to advance its state.
#[derive(Clone, Debug, PartialEq)]
pub enum OutboundHTLCStateDetails {
/// We are awaiting the appropriate revoke_and_ack's from the remote before the HTLC is added
/// on the remote's commitment transaction after update_add_htlc.
AwaitingRemoteRevokeToAdd,
/// The HTLC has been added to the remote's commitment transaction by sending commitment_signed
/// and receiving revoke_and_ack in return.
///
/// The HTLC will remain in this state until the remote node resolves the HTLC, or until we
/// unilaterally close the channel due to a timeout with an uncooperative remote node.
Committed,
/// The HTLC has been fulfilled successfully by the remote with a preimage in update_fulfill_htlc,
/// and we removed the HTLC from our commitment transaction by receiving commitment_signed and
/// returning revoke_and_ack. We are awaiting the appropriate revoke_and_ack's from the remote
/// for the removal from its commitment transaction.
AwaitingRemoteRevokeToRemoveSuccess,
/// The HTLC has been failed by the remote with update_fail_htlc or update_fail_malformed_htlc,
/// and we removed the HTLC from our commitment transaction by receiving commitment_signed and
/// returning revoke_and_ack. We are awaiting the appropriate revoke_and_ack's from the remote
/// for the removal from its commitment transaction.
AwaitingRemoteRevokeToRemoveFailure,
}
impl From<&OutboundHTLCState> for OutboundHTLCStateDetails {
fn from(state: &OutboundHTLCState) -> OutboundHTLCStateDetails {
match state {
@ -399,13 +271,6 @@ impl From<&OutboundHTLCState> for OutboundHTLCStateDetails {
}
}
impl_writeable_tlv_based_enum_upgradable!(OutboundHTLCStateDetails,
(0, AwaitingRemoteRevokeToAdd) => {},
(2, Committed) => {},
(4, AwaitingRemoteRevokeToRemoveSuccess) => {},
(6, AwaitingRemoteRevokeToRemoveFailure) => {};
);
#[derive(Clone)]
#[cfg_attr(test, derive(Debug, PartialEq))]
enum OutboundHTLCOutcome {
@ -444,58 +309,6 @@ struct OutboundHTLCOutput {
skimmed_fee_msat: Option<u64>,
}
/// Exposes details around pending outbound HTLCs.
#[derive(Clone, Debug, PartialEq)]
pub struct OutboundHTLCDetails {
/// The HTLC ID.
/// The IDs are incremented by 1 starting from 0 for each offered HTLC.
/// They are unique per channel and inbound/outbound direction, unless an HTLC was only announced
/// and not part of any commitment transaction.
///
/// Not present when we are awaiting a remote revocation and the HTLC is not added yet.
pub htlc_id: Option<u64>,
/// The amount in msat.
pub amount_msat: u64,
/// The block height at which this HTLC expires.
pub cltv_expiry: u32,
/// The payment hash.
pub payment_hash: PaymentHash,
/// The state of the HTLC in the state machine.
///
/// Determines on which commitment transactions the HTLC is included and what message the HTLC is
/// waiting for to advance to the next state.
///
/// See [`OutboundHTLCStateDetails`] for information on the specific states.
///
/// LDK will always fill this field in, but when downgrading to prior versions of LDK, new
/// states may result in `None` here.
pub state: Option<OutboundHTLCStateDetails>,
/// The extra fee being skimmed off the top of this HTLC.
pub skimmed_fee_msat: Option<u64>,
/// Whether the HTLC has an output below the local dust limit. If so, the output will be trimmed
/// from the local commitment transaction and added to the commitment transaction fee.
/// For non-anchor channels, this takes into account the cost of the second-stage HTLC
/// transactions as well.
///
/// When the local commitment transaction is broadcasted as part of a unilateral closure,
/// the value of this HTLC will therefore not be claimable but instead burned as a transaction
/// fee.
///
/// Note that dust limits are specific to each party. An HTLC can be dust for the local
/// commitment transaction but not for the counterparty's commitment transaction and vice versa.
pub is_dust: bool,
}
impl_writeable_tlv_based!(OutboundHTLCDetails, {
(0, htlc_id, required),
(2, amount_msat, required),
(4, cltv_expiry, required),
(6, payment_hash, required),
(7, state, upgradable_option),
(8, skimmed_fee_msat, required),
(10, is_dust, required),
});
/// See AwaitingRemoteRevoke ChannelState for more info
#[cfg_attr(test, derive(Clone, Debug, PartialEq))]
enum HTLCUpdateAwaitingACK {

560
lightning/src/ln/channel_state.rs Normal file
View file

@ -0,0 +1,560 @@
// This file is Copyright its original authors, visible in version control
// history.
//
// This file is licensed under the Apache License, Version 2.0 <LICENSE-APACHE
// or http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your option.
// You may not use this file except in accordance with one or both of these
// licenses.
//! Information about the state of a channel.
use alloc::vec::Vec;
use bitcoin::secp256k1::PublicKey;
use crate::chain::chaininterface::{FeeEstimator, LowerBoundedFeeEstimator};
use crate::chain::transaction::OutPoint;
use crate::ln::channel::ChannelContext;
use crate::ln::features::{ChannelTypeFeatures, InitFeatures};
use crate::ln::types::{ChannelId, PaymentHash};
use crate::sign::SignerProvider;
use crate::util::config::ChannelConfig;
use core::ops::Deref;
/// Exposes the state of pending inbound HTLCs.
///
/// At a high level, an HTLC being forwarded from one Lightning node to another Lightning node goes
/// through the following states in the state machine:
/// - Announced for addition by the originating node through the update_add_htlc message.
/// - Added to the commitment transaction of the receiving node and originating node in turn
/// through the exchange of commitment_signed and revoke_and_ack messages.
/// - Announced for resolution (fulfillment or failure) by the receiving node through either one of
/// the update_fulfill_htlc, update_fail_htlc, and update_fail_malformed_htlc messages.
/// - Removed from the commitment transaction of the originating node and receiving node in turn
/// through the exchange of commitment_signed and revoke_and_ack messages.
///
/// This can be used to inspect what next message an HTLC is waiting for to advance its state.
#[derive(Clone, Debug, PartialEq)]
pub enum InboundHTLCStateDetails {
/// We have added this HTLC in our commitment transaction by receiving commitment_signed and
/// returning revoke_and_ack. We are awaiting the appropriate revoke_and_ack's from the remote
/// before this HTLC is included on the remote commitment transaction.
AwaitingRemoteRevokeToAdd,
/// This HTLC has been included in the commitment_signed and revoke_and_ack messages on both sides
/// and is included in both commitment transactions.
///
/// This HTLC is now safe to either forward or be claimed as a payment by us. The HTLC will
/// remain in this state until the forwarded upstream HTLC has been resolved and we resolve this
/// HTLC correspondingly, or until we claim it as a payment. If it is part of a multipart
/// payment, it will only be claimed together with other required parts.
Committed,
/// We have received the preimage for this HTLC and it is being removed by fulfilling it with
/// update_fulfill_htlc. This HTLC is still on both commitment transactions, but we are awaiting
/// the appropriate revoke_and_ack's from the remote before this HTLC is removed from the remote
/// commitment transaction after update_fulfill_htlc.
AwaitingRemoteRevokeToRemoveFulfill,
/// The HTLC is being removed by failing it with update_fail_htlc or update_fail_malformed_htlc.
/// This HTLC is still on both commitment transactions, but we are awaiting the appropriate
/// revoke_and_ack's from the remote before this HTLC is removed from the remote commitment
/// transaction.
AwaitingRemoteRevokeToRemoveFail,
}
impl_writeable_tlv_based_enum_upgradable!(InboundHTLCStateDetails,
(0, AwaitingRemoteRevokeToAdd) => {},
(2, Committed) => {},
(4, AwaitingRemoteRevokeToRemoveFulfill) => {},
(6, AwaitingRemoteRevokeToRemoveFail) => {};
);
/// Exposes details around pending inbound HTLCs.
#[derive(Clone, Debug, PartialEq)]
pub struct InboundHTLCDetails {
/// The HTLC ID.
/// The IDs are incremented by 1 starting from 0 for each offered HTLC.
/// They are unique per channel and inbound/outbound direction, unless an HTLC was only announced
/// and not part of any commitment transaction.
pub htlc_id: u64,
/// The amount in msat.
pub amount_msat: u64,
/// The block height at which this HTLC expires.
pub cltv_expiry: u32,
/// The payment hash.
pub payment_hash: PaymentHash,
/// The state of the HTLC in the state machine.
///
/// Determines on which commitment transactions the HTLC is included and what message the HTLC is
/// waiting for to advance to the next state.
///
/// See [`InboundHTLCStateDetails`] for information on the specific states.
///
/// LDK will always fill this field in, but when downgrading to prior versions of LDK, new
/// states may result in `None` here.
pub state: Option<InboundHTLCStateDetails>,
/// Whether the HTLC has an output below the local dust limit. If so, the output will be trimmed
/// from the local commitment transaction and added to the commitment transaction fee.
/// For non-anchor channels, this takes into account the cost of the second-stage HTLC
/// transactions as well.
///
/// When the local commitment transaction is broadcasted as part of a unilateral closure,
/// the value of this HTLC will therefore not be claimable but instead burned as a transaction
/// fee.
///
/// Note that dust limits are specific to each party. An HTLC can be dust for the local
/// commitment transaction but not for the counterparty's commitment transaction and vice versa.
pub is_dust: bool,
}
impl_writeable_tlv_based!(InboundHTLCDetails, {
(0, htlc_id, required),
(2, amount_msat, required),
(4, cltv_expiry, required),
(6, payment_hash, required),
(7, state, upgradable_option),
(8, is_dust, required),
});
/// Exposes the state of pending outbound HTLCs.
///
/// At a high level, an HTLC being forwarded from one Lightning node to another Lightning node goes
/// through the following states in the state machine:
/// - Announced for addition by the originating node through the update_add_htlc message.
/// - Added to the commitment transaction of the receiving node and originating node in turn
/// through the exchange of commitment_signed and revoke_and_ack messages.
/// - Announced for resolution (fulfillment or failure) by the receiving node through either one of
/// the update_fulfill_htlc, update_fail_htlc, and update_fail_malformed_htlc messages.
/// - Removed from the commitment transaction of the originating node and receiving node in turn
/// through the exchange of commitment_signed and revoke_and_ack messages.
///
/// This can be used to inspect what next message an HTLC is waiting for to advance its state.
#[derive(Clone, Debug, PartialEq)]
pub enum OutboundHTLCStateDetails {
/// We are awaiting the appropriate revoke_and_ack's from the remote before the HTLC is added
/// on the remote's commitment transaction after update_add_htlc.
AwaitingRemoteRevokeToAdd,
/// The HTLC has been added to the remote's commitment transaction by sending commitment_signed
/// and receiving revoke_and_ack in return.
///
/// The HTLC will remain in this state until the remote node resolves the HTLC, or until we
/// unilaterally close the channel due to a timeout with an uncooperative remote node.
Committed,
/// The HTLC has been fulfilled successfully by the remote with a preimage in update_fulfill_htlc,
/// and we removed the HTLC from our commitment transaction by receiving commitment_signed and
/// returning revoke_and_ack. We are awaiting the appropriate revoke_and_ack's from the remote
/// for the removal from its commitment transaction.
AwaitingRemoteRevokeToRemoveSuccess,
/// The HTLC has been failed by the remote with update_fail_htlc or update_fail_malformed_htlc,
/// and we removed the HTLC from our commitment transaction by receiving commitment_signed and
/// returning revoke_and_ack. We are awaiting the appropriate revoke_and_ack's from the remote
/// for the removal from its commitment transaction.
AwaitingRemoteRevokeToRemoveFailure,
}
impl_writeable_tlv_based_enum_upgradable!(OutboundHTLCStateDetails,
(0, AwaitingRemoteRevokeToAdd) => {},
(2, Committed) => {},
(4, AwaitingRemoteRevokeToRemoveSuccess) => {},
(6, AwaitingRemoteRevokeToRemoveFailure) => {};
);
/// Exposes details around pending outbound HTLCs.
#[derive(Clone, Debug, PartialEq)]
pub struct OutboundHTLCDetails {
/// The HTLC ID.
/// The IDs are incremented by 1 starting from 0 for each offered HTLC.
/// They are unique per channel and inbound/outbound direction, unless an HTLC was only announced
/// and not part of any commitment transaction.
///
/// Not present when we are awaiting a remote revocation and the HTLC is not added yet.
pub htlc_id: Option<u64>,
/// The amount in msat.
pub amount_msat: u64,
/// The block height at which this HTLC expires.
pub cltv_expiry: u32,
/// The payment hash.
pub payment_hash: PaymentHash,
/// The state of the HTLC in the state machine.
///
/// Determines on which commitment transactions the HTLC is included and what message the HTLC is
/// waiting for to advance to the next state.
///
/// See [`OutboundHTLCStateDetails`] for information on the specific states.
///
/// LDK will always fill this field in, but when downgrading to prior versions of LDK, new
/// states may result in `None` here.
pub state: Option<OutboundHTLCStateDetails>,
/// The extra fee being skimmed off the top of this HTLC.
pub skimmed_fee_msat: Option<u64>,
/// Whether the HTLC has an output below the local dust limit. If so, the output will be trimmed
/// from the local commitment transaction and added to the commitment transaction fee.
/// For non-anchor channels, this takes into account the cost of the second-stage HTLC
/// transactions as well.
///
/// When the local commitment transaction is broadcasted as part of a unilateral closure,
/// the value of this HTLC will therefore not be claimable but instead burned as a transaction
/// fee.
///
/// Note that dust limits are specific to each party. An HTLC can be dust for the local
/// commitment transaction but not for the counterparty's commitment transaction and vice versa.
pub is_dust: bool,
}
impl_writeable_tlv_based!(OutboundHTLCDetails, {
(0, htlc_id, required),
(2, amount_msat, required),
(4, cltv_expiry, required),
(6, payment_hash, required),
(7, state, upgradable_option),
(8, skimmed_fee_msat, required),
(10, is_dust, required),
});
/// Information needed for constructing an invoice route hint for this channel.
#[derive(Clone, Debug, PartialEq)]
pub struct CounterpartyForwardingInfo {
/// Base routing fee in millisatoshis.
pub fee_base_msat: u32,
/// Amount in millionths of a satoshi the channel will charge per transferred satoshi.
pub fee_proportional_millionths: u32,
/// The minimum difference in cltv_expiry between an ingoing HTLC and its outgoing counterpart,
/// such that the outgoing HTLC is forwardable to this counterparty. See `msgs::ChannelUpdate`'s
/// `cltv_expiry_delta` for more details.
pub cltv_expiry_delta: u16,
}
/// Channel parameters which apply to our counterparty. These are split out from [`ChannelDetails`]
/// to better separate parameters.
#[derive(Clone, Debug, PartialEq)]
pub struct ChannelCounterparty {
/// The node_id of our counterparty
pub node_id: PublicKey,
/// The Features the channel counterparty provided upon last connection.
/// Useful for routing as it is the most up-to-date copy of the counterparty's features and
/// many routing-relevant features are present in the init context.
pub features: InitFeatures,
/// The value, in satoshis, that must always be held in the channel for our counterparty. This
/// value ensures that if our counterparty broadcasts a revoked state, we can punish them by
/// claiming at least this value on chain.
///
/// This value is not included in [`inbound_capacity_msat`] as it can never be spent.
///
/// [`inbound_capacity_msat`]: ChannelDetails::inbound_capacity_msat
pub unspendable_punishment_reserve: u64,
/// Information on the fees and requirements that the counterparty requires when forwarding
/// payments to us through this channel.
pub forwarding_info: Option<CounterpartyForwardingInfo>,
/// The smallest value HTLC (in msat) the remote peer will accept, for this channel. This field
/// is only `None` before we have received either the `OpenChannel` or `AcceptChannel` message
/// from the remote peer, or for `ChannelCounterparty` objects serialized prior to LDK 0.0.107.
pub outbound_htlc_minimum_msat: Option<u64>,
/// The largest value HTLC (in msat) the remote peer currently will accept, for this channel.
pub outbound_htlc_maximum_msat: Option<u64>,
}
/// Details of a channel, as returned by [`ChannelManager::list_channels`] and [`ChannelManager::list_usable_channels`]
///
/// [`ChannelManager::list_channels`]: crate::ln::channelmanager::ChannelManager::list_channels
/// [`ChannelManager::list_usable_channels`]: crate::ln::channelmanager::ChannelManager::list_usable_channels
#[derive(Clone, Debug, PartialEq)]
pub struct ChannelDetails {
/// The channel's ID (prior to funding transaction generation, this is a random 32 bytes,
/// thereafter this is the txid of the funding transaction xor the funding transaction output).
/// Note that this means this value is *not* persistent - it can change once during the
/// lifetime of the channel.
pub channel_id: ChannelId,
/// Parameters which apply to our counterparty. See individual fields for more information.
pub counterparty: ChannelCounterparty,
/// The Channel's funding transaction output, if we've negotiated the funding transaction with
/// our counterparty already.
pub funding_txo: Option<OutPoint>,
/// The features which this channel operates with. See individual features for more info.
///
/// `None` until negotiation completes and the channel type is finalized.
pub channel_type: Option<ChannelTypeFeatures>,
/// The position of the funding transaction in the chain. None if the funding transaction has
/// not yet been confirmed and the channel fully opened.
///
/// Note that if [`inbound_scid_alias`] is set, it must be used for invoices and inbound
/// payments instead of this. See [`get_inbound_payment_scid`].
///
/// For channels with [`confirmations_required`] set to `Some(0)`, [`outbound_scid_alias`] may
/// be used in place of this in outbound routes. See [`get_outbound_payment_scid`].
///
/// [`inbound_scid_alias`]: Self::inbound_scid_alias
/// [`outbound_scid_alias`]: Self::outbound_scid_alias
/// [`get_inbound_payment_scid`]: Self::get_inbound_payment_scid
/// [`get_outbound_payment_scid`]: Self::get_outbound_payment_scid
/// [`confirmations_required`]: Self::confirmations_required
pub short_channel_id: Option<u64>,
/// An optional [`short_channel_id`] alias for this channel, randomly generated by us and
/// usable in place of [`short_channel_id`] to reference the channel in outbound routes when
/// the channel has not yet been confirmed (as long as [`confirmations_required`] is
/// `Some(0)`).
///
/// This will be `None` as long as the channel is not available for routing outbound payments.
///
/// [`short_channel_id`]: Self::short_channel_id
/// [`confirmations_required`]: Self::confirmations_required
pub outbound_scid_alias: Option<u64>,
/// An optional [`short_channel_id`] alias for this channel, randomly generated by our
/// counterparty and usable in place of [`short_channel_id`] in invoice route hints. Our
/// counterparty will recognize the alias provided here in place of the [`short_channel_id`]
/// when they see a payment to be routed to us.
///
/// Our counterparty may choose to rotate this value at any time, though will always recognize
/// previous values for inbound payment forwarding.
///
/// [`short_channel_id`]: Self::short_channel_id
pub inbound_scid_alias: Option<u64>,
/// The value, in satoshis, of this channel as appears in the funding output
pub channel_value_satoshis: u64,
/// The value, in satoshis, that must always be held in the channel for us. This value ensures
/// that if we broadcast a revoked state, our counterparty can punish us by claiming at least
/// this value on chain.
///
/// This value is not included in [`outbound_capacity_msat`] as it can never be spent.
///
/// This value will be `None` for outbound channels until the counterparty accepts the channel.
///
/// [`outbound_capacity_msat`]: ChannelDetails::outbound_capacity_msat
pub unspendable_punishment_reserve: Option<u64>,
/// The `user_channel_id` value passed in to [`ChannelManager::create_channel`] for outbound
/// channels, or to [`ChannelManager::accept_inbound_channel`] for inbound channels if
/// [`UserConfig::manually_accept_inbound_channels`] config flag is set to true. Otherwise
/// `user_channel_id` will be randomized for an inbound channel. This may be zero for objects
/// serialized with LDK versions prior to 0.0.113.
///
/// [`ChannelManager::create_channel`]: crate::ln::channelmanager::ChannelManager::create_channel
/// [`ChannelManager::accept_inbound_channel`]: crate::ln::channelmanager::ChannelManager::accept_inbound_channel
/// [`UserConfig::manually_accept_inbound_channels`]: crate::util::config::UserConfig::manually_accept_inbound_channels
pub user_channel_id: u128,
/// The currently negotiated fee rate denominated in satoshi per 1000 weight units,
/// which is applied to commitment and HTLC transactions.
///
/// 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`]
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.
pub outbound_capacity_msat: u64,
/// The available outbound capacity for sending a single HTLC to the remote peer. This is
/// similar to [`ChannelDetails::outbound_capacity_msat`] but it may be further restricted by
/// 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`].
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
/// an upper-bound. This is intended for use when routing, allowing us to ensure we pick a
/// route which is valid.
pub next_outbound_htlc_minimum_msat: u64,
/// The available inbound capacity for the remote peer to send HTLCs to us. This does not
/// include any pending HTLCs which are not yet fully resolved (and, thus, whose balance is not
/// available for inclusion in new inbound HTLCs).
/// Note that there are some corner cases not fully handled here, so the actual available
/// inbound capacity may be slightly higher than this.
///
/// This value is not exact. Due to various in-flight changes, feerate changes, and our
/// counterparty's conflict-avoidance policy, exactly this amount is not likely to be spendable.
/// However, our counterparty should be able to spend nearly this amount.
pub inbound_capacity_msat: u64,
/// The number of required confirmations on the funding transaction before the funding will be
/// considered "locked". This number is selected by the channel fundee (i.e. us if
/// [`is_outbound`] is *not* set), and can be selected for inbound channels with
/// [`ChannelHandshakeConfig::minimum_depth`] or limited for outbound channels with
/// [`ChannelHandshakeLimits::max_minimum_depth`].
///
/// This value will be `None` for outbound channels until the counterparty accepts the channel.
///
/// [`is_outbound`]: ChannelDetails::is_outbound
/// [`ChannelHandshakeConfig::minimum_depth`]: crate::util::config::ChannelHandshakeConfig::minimum_depth
/// [`ChannelHandshakeLimits::max_minimum_depth`]: crate::util::config::ChannelHandshakeLimits::max_minimum_depth
pub confirmations_required: Option<u32>,
/// The current number of confirmations on the funding transaction.
///
/// This value will be `None` for objects serialized with LDK versions prior to 0.0.113.
pub confirmations: Option<u32>,
/// The number of blocks (after our commitment transaction confirms) that we will need to wait
/// until we can claim our funds after we force-close the channel. During this time our
/// counterparty is allowed to punish us if we broadcasted a stale state. If our counterparty
/// force-closes the channel and broadcasts a commitment transaction we do not have to wait any
/// time to claim our non-HTLC-encumbered funds.
///
/// This value will be `None` for outbound channels until the counterparty accepts the channel.
pub force_close_spend_delay: Option<u16>,
/// True if the channel was initiated (and thus funded) by us.
pub is_outbound: bool,
/// True if the channel is confirmed, channel_ready messages have been exchanged, and the
/// channel is not currently being shut down. `channel_ready` message exchange implies the
/// required confirmation count has been reached (and we were connected to the peer at some
/// point after the funding transaction received enough confirmations). The required
/// confirmation count is provided in [`confirmations_required`].
///
/// [`confirmations_required`]: ChannelDetails::confirmations_required
pub is_channel_ready: bool,
/// The stage of the channel's shutdown.
/// `None` for `ChannelDetails` serialized on LDK versions prior to 0.0.116.
pub channel_shutdown_state: Option<ChannelShutdownState>,
/// True if the channel is (a) confirmed and channel_ready messages have been exchanged, (b)
/// the peer is connected, and (c) the channel is not currently negotiating a shutdown.
///
/// This is a strict superset of `is_channel_ready`.
pub is_usable: bool,
/// True if this channel is (or will be) publicly-announced.
pub is_public: bool,
/// The smallest value HTLC (in msat) we will accept, for this channel. This field
/// is only `None` for `ChannelDetails` objects serialized prior to LDK 0.0.107
pub inbound_htlc_minimum_msat: Option<u64>,
/// The largest value HTLC (in msat) we currently will accept, for this channel.
pub inbound_htlc_maximum_msat: Option<u64>,
/// Set of configurable parameters that affect channel operation.
///
/// This field is only `None` for `ChannelDetails` objects serialized prior to LDK 0.0.109.
pub config: Option<ChannelConfig>,
/// Pending inbound HTLCs.
///
/// This field is empty for objects serialized with LDK versions prior to 0.0.122.
pub pending_inbound_htlcs: Vec<InboundHTLCDetails>,
/// Pending outbound HTLCs.
///
/// This field is empty for objects serialized with LDK versions prior to 0.0.122.
pub pending_outbound_htlcs: Vec<OutboundHTLCDetails>,
}
impl ChannelDetails {
/// Gets the current SCID which should be used to identify this channel for inbound payments.
/// This should be used for providing invoice hints or in any other context where our
/// counterparty will forward a payment to us.
///
/// This is either the [`ChannelDetails::inbound_scid_alias`], if set, or the
/// [`ChannelDetails::short_channel_id`]. See those for more information.
pub fn get_inbound_payment_scid(&self) -> Option<u64> {
self.inbound_scid_alias.or(self.short_channel_id)
}
/// Gets the current SCID which should be used to identify this channel for outbound payments.
/// This should be used in [`Route`]s to describe the first hop or in other contexts where
/// we're sending or forwarding a payment outbound over this channel.
///
/// This is either the [`ChannelDetails::short_channel_id`], if set, or the
/// [`ChannelDetails::outbound_scid_alias`]. See those for more information.
///
/// [`Route`]: crate::routing::router::Route
pub fn get_outbound_payment_scid(&self) -> Option<u64> {
self.short_channel_id.or(self.outbound_scid_alias)
}
pub(super) fn from_channel_context<SP: Deref, F: Deref>(
context: &ChannelContext<SP>, best_block_height: u32, latest_features: InitFeatures,
fee_estimator: &LowerBoundedFeeEstimator<F>,
) -> Self
where
SP::Target: SignerProvider,
F::Target: FeeEstimator,
{
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();
ChannelDetails {
channel_id: context.channel_id(),
counterparty: ChannelCounterparty {
node_id: context.get_counterparty_node_id(),
features: latest_features,
unspendable_punishment_reserve: to_remote_reserve_satoshis,
forwarding_info: context.counterparty_forwarding_info(),
// Ensures that we have actually received the `htlc_minimum_msat` value
// from the counterparty through the `OpenChannel` or `AcceptChannel`
// message (as they are always the first message from the counterparty).
// Else `Channel::get_counterparty_htlc_minimum_msat` could return the
// default `0` value set by `Channel::new_outbound`.
outbound_htlc_minimum_msat: if context.have_received_message() {
Some(context.get_counterparty_htlc_minimum_msat())
} else {
None
},
outbound_htlc_maximum_msat: context.get_counterparty_htlc_maximum_msat(),
},
funding_txo: context.get_funding_txo(),
// Note that accept_channel (or open_channel) is always the first message, so
// `have_received_message` indicates that type negotiation has completed.
channel_type: if context.have_received_message() {
Some(context.get_channel_type().clone())
} else {
None
},
short_channel_id: context.get_short_channel_id(),
outbound_scid_alias: if context.is_usable() {
Some(context.outbound_scid_alias())
} else {
None
},
inbound_scid_alias: context.latest_inbound_scid_alias(),
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,
next_outbound_htlc_minimum_msat: balance.next_outbound_htlc_minimum_msat,
user_channel_id: context.get_user_id(),
confirmations_required: context.minimum_depth(),
confirmations: Some(context.get_funding_tx_confirmations(best_block_height)),
force_close_spend_delay: context.get_counterparty_selected_contest_delay(),
is_outbound: context.is_outbound(),
is_channel_ready: context.is_usable(),
is_usable: context.is_live(),
is_public: context.should_announce(),
inbound_htlc_minimum_msat: Some(context.get_holder_htlc_minimum_msat()),
inbound_htlc_maximum_msat: context.get_holder_htlc_maximum_msat(),
config: Some(context.config()),
channel_shutdown_state: Some(context.shutdown_state()),
pending_inbound_htlcs: context.get_pending_inbound_htlc_details(),
pending_outbound_htlcs: context.get_pending_outbound_htlc_details(),
}
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
/// Further information on the details of the channel shutdown.
/// Upon channels being forced closed (i.e. commitment transaction confirmation detected
/// by `ChainMonitor`), ChannelShutdownState will be set to `ShutdownComplete` or
/// the channel will be removed shortly.
/// Also note, that in normal operation, peers could disconnect at any of these states
/// and require peer re-connection before making progress onto other states
pub enum ChannelShutdownState {
/// Channel has not sent or received a shutdown message.
NotShuttingDown,
/// Local node has sent a shutdown message for this channel.
ShutdownInitiated,
/// Shutdown message exchanges have concluded and the channels are in the midst of
/// resolving all existing open HTLCs before closing can continue.
ResolvingHTLCs,
/// All HTLCs have been resolved, nodes are currently negotiating channel close onchain fee rates.
NegotiatingClosingFee,
/// We've successfully negotiated a closing_signed dance. At this point `ChannelManager` is about
/// to drop the channel.
ShutdownComplete,
}

334
lightning/src/ln/channelmanager.rs
View file

@ -46,7 +46,7 @@ use crate::events::{Event, EventHandler, EventsProvider, MessageSendEvent, Messa
use crate::ln::inbound_payment;
use crate::ln::types::{ChannelId, PaymentHash, PaymentPreimage, PaymentSecret};
use crate::ln::channel::{self, Channel, ChannelPhase, ChannelContext, ChannelError, ChannelUpdateStatus, ShutdownResult, UnfundedChannelContext, UpdateFulfillCommitFetch, OutboundV1Channel, InboundV1Channel, WithChannelContext};
pub use crate::ln::channel::{InboundHTLCDetails, InboundHTLCStateDetails, OutboundHTLCDetails, OutboundHTLCStateDetails};
use crate::ln::channel_state::{ChannelCounterparty, ChannelDetails, ChannelShutdownState, CounterpartyForwardingInfo};
use crate::ln::features::{Bolt12InvoiceFeatures, ChannelFeatures, ChannelTypeFeatures, InitFeatures, NodeFeatures};
#[cfg(any(feature = "_test_utils", test))]
use crate::ln::features::Bolt11InvoiceFeatures;
@ -2287,338 +2287,6 @@ const MAX_UNFUNDED_CHANNEL_PEERS: usize = 50;
/// many peers we reject new (inbound) connections.
const MAX_NO_CHANNEL_PEERS: usize = 250;
/// Information needed for constructing an invoice route hint for this channel.
#[derive(Clone, Debug, PartialEq)]
pub struct CounterpartyForwardingInfo {
/// Base routing fee in millisatoshis.
pub fee_base_msat: u32,
/// Amount in millionths of a satoshi the channel will charge per transferred satoshi.
pub fee_proportional_millionths: u32,
/// The minimum difference in cltv_expiry between an ingoing HTLC and its outgoing counterpart,
/// such that the outgoing HTLC is forwardable to this counterparty. See `msgs::ChannelUpdate`'s
/// `cltv_expiry_delta` for more details.
pub cltv_expiry_delta: u16,
}
/// Channel parameters which apply to our counterparty. These are split out from [`ChannelDetails`]
/// to better separate parameters.
#[derive(Clone, Debug, PartialEq)]
pub struct ChannelCounterparty {
/// The node_id of our counterparty
pub node_id: PublicKey,
/// The Features the channel counterparty provided upon last connection.
/// Useful for routing as it is the most up-to-date copy of the counterparty's features and
/// many routing-relevant features are present in the init context.
pub features: InitFeatures,
/// The value, in satoshis, that must always be held in the channel for our counterparty. This
/// value ensures that if our counterparty broadcasts a revoked state, we can punish them by
/// claiming at least this value on chain.
///
/// This value is not included in [`inbound_capacity_msat`] as it can never be spent.
///
/// [`inbound_capacity_msat`]: ChannelDetails::inbound_capacity_msat
pub unspendable_punishment_reserve: u64,
/// Information on the fees and requirements that the counterparty requires when forwarding
/// payments to us through this channel.
pub forwarding_info: Option<CounterpartyForwardingInfo>,
/// The smallest value HTLC (in msat) the remote peer will accept, for this channel. This field
/// is only `None` before we have received either the `OpenChannel` or `AcceptChannel` message
/// from the remote peer, or for `ChannelCounterparty` objects serialized prior to LDK 0.0.107.
pub outbound_htlc_minimum_msat: Option<u64>,
/// The largest value HTLC (in msat) the remote peer currently will accept, for this channel.
pub outbound_htlc_maximum_msat: Option<u64>,
}
/// Details of a channel, as returned by [`ChannelManager::list_channels`] and [`ChannelManager::list_usable_channels`]
#[derive(Clone, Debug, PartialEq)]
pub struct ChannelDetails {
/// The channel's ID (prior to funding transaction generation, this is a random 32 bytes,
/// thereafter this is the txid of the funding transaction xor the funding transaction output).
/// Note that this means this value is *not* persistent - it can change once during the
/// lifetime of the channel.
pub channel_id: ChannelId,
/// Parameters which apply to our counterparty. See individual fields for more information.
pub counterparty: ChannelCounterparty,
/// The Channel's funding transaction output, if we've negotiated the funding transaction with
/// our counterparty already.
pub funding_txo: Option<OutPoint>,
/// The features which this channel operates with. See individual features for more info.
///
/// `None` until negotiation completes and the channel type is finalized.
pub channel_type: Option<ChannelTypeFeatures>,
/// The position of the funding transaction in the chain. None if the funding transaction has
/// not yet been confirmed and the channel fully opened.
///
/// Note that if [`inbound_scid_alias`] is set, it must be used for invoices and inbound
/// payments instead of this. See [`get_inbound_payment_scid`].
///
/// For channels with [`confirmations_required`] set to `Some(0)`, [`outbound_scid_alias`] may
/// be used in place of this in outbound routes. See [`get_outbound_payment_scid`].
///
/// [`inbound_scid_alias`]: Self::inbound_scid_alias
/// [`outbound_scid_alias`]: Self::outbound_scid_alias
/// [`get_inbound_payment_scid`]: Self::get_inbound_payment_scid
/// [`get_outbound_payment_scid`]: Self::get_outbound_payment_scid
/// [`confirmations_required`]: Self::confirmations_required
pub short_channel_id: Option<u64>,
/// An optional [`short_channel_id`] alias for this channel, randomly generated by us and
/// usable in place of [`short_channel_id`] to reference the channel in outbound routes when
/// the channel has not yet been confirmed (as long as [`confirmations_required`] is
/// `Some(0)`).
///
/// This will be `None` as long as the channel is not available for routing outbound payments.
///
/// [`short_channel_id`]: Self::short_channel_id
/// [`confirmations_required`]: Self::confirmations_required
pub outbound_scid_alias: Option<u64>,
/// An optional [`short_channel_id`] alias for this channel, randomly generated by our
/// counterparty and usable in place of [`short_channel_id`] in invoice route hints. Our
/// counterparty will recognize the alias provided here in place of the [`short_channel_id`]
/// when they see a payment to be routed to us.
///
/// Our counterparty may choose to rotate this value at any time, though will always recognize
/// previous values for inbound payment forwarding.
///
/// [`short_channel_id`]: Self::short_channel_id
pub inbound_scid_alias: Option<u64>,
/// The value, in satoshis, of this channel as appears in the funding output
pub channel_value_satoshis: u64,
/// The value, in satoshis, that must always be held in the channel for us. This value ensures
/// that if we broadcast a revoked state, our counterparty can punish us by claiming at least
/// this value on chain.
///
/// This value is not included in [`outbound_capacity_msat`] as it can never be spent.
///
/// This value will be `None` for outbound channels until the counterparty accepts the channel.
///
/// [`outbound_capacity_msat`]: ChannelDetails::outbound_capacity_msat
pub unspendable_punishment_reserve: Option<u64>,
/// The `user_channel_id` value passed in to [`ChannelManager::create_channel`] for outbound
/// channels, or to [`ChannelManager::accept_inbound_channel`] for inbound channels if
/// [`UserConfig::manually_accept_inbound_channels`] config flag is set to true. Otherwise
/// `user_channel_id` will be randomized for an inbound channel. This may be zero for objects
/// serialized with LDK versions prior to 0.0.113.
///
/// [`ChannelManager::create_channel`]: crate::ln::channelmanager::ChannelManager::create_channel
/// [`ChannelManager::accept_inbound_channel`]: crate::ln::channelmanager::ChannelManager::accept_inbound_channel
/// [`UserConfig::manually_accept_inbound_channels`]: crate::util::config::UserConfig::manually_accept_inbound_channels
pub user_channel_id: u128,
/// The currently negotiated fee rate denominated in satoshi per 1000 weight units,
/// which is applied to commitment and HTLC transactions.
///
/// 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`]
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.
pub outbound_capacity_msat: u64,
/// The available outbound capacity for sending a single HTLC to the remote peer. This is
/// similar to [`ChannelDetails::outbound_capacity_msat`] but it may be further restricted by
/// 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`].
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
/// an upper-bound. This is intended for use when routing, allowing us to ensure we pick a
/// route which is valid.
pub next_outbound_htlc_minimum_msat: u64,
/// The available inbound capacity for the remote peer to send HTLCs to us. This does not
/// include any pending HTLCs which are not yet fully resolved (and, thus, whose balance is not
/// available for inclusion in new inbound HTLCs).
/// Note that there are some corner cases not fully handled here, so the actual available
/// inbound capacity may be slightly higher than this.
///
/// This value is not exact. Due to various in-flight changes, feerate changes, and our
/// counterparty's conflict-avoidance policy, exactly this amount is not likely to be spendable.
/// However, our counterparty should be able to spend nearly this amount.
pub inbound_capacity_msat: u64,
/// The number of required confirmations on the funding transaction before the funding will be
/// considered "locked". This number is selected by the channel fundee (i.e. us if
/// [`is_outbound`] is *not* set), and can be selected for inbound channels with
/// [`ChannelHandshakeConfig::minimum_depth`] or limited for outbound channels with
/// [`ChannelHandshakeLimits::max_minimum_depth`].
///
/// This value will be `None` for outbound channels until the counterparty accepts the channel.
///
/// [`is_outbound`]: ChannelDetails::is_outbound
/// [`ChannelHandshakeConfig::minimum_depth`]: crate::util::config::ChannelHandshakeConfig::minimum_depth
/// [`ChannelHandshakeLimits::max_minimum_depth`]: crate::util::config::ChannelHandshakeLimits::max_minimum_depth
pub confirmations_required: Option<u32>,
/// The current number of confirmations on the funding transaction.
///
/// This value will be `None` for objects serialized with LDK versions prior to 0.0.113.
pub confirmations: Option<u32>,
/// The number of blocks (after our commitment transaction confirms) that we will need to wait
/// until we can claim our funds after we force-close the channel. During this time our
/// counterparty is allowed to punish us if we broadcasted a stale state. If our counterparty
/// force-closes the channel and broadcasts a commitment transaction we do not have to wait any
/// time to claim our non-HTLC-encumbered funds.
///
/// This value will be `None` for outbound channels until the counterparty accepts the channel.
pub force_close_spend_delay: Option<u16>,
/// True if the channel was initiated (and thus funded) by us.
pub is_outbound: bool,
/// True if the channel is confirmed, channel_ready messages have been exchanged, and the
/// channel is not currently being shut down. `channel_ready` message exchange implies the
/// required confirmation count has been reached (and we were connected to the peer at some
/// point after the funding transaction received enough confirmations). The required
/// confirmation count is provided in [`confirmations_required`].
///
/// [`confirmations_required`]: ChannelDetails::confirmations_required
pub is_channel_ready: bool,
/// The stage of the channel's shutdown.
/// `None` for `ChannelDetails` serialized on LDK versions prior to 0.0.116.
pub channel_shutdown_state: Option<ChannelShutdownState>,
/// True if the channel is (a) confirmed and channel_ready messages have been exchanged, (b)
/// the peer is connected, and (c) the channel is not currently negotiating a shutdown.
///
/// This is a strict superset of `is_channel_ready`.
pub is_usable: bool,
/// True if this channel is (or will be) publicly-announced.
pub is_public: bool,
/// The smallest value HTLC (in msat) we will accept, for this channel. This field
/// is only `None` for `ChannelDetails` objects serialized prior to LDK 0.0.107
pub inbound_htlc_minimum_msat: Option<u64>,
/// The largest value HTLC (in msat) we currently will accept, for this channel.
pub inbound_htlc_maximum_msat: Option<u64>,
/// Set of configurable parameters that affect channel operation.
///
/// This field is only `None` for `ChannelDetails` objects serialized prior to LDK 0.0.109.
pub config: Option<ChannelConfig>,
/// Pending inbound HTLCs.
///
/// This field is empty for objects serialized with LDK versions prior to 0.0.122.
pub pending_inbound_htlcs: Vec<InboundHTLCDetails>,
/// Pending outbound HTLCs.
///
/// This field is empty for objects serialized with LDK versions prior to 0.0.122.
pub pending_outbound_htlcs: Vec<OutboundHTLCDetails>,
}
impl ChannelDetails {
/// Gets the current SCID which should be used to identify this channel for inbound payments.
/// This should be used for providing invoice hints or in any other context where our
/// counterparty will forward a payment to us.
///
/// This is either the [`ChannelDetails::inbound_scid_alias`], if set, or the
/// [`ChannelDetails::short_channel_id`]. See those for more information.
pub fn get_inbound_payment_scid(&self) -> Option<u64> {
self.inbound_scid_alias.or(self.short_channel_id)
}
/// Gets the current SCID which should be used to identify this channel for outbound payments.
/// This should be used in [`Route`]s to describe the first hop or in other contexts where
/// we're sending or forwarding a payment outbound over this channel.
///
/// This is either the [`ChannelDetails::short_channel_id`], if set, or the
/// [`ChannelDetails::outbound_scid_alias`]. See those for more information.
pub fn get_outbound_payment_scid(&self) -> Option<u64> {
self.short_channel_id.or(self.outbound_scid_alias)
}
fn from_channel_context<SP: Deref, F: Deref>(
context: &ChannelContext<SP>, best_block_height: u32, latest_features: InitFeatures,
fee_estimator: &LowerBoundedFeeEstimator<F>
) -> Self
where
SP::Target: SignerProvider,
F::Target: FeeEstimator
{
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();
ChannelDetails {
channel_id: context.channel_id(),
counterparty: ChannelCounterparty {
node_id: context.get_counterparty_node_id(),
features: latest_features,
unspendable_punishment_reserve: to_remote_reserve_satoshis,
forwarding_info: context.counterparty_forwarding_info(),
// Ensures that we have actually received the `htlc_minimum_msat` value
// from the counterparty through the `OpenChannel` or `AcceptChannel`
// message (as they are always the first message from the counterparty).
// Else `Channel::get_counterparty_htlc_minimum_msat` could return the
// default `0` value set by `Channel::new_outbound`.
outbound_htlc_minimum_msat: if context.have_received_message() {
Some(context.get_counterparty_htlc_minimum_msat()) } else { None },
outbound_htlc_maximum_msat: context.get_counterparty_htlc_maximum_msat(),
},
funding_txo: context.get_funding_txo(),
// Note that accept_channel (or open_channel) is always the first message, so
// `have_received_message` indicates that type negotiation has completed.
channel_type: if context.have_received_message() { Some(context.get_channel_type().clone()) } else { None },
short_channel_id: context.get_short_channel_id(),
outbound_scid_alias: if context.is_usable() { Some(context.outbound_scid_alias()) } else { None },
inbound_scid_alias: context.latest_inbound_scid_alias(),
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,
next_outbound_htlc_minimum_msat: balance.next_outbound_htlc_minimum_msat,
user_channel_id: context.get_user_id(),
confirmations_required: context.minimum_depth(),
confirmations: Some(context.get_funding_tx_confirmations(best_block_height)),
force_close_spend_delay: context.get_counterparty_selected_contest_delay(),
is_outbound: context.is_outbound(),
is_channel_ready: context.is_usable(),
is_usable: context.is_live(),
is_public: context.should_announce(),
inbound_htlc_minimum_msat: Some(context.get_holder_htlc_minimum_msat()),
inbound_htlc_maximum_msat: context.get_holder_htlc_maximum_msat(),
config: Some(context.config()),
channel_shutdown_state: Some(context.shutdown_state()),
pending_inbound_htlcs: context.get_pending_inbound_htlc_details(),
pending_outbound_htlcs: context.get_pending_outbound_htlc_details(),
}
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
/// Further information on the details of the channel shutdown.
/// Upon channels being forced closed (i.e. commitment transaction confirmation detected
/// by `ChainMonitor`), ChannelShutdownState will be set to `ShutdownComplete` or
/// the channel will be removed shortly.
/// Also note, that in normal operation, peers could disconnect at any of these states
/// and require peer re-connection before making progress onto other states
pub enum ChannelShutdownState {
/// Channel has not sent or received a shutdown message.
NotShuttingDown,
/// Local node has sent a shutdown message for this channel.
ShutdownInitiated,
/// Shutdown message exchanges have concluded and the channels are in the midst of
/// resolving all existing open HTLCs before closing can continue.
ResolvingHTLCs,
/// All HTLCs have been resolved, nodes are currently negotiating channel close onchain fee rates.
NegotiatingClosingFee,
/// We've successfully negotiated a closing_signed dance. At this point `ChannelManager` is about
/// to drop the channel.
ShutdownComplete,
}
/// Used by [`ChannelManager::list_recent_payments`] to express the status of recent payments.
/// These include payments that have yet to find a successful path, or have unresolved HTLCs.
#[derive(Debug, PartialEq)]

1
lightning/src/ln/mod.rs
View file

@ -16,6 +16,7 @@ pub mod functional_test_utils;
pub mod onion_payment;
pub mod channelmanager;
pub mod channel_keys;
pub mod channel_state;
pub mod inbound_payment;
pub mod msgs;
pub mod peer_handler;

3
lightning/src/ln/outbound_payment.rs
View file

@ -16,7 +16,8 @@ use bitcoin::secp256k1::{self, Secp256k1, SecretKey};
use crate::sign::{EntropySource, NodeSigner, Recipient};
use crate::events::{self, PaymentFailureReason};
use crate::ln::types::{PaymentHash, PaymentPreimage, PaymentSecret};
use crate::ln::channelmanager::{ChannelDetails, EventCompletionAction, HTLCSource, PaymentId};
use crate::ln::channel_state::ChannelDetails;
use crate::ln::channelmanager::{EventCompletionAction, HTLCSource, PaymentId};
use crate::ln::onion_utils;
use crate::ln::onion_utils::{DecodedOnionFailure, HTLCFailReason};
use crate::offers::invoice::Bolt12Invoice;

3
lightning/src/ln/shutdown_tests.rs
View file

@ -14,7 +14,8 @@ use crate::sign::{EntropySource, SignerProvider};
use crate::chain::ChannelMonitorUpdateStatus;
use crate::chain::transaction::OutPoint;
use crate::events::{Event, MessageSendEvent, HTLCDestination, MessageSendEventsProvider, ClosureReason};
use crate::ln::channelmanager::{self, PaymentSendFailure, PaymentId, RecipientOnionFields, Retry, ChannelShutdownState, ChannelDetails};
use crate::ln::channel_state::{ChannelDetails, ChannelShutdownState};
use crate::ln::channelmanager::{self, PaymentSendFailure, PaymentId, RecipientOnionFields, Retry};
use crate::routing::router::{PaymentParameters, get_route, RouteParameters};
use crate::ln::msgs;
use crate::ln::types::ChannelId;

17
lightning/src/routing/router.rs
View file

@ -15,7 +15,8 @@ use crate::blinded_path::{BlindedHop, BlindedPath, Direction, IntroductionNode};
use crate::blinded_path::message;
use crate::blinded_path::payment::{ForwardTlvs, PaymentConstraints, PaymentRelay, ReceiveTlvs, self};
use crate::ln::{PaymentHash, PaymentPreimage};
use crate::ln::channelmanager::{ChannelDetails, PaymentId, MIN_FINAL_CLTV_EXPIRY_DELTA, RecipientOnionFields};
use crate::ln::channel_state::ChannelDetails;
use crate::ln::channelmanager::{PaymentId, MIN_FINAL_CLTV_EXPIRY_DELTA, RecipientOnionFields};
use crate::ln::features::{BlindedHopFeatures, Bolt11InvoiceFeatures, Bolt12InvoiceFeatures, ChannelFeatures, NodeFeatures};
use crate::ln::msgs::{DecodeError, ErrorAction, LightningError, MAX_VALUE_MSAT};
use crate::ln::onion_utils;
@ -3321,6 +3322,7 @@ mod tests {
use crate::routing::test_utils::{add_channel, add_or_update_node, build_graph, build_line_graph, id_to_feature_flags, get_nodes, update_channel};
use crate::chain::transaction::OutPoint;
use crate::sign::EntropySource;
use crate::ln::channel_state::{ChannelCounterparty, ChannelDetails, ChannelShutdownState};
use crate::ln::types::ChannelId;
use crate::ln::features::{BlindedHopFeatures, ChannelFeatures, InitFeatures, NodeFeatures};
use crate::ln::msgs::{ErrorAction, LightningError, UnsignedChannelUpdate, MAX_VALUE_MSAT};
@ -3349,10 +3351,10 @@ mod tests {
use crate::sync::Arc;
fn get_channel_details(short_channel_id: Option<u64>, node_id: PublicKey,
features: InitFeatures, outbound_capacity_msat: u64) -> channelmanager::ChannelDetails {
channelmanager::ChannelDetails {
features: InitFeatures, outbound_capacity_msat: u64) -> ChannelDetails {
ChannelDetails {
channel_id: ChannelId::new_zero(),
counterparty: channelmanager::ChannelCounterparty {
counterparty: ChannelCounterparty {
features,
node_id,
unspendable_punishment_reserve: 0,
@ -3382,7 +3384,7 @@ mod tests {
inbound_htlc_maximum_msat: None,
config: None,
feerate_sat_per_1000_weight: None,
channel_shutdown_state: Some(channelmanager::ChannelShutdownState::NotShuttingDown),
channel_shutdown_state: Some(ChannelShutdownState::NotShuttingDown),
pending_inbound_htlcs: Vec::new(),
pending_outbound_htlcs: Vec::new(),
}
@ -8504,8 +8506,9 @@ pub(crate) mod bench_utils {
use crate::chain::transaction::OutPoint;
use crate::routing::scoring::ScoreUpdate;
use crate::sign::KeysManager;
use crate::ln::channel_state::{ChannelCounterparty, ChannelShutdownState};
use crate::ln::channelmanager;
use crate::ln::types::ChannelId;
use crate::ln::channelmanager::{self, ChannelCounterparty};
use crate::util::config::UserConfig;
use crate::util::test_utils::TestLogger;
@ -8590,7 +8593,7 @@ pub(crate) mod bench_utils {
inbound_htlc_maximum_msat: None,
config: None,
feerate_sat_per_1000_weight: None,
channel_shutdown_state: Some(channelmanager::ChannelShutdownState::NotShuttingDown),
channel_shutdown_state: Some(ChannelShutdownState::NotShuttingDown),
pending_inbound_htlcs: Vec::new(),
pending_outbound_htlcs: Vec::new(),
}

3
lightning/src/util/test_utils.rs
View file

@ -25,7 +25,8 @@ use crate::sign;
use crate::events;
use crate::events::bump_transaction::{WalletSource, Utxo};
use crate::ln::types::ChannelId;
use crate::ln::channelmanager::{ChannelDetails, self};
use crate::ln::channel_state::ChannelDetails;
use crate::ln::channelmanager;
#[cfg(test)]
use crate::ln::chan_utils::CommitmentTransaction;
use crate::ln::features::{ChannelFeatures, InitFeatures, NodeFeatures};