Update PaymentPath, and ClaimAlongRoute arguments

Upcoming commits will need the ability to specify whether a blinded path
contains dummy hops. This change adds that support to the testing
framework ahead of time, so later tests can express dummy-hop scenarios
explicitly.

Author: shaavan

lightning/src/ln/channelmanager.rs

@@ -7144,14 +7144,10 @@ where
 		// (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();
+			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);
+				decode_update_add_htlc_source.entry(incoming_scid_alias).or_default().extend(htlcs);
 			}
 		}
 

lightning/src/ln/functional_test_utils.rs

@@ -3435,6 +3435,7 @@ fn fail_payment_along_path<'a, 'b, 'c>(expected_path: &[&Node<'a, 'b, 'c>]) {
 pub struct PassAlongPathArgs<'a, 'b, 'c, 'd> {
 	pub origin_node: &'a Node<'b, 'c, 'd>,
 	pub expected_path: &'a [&'a Node<'b, 'c, 'd>],
+	pub dummy_hop_override: Option<usize>,
 	pub recv_value: u64,
 	pub payment_hash: PaymentHash,
 	pub payment_secret: Option<PaymentSecret>,
@@ -3456,6 +3457,7 @@ impl<'a, 'b, 'c, 'd> PassAlongPathArgs<'a, 'b, 'c, 'd> {
 		Self {
 			origin_node,
 			expected_path,
+			dummy_hop_override: None,
 			recv_value,
 			payment_hash,
 			payment_secret: None,
@@ -3503,12 +3505,17 @@ impl<'a, 'b, 'c, 'd> PassAlongPathArgs<'a, 'b, 'c, 'd> {
 		self.expected_failure = Some(failure);
 		self
 	}
+	pub fn with_dummy_override(mut self, dummy_override: usize) -> Self {
+		self.dummy_hop_override = Some(dummy_override);
+		self
+	}
 }
 
 pub fn do_pass_along_path<'a, 'b, 'c>(args: PassAlongPathArgs) -> Option<Event> {
 	let PassAlongPathArgs {
 		origin_node,
 		expected_path,
+		dummy_hop_override,
 		recv_value,
 		payment_hash: our_payment_hash,
 		payment_secret: our_payment_secret,
@@ -3755,6 +3762,29 @@ pub struct ClaimAlongRouteArgs<'a, 'b, 'c, 'd> {
 	pub origin_node: &'a Node<'b, 'c, 'd>,
 	pub expected_paths: &'a [&'a [&'a Node<'b, 'c, 'd>]],
 	pub expected_extra_fees: Vec<u32>,
+	/// A one-off adjustment used only in tests to account for an existing
+	/// fee-handling trade-off in LDK.
+	///
+	/// When the payer is the introduction node of a blinded path, LDK does not
+	/// subtract the forward fee for the `payer -> next_hop` channel
+	/// (see [`BlindedPaymentPath::advance_path_by_one`]). This keeps the fee
+	/// logic simpler at the cost of a small, intentional overpayment.
+	///
+	/// In the simple two-hop case (payer as introduction node → payee),
+	/// this overpayment has historically been avoided by simply not charging
+	/// the payer the forward fee, since the payer knows there is only
+	/// a single hop after them.
+	///
+	/// However, with the introduction of dummy hops in LDK v0.3, even a
+	/// two-node real path (payer as introduction node → payee) may appear as a
+	/// multi-hop blinded path. This makes the existing overpayment surface in
+	/// tests.
+	///
+	/// Until the fee-handling trade-off is revisited, this field allows tests
+	/// to compensate for that expected difference.
+	///
+	/// [`BlindedPaymentPath::advance_path_by_one`]: crate::blinded_path::payment::BlindedPaymentPath::advance_path_by_one
+	pub expected_extra_total_fees_msat: u64,
 	pub expected_min_htlc_overpay: Vec<u32>,
 	pub skip_last: bool,
 	pub payment_preimage: PaymentPreimage,
@@ -3778,6 +3808,7 @@ impl<'a, 'b, 'c, 'd> ClaimAlongRouteArgs<'a, 'b, 'c, 'd> {
 			origin_node,
 			expected_paths,
 			expected_extra_fees: vec![0; expected_paths.len()],
+			expected_extra_total_fees_msat: 0,
 			expected_min_htlc_overpay: vec![0; expected_paths.len()],
 			skip_last: false,
 			payment_preimage,
@@ -3793,6 +3824,10 @@ impl<'a, 'b, 'c, 'd> ClaimAlongRouteArgs<'a, 'b, 'c, 'd> {
 		self.expected_extra_fees = extra_fees;
 		self
 	}
+	pub fn with_expected_extra_total_fees_msat(mut self, extra_total_fees: u64) -> Self {
+		self.expected_extra_total_fees_msat = extra_total_fees;
+		self
+	}
 	pub fn with_expected_min_htlc_overpay(mut self, extra_fees: Vec<u32>) -> Self {
 		self.expected_min_htlc_overpay = extra_fees;
 		self
@@ -3817,6 +3852,7 @@ pub fn pass_claimed_payment_along_route(args: ClaimAlongRouteArgs) -> u64 {
 		payment_preimage: our_payment_preimage,
 		allow_1_msat_fee_overpay,
 		custom_tlvs,
+		..
 	} = args;
 	let claim_event = expected_paths[0].last().unwrap().node.get_and_clear_pending_events();
 	assert_eq!(claim_event.len(), 1);
@@ -4049,13 +4085,21 @@ pub fn pass_claimed_payment_along_route(args: ClaimAlongRouteArgs) -> u64 {
 
 	expected_total_fee_msat
 }
+
 pub fn claim_payment_along_route(
 	args: ClaimAlongRouteArgs,
 ) -> (Option<PaidBolt12Invoice>, Vec<Event>) {
-	let origin_node = args.origin_node;
-	let payment_preimage = args.payment_preimage;
-	let skip_last = args.skip_last;
-	let expected_total_fee_msat = do_claim_payment_along_route(args);
+	let ClaimAlongRouteArgs {
+		origin_node,
+		payment_preimage,
+		skip_last,
+		expected_extra_total_fees_msat,
+		..
+	} = args;
+
+	let expected_total_fee_msat =
+		do_claim_payment_along_route(args) + expected_extra_total_fees_msat;
+
 	if !skip_last {
 		expect_payment_sent!(origin_node, payment_preimage, Some(expected_total_fee_msat))
 	} else {

lightning/src/ln/offers_tests.rs

@@ -185,7 +185,20 @@ fn route_bolt12_payment<'a, 'b, 'c>(
 fn claim_bolt12_payment<'a, 'b, 'c>(
 	node: &Node<'a, 'b, 'c>, path: &[&Node<'a, 'b, 'c>], expected_payment_context: PaymentContext, invoice: &Bolt12Invoice
 ) {
-	let recipient = &path[path.len() - 1];
+	claim_bolt12_payment_with_extra_fees(
+		node,
+		path,
+		expected_payment_context,
+		invoice,
+		None,
+	)
+}
+
+fn claim_bolt12_payment_with_extra_fees<'a, 'b, 'c>(
+	node: &Node<'a, 'b, 'c>, path: &[&Node<'a, 'b, 'c>], expected_payment_context: PaymentContext, invoice: &Bolt12Invoice,
+	expected_extra_fees_msat: Option<u64>,
+) {
+	let recipient = path.last().expect("Empty path?");
 	let payment_purpose = match get_event!(recipient, Event::PaymentClaimable) {
 		Event::PaymentClaimable { purpose, .. } => purpose,
 		_ => panic!("No Event::PaymentClaimable"),
@@ -194,20 +207,29 @@ fn claim_bolt12_payment<'a, 'b, 'c>(
 		Some(preimage) => preimage,
 		None => panic!("No preimage in Event::PaymentClaimable"),
 	};
-	match payment_purpose {
-		PaymentPurpose::Bolt12OfferPayment { payment_context, .. } => {
-			assert_eq!(PaymentContext::Bolt12Offer(payment_context), expected_payment_context);
-		},
-		PaymentPurpose::Bolt12RefundPayment { payment_context, .. } => {
-			assert_eq!(PaymentContext::Bolt12Refund(payment_context), expected_payment_context);
-		},
+	let context = match payment_purpose {
+		PaymentPurpose::Bolt12OfferPayment { payment_context, .. } =>
+			PaymentContext::Bolt12Offer(payment_context),
+		PaymentPurpose::Bolt12RefundPayment { payment_context, .. } =>
+			PaymentContext::Bolt12Refund(payment_context),
 		_ => panic!("Unexpected payment purpose: {:?}", payment_purpose),
-	}
-	if let Some(inv) = claim_payment(node, path, payment_preimage) {
-		assert_eq!(inv, PaidBolt12Invoice::Bolt12Invoice(invoice.to_owned()));
-	} else {
-		panic!("Expected PaidInvoice::Bolt12Invoice");
 	};
+
+	assert_eq!(context, expected_payment_context);
+
+	let expected_paths = [path];
+	let mut args = ClaimAlongRouteArgs::new(
+		node,
+		&expected_paths,
+		payment_preimage,
+	);
+
+	if let Some(extra) = expected_extra_fees_msat {
+		args = args.with_expected_extra_total_fees_msat(extra);
+	}
+
+	let (inv, _) = claim_payment_along_route(args);
+	assert_eq!(inv, Some(PaidBolt12Invoice::Bolt12Invoice(invoice.clone())));
 }
 
 fn extract_offer_nonce<'a, 'b, 'c>(node: &Node<'a, 'b, 'c>, message: &OnionMessage) -> Nonce {