lightning: add HTLCHandlingFailure to HTLCHandlingFailed event

Author: carlaKC

lightning/src/events/mod.rs

@@ -627,6 +627,26 @@ pub enum InboundChannelFunds {
 	DualFunded,
 }
 
+/// Used to describe the types of failures that may occur when handling HTLCs.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum HTLCHandlingFailure {
+	/// The HTLC was failed by the local node.
+	Local {
+		/// The BOLT 04 failure code providing a specific failure reason.
+		failure_code: u16
+	},
+	/// The HTLC was failed by the remote downstream node. The specific reason for failure is not
+	/// known because it is encrypted.
+	Remote,
+}
+
+impl_writeable_tlv_based_enum!(HTLCHandlingFailure,
+	(0, Local) => {
+		(0, failure_code, required)
+	},
+	(1, Remote) => {},
+);
+
 /// An Event which you should probably take some action in response to.
 ///
 /// Note that while Writeable and Readable are implemented for Event, you probably shouldn't use
@@ -1441,6 +1461,10 @@ pub enum Event {
 		prev_channel_id: ChannelId,
 		/// Destination of the HTLC that failed to be processed.
 		failed_next_destination: HTLCDestination,
+		/// The cause of the processing failure.
+		///
+		/// This field will be `None` for objects serialized prior to LDK 0.1.1.
+		reason: Option<HTLCHandlingFailure>,
 	},
 	/// Indicates that a transaction originating from LDK needs to have its fee bumped. This event
 	/// requires confirmed external funds to be readily available to spend.
@@ -1743,10 +1767,11 @@ impl Writeable for Event {
 					(8, path.blinded_tail, option),
 				})
 			},
-			&Event::HTLCHandlingFailed { ref prev_channel_id, ref failed_next_destination } => {
+			&Event::HTLCHandlingFailed { ref prev_channel_id, ref failed_next_destination, ref reason} => {
 				25u8.write(writer)?;
 				write_tlv_fields!(writer, {
 					(0, prev_channel_id, required),
+					(1, reason, option),
 					(2, failed_next_destination, required),
 				})
 			},
@@ -2190,13 +2215,16 @@ impl MaybeReadable for Event {
 				let mut f = || {
 					let mut prev_channel_id = ChannelId::new_zero();
 					let mut failed_next_destination_opt = UpgradableRequired(None);
+					let mut reason = None;
 					read_tlv_fields!(reader, {
 						(0, prev_channel_id, required),
+						(1, reason, option),
 						(2, failed_next_destination_opt, upgradable_required),
 					});
 					Ok(Some(Event::HTLCHandlingFailed {
 						prev_channel_id,
 						failed_next_destination: _init_tlv_based_struct_field!(failed_next_destination_opt, upgradable_required),
+						reason,
 					}))
 				};
 				f()

lightning/src/ln/channelmanager.rs

@@ -32,7 +32,7 @@ use bitcoin::secp256k1::{SecretKey,PublicKey};
 use bitcoin::secp256k1::Secp256k1;
 use bitcoin::{secp256k1, Sequence, Weight};
 
-use crate::events::FundingInfo;
+use crate::events::{FundingInfo, HTLCHandlingFailure};
 use crate::blinded_path::message::{AsyncPaymentsContext, MessageContext, OffersContext};
 use crate::blinded_path::NodeIdLookUp;
 use crate::blinded_path::message::{BlindedMessagePath, MessageForwardNode};
@@ -336,6 +336,15 @@ pub(super) enum HTLCFailureMsg {
 	Malformed(msgs::UpdateFailMalformedHTLC),
 }
 
+impl From<&HTLCFailureMsg> for HTLCHandlingFailure {
+    fn from(value: &HTLCFailureMsg) -> Self {
+        match value {
+			HTLCFailureMsg::Relay(_) => HTLCHandlingFailure::Remote,
+			HTLCFailureMsg::Malformed(msg) => HTLCHandlingFailure::Local{ failure_code: msg.failure_code },
+		}
+    }
+}
+
 /// Stores whether we can't forward an HTLC or relevant forwarding info
 #[derive(Clone)] // See FundedChannel::revoke_and_ack for why, tl;dr: Rust bug
 pub(super) enum PendingHTLCStatus {
@@ -5720,6 +5729,7 @@ where
 			);
 			self.forward_htlcs_without_forward_event(&mut [pending_forwards]);
 			for (htlc_fail, htlc_destination) in htlc_fails.drain(..) {
+				let handling_fail = (&htlc_fail).into();
 				let failure = match htlc_fail {
 					HTLCFailureMsg::Relay(fail_htlc) => HTLCForwardInfo::FailHTLC {
 						htlc_id: fail_htlc.htlc_id,
@@ -5735,6 +5745,7 @@ where
 				self.pending_events.lock().unwrap().push_back((events::Event::HTLCHandlingFailed {
 					prev_channel_id: incoming_channel_id,
 					failed_next_destination: htlc_destination,
+					reason: Some(handling_fail),
 				}, None));
 			}
 		}
@@ -6926,6 +6937,7 @@ where
 				pending_events.push_back((events::Event::HTLCHandlingFailed {
 					prev_channel_id: *channel_id,
 					failed_next_destination: destination,
+					reason: Some(onion_error.into()),
 				}, None));
 			},
 		}

lightning/src/ln/onion_utils.rs

@@ -10,6 +10,7 @@
 use crate::blinded_path::BlindedHop;
 use crate::crypto::chacha20::ChaCha20;
 use crate::crypto::streams::ChaChaReader;
+use crate::events::HTLCHandlingFailure;
 use crate::ln::channel::TOTAL_BITCOIN_SUPPLY_SATOSHIS;
 use crate::ln::channelmanager::{HTLCSource, RecipientOnionFields};
 use crate::ln::msgs;
@@ -1243,6 +1244,15 @@ enum HTLCFailReasonRepr {
 	Reason { failure_code: u16, data: Vec<u8> },
 }
 
+impl From<&HTLCFailReason> for HTLCHandlingFailure {
+	fn from(value: &HTLCFailReason) -> Self {
+		match value.0 {
+			HTLCFailReasonRepr::LightningError { .. } => Self::Remote,
+			HTLCFailReasonRepr::Reason { failure_code, .. } => Self::Local { failure_code },
+		}
+	}
+}
+
 impl core::fmt::Debug for HTLCFailReason {
 	fn fmt(&self, f: &mut core::fmt::Formatter) -> Result<(), core::fmt::Error> {
 		match self.0 {