Include pending HTLCs in ChannelDetails

Author: wvanlint

fuzz/src/router.rs

@@ -241,6 +241,8 @@ pub fn do_test<Out: test_logger::Output>(data: &[u8], out: Out) {
 							config: None,
 							feerate_sat_per_1000_weight: None,
 							channel_shutdown_state: Some(channelmanager::ChannelShutdownState::NotShuttingDown),
+							pending_inbound_htlcs: Vec::new(),
+							pending_outbound_htlcs: Vec::new(),
 						});
 					}
 					Some(&$first_hops_vec[..])

lightning/src/ln/channel.rs

@@ -152,6 +152,72 @@ enum InboundHTLCState {
 	LocalRemoved(InboundHTLCRemovalReason),
 }
 
+/// Exposes the state of pending inbound HTLCs.
+///
+/// Fail and fulfill suffixes indicate the resolution of the HTLC.
+#[derive(Clone, Debug, PartialEq)]
+pub enum InboundHTLCStateDetails {
+	/// The RemoteAnnounced states indicate that the HTLC is not any commitment transactions yet,
+	/// but the remote node sent update_add_htlc.
+	RemoteAnnouncedForward,
+	/// See above.
+	RemoteAnnouncedFail,
+	/// AwaitingRemoteRevoke states indicate that we have received commitment_signed with
+	/// this HTLC, returned revoke_and_ack, and this HTLC is included on the local commitment
+	/// transaction but not the remote commitment transaction.
+	/// We are awaiting the appropriate revoke_and_ack's from the remote before this HTLC is included
+	/// on the remote commitment transaction, possibly for a prior state first.
+	AwaitingRemoteRevokeToAddForward,
+	/// See above.
+	AwaitingRemoteRevokeToAddFail,
+	/// Committed indicates that this HTLC has been included in the commitment_signed and
+	/// revoke_and_ack flow on both sides and is included in both commitment transactions.
+	Committed,
+	/// AwaitingRemoteRevokeToRemove states indicate that this HTLC is still on both commitment
+	/// transactions, but we are awaiting the appropriate revoke_and_ack's to remove this HTLC from
+	/// the remote commitment transaction, possibly for a prior state first.
+	AwaitingRemoteRevokeToRemoveFulfill,
+	/// See above.
+	AwaitingRemoteRevokeToRemoveFail,
+}
+
+impl From<&InboundHTLCState> for InboundHTLCStateDetails {
+	fn from(state: &InboundHTLCState) -> InboundHTLCStateDetails {
+		match state {
+			InboundHTLCState::RemoteAnnounced(PendingHTLCStatus::Forward(_)) =>
+				InboundHTLCStateDetails::RemoteAnnouncedForward,
+			InboundHTLCState::RemoteAnnounced(PendingHTLCStatus::Fail(_)) =>
+				InboundHTLCStateDetails::RemoteAnnouncedFail,
+			InboundHTLCState::AwaitingRemoteRevokeToAnnounce(PendingHTLCStatus::Forward(_)) =>
+				InboundHTLCStateDetails::AwaitingRemoteRevokeToAddForward,
+			InboundHTLCState::AwaitingRemoteRevokeToAnnounce(PendingHTLCStatus::Fail(_)) =>
+				InboundHTLCStateDetails::AwaitingRemoteRevokeToAddFail,
+			InboundHTLCState::AwaitingAnnouncedRemoteRevoke(PendingHTLCStatus::Forward(_)) =>
+				InboundHTLCStateDetails::AwaitingRemoteRevokeToAddForward,
+			InboundHTLCState::AwaitingAnnouncedRemoteRevoke(PendingHTLCStatus::Fail(_)) =>
+				InboundHTLCStateDetails::AwaitingRemoteRevokeToAddFail,
+			InboundHTLCState::Committed =>
+				InboundHTLCStateDetails::Committed,
+			InboundHTLCState::LocalRemoved(InboundHTLCRemovalReason::FailRelay(_)) =>
+				InboundHTLCStateDetails::AwaitingRemoteRevokeToRemoveFail,
+			InboundHTLCState::LocalRemoved(InboundHTLCRemovalReason::FailMalformed(_)) =>
+				InboundHTLCStateDetails::AwaitingRemoteRevokeToRemoveFail,
+			InboundHTLCState::LocalRemoved(InboundHTLCRemovalReason::Fulfill(_)) =>
+				InboundHTLCStateDetails::AwaitingRemoteRevokeToRemoveFulfill,
+		}
+	}
+}
+
+impl_writeable_tlv_based_enum!(InboundHTLCStateDetails,
+	(0, RemoteAnnouncedForward) => {},
+	(2, RemoteAnnouncedFail) => {},
+	(4, AwaitingRemoteRevokeToAddForward) => {},
+	(6, AwaitingRemoteRevokeToAddFail) => {},
+	(8, Committed) => {},
+	(10, AwaitingRemoteRevokeToRemoveFulfill) => {},
+	(12, AwaitingRemoteRevokeToRemoveFail) => {};
+);
+
 struct InboundHTLCOutput {
 	htlc_id: u64,
 	amount_msat: u64,
@@ -160,6 +226,35 @@ struct InboundHTLCOutput {
 	state: InboundHTLCState,
 }
 
+/// Exposes details around pending inbound HTLCs.
+#[derive(Clone, Debug, PartialEq)]
+pub struct InboundHTLCDetails {
+	/// The corresponding HTLC ID.
+	pub htlc_id: u64,
+	/// The amount in msat.
+	pub amount_msat: u64,
+	/// The CLTV expiry.
+	pub cltv_expiry: u32,
+	/// The payment hash.
+	pub payment_hash: PaymentHash,
+	/// The state of the HTLC in the update_*_htlc, commitment_signed, revoke_and_ack flow.
+	/// Informs on which commitment transactions the HTLC is included.
+	pub state: 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.
+	/// This takes into account the second-stage HTLC transactions as well.
+	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),
+	(8, state, required),
+	(10, is_dust, required),
+});
+
 enum OutboundHTLCState {
 	/// Added by us and included in a commitment_signed (if we were AwaitingRemoteRevoke when we
 	/// created it we would have put it in the holding cell instead). When they next revoke_and_ack
@@ -192,6 +287,65 @@ enum OutboundHTLCState {
 	AwaitingRemovedRemoteRevoke(OutboundHTLCOutcome),
 }
 
+/// Exposes the state of pending outbound HTLCs.
+///
+/// Failure and success suffixes indicate the resolution of the HTLC.
+#[derive(Clone, Debug, PartialEq)]
+pub enum OutboundHTLCStateDetails {
+	/// THe AwaitingRemoteRevoke state indicates that this HTLC is not on any commitment transactions
+	/// yet, but we are awaiting the appropriate revoke_and_ack's from the remote before it will be
+	/// on the remote commitment transaction, possibly for a prior state first.
+	AwaitingRemoteRevokeToAdd,
+	/// The Committed state indicates that this HTLC is included on the remote's commitment
+	/// transaction. This includes the subsequent state where we include it in the local commitment
+	/// transaction, as:
+	///  * they've revoked, so worst case we can announce an old state and get our (option on)
+	///    money back (though we won't), and,
+	///  * we'll send them a revoke when they send a commitment_signed, and since only they're
+	///    allowed to remove it, the "can only be removed once committed on both sides" requirement
+	///    doesn't matter to us and it's up to them to enforce it, worst-case they jump ahead but
+	///    we'll never get out of sync).
+	Committed,
+	/// AwaitingRemoteRevokeToRemove states indicate that the remote removed this HTLC and sent a
+	/// commitment_signed and we've revoke_and_ack'ed it. It is removed from the local commitment
+	/// transaction and we're awaiting the appropriate revoke_and_ack's from the remote before it
+	/// will be removed from the remote's commitmen transaction as well, possibly for a prior state
+	/// first.
+	AwaitingRemoteRevokeToRemoveSuccess,
+	/// See above.
+	AwaitingRemoteRevokeToRemoveFailure,
+}
+
+impl From<&OutboundHTLCState> for OutboundHTLCStateDetails {
+	fn from(state: &OutboundHTLCState) -> OutboundHTLCStateDetails {
+		match state {
+			OutboundHTLCState::LocalAnnounced(_) =>
+				OutboundHTLCStateDetails::AwaitingRemoteRevokeToAdd,
+			OutboundHTLCState::Committed =>
+				OutboundHTLCStateDetails::Committed,
+			// RemoteRemoved states are ignored as the state is transient and the remote has not committed to
+			// the state yet.
+			OutboundHTLCState::RemoteRemoved(_) =>
+				OutboundHTLCStateDetails::Committed,
+			OutboundHTLCState::AwaitingRemoteRevokeToRemove(OutboundHTLCOutcome::Success(_)) =>
+				OutboundHTLCStateDetails::AwaitingRemoteRevokeToRemoveSuccess,
+			OutboundHTLCState::AwaitingRemoteRevokeToRemove(OutboundHTLCOutcome::Failure(_)) =>
+				OutboundHTLCStateDetails::AwaitingRemoteRevokeToRemoveFailure,
+			OutboundHTLCState::AwaitingRemovedRemoteRevoke(OutboundHTLCOutcome::Success(_)) =>
+				OutboundHTLCStateDetails::AwaitingRemoteRevokeToRemoveSuccess,
+			OutboundHTLCState::AwaitingRemovedRemoteRevoke(OutboundHTLCOutcome::Failure(_)) =>
+				OutboundHTLCStateDetails::AwaitingRemoteRevokeToRemoveFailure,
+		}
+	}
+}
+
+impl_writeable_tlv_based_enum!(OutboundHTLCStateDetails,
+	(0, AwaitingRemoteRevokeToAdd) => {},
+	(2, Committed) => {},
+	(4, AwaitingRemoteRevokeToRemoveSuccess) => {},
+	(6, AwaitingRemoteRevokeToRemoveFailure) => {};
+);
+
 #[derive(Clone)]
 enum OutboundHTLCOutcome {
 	/// LDK version 0.0.105+ will always fill in the preimage here.
@@ -227,6 +381,39 @@ struct OutboundHTLCOutput {
 	skimmed_fee_msat: Option<u64>,
 }
 
+/// Exposes details around pending outbound HTLCs.
+#[derive(Clone, Debug, PartialEq)]
+pub struct OutboundHTLCDetails {
+	/// The corresponding HTLC ID.
+	/// 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 CLTV expiry.
+	pub cltv_expiry: u32,
+	/// The payment hash.
+	pub payment_hash: PaymentHash,
+	/// The state of the HTLC in the update_*_htlc, commitment_signed, revoke_and_ack flow.
+	/// Informs on which commitment transactions the HTLC is included.
+	pub state: 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.
+	/// This takes into account the second-stage HTLC transactions as well.
+	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),
+	(8, state, required),
+	(10, skimmed_fee_msat, required),
+	(12, is_dust, required),
+});
+
 /// See AwaitingRemoteRevoke ChannelState for more info
 enum HTLCUpdateAwaitingACK {
 	AddHTLC { // TODO: Time out if we're getting close to cltv_expiry
@@ -1598,6 +1785,90 @@ impl<Signer: ChannelSigner> ChannelContext<Signer> {
 		stats
 	}
 
+	/// Returns information on all pending inbound HTLCs.
+	pub fn get_pending_inbound_htlc_details(&self) -> Vec<InboundHTLCDetails> {
+		let mut holding_cell_states = HashMap::new();
+		for holding_cell_update in self.holding_cell_htlc_updates.iter() {
+			match holding_cell_update {
+				HTLCUpdateAwaitingACK::ClaimHTLC { htlc_id, .. } => {
+					holding_cell_states.insert(
+						htlc_id,
+						InboundHTLCStateDetails::AwaitingRemoteRevokeToRemoveFulfill,
+					);
+				},
+				HTLCUpdateAwaitingACK::FailHTLC { htlc_id, .. } => {
+					holding_cell_states.insert(
+						htlc_id,
+						InboundHTLCStateDetails::AwaitingRemoteRevokeToRemoveFail,
+					);
+				},
+				_ => {},
+			}
+		}
+		let mut inbound_details = Vec::new();
+		let htlc_success_dust_limit = if self.get_channel_type().supports_anchors_zero_fee_htlc_tx() {
+			0
+		} else {
+			let dust_buffer_feerate = self.get_dust_buffer_feerate(None) as u64;
+			dust_buffer_feerate * htlc_success_tx_weight(self.get_channel_type()) / 1000
+		};
+		let holder_dust_limit_success_sat = htlc_success_dust_limit + self.holder_dust_limit_satoshis;
+		for htlc in self.pending_inbound_htlcs.iter() {
+			inbound_details.push(InboundHTLCDetails{
+				htlc_id: htlc.htlc_id,
+				amount_msat: htlc.amount_msat,
+				cltv_expiry: htlc.cltv_expiry,
+				payment_hash: htlc.payment_hash,
+				state: holding_cell_states.remove(&htlc.htlc_id).unwrap_or((&htlc.state).into()),
+				is_dust: htlc.amount_msat / 1000 < holder_dust_limit_success_sat,
+			});
+		}
+		inbound_details
+	}
+
+	/// Returns information on all pending outbound HTLCs.
+	pub fn get_pending_outbound_htlc_details(&self) -> Vec<OutboundHTLCDetails> {
+		let mut outbound_details = Vec::new();
+		let htlc_timeout_dust_limit = if self.get_channel_type().supports_anchors_zero_fee_htlc_tx() {
+			0
+		} else {
+			let dust_buffer_feerate = self.get_dust_buffer_feerate(None) as u64;
+			dust_buffer_feerate * htlc_success_tx_weight(self.get_channel_type()) / 1000
+		};
+		let holder_dust_limit_timeout_sat = htlc_timeout_dust_limit + self.holder_dust_limit_satoshis;
+		for htlc in self.pending_outbound_htlcs.iter() {
+			outbound_details.push(OutboundHTLCDetails{
+				htlc_id: Some(htlc.htlc_id),
+				amount_msat: htlc.amount_msat,
+				cltv_expiry: htlc.cltv_expiry,
+				payment_hash: htlc.payment_hash,
+				skimmed_fee_msat: htlc.skimmed_fee_msat,
+				state: (&htlc.state).into(),
+				is_dust: htlc.amount_msat / 1000 < holder_dust_limit_timeout_sat,
+			});
+		}
+		for holding_cell_update in self.holding_cell_htlc_updates.iter() {
+			if let HTLCUpdateAwaitingACK::AddHTLC {
+				amount_msat,
+				cltv_expiry,
+				payment_hash,
+				skimmed_fee_msat,
+				..
+			} = *holding_cell_update {
+				outbound_details.push(OutboundHTLCDetails{
+					htlc_id: None,
+					amount_msat: amount_msat,
+					cltv_expiry: cltv_expiry,
+					payment_hash: payment_hash,
+					skimmed_fee_msat: skimmed_fee_msat,
+					state: OutboundHTLCStateDetails::AwaitingRemoteRevokeToAdd,
+					is_dust: amount_msat / 1000 < holder_dust_limit_timeout_sat,
+				});
+			}
+		}
+		outbound_details
+	}
+
 	/// Get the available balances, see [`AvailableBalances`]'s fields for more info.
 	/// Doesn't bother handling the
 	/// if-we-removed-it-already-but-haven't-fully-resolved-they-can-still-send-an-inbound-HTLC

lightning/src/ln/channelmanager.rs

@@ -41,6 +41,7 @@ use crate::events::{Event, EventHandler, EventsProvider, MessageSendEvent, Messa
 // construct one themselves.
 use crate::ln::{inbound_payment, PaymentHash, PaymentPreimage, PaymentSecret};
 use crate::ln::channel::{Channel, ChannelContext, ChannelError, ChannelUpdateStatus, ShutdownResult, UnfundedChannelContext, UpdateFulfillCommitFetch, OutboundV1Channel, InboundV1Channel};
+pub use crate::ln::channel::{InboundHTLCDetails, InboundHTLCStateDetails, OutboundHTLCDetails, OutboundHTLCStateDetails};
 use crate::ln::features::{ChannelFeatures, ChannelTypeFeatures, InitFeatures, NodeFeatures};
 #[cfg(any(feature = "_test_utils", test))]
 use crate::ln::features::Bolt11InvoiceFeatures;
@@ -1526,6 +1527,14 @@ pub struct ChannelDetails {
 	///
 	/// 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.117.
+	pub pending_inbound_htlcs: Vec<InboundHTLCDetails>,
+	/// Pending outbound HTLCs.
+	///
+	/// This field is empty for objects serialized with LDK versions prior to 0.0.117.
+	pub pending_outbound_htlcs: Vec<OutboundHTLCDetails>,
 }
 
 impl ChannelDetails {
@@ -1601,6 +1610,8 @@ impl ChannelDetails {
 			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(),
 		}
 	}
 }
@@ -7614,6 +7625,8 @@ impl Writeable for ChannelDetails {
 			(37, user_channel_id_high_opt, option),
 			(39, self.feerate_sat_per_1000_weight, option),
 			(41, self.channel_shutdown_state, option),
+			(43, self.pending_inbound_htlcs, optional_vec),
+			(45, self.pending_outbound_htlcs, optional_vec),
 		});
 		Ok(())
 	}
@@ -7652,6 +7665,8 @@ impl Readable for ChannelDetails {
 			(37, user_channel_id_high_opt, option),
 			(39, feerate_sat_per_1000_weight, option),
 			(41, channel_shutdown_state, option),
+			(43, pending_inbound_htlcs, optional_vec),
+			(45, pending_outbound_htlcs, optional_vec),
 		});
 
 		// `user_channel_id` used to be a single u64 value. In order to remain backwards compatible with
@@ -7688,6 +7703,8 @@ impl Readable for ChannelDetails {
 			inbound_htlc_maximum_msat,
 			feerate_sat_per_1000_weight,
 			channel_shutdown_state,
+			pending_inbound_htlcs: pending_inbound_htlcs.unwrap_or(Vec::new()),
+			pending_outbound_htlcs: pending_outbound_htlcs.unwrap_or(Vec::new()),
 		})
 	}
 }

lightning/src/routing/router.rs

@@ -2741,6 +2741,8 @@ mod tests {
 			config: None,
 			feerate_sat_per_1000_weight: None,
 			channel_shutdown_state: Some(channelmanager::ChannelShutdownState::NotShuttingDown),
+			pending_inbound_htlcs: Vec::new(),
+			pending_outbound_htlcs: Vec::new(),
 		}
 	}
 
@@ -6812,6 +6814,8 @@ pub(crate) mod bench_utils {
 			config: None,
 			feerate_sat_per_1000_weight: None,
 			channel_shutdown_state: Some(channelmanager::ChannelShutdownState::NotShuttingDown),
+			pending_inbound_htlcs: Vec::new(),
+			pending_outbound_htlcs: Vec::new(),
 		}
 	}