ln+events: add htlc failure reason to HTLCHandlingFailed

Author: carlaKC

lightning/src/events/mod.rs

@@ -26,7 +26,7 @@ use crate::ln::channel::FUNDING_CONF_DEADLINE_BLOCKS;
 use crate::offers::invoice::Bolt12Invoice;
 use crate::offers::static_invoice::StaticInvoice;
 use crate::types::features::ChannelTypeFeatures;
-use crate::ln::msgs;
+use crate::ln::{msgs, LocalHTLCFailureReason};
 use crate::ln::types::ChannelId;
 use crate::types::payment::{PaymentPreimage, PaymentHash, PaymentSecret};
 use crate::onion_message::messenger::Responder;
@@ -525,6 +525,31 @@ impl_writeable_tlv_based_enum_upgradable!(HTLCHandlingFailureType,
 	},
 );
 
+/// The reason for HTLC failures in [`Event::HTLCHandlingFailed`].
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum HTLCHandlingFailureReason {
+	/// The forwarded HTLC was failed back by the downstream node with an encrypted error reason.
+	Downstream,
+	/// The HTLC was failed locally by our node.
+	Local {
+		/// The reason that our node chose to fail the HTLC.
+		reason: LocalHTLCFailureReason,
+	},
+}
+
+impl_writeable_tlv_based_enum!(HTLCHandlingFailureReason,
+	(1, Downstream) => {},
+	(3, Local) => {
+		(0, reason, required),
+	},
+);
+
+impl From<LocalHTLCFailureReason> for HTLCHandlingFailureReason {
+	fn from(value: LocalHTLCFailureReason) -> Self {
+		HTLCHandlingFailureReason::Local { reason: value }
+	}
+}
+
 /// Will be used in [`Event::HTLCIntercepted`] to identify the next hop in the HTLC's path.
 /// Currently only used in serialization for the sake of maintaining compatibility. More variants
 /// will be added for general-purpose HTLC forward intercepts as well as trampoline forward
@@ -1462,6 +1487,10 @@ pub enum Event {
 		prev_channel_id: ChannelId,
 		/// The type of HTLC handling that failed.
 		failure_type: HTLCHandlingFailureType,
+		/// The reason that the HTLC failed.
+		///
+		/// This field will be `None` only for objects serialized prior to LDK 0.2.0.
+		failure_reason: Option<HTLCHandlingFailureReason>
 	},
 	/// 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.
@@ -1766,10 +1795,11 @@ impl Writeable for Event {
 					(8, path.blinded_tail, option),
 				})
 			},
-			&Event::HTLCHandlingFailed { ref prev_channel_id, ref failure_type } => {
+			&Event::HTLCHandlingFailed { ref prev_channel_id, ref failure_type, ref failure_reason } => {
 				25u8.write(writer)?;
 				write_tlv_fields!(writer, {
 					(0, prev_channel_id, required),
+					(1, failure_reason, option),
 					(2, failure_type, required),
 				})
 			},
@@ -2218,14 +2248,17 @@ impl MaybeReadable for Event {
 			25u8 => {
 				let mut f = || {
 					let mut prev_channel_id = ChannelId::new_zero();
+					let mut failure_reason = None;
 					let mut failure_type_opt = UpgradableRequired(None);
 					read_tlv_fields!(reader, {
 						(0, prev_channel_id, required),
+						(1, failure_reason, option),
 						(2, failure_type_opt, upgradable_required),
 					});
 					Ok(Some(Event::HTLCHandlingFailed {
 						prev_channel_id,
 						failure_type: _init_tlv_based_struct_field!(failure_type_opt, upgradable_required),
+						failure_reason,
 					}))
 				};
 				f()

lightning/src/ln/channelmanager.rs

@@ -5787,8 +5787,9 @@ where
 					&update_add_htlc, &*self.node_signer, &*self.logger, &self.secp_ctx
 				) {
 					Ok(decoded_onion) => decoded_onion,
-					Err((htlc_fail, _)) => {
-						htlc_fails.push((htlc_fail, HTLCHandlingFailureType::InvalidOnion));
+
+					Err((htlc_fail, reason)) => {
+						htlc_fails.push((htlc_fail, HTLCHandlingFailureType::InvalidOnion, reason.into()));
 						continue;
 					},
 				};
@@ -5816,7 +5817,7 @@ where
 							is_intro_node_blinded_forward, &shared_secret,
 						);
 						let failure_type = get_htlc_failure_type(outgoing_scid_opt, update_add_htlc.payment_hash);
-						htlc_fails.push((htlc_fail, failure_type));
+						htlc_fails.push((htlc_fail, failure_type, reason.into()));
 						continue;
 					},
 					// The incoming channel no longer exists, HTLCs should be resolved onchain instead.
@@ -5833,7 +5834,7 @@ where
 							is_intro_node_blinded_forward, &shared_secret,
 						);
 						let failure_type = get_htlc_failure_type(outgoing_scid_opt, update_add_htlc.payment_hash);
-						htlc_fails.push((htlc_fail, failure_type));
+						htlc_fails.push((htlc_fail, failure_type, reason.into()));
 						continue;
 					}
 				}
@@ -5845,8 +5846,9 @@ where
 					Ok(info) => htlc_forwards.push((info, update_add_htlc.htlc_id)),
 					Err(inbound_err) => {
 						let failure_type = get_htlc_failure_type(outgoing_scid_opt, update_add_htlc.payment_hash);
+						let htlc_failure = inbound_err.reason.into();
 						let htlc_fail = self.construct_pending_htlc_fail_msg(&update_add_htlc, &incoming_counterparty_node_id, shared_secret, inbound_err);
-						htlc_fails.push((htlc_fail, failure_type));
+						htlc_fails.push((htlc_fail, failure_type, htlc_failure));
 					},
 				}
 			}
@@ -5858,7 +5860,7 @@ where
 				incoming_channel_id, incoming_user_channel_id, htlc_forwards.drain(..).collect()
 			);
 			self.forward_htlcs_without_forward_event(&mut [pending_forwards]);
-			for (htlc_fail, failure_type) in htlc_fails.drain(..) {
+			for (htlc_fail, failure_type, failure_reason) in htlc_fails.drain(..) {
 				let failure = match htlc_fail {
 					HTLCFailureMsg::Relay(fail_htlc) => HTLCForwardInfo::FailHTLC {
 						htlc_id: fail_htlc.htlc_id,
@@ -5874,6 +5876,7 @@ where
 				self.pending_events.lock().unwrap().push_back((events::Event::HTLCHandlingFailed {
 					prev_channel_id: incoming_channel_id,
 					failure_type,
+					failure_reason: Some(failure_reason),
 				}, None));
 			}
 		}
@@ -7054,6 +7057,7 @@ where
 				pending_events.push_back((events::Event::HTLCHandlingFailed {
 					prev_channel_id: *channel_id,
 					failure_type,
+					failure_reason: Some(onion_error.into()),
 				}, None));
 			},
 		}

lightning/src/ln/onion_utils.rs

@@ -11,6 +11,7 @@ use super::msgs::OnionErrorPacket;
 use crate::blinded_path::BlindedHop;
 use crate::crypto::chacha20::ChaCha20;
 use crate::crypto::streams::ChaChaReader;
+use crate::events::HTLCHandlingFailureReason;
 use crate::ln::channel::TOTAL_BITCOIN_SUPPLY_SATOSHIS;
 use crate::ln::channelmanager::{HTLCSource, RecipientOnionFields};
 use crate::ln::msgs;
@@ -1761,6 +1762,17 @@ impl_writeable_tlv_based_enum!(LocalHTLCFailureReason,
 	(85, PeerOffline) => {},
 );
 
+impl From<&HTLCFailReason> for HTLCHandlingFailureReason {
+	fn from(value: &HTLCFailReason) -> Self {
+		match value.0 {
+			HTLCFailReasonRepr::LightningError { .. } => HTLCHandlingFailureReason::Downstream,
+			HTLCFailReasonRepr::Reason { failure_reason, .. } => {
+				HTLCHandlingFailureReason::Local { reason: failure_reason }
+			},
+		}
+	}
+}
+
 #[derive(Clone)] // See Channel::revoke_and_ack for why, tl;dr: Rust bug
 #[cfg_attr(test, derive(PartialEq))]
 pub(super) struct HTLCFailReason(HTLCFailReasonRepr);