Track dummy-hop skimmed fees through receive handling

Propagate dummy-hop skimmed fees through HTLC peeling, channel
persistence, and receive-side payment tracking.

Expose the accumulated value on `PaymentClaimable` and
`PaymentClaimed`.

This keeps `amount_msat` focused on the amount delivered to the final
receive TLVs, while still surfacing the additional revenue from dummy
hops. Receivers can account for these fees without changing the meaning
of existing skimmed-fee fields.

Author: shaavan

lightning/src/events/mod.rs

@@ -902,6 +902,12 @@ pub enum Event {
 		///
 		/// [`ChannelConfig::accept_underpaying_htlcs`]: crate::util::config::ChannelConfig::accept_underpaying_htlcs
 		amount_msat: u64,
+		/// The additional skimmed fee, in thousandths of a satoshi, that the receiver earns from
+		/// dummy hops preceding the final receipt, in addition to the `amount_msat`.
+		///
+		/// For backwards compatibility with older LDK versions where this TLV was not serialized,
+		/// this defaults to 0 when absent.
+		dummy_hops_skimmed_fee_msat: u64,
 		/// The value, in thousands of a satoshi, that was skimmed off of this payment as an extra fee
 		/// taken by our channel counterparty.
 		///
@@ -965,6 +971,12 @@ pub enum Event {
 		/// The value, in thousandths of a satoshi, that this payment is for. May be greater than the
 		/// invoice amount.
 		amount_msat: u64,
+		/// The additional skimmed fee, in thousandths of a satoshi, that the receiver earns from
+		/// dummy hops preceding the final receipt, in addition to the `amount_msat`.
+		///
+		/// For backwards compatibility with older LDK versions where this TLV was not serialized,
+		/// this defaults to 0 when absent.
+		dummy_hops_skimmed_fee_msat: u64,
 		/// The purpose of the claimed payment, i.e. whether the payment was for an invoice or a
 		/// spontaneous payment.
 		purpose: PaymentPurpose,
@@ -1891,6 +1903,7 @@ impl Writeable for Event {
 			&Event::PaymentClaimable {
 				ref payment_hash,
 				ref amount_msat,
+				dummy_hops_skimmed_fee_msat,
 				counterparty_skimmed_fee_msat,
 				ref purpose,
 				ref receiver_node_id,
@@ -1938,6 +1951,11 @@ impl Writeable for Event {
 				} else {
 					Some(counterparty_skimmed_fee_msat)
 				};
+				let dummy_skimmed_fee_opt = if dummy_hops_skimmed_fee_msat == 0 {
+					None
+				} else {
+					Some(dummy_hops_skimmed_fee_msat)
+				};
 
 				let (receiving_channel_id_legacy, receiving_user_channel_id_legacy) =
 					match receiving_channel_ids.last() {
@@ -1964,6 +1982,7 @@ impl Writeable for Event {
 					(11, payment_context, option),
 					(13, payment_id, option),
 					(15, *receiving_channel_ids, optional_vec),
+					(17, dummy_skimmed_fee_opt, option),
 				});
 			},
 			&Event::PaymentSent {
@@ -2189,6 +2208,7 @@ impl Writeable for Event {
 			&Event::PaymentClaimed {
 				ref payment_hash,
 				ref amount_msat,
+				dummy_hops_skimmed_fee_msat,
 				ref purpose,
 				ref receiver_node_id,
 				ref htlcs,
@@ -2197,6 +2217,11 @@ impl Writeable for Event {
 				ref payment_id,
 			} => {
 				19u8.write(writer)?;
+				let dummy_skimmed_fee_opt = if dummy_hops_skimmed_fee_msat == 0 {
+					None
+				} else {
+					Some(dummy_hops_skimmed_fee_msat)
+				};
 				write_tlv_fields!(writer, {
 					(0, payment_hash, required),
 					(1, receiver_node_id, option),
@@ -2206,6 +2231,7 @@ impl Writeable for Event {
 					(7, sender_intended_total_msat, option),
 					(9, onion_fields, option),
 					(11, payment_id, option),
+					(13, dummy_skimmed_fee_opt, option),
 				});
 			},
 			&Event::ProbeSuccessful { ref payment_id, ref payment_hash, ref path } => {
@@ -2407,6 +2433,7 @@ impl MaybeReadable for Event {
 					let mut payment_preimage = None;
 					let mut payment_secret = None;
 					let mut amount_msat = 0;
+					let mut dummy_skimmed_fee_msat_opt = None;
 					let mut counterparty_skimmed_fee_msat_opt = None;
 					let mut receiver_node_id = None;
 					let mut _user_payment_id = None::<u64>; // Used in 0.0.103 and earlier, no longer written in 0.0.116+.
@@ -2432,6 +2459,7 @@ impl MaybeReadable for Event {
 						(11, payment_context, option),
 						(13, payment_id, option),
 						(15, receiving_channel_ids_opt, optional_vec),
+						(17, dummy_skimmed_fee_msat_opt, option),
 					});
 					let purpose = match payment_secret {
 						Some(secret) => {
@@ -2455,6 +2483,7 @@ impl MaybeReadable for Event {
 						receiver_node_id,
 						payment_hash,
 						amount_msat,
+						dummy_hops_skimmed_fee_msat: dummy_skimmed_fee_msat_opt.unwrap_or(0),
 						counterparty_skimmed_fee_msat: counterparty_skimmed_fee_msat_opt
 							.unwrap_or(0),
 						purpose,
@@ -2760,6 +2789,7 @@ impl MaybeReadable for Event {
 					let mut payment_hash = PaymentHash([0; 32]);
 					let mut purpose = UpgradableRequired(None);
 					let mut amount_msat = 0;
+					let mut dummy_hops_skimmed_fee_msat_opt = None;
 					let mut receiver_node_id = None;
 					let mut htlcs: Option<Vec<ClaimedHTLC>> = Some(vec![]);
 					let mut sender_intended_total_msat: Option<u64> = None;
@@ -2775,12 +2805,14 @@ impl MaybeReadable for Event {
 						(9, onion_fields, (option: ReadableArgs,
 							sender_intended_total_msat.unwrap_or(amount_msat))),
 						(11, payment_id, option),
+						(13, dummy_hops_skimmed_fee_msat_opt, option),
 					});
 					Ok(Some(Event::PaymentClaimed {
 						receiver_node_id,
 						payment_hash,
 						purpose: _init_tlv_based_struct_field!(purpose, upgradable_required),
 						amount_msat,
+						dummy_hops_skimmed_fee_msat: dummy_hops_skimmed_fee_msat_opt.unwrap_or(0),
 						htlcs: htlcs.unwrap_or_default(),
 						sender_intended_total_msat,
 						onion_fields,

lightning/src/ln/blinded_payment_tests.rs

@@ -1586,6 +1586,7 @@ fn update_add_msg(
 		cltv_expiry,
 		payment_hash: PaymentHash([0; 32]),
 		onion_routing_packet,
+		dummy_hops_skimmed_fee_msat: None,
 		skimmed_fee_msat: None,
 		blinding_point,
 		hold_htlc: None,