Introduce Dummy BlindedPaymentTlv

Dummy BlindedPaymentTlvs 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,36 @@ pub struct TrampolineForwardTlvs {
 	pub next_blinding_override: Option<PublicKey>,
 }
 
+/// TLVs carried by a dummy hop within a blinded payment path.
+///
+/// Dummy hops do not correspond to real forwarding decisions, but are processed
+/// identically to real hops at the protocol level. The TLVs contained here define
+/// the relay requirements and constraints that must be satisfied for the payment
+/// to continue through this hop.
+///
+/// By enforcing realistic relay semantics on dummy hops, the payment path remains
+/// indistinguishable from a fully real route with respect to fees, CLTV deltas, and
+/// validation behavior.
+pub struct DummyTlvs {
+	/// Relay requirements (fees and CLTV delta) that must be satisfied when
+	/// processing this dummy hop.
+	pub payment_relay: PaymentRelay,
+	/// Constraints that apply to the payment when relaying over this dummy hop.
+	pub payment_constraints: PaymentConstraints,
+}
+
+impl Default for DummyTlvs {
+	fn default() -> Self {
+		let payment_relay =
+			PaymentRelay { cltv_expiry_delta: 0, fee_proportional_millionths: 0, fee_base_msat: 0 };
+
+		let payment_constraints =
+			PaymentConstraints { max_cltv_expiry: u32::MAX, htlc_minimum_msat: 0 };
+
+		Self { payment_relay, payment_constraints }
+	}
+}
+
 /// 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 +376,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(DummyTlvs),
 	/// This blinded payment data is for the receiving node.
 	Receive(ReceiveTlvs),
 }
@@ -363,6 +395,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 DummyTlvs),
 	Receive(&'a ReceiveTlvs),
 }
 
@@ -512,6 +545,17 @@ impl Writeable for TrampolineForwardTlvs {
 	}
 }
 
+impl Writeable for DummyTlvs {
+	fn write<W: Writer>(&self, w: &mut W) -> Result<(), io::Error> {
+		encode_tlv_stream!(w, {
+			(10, self.payment_relay, required),
+			(12, self.payment_constraints, required),
+			(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 +576,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(tlvs) => tlvs.write(w)?,
 			Self::Receive(tlvs) => tlvs.write(w)?,
 		}
 		Ok(())
@@ -552,28 +597,41 @@ impl Readable for BlindedPaymentTlvs {
 			(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 {
-				short_channel_id,
-				payment_relay: payment_relay.ok_or(DecodeError::InvalidValue)?,
-				payment_constraints: payment_constraints.0.unwrap(),
-				next_blinding_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)?,
-			}))
+		match (
+			scid,
+			next_blinding_override,
+			payment_relay,
+			features,
+			payment_secret,
+			payment_context,
+			is_dummy,
+		) {
+			(Some(short_channel_id), next_override, Some(relay), features, None, None, None) => {
+				Ok(BlindedPaymentTlvs::Forward(ForwardTlvs {
+					short_channel_id,
+					payment_relay: relay,
+					payment_constraints: payment_constraints.0.unwrap(),
+					next_blinding_override: next_override,
+					features: features.unwrap_or_else(BlindedHopFeatures::empty),
+				}))
+			},
+			(None, None, None, None, Some(secret), Some(context), None) => {
+				Ok(BlindedPaymentTlvs::Receive(ReceiveTlvs {
+					payment_secret: secret,
+					payment_constraints: payment_constraints.0.unwrap(),
+					payment_context: context,
+				}))
+			},
+			(None, None, Some(relay), None, None, None, Some(())) => {
+				Ok(BlindedPaymentTlvs::Dummy(DummyTlvs {
+					payment_relay: relay,
+					payment_constraints: payment_constraints.0.unwrap(),
+				}))
+			},
+			_ => return Err(DecodeError::InvalidValue),
 		}
 	}
 }

lightning/src/ln/channelmanager.rs

@@ -5105,6 +5105,20 @@ 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,
+					"Reached unreachable dummy-hop HTLC. Dummy hops are peeled in \
+					`process_pending_update_add_htlcs`, and the resulting HTLC is \
+					re-enqueued for processing. Hitting this means the peel-and-requeue \
+					step was missed."
+				);
+				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

@@ -32,7 +32,7 @@ use bitcoin::secp256k1::PublicKey;
 use bitcoin::{secp256k1, Transaction, Witness};
 
 use crate::blinded_path::message::BlindedMessagePath;
-use crate::blinded_path::payment::{BlindedPaymentTlvs, ForwardTlvs, ReceiveTlvs};
+use crate::blinded_path::payment::{BlindedPaymentTlvs, DummyTlvs, ForwardTlvs, ReceiveTlvs};
 use crate::blinded_path::payment::{BlindedTrampolineTlvs, TrampolineForwardTlvs};
 use crate::ln::onion_utils;
 use crate::ln::types::ChannelId;
@@ -2336,6 +2336,11 @@ mod fuzzy_internal_msgs {
 		pub intro_node_blinding_point: Option<PublicKey>,
 		pub next_blinding_override: Option<PublicKey>,
 	}
+	pub struct InboundOnionDummyPayload {
+		pub payment_relay: PaymentRelay,
+		pub payment_constraints: PaymentConstraints,
+		pub intro_node_blinding_point: Option<PublicKey>,
+	}
 	pub struct InboundOnionBlindedReceivePayload {
 		pub sender_intended_htlc_amt_msat: u64,
 		pub total_msat: u64,
@@ -2355,6 +2360,7 @@ mod fuzzy_internal_msgs {
 		Receive(InboundOnionReceivePayload),
 		BlindedForward(InboundOnionBlindedForwardPayload),
 		BlindedReceive(InboundOnionBlindedReceivePayload),
+		Dummy(InboundOnionDummyPayload),
 	}
 
 	pub struct InboundTrampolineForwardPayload {
@@ -3694,6 +3700,25 @@ where
 						next_blinding_override,
 					}))
 				},
+				ChaChaDualPolyReadAdapter {
+					readable:
+						BlindedPaymentTlvs::Dummy(DummyTlvs { payment_relay, payment_constraints }),
+					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(InboundOnionDummyPayload {
+						payment_relay,
+						payment_constraints,
+						intro_node_blinding_point,
+					}))
+				},
 				ChaChaDualPolyReadAdapter {
 					readable: BlindedPaymentTlvs::Receive(receive_tlvs),
 					used_aad,

lightning/src/ln/onion_payment.rs

@@ -149,6 +149,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, "Dummy hop should have been peeled earlier");
+			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",
@@ -364,6 +372,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, "Dummy hop should have been peeled earlier");
+			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

@@ -2223,6 +2223,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 {
+		/// Blinding point for introduction-node dummy hops.
+		dummy_hop_data: msgs::InboundOnionDummyPayload,
+		/// Shared secret for decrypting the next-hop public key.
+		shared_secret: SharedSecret,
+		/// HMAC of the next hop's onion packet.
+		next_hop_hmac: [u8; 32],
+		/// Onion packet bytes after this dummy layer is peeled.
+		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 {
@@ -2277,6 +2288,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,