Expose per-HTLC forwarded amounts

Preserve LDK's per-HTLC amount when forwarding events cross the LDK
Node API boundary. This lets callers attribute multi-HTLC forwards to
individual channels.

Store the amount in an optional TLV so previously serialized events
continue to decode without it.

Co-Authored-By: HAL 9000

Author: tnull

src/event.rs

@@ -68,6 +68,10 @@ use crate::{
 pub struct HTLCLocator {
 	/// The channel that the HTLC was sent or received on.
 	pub channel_id: ChannelId,
+	/// The amount, in milli-satoshis, of the HTLC that was sent or received, if known.
+	///
+	/// This will be `None` for events serialized by LDK Node v0.7.0 and prior.
+	pub amount_msat: Option<u64>,
 	/// The `user_channel_id` for the channel.
 	///
 	/// Will only be `None` for events serialized with LDK Node v0.3.0 or prior, or if the
@@ -84,12 +88,14 @@ impl_writeable_tlv_based!(HTLCLocator, {
 	(1, channel_id, required),
 	(3, user_channel_id, option),
 	(5, node_id, option),
+	(7, amount_msat, option),
 });
 
 impl From<LdkHtlcLocator> for HTLCLocator {
 	fn from(value: LdkHtlcLocator) -> Self {
 		HTLCLocator {
 			channel_id: value.channel_id,
+			amount_msat: value.amount_msat,
 			user_channel_id: value.user_channel_id.map(|u| UserChannelId(u)),
 			node_id: value.node_id,
 		}
@@ -355,11 +361,13 @@ impl_writeable_tlv_based_enum!(Event,
 		(14, outbound_amount_forwarded_msat, (default_value, 0)),
 		(15, prev_htlcs, (default_value_vec, vec![HTLCLocator {
 			channel_id: legacy_prev_channel_id.ok_or(lightning::ln::msgs::DecodeError::InvalidValue)?,
+			amount_msat: None,
 			user_channel_id: legacy_prev_user_channel_id.map(UserChannelId),
 			node_id: legacy_prev_node_id,
 		}])),
 		(17, next_htlcs, (default_value_vec, vec![HTLCLocator {
 			channel_id: legacy_next_channel_id.ok_or(lightning::ln::msgs::DecodeError::InvalidValue)?,
+			amount_msat: None,
 			user_channel_id: legacy_next_user_channel_id.map(UserChannelId),
 			node_id: legacy_next_node_id,
 		}])),
@@ -2027,6 +2035,56 @@ mod tests {
 	use crate::payment::store::LSPS2Parameters;
 	use crate::types::DynStoreWrapper;
 
+	#[derive(Clone, Debug, PartialEq, Eq)]
+	struct LegacyHTLCLocator {
+		channel_id: ChannelId,
+		user_channel_id: Option<UserChannelId>,
+		node_id: Option<PublicKey>,
+	}
+
+	impl_writeable_tlv_based!(LegacyHTLCLocator, {
+		(1, channel_id, required),
+		(3, user_channel_id, option),
+		(5, node_id, option),
+	});
+
+	#[test]
+	fn htlc_locator_conversion_preserves_amount() {
+		let ldk_locator = LdkHtlcLocator {
+			channel_id: ChannelId([42; 32]),
+			amount_msat: Some(100_000),
+			user_channel_id: None,
+			node_id: None,
+		};
+		let expected_encoding = ldk_locator.encode();
+
+		assert_eq!(
+			HTLCLocator::from(ldk_locator).encode(),
+			expected_encoding,
+			"converted HTLC locator should preserve its amount"
+		);
+	}
+
+	#[test]
+	fn htlc_locator_defaults_amount_for_legacy_encoding() {
+		let legacy_locator = LegacyHTLCLocator {
+			channel_id: ChannelId([42; 32]),
+			user_channel_id: Some(UserChannelId(43)),
+			node_id: None,
+		};
+		let encoded_locator = legacy_locator.encode();
+
+		let locator = HTLCLocator::read(&mut &encoded_locator[..]).unwrap();
+
+		assert_eq!(locator.channel_id, legacy_locator.channel_id);
+		assert_eq!(locator.user_channel_id, legacy_locator.user_channel_id);
+		assert_eq!(locator.node_id, legacy_locator.node_id);
+		assert_eq!(
+			locator.amount_msat, None,
+			"legacy HTLC locator should default its amount to None"
+		);
+	}
+
 	#[test]
 	fn lsps2_payment_metadata_decodes_total_fee_limit() {
 		let metadata = PaymentMetadata {
@@ -2214,11 +2272,13 @@ mod tests {
 		let logger = Arc::new(TestLogger::new());
 		let prev_htlcs = vec![HTLCLocator {
 			channel_id: ChannelId([1; 32]),
+			amount_msat: None,
 			user_channel_id: None,
 			node_id: None,
 		}];
 		let next_htlcs = vec![HTLCLocator {
 			channel_id: ChannelId([2; 32]),
+			amount_msat: None,
 			user_channel_id: None,
 			node_id: None,
 		}];