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;
@@ -121,6 +122,32 @@ impl BlindedPaymentPath {
 		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,
+	{
+		BlindedPaymentPath::new_with_dummy_hops(
+			intermediate_nodes,
+			payee_node_id,
+			0,
+			local_node_receive_key,
+			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.
+	///
+	/// 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,
 	{
@@ -145,6 +172,7 @@ impl BlindedPaymentPath {
 					secp_ctx,
 					intermediate_nodes,
 					payee_node_id,
+					dummy_hop_count,
 					payee_tlvs,
 					&blinding_secret,
 					local_node_receive_key,
@@ -363,6 +391,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,
@@ -644,22 +673,48 @@ 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_hop_count: usize, payee_tlvs: ReceiveTlvs, session_priv: &SecretKey,
+	local_node_receive_key: ReceiveAuthKey,
 ) -> Vec<BlindedHop> {
+	let dummy_count = core::cmp::min(dummy_hop_count, MAX_DUMMY_HOPS_COUNT);
 	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).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 }),
 	);
 
-	utils::construct_blinded_hops(secp_ctx, path, session_priv)
+	// 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.into_iter(), session_priv)
 }
 
 /// `None` if underflow occurs.