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

[0.0.123-bindings] Move the public channel state API into a new module

Author: TheBlueMatt

fuzz/src/chanmon_consistency.rs

@@ -41,7 +41,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, ChannelManagerReadArgs, PaymentId};
+use lightning::ln::channel_state::ChannelDetails;
+use lightning::ln::channelmanager::{ChainParameters, ChannelManager, ChannelManagerReadArgs, PaymentId};
 use lightning::ln::outbound_payment::{RecipientOnionFields, PaymentSendFailure};
 use lightning::ln::channel::FEE_SPIKE_BUFFER_FEE_INCREASE_MULTIPLE;
 use lightning::ln::msgs::{self, CommitmentUpdate, ChannelMessageHandler, DecodeError, UpdateAddHTLC, Init};

fuzz/src/full_stack.rs

@@ -37,7 +37,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, InterceptId};
+use lightning::ln::channel_state::ChannelDetails;
+use lightning::ln::channelmanager::{ChainParameters, ChannelManager, PaymentId, InterceptId};
 use lightning::ln::outbound_payment::{RecipientOnionFields, Retry};
 use lightning::ln::peer_handler::{MessageHandler,PeerManager,SocketDescriptor,IgnoringMessageHandler};
 use lightning::ln::msgs::{self, DecodeError};

fuzz/src/msg_targets/gen_target.sh

@@ -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 ""

fuzz/src/msg_targets/msg_channel_details.rs

@@ -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);
 }

fuzz/src/router.rs

@@ -14,7 +14,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;
@@ -243,7 +244,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(),
 						});

lightning-invoice/src/utils.rs

@@ -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;

lightning/src/blinded_path/payment.rs

@@ -8,7 +8,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;

lightning/src/chain/chainmonitor.rs

@@ -39,7 +39,7 @@ use crate::util::atomic_counter::AtomicCounter;
 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};

lightning/src/ln/channel.rs

@@ -29,7 +29,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;
@@ -185,45 +186,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 {
@@ -244,13 +206,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,
@@ -259,53 +214,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
@@ -339,42 +247,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 {
@@ -398,13 +270,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 {
@@ -443,58 +308,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 {