Add HTLCIntercepted event

Used in upcoming commit(s) so users can intercept forwarded HTLCs

Co-authored-by: John Cantrell <johncantrell97@gmail.com>
Co-authored-by: Valentine Wallace <vwallace@protonmail.com>

Author: valentinewallace

lightning/src/util/events.rs

@@ -17,7 +17,7 @@
 use crate::chain::keysinterface::SpendableOutputDescriptor;
 #[cfg(anchors)]
 use crate::ln::chan_utils::HTLCOutputInCommitment;
-use crate::ln::channelmanager::PaymentId;
+use crate::ln::channelmanager::{InterceptId, PaymentId};
 use crate::ln::channel::FUNDING_CONF_DEADLINE_BLOCKS;
 use crate::ln::features::ChannelTypeFeatures;
 use crate::ln::msgs;
@@ -288,6 +288,18 @@ pub enum BumpTransactionEvent {
 	},
 }
 
+/// 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
+/// intercepts in upcoming work.
+enum InterceptNextHop {
+	FakeScid(u64),
+}
+
+impl_writeable_tlv_based_enum!(InterceptNextHop, ;
+	(0, FakeScid)
+);
+
 /// 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
@@ -566,6 +578,20 @@ pub enum Event {
 		/// now + 5*time_forwardable).
 		time_forwardable: Duration,
 	},
+	/// Used to indicate that we've intercepted an HTLC forward.
+	HTLCIntercepted {
+		/// The fake scid that was programmed as the next hop's scid.
+		requested_next_hop_scid: u64,
+		/// The payment hash used for this HTLC.
+		payment_hash: PaymentHash,
+		/// How many msats are to be received on the inbound edge of this HTLC.
+		inbound_amount_msat: u64,
+		/// How many msats the payer intended to route to the next node. Depending on the reason you are
+		/// intercepting this payment, you might take a fee by forwarding less than this amount.
+		expected_outbound_amount_msat: u64,
+		/// A id to help LDK identify which HTLC is being forwarded or failed.
+		intercept_id: InterceptId
+	},
 	/// Used to indicate that an output which you should know how to spend was confirmed on chain
 	/// and is now spendable.
 	/// Such an output will *not* ever be spent by rust-lightning, and are not at risk of your
@@ -896,6 +922,17 @@ impl Writeable for Event {
 					(6, channel_type, required),
 				});
 			},
+			&Event::HTLCIntercepted { requested_next_hop_scid, payment_hash, inbound_amount_msat: inbound_amount_msats, expected_outbound_amount_msat: expected_outbound_amount_msats, intercept_id } => {
+				31u8.write(writer)?;
+				let intercept_scid = InterceptNextHop::FakeScid(requested_next_hop_scid);
+				write_tlv_fields!(writer, {
+					(0, intercept_scid, required),
+					(2, payment_hash, required),
+					(4, inbound_amount_msats, required),
+					(6, expected_outbound_amount_msats, required),
+					(8, intercept_id, 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`.
@@ -1199,6 +1236,30 @@ impl MaybeReadable for Event {
 				};
 				f()
 			},
+			31u8 => {
+				let mut payment_hash = PaymentHash([0; 32]);
+				let mut intercept_id = InterceptId([0; 32]);
+				let mut requested_next_hop_scid = InterceptNextHop::FakeScid(0);
+				let mut inbound_amount_msats = 0;
+				let mut expected_outbound_amount_msats = 0;
+				read_tlv_fields!(reader, {
+					(0, requested_next_hop_scid, required),
+					(2, payment_hash, required),
+					(4, inbound_amount_msats, required),
+					(6, expected_outbound_amount_msats, required),
+					(8, intercept_id, required)
+				});
+				let next_scid = match requested_next_hop_scid {
+					InterceptNextHop::FakeScid(scid) => scid
+				};
+				Ok(Some(Event::HTLCIntercepted {
+					payment_hash,
+					requested_next_hop_scid: next_scid,
+					inbound_amount_msat: inbound_amount_msats,
+					expected_outbound_amount_msat: expected_outbound_amount_msats,
+					intercept_id,
+				}))
+			},
 			// Versions prior to 0.0.100 did not ignore odd types, instead returning InvalidValue.
 			// Version 0.0.100 failed to properly ignore odd types, possibly resulting in corrupt
 			// reads.