Introduce Payment Dummy Hop parsing mechanism

shaavan · shaavan · commit ca438fb5ad77 · 2025-12-18T19:11:36.000+05:30
diff --git a/lightning/src/blinded_path/payment.rs b/lightning/src/blinded_path/payment.rs
@@ -34,7 +34,6 @@ use crate::util::ser::{
 	Writeable, Writer,
 };
 
-use core::mem;
 use core::ops::Deref;
 
 #[allow(unused_imports)]
@@ -219,28 +218,31 @@ impl BlindedPaymentPath {
 		NL::Target: NodeIdLookUp,
 		T: secp256k1::Signing + secp256k1::Verification,
 	{
-		match self.decrypt_intro_payload::<NS>(node_signer) {
-			Ok((
-				BlindedPaymentTlvs::Forward(ForwardTlvs { short_channel_id, .. }),
-				control_tlvs_ss,
-			)) => {
-				let next_node_id = match node_id_lookup.next_node_id(short_channel_id) {
-					Some(node_id) => node_id,
-					None => return Err(()),
-				};
-				let mut new_blinding_point = onion_utils::next_hop_pubkey(
-					secp_ctx,
-					self.inner_path.blinding_point,
-					control_tlvs_ss.as_ref(),
-				)
-				.map_err(|_| ())?;
-				mem::swap(&mut self.inner_path.blinding_point, &mut new_blinding_point);
-				self.inner_path.introduction_node = IntroductionNode::NodeId(next_node_id);
-				self.inner_path.blinded_hops.remove(0);
-				Ok(())
-			},
-			_ => Err(()),
-		}
+		let (next_node_id, control_tlvs_ss) =
+			match self.decrypt_intro_payload::<NS>(node_signer).map_err(|_| ())? {
+				(BlindedPaymentTlvs::Forward(ForwardTlvs { short_channel_id, .. }), ss) => {
+					let node_id = node_id_lookup.next_node_id(short_channel_id).ok_or(())?;
+					(node_id, ss)
+				},
+				(BlindedPaymentTlvs::Dummy, ss) => {
+					let node_id = node_signer.get_node_id(Recipient::Node)?;
+					(node_id, ss)
+				},
+				_ => return Err(()),
+			};
+
+		let new_blinding_point = onion_utils::next_hop_pubkey(
+			secp_ctx,
+			self.inner_path.blinding_point,
+			control_tlvs_ss.as_ref(),
+		)
+		.map_err(|_| ())?;
+
+		self.inner_path.blinding_point = new_blinding_point;
+		self.inner_path.introduction_node = IntroductionNode::NodeId(next_node_id);
+		self.inner_path.blinded_hops.remove(0);
+
+		Ok(())
 	}
 
 	pub(crate) fn decrypt_intro_payload<NS: Deref>(
@@ -262,9 +264,9 @@ impl BlindedPaymentPath {
 				.map_err(|_| ())?;
 
 		match (&readable, used_aad) {
-			(BlindedPaymentTlvs::Forward(_), false) | (BlindedPaymentTlvs::Receive(_), true) => {
-				Ok((readable, control_tlvs_ss))
-			},
+			(BlindedPaymentTlvs::Forward(_), false)
+			| (BlindedPaymentTlvs::Dummy, true)
+			| (BlindedPaymentTlvs::Receive(_), true) => Ok((readable, control_tlvs_ss)),
 			_ => Err(()),
 		}
 	}
diff --git a/lightning/src/ln/channelmanager.rs b/lightning/src/ln/channelmanager.rs
@@ -66,7 +66,7 @@ use crate::ln::channel_state::ChannelDetails;
 use crate::ln::funding::SpliceContribution;
 use crate::ln::inbound_payment;
 use crate::ln::interactivetxs::InteractiveTxMessageSend;
-use crate::ln::msgs;
+use crate::ln::msgs::{self, OnionPacket, UpdateAddHTLC};
 use crate::ln::msgs::{
 	BaseMessageHandler, ChannelMessageHandler, CommitmentUpdate, DecodeError, LightningError,
 	MessageSendEvent,
@@ -229,6 +229,22 @@ pub enum PendingHTLCRouting {
 		/// [`ReleaseHeldHtlc`] onion message.
 		hold_htlc: Option<()>,
 	},
+	/// A dummy HTLC hop which does not represent a real routing decision.
+	///
+	/// Dummy HTLCs are introduced to pad a blinded path. When such an HTLC is received, the dummy
+	/// layer is peeled, producing a new onion packet which must be processed again. This process
+	/// repeats until a non-dummy routing decision is reached, which is guaranteed to be
+	/// [`PendingHTLCRouting::Receive`].
+	Dummy {
+		/// The onion packet obtained after removing the dummy layer.
+		///
+		/// This packet must be re-processed as if it were freshly received.
+		onion_packet: msgs::OnionPacket,
+		/// Set if this HTLC is being forwarded within a blinded path.
+		blinded: Option<BlindedForward>,
+		/// The absolute CLTV of the inbound HTLC.
+		incoming_cltv_expiry: Option<u32>,
+	},
 	/// An HTLC which should be forwarded on to another Trampoline node.
 	TrampolineForward {
 		/// The onion shared secret we build with the sender (or the preceding Trampoline node) used
@@ -352,6 +368,7 @@ impl PendingHTLCRouting {
 	fn blinded_failure(&self) -> Option<BlindedFailure> {
 		match self {
 			Self::Forward { blinded: Some(BlindedForward { failure, .. }), .. } => Some(*failure),
+			Self::Dummy { blinded: Some(BlindedForward { failure, .. }), .. } => Some(*failure),
 			Self::TrampolineForward { blinded: Some(BlindedForward { failure, .. }), .. } => {
 				Some(*failure)
 			},
@@ -368,6 +385,7 @@ impl PendingHTLCRouting {
 	fn incoming_cltv_expiry(&self) -> Option<u32> {
 		match self {
 			Self::Forward { incoming_cltv_expiry, .. } => *incoming_cltv_expiry,
+			Self::Dummy { incoming_cltv_expiry, .. } => *incoming_cltv_expiry,
 			Self::TrampolineForward { incoming_cltv_expiry, .. } => Some(*incoming_cltv_expiry),
 			Self::Receive { incoming_cltv_expiry, .. } => Some(*incoming_cltv_expiry),
 			Self::ReceiveKeysend { incoming_cltv_expiry, .. } => Some(*incoming_cltv_expiry),
@@ -4974,6 +4992,11 @@ where
 	) -> Result<(), LocalHTLCFailureReason> {
 		let outgoing_scid = match next_packet_details.outgoing_connector {
 			HopConnector::ShortChannelId(scid) => scid,
+			HopConnector::Dummy => {
+				// Dummy hops are only used for path padding and must not reach HTLC processing.
+				debug_assert!(false, "Dummy hop reached HTLC handling.");
+				return Err(LocalHTLCFailureReason::InvalidOnionPayload);
+			}
 			HopConnector::Trampoline(_) => {
 				return Err(LocalHTLCFailureReason::InvalidTrampolineForward);
 			}
@@ -6878,6 +6901,7 @@ where
 	fn process_pending_update_add_htlcs(&self) -> bool {
 		let mut should_persist = false;
 		let mut decode_update_add_htlcs = new_hash_map();
+		let mut dummy_update_add_htlcs = new_hash_map();
 		mem::swap(&mut decode_update_add_htlcs, &mut self.decode_update_add_htlcs.lock().unwrap());
 
 		let get_htlc_failure_type = |outgoing_scid_opt: Option<u64>, payment_hash: PaymentHash| {
@@ -6941,7 +6965,68 @@ where
 						&*self.logger,
 						&self.secp_ctx,
 					) {
-						Ok(decoded_onion) => decoded_onion,
+						Ok(decoded_onion) => match decoded_onion {
+							(
+								onion_utils::Hop::Dummy {
+									intro_node_blinding_point,
+									next_hop_hmac,
+									new_packet_bytes,
+									..
+								},
+								Some(NextPacketDetails {
+									next_packet_pubkey,
+									outgoing_connector,
+									..
+								}),
+							) => {
+								debug_assert!(
+									matches!(outgoing_connector, HopConnector::Dummy),
+									"Dummy hop must always map to HopConnector::Dummy"
+								);
+
+								// Dummy hops are not forwarded. Instead, we reconstruct a new UpdateAddHTLC
+								// with the next onion packet (ephemeral pubkey, hop data, and HMAC) and push
+								// it back into our own processing queue. This lets us step through the dummy
+								// layers locally until we reach the next real hop.
+								let next_blinding_point = intro_node_blinding_point
+									.or(update_add_htlc.blinding_point)
+									.and_then(|blinding_point| {
+										let ss = self
+											.node_signer
+											.ecdh(Recipient::Node, &blinding_point, None)
+											.ok()?
+											.secret_bytes();
+
+										onion_utils::next_hop_pubkey(
+											&self.secp_ctx,
+											blinding_point,
+											&ss,
+										)
+										.ok()
+									});
+
+								let new_onion_packet = OnionPacket {
+									version: 0,
+									public_key: next_packet_pubkey,
+									hop_data: new_packet_bytes,
+									hmac: next_hop_hmac,
+								};
+
+								let new_update_add_htlc = UpdateAddHTLC {
+									onion_routing_packet: new_onion_packet,
+									blinding_point: next_blinding_point,
+									..update_add_htlc.clone()
+								};
+
+								dummy_update_add_htlcs
+									.entry(incoming_scid_alias)
+									.or_insert_with(Vec::new)
+									.push(new_update_add_htlc);
+
+								continue;
+							},
+							_ => decoded_onion,
+						},
 
 						Err((htlc_fail, reason)) => {
 							let failure_type = HTLCHandlingFailureType::InvalidOnion;
@@ -6954,6 +7039,13 @@ where
 				let outgoing_scid_opt =
 					next_packet_details_opt.as_ref().and_then(|d| match d.outgoing_connector {
 						HopConnector::ShortChannelId(scid) => Some(scid),
+						HopConnector::Dummy => {
+							debug_assert!(
+								false,
+								"Dummy hops must never be processed at this stage."
+							);
+							None
+						},
 						HopConnector::Trampoline(_) => None,
 					});
 				let shared_secret = next_hop.shared_secret().secret_bytes();
@@ -7097,6 +7189,19 @@ where
 				));
 			}
 		}
+
+		// Merge peeled dummy HTLCs into the existing decode queue so they can be
+		// processed in the next iteration. We avoid replacing the whole queue
+		// (e.g. via mem::swap) because other threads may have enqueued new HTLCs
+		// meanwhile; merging preserves everything safely.
+		if !dummy_update_add_htlcs.is_empty() {
+			let mut decode_update_add_htlc_source = self.decode_update_add_htlcs.lock().unwrap();
+
+			for (incoming_scid_alias, htlcs) in dummy_update_add_htlcs.into_iter() {
+				decode_update_add_htlc_source.entry(incoming_scid_alias).or_default().extend(htlcs);
+			}
+		}
+
 		should_persist
 	}
 
@@ -11419,6 +11524,13 @@ This indicates a bug inside LDK. Please report this error at https://github.com/
 				for (forward_info, prev_htlc_id) in pending_forwards.drain(..) {
 					let scid = match forward_info.routing {
 						PendingHTLCRouting::Forward { short_channel_id, .. } => short_channel_id,
+						PendingHTLCRouting::Dummy { .. } => {
+							debug_assert!(
+								false,
+								"Dummy hops must never be processed at this stage."
+							);
+							0
+						},
 						PendingHTLCRouting::TrampolineForward { .. } => 0,
 						PendingHTLCRouting::Receive { .. } => 0,
 						PendingHTLCRouting::ReceiveKeysend { .. } => 0,
@@ -15966,6 +16078,11 @@ impl_writeable_tlv_based_enum!(PendingHTLCRouting,
 		(4, blinded, option),
 		(6, node_id, required),
 		(8, incoming_cltv_expiry, required),
+	},
+	(4, Dummy) => {
+		(0, onion_packet, required),
+		(1, blinded, option),
+		(2, incoming_cltv_expiry, option),
 	}
 );
 
diff --git a/lightning/src/ln/onion_payment.rs b/lightning/src/ln/onion_payment.rs
@@ -106,6 +106,10 @@ enum RoutingInfo {
 		new_packet_bytes: [u8; ONION_DATA_LEN],
 		next_hop_hmac: [u8; 32],
 	},
+	Dummy {
+		new_packet_bytes: [u8; ONION_DATA_LEN],
+		next_hop_hmac: [u8; 32],
+	},
 	Trampoline {
 		next_trampoline: PublicKey,
 		// Trampoline onions are currently variable length
@@ -149,13 +153,8 @@ 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::Dummy { intro_node_blinding_point, next_hop_hmac, new_packet_bytes, .. } => {
+			(RoutingInfo::Dummy { new_packet_bytes, next_hop_hmac }, msg.amount_msat, msg.cltv_expiry, intro_node_blinding_point, None)
 		},
 		onion_utils::Hop::Receive { .. } | onion_utils::Hop::BlindedReceive { .. } =>
 			return Err(InboundHTLCErr {
@@ -234,7 +233,28 @@ pub(super) fn create_fwd_pending_htlc_info(
 							.unwrap_or(BlindedFailure::FromBlindedNode),
 					}),
 			}
-		}
+		},
+		RoutingInfo::Dummy { new_packet_bytes, next_hop_hmac } => {
+			let outgoing_packet = msgs::OnionPacket {
+				version: 0,
+				public_key: next_packet_pubkey_opt.unwrap_or(Err(secp256k1::Error::InvalidPublicKey)),
+				hop_data: new_packet_bytes,
+				hmac: next_hop_hmac,
+			};
+
+			PendingHTLCRouting::Dummy {
+				onion_packet: outgoing_packet,
+				incoming_cltv_expiry: Some(msg.cltv_expiry),
+				blinded: intro_node_blinding_point.or(msg.blinding_point)
+					.map(|bp| BlindedForward {
+						inbound_blinding_point: bp,
+						next_blinding_override: None,
+						failure: intro_node_blinding_point
+							.map(|_| BlindedFailure::FromIntroductionNode)
+							.unwrap_or(BlindedFailure::FromBlindedNode),
+					}),
+			}
+		},
 		RoutingInfo::Trampoline { next_trampoline, new_packet_bytes, next_hop_hmac, shared_secret, current_path_key } => {
 			let next_trampoline_packet_pubkey = match next_packet_pubkey_opt {
 				Some(Ok(pubkey)) => pubkey,
@@ -545,6 +565,8 @@ where
 pub(super) enum HopConnector {
 	// scid-based routing
 	ShortChannelId(u64),
+	// Dummy hop for path padding
+	Dummy,
 	// Trampoline-based routing
 	#[allow(unused)]
 	Trampoline(PublicKey),
@@ -648,7 +670,13 @@ where
 				next_packet_pubkey, outgoing_connector: HopConnector::ShortChannelId(short_channel_id), outgoing_amt_msat: amt_to_forward,
 				outgoing_cltv_value
 			})
-		}
+		},
+		onion_utils::Hop::Dummy { shared_secret, .. } => {
+			let next_packet_pubkey = onion_utils::next_hop_pubkey(secp_ctx,
+				msg.onion_routing_packet.public_key.unwrap(), &shared_secret.secret_bytes());
+
+			Some(NextPacketDetails { next_packet_pubkey, outgoing_connector: HopConnector::Dummy, outgoing_amt_msat: msg.amount_msat, outgoing_cltv_value: msg.cltv_expiry })
+		},
 		onion_utils::Hop::TrampolineForward { next_trampoline_hop_data: msgs::InboundTrampolineForwardPayload { amt_to_forward, outgoing_cltv_value, next_trampoline }, trampoline_shared_secret, incoming_trampoline_public_key, .. } => {
 			let next_trampoline_packet_pubkey = onion_utils::next_hop_pubkey(secp_ctx,
 				incoming_trampoline_public_key, &trampoline_shared_secret.secret_bytes());
diff --git a/lightning/src/ln/onion_utils.rs b/lightning/src/ln/onion_utils.rs
@@ -2356,6 +2356,12 @@ where
 						new_packet_bytes,
 					})
 				},
+				msgs::InboundOnionPayload::Dummy { intro_node_blinding_point } => Ok(Hop::Dummy {
+					intro_node_blinding_point,
+					shared_secret,
+					next_hop_hmac,
+					new_packet_bytes,
+				}),
 				_ => {
 					if blinding_point.is_some() {
 						return Err(OnionDecodeErr::Malformed {
