Add HTLCHandlingFailed event

Adds a HTLCHandlingFailed that expresses failure by our node to process
a specific HTLC. A HTLCDestination enum is defined to express the
possible cases that causes the handling to fail.

Author: jurvis

fuzz/src/chanmon_consistency.rs

@@ -860,6 +860,7 @@ pub fn do_test<Out: Output>(data: &[u8], underlying_out: Out) {
 						events::Event::PendingHTLCsForwardable { .. } => {
 							nodes[$node].process_pending_htlc_forwards();
 						},
+						events::Event::HTLCHandlingFailed { .. } => {},
 						_ => if out.may_fail.load(atomic::Ordering::Acquire) {
 							return;
 						} else {

lightning/src/util/events.rs

@@ -540,6 +540,19 @@ pub enum Event {
 		/// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
 		channel_type: ChannelTypeFeatures,
 	},
+	/// Indicates that the HTLC was accepted, but could not be processed when or after attempting to
+	/// forward it. Some scenarios where this event may be sent include:
+	/// 1. While waiting to forward the HTLC, the channel it is meant to be forwarded through closes
+	/// 2. When forwarding for a phantom payment, the scid to forward to was invalid
+	/// 3. Attempting to claim a payment without any HTLCs left over
+	/// 4. Claiming an amount for an MPP payment that exceeds the HTLC total
+	/// 5. The HTLC has timed out
+	HTLCHandlingFailed {
+		/// The channel over which the HTLC was received.
+		prev_channel_id: [u8; 32],
+		/// Destination of the HTLC that failed to be processed.
+		failed_next_destination: HTLCDestination,
+	},
 }
 
 impl Writeable for Event {
@@ -684,6 +697,13 @@ impl Writeable for Event {
 					(6, short_channel_id, option),
 				})
 			},
+			&Event::HTLCHandlingFailed { ref prev_channel_id, ref failed_next_destination } => {
+				25u8.write(writer)?;
+				write_tlv_fields!(writer, {
+					(0, prev_channel_id, required),
+					(2, failed_next_destination, required),
+				})
+			},
 			// Note that, going forward, all new events must only write data inside of
 			// `write_tlv_fields`. Versions 0.0.101+ will ignore odd-numbered events that write
 			// data via `write_tlv_fields`.
@@ -1178,3 +1198,48 @@ impl<T: EventHandler> EventHandler for Arc<T> {
 		self.deref().handle_event(event)
 	}
 }
+
+/// Intended destination of a failed HTLC as indicated in [`Event::HTLCHandlingFailed`].
+#[derive(Clone, Debug, PartialEq)]
+pub enum HTLCDestination {
+	/// We tried forwarding to a channel, but failed to do so. An example of such an instance
+	/// is when a channel closes while we were waiting to forward to it.
+	NextHopChannel {
+		/// The node_id of the next node. For backwards compatibility, this field is
+		/// marked as optional, since prior versions may not always be able to provide
+		/// counterparty node information.
+		node_id: Option<PublicKey>,
+		/// The outgoing channel_id between us and the next node.
+		channel_id: [u8; 32],
+	},
+	/// Scenario where we are unsure of the next node to forward the HTLC to.
+	UnknownNextHop {
+		/// Short channel id we are requesting to forward a HTLC to.
+		requested_forward_scid: u64,
+	},
+	/// Failure scenario where an HTLC may have been forwarded to be intended for us,
+	/// but is invalid for some reason, so we reject it.
+	///
+	/// Some of the reasons may include:
+	/// 1. HTLC Timeouts
+	/// 2. Expected MPP amount to claim does not equal HTLC total
+	/// 3. Claimable amount does not match expected amount
+	/// 4. Attempting to claim a payment without any HTLCs left over
+	FailedPayment {
+		/// The payment hash of the payment we attempted to process.
+		payment_hash: PaymentHash
+	},
+}
+
+impl_writeable_tlv_based_enum_upgradable!(HTLCDestination,
+	(0, NextHopChannel) => {
+		(0, node_id, required),
+		(2, channel_id, required),
+	},
+	(2, UnknownNextHop) => {
+		(0, requested_forward_scid, required),
+	},
+	(4, FailedPayment) => {
+		(0, payment_hash, required),
+	}
+);