Introduce Payment Dummy Hop parsing mechanism

Author: shaavan

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)]
@@ -265,28 +264,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>(
@@ -308,9 +310,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(()),
 		}
 	}

lightning/src/ln/channelmanager.rs

@@ -229,6 +229,23 @@ 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 extend a blinded path without adding a real hop.
+	/// 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,
+		/// Forwarding context for this HTLC within a blinded path.
+		blinded: 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 +369,7 @@ impl PendingHTLCRouting {
 	fn blinded_failure(&self) -> Option<BlindedFailure> {
 		match self {
 			Self::Forward { blinded: Some(BlindedForward { failure, .. }), .. } => Some(*failure),
+			Self::Dummy { blinded: BlindedForward { failure, .. }, .. } => Some(*failure),
 			Self::TrampolineForward { blinded: Some(BlindedForward { failure, .. }), .. } => {
 				Some(*failure)
 			},
@@ -368,6 +386,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 +4993,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 +6902,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 +6966,36 @@ where
 						&*self.logger,
 						&self.secp_ctx,
 					) {
-						Ok(decoded_onion) => decoded_onion,
+						Ok(decoded_onion) => match decoded_onion {
+							(
+								onion_utils::Hop::Dummy {
+									dummy_hop_data,
+									next_hop_hmac,
+									new_packet_bytes,
+									..
+								},
+								Some(next_packet_details),
+							) => {
+								let new_update_add_htlc =
+									onion_utils::peel_dummy_hop_update_add_htlc(
+										update_add_htlc,
+										dummy_hop_data,
+										next_hop_hmac,
+										new_packet_bytes,
+										next_packet_details,
+										&*self.node_signer,
+										&self.secp_ctx,
+									);
+
+								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 +7008,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 +7158,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 +11493,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 +16047,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, required),
+		(2, incoming_cltv_expiry, option),
 	}
 );
 

lightning/src/ln/onion_payment.rs

@@ -74,6 +74,22 @@ fn check_blinded_forward(
 	Ok((amt_to_forward, outgoing_cltv_value))
 }
 
+#[rustfmt::skip]
+fn check_dummy_forward(
+	inbound_amt_msat: u64, inbound_cltv_expiry: u32, payment_relay: &PaymentRelay,
+	payment_constraints: &PaymentConstraints,
+) -> Result<(u64, u32), ()> {
+	let amt_to_forward = blinded_path::payment::amt_to_forward_msat(
+		inbound_amt_msat, payment_relay
+	).ok_or(())?;
+	let outgoing_cltv_value = inbound_cltv_expiry.checked_sub(
+		payment_relay.cltv_expiry_delta as u32
+	).ok_or(())?;
+	check_blinded_payment_constraints(inbound_amt_msat, outgoing_cltv_value, payment_constraints)?;
+
+	Ok((amt_to_forward, outgoing_cltv_value))
+}
+
 fn check_trampoline_payment_constraints(
 	outer_hop_data: &msgs::InboundTrampolineEntrypointPayload, trampoline_cltv_value: u32,
 	trampoline_amount: u64,
@@ -234,7 +250,7 @@ pub(super) fn create_fwd_pending_htlc_info(
 							.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,
@@ -494,7 +510,7 @@ where
 	L::Target: Logger,
 {
 	let (hop, next_packet_details_opt) =
-		decode_incoming_update_add_htlc_onion(msg, node_signer, logger, secp_ctx
+		decode_incoming_update_add_htlc_onion(msg, &*node_signer, &*logger, secp_ctx
 	).map_err(|(msg, failure_reason)| {
 		let (reason, err_data) = match msg {
 			HTLCFailureMsg::Malformed(_) => (failure_reason, Vec::new()),
@@ -532,6 +548,29 @@ where
 			// onion here and check it.
 			create_fwd_pending_htlc_info(msg, hop, shared_secret.secret_bytes(), Some(next_packet_pubkey))?
 		},
+		onion_utils::Hop::Dummy { dummy_hop_data, next_hop_hmac, new_packet_bytes, .. } => {
+			let next_packet_details = match next_packet_details_opt {
+				Some(next_packet_details) => next_packet_details,
+				// Dummy Hops should always include the next hop details
+				None => return Err(InboundHTLCErr {
+					msg: "Failed to decode update add htlc onion",
+					reason: LocalHTLCFailureReason::InvalidOnionPayload,
+					err_data: Vec::new(),
+				}),
+			};
+
+			let new_update_add_htlc = onion_utils::peel_dummy_hop_update_add_htlc(
+				msg,
+				dummy_hop_data,
+				next_hop_hmac,
+				new_packet_bytes,
+				next_packet_details,
+				&*node_signer,
+				secp_ctx
+			);
+
+			peel_payment_onion(&new_update_add_htlc, node_signer, logger, secp_ctx, cur_height, allow_skimmed_fees)?
+		},
 		_ => {
 			let shared_secret = hop.shared_secret().secret_bytes();
 			create_recv_pending_htlc_info(
@@ -545,6 +584,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 +689,23 @@ where
 				next_packet_pubkey, outgoing_connector: HopConnector::ShortChannelId(short_channel_id), outgoing_amt_msat: amt_to_forward,
 				outgoing_cltv_value
 			})
-		}
+		},
+		onion_utils::Hop::Dummy { dummy_hop_data: msgs::InboundOnionDummyPayload { ref payment_relay, ref payment_constraints, .. },  shared_secret, .. } => {
+			let (amt_to_forward, outgoing_cltv_value) = match check_dummy_forward(
+				msg.amount_msat, msg.cltv_expiry, &payment_relay, &payment_constraints,
+			) {
+				Ok((amt, cltv)) => (amt, cltv),
+				Err(()) => {
+					return encode_relay_error("Underflow calculating outbound amount or cltv value for blinded forward",
+						LocalHTLCFailureReason::InvalidOnionBlinding, shared_secret.secret_bytes(), None, &[0; 32]);
+				}
+			};
+
+			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: amt_to_forward, outgoing_cltv_value })
+		},
 		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());