Introduce Dummy Hop support in Blinded Path Constructor

Adds a new constructor for blinded paths that allows specifying
the number of dummy hops.
This enables users to insert arbitrary hops before the real destination,
enhancing privacy by making it harder to infer the sender–receiver
distance or identify the final destination.

Lays the groundwork for future use of dummy hops in blinded path construction.

Author: shaavan

lightning/src/blinded_path/payment.rs

@@ -12,6 +12,7 @@
 use bitcoin::secp256k1::ecdh::SharedSecret;
 use bitcoin::secp256k1::{self, PublicKey, Secp256k1, SecretKey};
 
+use crate::blinded_path::message::MAX_DUMMY_HOPS_COUNT;
 use crate::blinded_path::utils::{self, BlindedPathWithPadding};
 use crate::blinded_path::{BlindedHop, BlindedPath, IntroductionNode, NodeIdLookUp};
 use crate::crypto::streams::ChaChaDualPolyReadAdapter;
@@ -124,6 +125,74 @@ impl BlindedPaymentPath {
 	where
 		ES::Target: EntropySource,
 	{
+		BlindedPaymentPath::new_inner(
+			intermediate_nodes,
+			payee_node_id,
+			local_node_receive_key,
+			0,
+			None,
+			payee_tlvs,
+			htlc_maximum_msat,
+			min_final_cltv_expiry_delta,
+			entropy_source,
+			secp_ctx,
+		)
+	}
+
+	/// Same as [`BlindedPaymentPath::new`], but allows specifying a number of dummy hops.
+	///
+	/// Dummy TLVs allow callers to override the payment relay values used for dummy hops.
+	/// Any additional fees introduced by these dummy hops are ultimately paid to the final
+	/// recipient as part of the total amount.
+	///
+	/// This improves privacy by making path-length analysis based on fee and CLTV delta
+	/// values less reliable.
+	///
+	/// Note:
+	/// At most [`MAX_DUMMY_HOPS_COUNT`] dummy hops can be added to the blinded path.
+	pub fn new_with_dummy_hops<ES: Deref, T: secp256k1::Signing + secp256k1::Verification>(
+		intermediate_nodes: &[PaymentForwardNode], payee_node_id: PublicKey,
+		dummy_hop_count: usize, local_node_receive_key: ReceiveAuthKey, payee_tlvs: ReceiveTlvs,
+		htlc_maximum_msat: u64, min_final_cltv_expiry_delta: u16, entropy_source: ES,
+		secp_ctx: &Secp256k1<T>,
+	) -> Result<Self, ()>
+	where
+		ES::Target: EntropySource,
+	{
+		// TODO: Expose DummyTlvs in the public API instead of always using defaults.
+		let dummy_tlvs = DummyTlvs::default();
+
+		BlindedPaymentPath::new_inner(
+			intermediate_nodes,
+			payee_node_id,
+			local_node_receive_key,
+			dummy_hop_count,
+			Some(dummy_tlvs),
+			payee_tlvs,
+			htlc_maximum_msat,
+			min_final_cltv_expiry_delta,
+			entropy_source,
+			secp_ctx,
+		)
+	}
+
+	fn new_inner<ES: Deref, T: secp256k1::Signing + secp256k1::Verification>(
+		intermediate_nodes: &[PaymentForwardNode], payee_node_id: PublicKey,
+		local_node_receive_key: ReceiveAuthKey, dummy_hop_count: usize,
+		dummy_tlvs_opt: Option<DummyTlvs>, payee_tlvs: ReceiveTlvs, htlc_maximum_msat: u64,
+		min_final_cltv_expiry_delta: u16, entropy_source: ES, secp_ctx: &Secp256k1<T>,
+	) -> Result<Self, ()>
+	where
+		ES::Target: EntropySource,
+	{
+		debug_assert!(
+			(dummy_hop_count > 0) == dummy_tlvs_opt.is_some(),
+			"dummy_hop_count and dummy_tlvs must either both be present or both be absent"
+		);
+
+		let dummy_count = core::cmp::min(dummy_hop_count, MAX_DUMMY_HOPS_COUNT);
+		let dummy_tlvs = dummy_tlvs_opt.unwrap_or_default();
+
 		let introduction_node = IntroductionNode::NodeId(
 			intermediate_nodes.first().map_or(payee_node_id, |n| n.node_id),
 		);
@@ -133,10 +202,13 @@ impl BlindedPaymentPath {
 
 		let blinded_payinfo = compute_payinfo(
 			intermediate_nodes,
+			dummy_count,
+			&dummy_tlvs,
 			&payee_tlvs,
 			htlc_maximum_msat,
 			min_final_cltv_expiry_delta,
 		)?;
+
 		Ok(Self {
 			inner_path: BlindedPath {
 				introduction_node,
@@ -145,6 +217,8 @@ impl BlindedPaymentPath {
 					secp_ctx,
 					intermediate_nodes,
 					payee_node_id,
+					dummy_count,
+					dummy_tlvs,
 					payee_tlvs,
 					&blinding_secret,
 					local_node_receive_key,
@@ -393,6 +467,7 @@ pub(crate) enum BlindedTrampolineTlvs {
 }
 
 // Used to include forward and receive TLVs in the same iterator for encoding.
+#[derive(Clone)]
 enum BlindedPaymentTlvsRef<'a> {
 	Forward(&'a ForwardTlvs),
 	Dummy(&'a DummyTlvs),
@@ -678,21 +753,46 @@ pub(crate) const PAYMENT_PADDING_ROUND_OFF: usize = 30;
 /// Construct blinded payment hops for the given `intermediate_nodes` and payee info.
 pub(super) fn blinded_hops<T: secp256k1::Signing + secp256k1::Verification>(
 	secp_ctx: &Secp256k1<T>, intermediate_nodes: &[PaymentForwardNode], payee_node_id: PublicKey,
-	payee_tlvs: ReceiveTlvs, session_priv: &SecretKey, local_node_receive_key: ReceiveAuthKey,
+	dummy_count: usize, dummy_tlvs: DummyTlvs, payee_tlvs: ReceiveTlvs, session_priv: &SecretKey,
+	local_node_receive_key: ReceiveAuthKey,
 ) -> Vec<BlindedHop> {
 	let pks = intermediate_nodes
 		.iter()
 		.map(|node| (node.node_id, None))
+		.chain(core::iter::repeat((payee_node_id, Some(local_node_receive_key))).take(dummy_count))
 		.chain(core::iter::once((payee_node_id, Some(local_node_receive_key))));
 	let tlvs = intermediate_nodes
 		.iter()
 		.map(|node| BlindedPaymentTlvsRef::Forward(&node.tlvs))
+		.chain(core::iter::repeat(BlindedPaymentTlvsRef::Dummy(&dummy_tlvs)).take(dummy_count))
 		.chain(core::iter::once(BlindedPaymentTlvsRef::Receive(&payee_tlvs)));
 
 	let path = pks.zip(
 		tlvs.map(|tlv| BlindedPathWithPadding { tlvs: tlv, round_off: PAYMENT_PADDING_ROUND_OFF }),
 	);
 
+	// Debug invariant: all non-final hops must have identical serialized size.
+	#[cfg(debug_assertions)]
+	{
+		let mut iter = path.clone();
+		if let Some((_, first)) = iter.next() {
+			let remaining = iter.clone().count(); // includes intermediate + final
+
+			// At least one intermediate hop
+			if remaining > 1 {
+				let expected = first.serialized_length();
+
+				// skip final hop: take(remaining - 1)
+				for (_, hop) in iter.take(remaining - 1) {
+					debug_assert!(
+						hop.serialized_length() == expected,
+						"All intermediate blinded hops must have identical serialized size"
+					);
+				}
+			}
+		}
+	}
+
 	utils::construct_blinded_hops(secp_ctx, path, session_priv)
 }
 
@@ -752,14 +852,24 @@ where
 }
 
 pub(super) fn compute_payinfo(
-	intermediate_nodes: &[PaymentForwardNode], payee_tlvs: &ReceiveTlvs,
-	payee_htlc_maximum_msat: u64, min_final_cltv_expiry_delta: u16,
+	intermediate_nodes: &[PaymentForwardNode], dummy_count: usize, dummy_tlvs: &DummyTlvs,
+	payee_tlvs: &ReceiveTlvs, payee_htlc_maximum_msat: u64, min_final_cltv_expiry_delta: u16,
 ) -> Result<BlindedPayInfo, ()> {
-	let (aggregated_base_fee, aggregated_prop_fee) =
-		compute_aggregated_base_prop_fee(intermediate_nodes.iter().map(|node| RoutingFees {
+	let dummy_tlvs_iter = core::iter::repeat(dummy_tlvs).take(dummy_count);
+
+	let routing_fees = intermediate_nodes
+		.iter()
+		.map(|node| RoutingFees {
 			base_msat: node.tlvs.payment_relay.fee_base_msat,
 			proportional_millionths: node.tlvs.payment_relay.fee_proportional_millionths,
-		}))?;
+		})
+		.chain(dummy_tlvs_iter.clone().map(|tlvs| RoutingFees {
+			base_msat: tlvs.payment_relay.fee_base_msat,
+			proportional_millionths: tlvs.payment_relay.fee_proportional_millionths,
+		}));
+
+	let (aggregated_base_fee, aggregated_prop_fee) =
+		compute_aggregated_base_prop_fee(routing_fees)?;
 
 	let mut htlc_minimum_msat: u64 = 1;
 	let mut htlc_maximum_msat: u64 = 21_000_000 * 100_000_000 * 1_000; // Total bitcoin supply
@@ -788,6 +898,16 @@ pub(super) fn compute_payinfo(
 		)
 		.ok_or(())?; // If underflow occurs, we cannot send to this hop without exceeding their max
 	}
+	for dummy_tlvs in dummy_tlvs_iter {
+		cltv_expiry_delta =
+			cltv_expiry_delta.checked_add(dummy_tlvs.payment_relay.cltv_expiry_delta).ok_or(())?;
+
+		htlc_minimum_msat = amt_to_forward_msat(
+			core::cmp::max(dummy_tlvs.payment_constraints.htlc_minimum_msat, htlc_minimum_msat),
+			&dummy_tlvs.payment_relay,
+		)
+		.unwrap_or(1); // If underflow occurs, we definitely reached this node's min
+	}
 	htlc_minimum_msat =
 		core::cmp::max(payee_tlvs.payment_constraints.htlc_minimum_msat, htlc_minimum_msat);
 	htlc_maximum_msat = core::cmp::min(payee_htlc_maximum_msat, htlc_maximum_msat);
@@ -874,8 +994,8 @@ impl_writeable_tlv_based!(Bolt12RefundContext, {});
 #[cfg(test)]
 mod tests {
 	use crate::blinded_path::payment::{
-		Bolt12RefundContext, ForwardTlvs, PaymentConstraints, PaymentContext, PaymentForwardNode,
-		PaymentRelay, ReceiveTlvs,
+		Bolt12RefundContext, DummyTlvs, ForwardTlvs, PaymentConstraints, PaymentContext,
+		PaymentForwardNode, PaymentRelay, ReceiveTlvs,
 	};
 	use crate::ln::functional_test_utils::TEST_FINAL_CLTV;
 	use crate::types::features::BlindedHopFeatures;
@@ -931,9 +1051,15 @@ mod tests {
 			payment_context: PaymentContext::Bolt12Refund(Bolt12RefundContext {}),
 		};
 		let htlc_maximum_msat = 100_000;
-		let blinded_payinfo =
-			super::compute_payinfo(&intermediate_nodes[..], &recv_tlvs, htlc_maximum_msat, 12)
-				.unwrap();
+		let blinded_payinfo = super::compute_payinfo(
+			&intermediate_nodes[..],
+			0,
+			&DummyTlvs::default(),
+			&recv_tlvs,
+			htlc_maximum_msat,
+			12,
+		)
+		.unwrap();
 		assert_eq!(blinded_payinfo.fee_base_msat, 201);
 		assert_eq!(blinded_payinfo.fee_proportional_millionths, 1001);
 		assert_eq!(blinded_payinfo.cltv_expiry_delta, 300);
@@ -948,8 +1074,15 @@ mod tests {
 			payment_constraints: PaymentConstraints { max_cltv_expiry: 0, htlc_minimum_msat: 1 },
 			payment_context: PaymentContext::Bolt12Refund(Bolt12RefundContext {}),
 		};
-		let blinded_payinfo =
-			super::compute_payinfo(&[], &recv_tlvs, 4242, TEST_FINAL_CLTV as u16).unwrap();
+		let blinded_payinfo = super::compute_payinfo(
+			&[],
+			0,
+			&DummyTlvs::default(),
+			&recv_tlvs,
+			4242,
+			TEST_FINAL_CLTV as u16,
+		)
+		.unwrap();
 		assert_eq!(blinded_payinfo.fee_base_msat, 0);
 		assert_eq!(blinded_payinfo.fee_proportional_millionths, 0);
 		assert_eq!(blinded_payinfo.cltv_expiry_delta, TEST_FINAL_CLTV as u16);
@@ -1008,6 +1141,8 @@ mod tests {
 		let htlc_maximum_msat = 100_000;
 		let blinded_payinfo = super::compute_payinfo(
 			&intermediate_nodes[..],
+			0,
+			&DummyTlvs::default(),
 			&recv_tlvs,
 			htlc_maximum_msat,
 			TEST_FINAL_CLTV as u16,
@@ -1067,6 +1202,8 @@ mod tests {
 		let htlc_minimum_msat = 3798;
 		assert!(super::compute_payinfo(
 			&intermediate_nodes[..],
+			0,
+			&DummyTlvs::default(),
 			&recv_tlvs,
 			htlc_minimum_msat - 1,
 			TEST_FINAL_CLTV as u16
@@ -1076,6 +1213,8 @@ mod tests {
 		let htlc_maximum_msat = htlc_minimum_msat + 1;
 		let blinded_payinfo = super::compute_payinfo(
 			&intermediate_nodes[..],
+			0,
+			&DummyTlvs::default(),
 			&recv_tlvs,
 			htlc_maximum_msat,
 			TEST_FINAL_CLTV as u16,
@@ -1136,6 +1275,8 @@ mod tests {
 
 		let blinded_payinfo = super::compute_payinfo(
 			&intermediate_nodes[..],
+			0,
+			&DummyTlvs::default(),
 			&recv_tlvs,
 			10_000,
 			TEST_FINAL_CLTV as u16,