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

@@ -346,6 +346,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,
 	/// This blinded payment data is for the receiving node.
 	Receive(ReceiveTlvs),
 }
@@ -363,6 +365,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,
 	Receive(&'a ReceiveTlvs),
 }
 
@@ -532,6 +535,11 @@ 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 => {
+				encode_tlv_stream!(w, {
+					(65539, (), required),
+				})
+			},
 			Self::Receive(tlvs) => tlvs.write(w)?,
 		}
 		Ok(())
@@ -548,32 +556,48 @@ 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),
+			_ => return Err(DecodeError::InvalidValue),
 		}
 	}
 }

lightning/src/ln/channelmanager.rs

@@ -5089,6 +5089,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

@@ -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,17 @@ where
 						next_blinding_override,
 					}))
 				},
+				ChaChaDualPolyReadAdapter { readable: BlindedPaymentTlvs::Dummy, 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, "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",
@@ -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, "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

@@ -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 {
+		/// Blinding point for introduction-node dummy hops.
+		intro_node_blinding_point: Option<PublicKey>,
+		/// 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 {
@@ -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,