Introduce PaymentDummyTlv

PaymentDummyTlv is an empty TLV inserted immediately before the
actual ReceiveTlvs in a blinded path. Receivers treat these dummy
hops as real hops, which prevents timing-based attacks.

Allowing arbitrary dummy hops before the final ReceiveTlvs obscures
the recipient's true position in the route and makes it harder for
an onlooker to infer the destination, strengthening recipient privacy.

Author: shaavan

lightning/src/blinded_path/payment.rs

@@ -328,6 +328,15 @@ pub struct TrampolineForwardTlvs {
 	pub next_blinding_override: Option<PublicKey>,
 }
 
+/// Represents the dummy TLV encoded immediately before the actual [`ReceiveTlvs`] in a blinded path.
+/// These TLVs are intended for the final node and are recursively authenticated until the real
+/// [`ReceiveTlvs`] is reached.
+///
+/// Their purpose is to arbitrarily extend the path length, obscuring the receiver's position in the
+/// route and thereby enhancing privacy.
+#[derive(Debug)]
+pub(crate) struct PaymentDummyTlv;
+
 /// Data to construct a [`BlindedHop`] for receiving a payment. This payload is custom to LDK and
 /// may not be valid if received by another lightning implementation.
 #[derive(Clone, Debug)]
@@ -346,6 +355,8 @@ pub struct ReceiveTlvs {
 pub(crate) enum BlindedPaymentTlvs {
 	/// This blinded payment data is for a forwarding node.
 	Forward(ForwardTlvs),
+	/// This blinded payment data is dummy and is to be peeled by receiving node.
+	Dummy(PaymentDummyTlv),
 	/// This blinded payment data is for the receiving node.
 	Receive(ReceiveTlvs),
 }
@@ -363,6 +374,7 @@ pub(crate) enum BlindedTrampolineTlvs {
 // Used to include forward and receive TLVs in the same iterator for encoding.
 enum BlindedPaymentTlvsRef<'a> {
 	Forward(&'a ForwardTlvs),
+	Dummy(&'a PaymentDummyTlv),
 	Receive(&'a ReceiveTlvs),
 }
 
@@ -512,6 +524,15 @@ impl Writeable for TrampolineForwardTlvs {
 	}
 }
 
+impl Writeable for PaymentDummyTlv {
+	fn write<W: Writer>(&self, writer: &mut W) -> Result<(), io::Error> {
+		encode_tlv_stream!(writer, {
+			(65539, (), required),
+		});
+		Ok(())
+	}
+}
+
 // Note: The `authentication` TLV field was removed in LDK v0.3 following
 // the introduction of `ReceiveAuthKey`-based authentication for inbound
 // `BlindedPaymentPaths`s. Because we do not support receiving to those
@@ -532,6 +553,7 @@ impl<'a> Writeable for BlindedPaymentTlvsRef<'a> {
 	fn write<W: Writer>(&self, w: &mut W) -> Result<(), io::Error> {
 		match self {
 			Self::Forward(tlvs) => tlvs.write(w)?,
+			Self::Dummy(tlv) => tlv.write(w)?,
 			Self::Receive(tlvs) => tlvs.write(w)?,
 		}
 		Ok(())
@@ -548,32 +570,50 @@ impl Readable for BlindedPaymentTlvs {
 			(2, scid, option),
 			(8, next_blinding_override, option),
 			(10, payment_relay, option),
-			(12, payment_constraints, required),
+			(12, payment_constraints, option),
 			(14, features, (option, encoding: (BlindedHopFeatures, WithoutLength))),
 			(65536, payment_secret, option),
 			(65537, payment_context, option),
+			(65539, is_dummy, option)
 		});
 
-		if let Some(short_channel_id) = scid {
-			if payment_secret.is_some() {
-				return Err(DecodeError::InvalidValue);
-			}
-			Ok(BlindedPaymentTlvs::Forward(ForwardTlvs {
+		match (
+			scid,
+			next_blinding_override,
+			payment_relay,
+			payment_constraints,
+			features,
+			payment_secret,
+			payment_context,
+			is_dummy,
+		) {
+			(
+				Some(short_channel_id),
+				next_override,
+				Some(relay),
+				Some(constraints),
+				features,
+				None,
+				None,
+				None,
+			) => Ok(BlindedPaymentTlvs::Forward(ForwardTlvs {
 				short_channel_id,
-				payment_relay: payment_relay.ok_or(DecodeError::InvalidValue)?,
-				payment_constraints: payment_constraints.0.unwrap(),
-				next_blinding_override,
+				payment_relay: relay,
+				payment_constraints: constraints,
+				next_blinding_override: next_override,
 				features: features.unwrap_or_else(BlindedHopFeatures::empty),
-			}))
-		} else {
-			if payment_relay.is_some() || features.is_some() {
-				return Err(DecodeError::InvalidValue);
-			}
-			Ok(BlindedPaymentTlvs::Receive(ReceiveTlvs {
-				payment_secret: payment_secret.ok_or(DecodeError::InvalidValue)?,
-				payment_constraints: payment_constraints.0.unwrap(),
-				payment_context: payment_context.ok_or(DecodeError::InvalidValue)?,
-			}))
+			})),
+			(None, None, None, Some(constraints), None, Some(secret), Some(context), None) => {
+				Ok(BlindedPaymentTlvs::Receive(ReceiveTlvs {
+					payment_secret: secret,
+					payment_constraints: constraints,
+					payment_context: context,
+				}))
+			},
+			(None, None, None, None, None, None, None, Some(())) => {
+				Ok(BlindedPaymentTlvs::Dummy(PaymentDummyTlv))
+			},
+			_ => return Err(DecodeError::InvalidValue),
 		}
 	}
 }

lightning/src/ln/channelmanager.rs

@@ -5089,6 +5089,14 @@ where
 			onion_utils::Hop::Forward { .. } | onion_utils::Hop::BlindedForward { .. } => {
 				create_fwd_pending_htlc_info(msg, decoded_hop, shared_secret, next_packet_pubkey_opt)
 			},
+			onion_utils::Hop::Dummy { .. } => {
+				debug_assert!(false, "Shouldn't be triggered.");
+				return Err(InboundHTLCErr {
+					msg: "Failed to decode update add htlc onion",
+					reason: LocalHTLCFailureReason::InvalidOnionPayload,
+					err_data: Vec::new(),
+				})
+			},
 			onion_utils::Hop::TrampolineForward { .. } | onion_utils::Hop::TrampolineBlindedForward { .. } => {
 				create_fwd_pending_htlc_info(msg, decoded_hop, shared_secret, next_packet_pubkey_opt)
 			},

lightning/src/ln/msgs.rs

@@ -2355,6 +2355,7 @@ mod fuzzy_internal_msgs {
 		Receive(InboundOnionReceivePayload),
 		BlindedForward(InboundOnionBlindedForwardPayload),
 		BlindedReceive(InboundOnionBlindedReceivePayload),
+		Dummy { intro_node_blinding_point: Option<PublicKey> },
 	}
 
 	pub struct InboundTrampolineForwardPayload {
@@ -3694,6 +3695,20 @@ where
 						next_blinding_override,
 					}))
 				},
+				ChaChaDualPolyReadAdapter {
+					readable: BlindedPaymentTlvs::Dummy(_dummy_tlv),
+					used_aad,
+				} => {
+					if amt.is_some()
+						|| cltv_value.is_some() || total_msat.is_some()
+						|| keysend_preimage.is_some()
+						|| invoice_request.is_some()
+						|| !used_aad
+					{
+						return Err(DecodeError::InvalidValue);
+					}
+					Ok(Self::Dummy { intro_node_blinding_point })
+				},
 				ChaChaDualPolyReadAdapter {
 					readable: BlindedPaymentTlvs::Receive(receive_tlvs),
 					used_aad,

lightning/src/ln/onion_payment.rs

@@ -123,6 +123,14 @@ pub(super) fn create_fwd_pending_htlc_info(
 			(RoutingInfo::Direct { short_channel_id, new_packet_bytes, next_hop_hmac }, amt_to_forward, outgoing_cltv_value, intro_node_blinding_point,
 				next_blinding_override)
 		},
+		onion_utils::Hop::Dummy { .. } => {
+			debug_assert!(false, "This case shall not be triggered");
+			return Err(InboundHTLCErr {
+				msg: "Dummy Hop OnionHopData provided for us as an intermediary node",
+				reason: LocalHTLCFailureReason::InvalidOnionPayload,
+				err_data: Vec::new(),
+			})
+		},
 		onion_utils::Hop::Receive { .. } | onion_utils::Hop::BlindedReceive { .. } =>
 			return Err(InboundHTLCErr {
 				msg: "Final Node OnionHopData provided for us as an intermediary node",
@@ -327,6 +335,14 @@ pub(super) fn create_recv_pending_htlc_info(
 				msg: "Got blinded non final data with an HMAC of 0",
 			})
 		},
+		onion_utils::Hop::Dummy { .. } => {
+			debug_assert!(false, "This case shall not be triggered.");
+			return Err(InboundHTLCErr {
+				reason: LocalHTLCFailureReason::InvalidOnionBlinding,
+				err_data: vec![0; 32],
+				msg: "Got blinded non final data with an HMAC of 0",
+			})
+		}
 		onion_utils::Hop::TrampolineForward { .. } | onion_utils::Hop::TrampolineBlindedForward { .. } => {
 			return Err(InboundHTLCErr {
 				reason: LocalHTLCFailureReason::InvalidOnionPayload,

lightning/src/ln/onion_utils.rs

@@ -2202,6 +2202,17 @@ pub(crate) enum Hop {
 		/// Bytes of the onion packet we're forwarding.
 		new_packet_bytes: [u8; ONION_DATA_LEN],
 	},
+	/// This onion payload is dummy, and needs to be peeled by us.
+	Dummy {
+		/// Onion payload data used in interpreting the dummy hop
+		intro_node_blinding_point: Option<PublicKey>,
+		/// Shared secret that was used to decrypt next_hop_data.
+		shared_secret: SharedSecret,
+		/// HMAC of the next hop's onion packet.
+		next_hop_hmac: [u8; 32],
+		/// Bytes of the onion packet we're forwarding.
+		new_packet_bytes: [u8; ONION_DATA_LEN],
+	},
 	/// This onion payload was for us, not for forwarding to a next-hop. Contains information for
 	/// verifying the incoming payment.
 	Receive {
@@ -2256,6 +2267,7 @@ impl Hop {
 		match self {
 			Hop::Forward { shared_secret, .. } => shared_secret,
 			Hop::BlindedForward { shared_secret, .. } => shared_secret,
+			Hop::Dummy { shared_secret, .. } => shared_secret,
 			Hop::TrampolineForward { outer_shared_secret, .. } => outer_shared_secret,
 			Hop::TrampolineBlindedForward { outer_shared_secret, .. } => outer_shared_secret,
 			Hop::Receive { shared_secret, .. } => shared_secret,