Utils for forwarding intercepted htlcs + getting intercept scids

See ChannelManager::forward_intercepted_htlc and
ChannelManager::get_intercept_scid for details

Co-authored-by: John Cantrell <[email protected]>
Co-authored-by: Valentine Wallace <[email protected]>

Author: valentinewallace

lightning/src/ln/channelmanager.rs

@@ -3157,6 +3157,50 @@ impl<M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> ChannelManager<M, T, K, F
 		Ok(())
 	}
 
+	/// Attempts to forward an intercepted HTLC over the provided scid and with the provided
+	/// amount to forward. Should only be called in response to an [`HTLCIntercepted`] event.
+	///
+	/// Intercepted HTLCs can be useful for Lightning Service Providers (LSPs) to open a just-in-time
+	/// channel to a receiving node if the node lacks sufficient inbound liquidity.
+	///
+	/// To make use of intercepted HTLCs, use [`ChannelManager::get_intercept_scid`] to generate short
+	/// channel id(s) to put in the receiver's invoice route hints. These route hints will signal to
+	/// LDK to generate an [`HTLCIntercepted`] event when it receives the forwarded HTLC.
+	///
+	/// [`HTLCIntercepted`]: events::Event::HTLCIntercepted
+	pub fn forward_intercepted_htlc(&self, intercept_id: InterceptId, short_channel_id: u64, amt_to_forward_msat: u64) -> Result<(), APIError> {
+		let _persistence_guard = PersistenceNotifierGuard::notify_on_drop(&self.total_consistency_lock, &self.persistence_notifier);
+
+		let payment = self.pending_intercepted_htlcs.lock().unwrap().remove(&intercept_id)
+			.ok_or_else(|| APIError::APIMisuseError {
+				err: format!("Payment with InterceptId {:?} not found", intercept_id)
+			})?;
+
+		if self.short_to_chan_info.read().unwrap().get(&short_channel_id).is_none() {
+			return Err(APIError::APIMisuseError {
+				err: format!("Channel with short channel id {:?} not found", short_channel_id)
+			})
+		}
+
+		let routing = match payment.forward_info.routing {
+			PendingHTLCRouting::Forward { onion_packet, .. } => {
+				PendingHTLCRouting::Forward { onion_packet, short_channel_id }
+			},
+			_ => unreachable!()
+		};
+		let pending_htlc_info = PendingHTLCInfo {
+			amt_to_forward: amt_to_forward_msat, routing, ..payment.forward_info
+		};
+
+		let mut per_source_pending_forward = [(
+			payment.prev_short_channel_id,
+			payment.prev_funding_outpoint,
+			vec![(pending_htlc_info, payment.prev_htlc_id)]
+		)];
+		self.forward_htlcs(&mut per_source_pending_forward);
+		Ok(())
+	}
+
 	/// Processes HTLCs which are pending waiting on random forward delay.
 	///
 	/// Should only really ever be called in response to a PendingHTLCsForwardable event.
@@ -5791,6 +5835,20 @@ impl<M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> ChannelManager<M, T, K, F
 		}
 	}
 
+	/// Gets a fake short channel id for use in receiving intercepted payments. These fake scids are
+	/// used when constructing the route hints for HTLCs intended to be intercepted. See
+	/// [`ChannelManager::forward_intercepted_htlc`].
+	pub fn get_intercept_scid(&self) -> u64 {
+		let short_to_chan_info = self.short_to_chan_info.read().unwrap();
+		let best_block = self.best_block.read().unwrap();
+		loop {
+			let scid_candidate = fake_scid::Namespace::Intercept.get_fake_scid(best_block.height(), &self.genesis_hash, &self.fake_scid_rand_bytes, &self.keys_manager);
+			// Ensure the generated scid doesn't conflict with a real channel.
+			if short_to_chan_info.contains_key(&scid_candidate) { continue }
+			return scid_candidate
+		}
+	}
+
 	#[cfg(any(test, fuzzing, feature = "_test_utils"))]
 	pub fn get_and_clear_pending_events(&self) -> Vec<events::Event> {
 		let events = core::cell::RefCell::new(Vec::new());

lightning/src/ln/payment_tests.rs

@@ -19,7 +19,8 @@ use crate::ln::channel::EXPIRE_PREV_CONFIG_TICKS;
 use crate::ln::channelmanager::{self, BREAKDOWN_TIMEOUT, ChannelManager, ChannelManagerReadArgs, MPP_TIMEOUT_TICKS, MIN_CLTV_EXPIRY_DELTA, PaymentId, PaymentSendFailure, IDEMPOTENCY_TIMEOUT_TICKS};
 use crate::ln::msgs;
 use crate::ln::msgs::ChannelMessageHandler;
-use crate::routing::router::{PaymentParameters, get_route};
+use crate::routing::gossip::RoutingFees;
+use crate::routing::router::{find_route, get_route, PaymentParameters, RouteHint, RouteHintHop, RouteParameters};
 use crate::util::events::{ClosureReason, Event, HTLCDestination, MessageSendEvent, MessageSendEventsProvider};
 use crate::util::test_utils;
 use crate::util::errors::APIError;
@@ -1385,3 +1386,115 @@ fn abandoned_send_payment_idempotent() {
 	pass_along_route(&nodes[0], &[&[&nodes[1]]], 100_000, second_payment_hash, second_payment_secret);
 	claim_payment(&nodes[0], &[&nodes[1]], second_payment_preimage);
 }
+
+#[test]
+fn forward_intercepted_payment() {
+	// Test that detecting an intercept scid on payment forward will signal LDK to generate an
+	// intercept event, which the LSP can then use to open a JIT channel to forward the payment.
+	let chanmon_cfgs = create_chanmon_cfgs(3);
+	let node_cfgs = create_node_cfgs(3, &chanmon_cfgs);
+	let node_chanmgrs = create_node_chanmgrs(3, &node_cfgs, &[None, None, None]);
+	let nodes = create_network(3, &node_cfgs, &node_chanmgrs);
+	let scorer = test_utils::TestScorer::with_penalty(0);
+	let random_seed_bytes = chanmon_cfgs[0].keys_manager.get_secure_random_bytes();
+
+	let _ = create_announced_chan_between_nodes(&nodes, 0, 1, channelmanager::provided_init_features(), channelmanager::provided_init_features()).2;
+
+	let amt_msat = 100_000;
+	let intercept_scid = nodes[1].node.get_intercept_scid();
+	let payment_params = PaymentParameters::from_node_id(nodes[2].node.get_our_node_id())
+		.with_route_hints(vec![
+			RouteHint(vec![RouteHintHop {
+				src_node_id: nodes[1].node.get_our_node_id(),
+				short_channel_id: intercept_scid,
+				fees: RoutingFees {
+					base_msat: 1000,
+					proportional_millionths: 0,
+				},
+				cltv_expiry_delta: 130,
+				htlc_minimum_msat: None,
+				htlc_maximum_msat: None,
+			}])
+		])
+		.with_features(channelmanager::provided_invoice_features());
+	let route_params = RouteParameters {
+		payment_params,
+		final_value_msat: amt_msat,
+		final_cltv_expiry_delta: TEST_FINAL_CLTV,
+	};
+	let route = find_route(
+		&nodes[0].node.get_our_node_id(), &route_params, &nodes[0].network_graph, None, nodes[0].logger,
+		&scorer, &random_seed_bytes
+	).unwrap();
+
+	let (payment_hash, payment_secret) = nodes[2].node.create_inbound_payment(Some(amt_msat), 60 * 60).unwrap();
+	nodes[0].node.send_payment(&route, payment_hash, &Some(payment_secret), PaymentId(payment_hash.0)).unwrap();
+	let payment_event = {
+		{
+			let mut added_monitors = nodes[0].chain_monitor.added_monitors.lock().unwrap();
+			assert_eq!(added_monitors.len(), 1);
+			added_monitors.clear();
+		}
+		let mut events = nodes[0].node.get_and_clear_pending_msg_events();
+		assert_eq!(events.len(), 1);
+		SendEvent::from_event(events.remove(0))
+	};
+	nodes[1].node.handle_update_add_htlc(&nodes[0].node.get_our_node_id(), &payment_event.msgs[0]);
+	commitment_signed_dance!(nodes[1], nodes[0], &payment_event.commitment_msg, false, true);
+
+	// Check that we generate the PaymentIntercepted event when an intercept forward is detected.
+	let events = nodes[1].node.get_and_clear_pending_events();
+	assert_eq!(events.len(), 1);
+	let (intercept_id, expected_outbound_amount_msat) = match events[0] {
+		crate::util::events::Event::HTLCIntercepted {
+			intercept_id, expected_outbound_amount_msat, payment_hash: pmt_hash, inbound_amount_msat, requested_next_hop_scid: short_channel_id
+		} => {
+			assert_eq!(pmt_hash, payment_hash);
+			assert_eq!(inbound_amount_msat, route.get_total_amount() + route.get_total_fees());
+			assert_eq!(short_channel_id, intercept_scid);
+			(intercept_id, expected_outbound_amount_msat)
+		},
+		_ => panic!()
+	};
+
+	// Open the just-in-time channel so the payment can then be forwarded.
+	let scid = create_announced_chan_between_nodes(&nodes, 1, 2, channelmanager::provided_init_features(), channelmanager::provided_init_features()).0.contents.short_channel_id;
+
+	// Finally, forward the intercepted payment through and claim it.
+	nodes[1].node.forward_intercepted_htlc(intercept_id, scid, expected_outbound_amount_msat).unwrap();
+	expect_pending_htlcs_forwardable!(nodes[1]);
+
+	let payment_event = {
+		{
+			let mut added_monitors = nodes[1].chain_monitor.added_monitors.lock().unwrap();
+			assert_eq!(added_monitors.len(), 1);
+			added_monitors.clear();
+		}
+		let mut events = nodes[1].node.get_and_clear_pending_msg_events();
+		assert_eq!(events.len(), 1);
+		SendEvent::from_event(events.remove(0))
+	};
+	nodes[2].node.handle_update_add_htlc(&nodes[1].node.get_our_node_id(), &payment_event.msgs[0]);
+	commitment_signed_dance!(nodes[2], nodes[1], &payment_event.commitment_msg, false, true);
+	expect_pending_htlcs_forwardable!(nodes[2]);
+
+	let payment_preimage = nodes[2].node.get_payment_preimage(payment_hash, payment_secret).unwrap();
+	expect_payment_received!(&nodes[2], payment_hash, payment_secret, amt_msat, Some(payment_preimage));
+	do_claim_payment_along_route(&nodes[0], &vec!(&vec!(&nodes[1], &nodes[2])[..]), false, payment_preimage);
+	let events = nodes[0].node.get_and_clear_pending_events();
+	assert_eq!(events.len(), 2);
+	match events[0] {
+		Event::PaymentSent { payment_preimage: ref ev_preimage, payment_hash: ref ev_hash, ref fee_paid_msat, .. } => {
+			assert_eq!(payment_preimage, *ev_preimage);
+			assert_eq!(payment_hash, *ev_hash);
+			assert_eq!(fee_paid_msat, &Some(1000));
+		},
+		_ => panic!("Unexpected event")
+	}
+	match events[1] {
+		Event::PaymentPathSuccessful { payment_hash: hash, .. } => {
+			assert_eq!(hash, Some(payment_hash));
+		},
+		_ => panic!("Unexpected event")
+	}
+}

lightning/src/util/events.rs

@@ -578,9 +578,16 @@ pub enum Event {
 		/// now + 5*time_forwardable).
 		time_forwardable: Duration,
 	},
-	/// Used to indicate that we've intercepted an HTLC forward.
+	/// Used to indicate that we've intercepted an HTLC forward. This event will only be generated if
+	/// you've encoded an intercept scid in the receiver's invoice route hints using
+	/// [`ChannelManager::get_intercept_scid`].
+	///
+	/// [`ChannelManager::get_intercept_scid`]: crate::ln::channelmanager::ChannelManager::get_intercept_scid
 	HTLCIntercepted {
-		/// The fake scid that was programmed as the next hop's scid.
+		/// The fake scid that was programmed as the next hop's scid, generated using
+		/// [`ChannelManager::get_intercept_scid`].
+		///
+		/// [`ChannelManager::get_intercept_scid`]: crate::ln::channelmanager::ChannelManager::get_intercept_scid
 		requested_next_hop_scid: u64,
 		/// The payment hash used for this HTLC.
 		payment_hash: PaymentHash,