Merge pull request #4300 from TheBlueMatt/2025-12-full-interception

Support generic HTLC interception

Author: tnull

lightning-liquidity/tests/lsps2_integration_tests.rs

@@ -38,6 +38,7 @@ use lightning::ln::peer_handler::CustomMessageHandler;
 use lightning::log_error;
 use lightning::routing::router::{RouteHint, RouteHintHop};
 use lightning::sign::NodeSigner;
+use lightning::util::config::HTLCInterceptionFlags;
 use lightning::util::errors::APIError;
 use lightning::util::logger::Logger;
 use lightning::util::test_utils::{TestBroadcaster, TestStore};
@@ -1157,7 +1158,7 @@ fn client_trusts_lsp_end_to_end_test() {
 	let chanmon_cfgs = create_chanmon_cfgs(3);
 	let node_cfgs = create_node_cfgs(3, &chanmon_cfgs);
 	let mut service_node_config = test_default_channel_config();
-	service_node_config.accept_intercept_htlcs = true;
+	service_node_config.htlc_interception_flags = HTLCInterceptionFlags::ToInterceptSCIDs as u8;
 
 	let mut client_node_config = test_default_channel_config();
 	client_node_config.manually_accept_inbound_channels = true;
@@ -1630,7 +1631,7 @@ fn late_payment_forwarded_and_safe_after_force_close_does_not_broadcast() {
 	let chanmon_cfgs = create_chanmon_cfgs(3);
 	let node_cfgs = create_node_cfgs(3, &chanmon_cfgs);
 	let mut service_node_config = test_default_channel_config();
-	service_node_config.accept_intercept_htlcs = true;
+	service_node_config.htlc_interception_flags = HTLCInterceptionFlags::ToInterceptSCIDs as u8;
 
 	let mut client_node_config = test_default_channel_config();
 	client_node_config.manually_accept_inbound_channels = true;
@@ -1821,7 +1822,7 @@ fn htlc_timeout_before_client_claim_results_in_handling_failed() {
 	let chanmon_cfgs = create_chanmon_cfgs(3);
 	let node_cfgs = create_node_cfgs(3, &chanmon_cfgs);
 	let mut service_node_config = test_default_channel_config();
-	service_node_config.accept_intercept_htlcs = true;
+	service_node_config.htlc_interception_flags = HTLCInterceptionFlags::ToInterceptSCIDs as u8;
 
 	let mut client_node_config = test_default_channel_config();
 	client_node_config.manually_accept_inbound_channels = true;
@@ -2157,7 +2158,7 @@ fn client_trusts_lsp_partial_fee_does_not_trigger_broadcast() {
 	let chanmon_cfgs = create_chanmon_cfgs(3);
 	let node_cfgs = create_node_cfgs(3, &chanmon_cfgs);
 	let mut service_node_config = test_default_channel_config();
-	service_node_config.accept_intercept_htlcs = true;
+	service_node_config.htlc_interception_flags = HTLCInterceptionFlags::ToInterceptSCIDs as u8;
 
 	let mut client_node_config = test_default_channel_config();
 	client_node_config.manually_accept_inbound_channels = true;

lightning/src/events/mod.rs

@@ -1250,28 +1250,29 @@ pub enum Event {
 		short_channel_id: Option<u64>,
 	},
 	/// 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`] and have set [`UserConfig::accept_intercept_htlcs`].
+	/// you've set some flags on [`UserConfig::htlc_interception_flags`].
 	///
 	/// [`ChannelManager::forward_intercepted_htlc`] or
-	/// [`ChannelManager::fail_intercepted_htlc`] MUST be called in response to this event. See
-	/// their docs for more information.
+	/// [`ChannelManager::fail_intercepted_htlc`] MUST be called in response to this event in a
+	/// timely manner (i.e. within some number of seconds, not minutes). See their docs for more
+	/// information.
 	///
 	/// # Failure Behavior and Persistence
 	/// This event will eventually be replayed after failures-to-handle (i.e., the event handler
 	/// returning `Err(ReplayEvent ())`) and will be persisted across restarts.
 	///
-	/// [`ChannelManager::get_intercept_scid`]: crate::ln::channelmanager::ChannelManager::get_intercept_scid
-	/// [`UserConfig::accept_intercept_htlcs`]: crate::util::config::UserConfig::accept_intercept_htlcs
+	/// [`UserConfig::htlc_interception_flags`]: crate::util::config::UserConfig::htlc_interception_flags
 	/// [`ChannelManager::forward_intercepted_htlc`]: crate::ln::channelmanager::ChannelManager::forward_intercepted_htlc
 	/// [`ChannelManager::fail_intercepted_htlc`]: crate::ln::channelmanager::ChannelManager::fail_intercepted_htlc
 	HTLCIntercepted {
 		/// An id to help LDK identify which HTLC is being forwarded or failed.
 		intercept_id: InterceptId,
-		/// The fake scid that was programmed as the next hop's scid, generated using
-		/// [`ChannelManager::get_intercept_scid`].
+		/// The SCID which was selected by the sender as the next hop. It may point to one of our
+		/// channels, an intercept SCID generated with [`ChannelManager::get_intercept_scid`], or
+		/// an unknown SCID if [`HTLCInterceptionFlags::ToUnknownSCIDs`] was selected.
 		///
 		/// [`ChannelManager::get_intercept_scid`]: crate::ln::channelmanager::ChannelManager::get_intercept_scid
+		/// [`HTLCInterceptionFlags::ToUnknownSCIDs`]: crate::util::config::HTLCInterceptionFlags::ToUnknownSCIDs
 		requested_next_hop_scid: u64,
 		/// The payment hash used for this HTLC.
 		payment_hash: PaymentHash,
@@ -1282,9 +1283,17 @@ pub enum Event {
 		/// Forwarding less than this amount may break compatibility with LDK versions prior to 0.0.116.
 		///
 		/// Note that LDK will NOT check that expected fees were factored into this value. You MUST
-		/// check that whatever fee you want has been included here or subtract it as required. Further,
+		/// check that whatever fee you want has been included here (by comparing with
+		/// [`Self::HTLCIntercepted::inbound_amount_msat`]) or subtract it as required. Further,
 		/// LDK will not stop you from forwarding more than you received.
 		expected_outbound_amount_msat: u64,
+		/// The block height at which the forwarded HTLC sent to our peer will time out. In
+		/// practice, LDK will refuse to forward an HTLC several blocks before this height (as if
+		/// we attempted to forward an HTLC at this height we'd run some risk that our peer
+		/// force-closes the channel immediately).
+		///
+		/// This will only be `None` for events generated or serialized by LDK 0.2 or prior.
+		outgoing_htlc_expiry_block_height: Option<u32>,
 	},
 	/// Used to indicate that an output which you should know how to spend was confirmed on chain
 	/// and is now spendable.
@@ -2015,11 +2024,13 @@ impl Writeable for Event {
 				inbound_amount_msat,
 				expected_outbound_amount_msat,
 				intercept_id,
+				outgoing_htlc_expiry_block_height,
 			} => {
 				6u8.write(writer)?;
 				let intercept_scid = InterceptNextHop::FakeScid { requested_next_hop_scid };
 				write_tlv_fields!(writer, {
 					(0, intercept_id, required),
+					(1, outgoing_htlc_expiry_block_height, option),
 					(2, intercept_scid, required),
 					(4, payment_hash, required),
 					(6, inbound_amount_msat, required),
@@ -2524,8 +2535,10 @@ impl MaybeReadable for Event {
 					InterceptNextHop::FakeScid { requested_next_hop_scid: 0 };
 				let mut inbound_amount_msat = 0;
 				let mut expected_outbound_amount_msat = 0;
+				let mut outgoing_htlc_expiry_block_height = None;
 				read_tlv_fields!(reader, {
 					(0, intercept_id, required),
+					(1, outgoing_htlc_expiry_block_height, option),
 					(2, requested_next_hop_scid, required),
 					(4, payment_hash, required),
 					(6, inbound_amount_msat, required),
@@ -2540,6 +2553,7 @@ impl MaybeReadable for Event {
 					inbound_amount_msat,
 					expected_outbound_amount_msat,
 					intercept_id,
+					outgoing_htlc_expiry_block_height,
 				}))
 			},
 			7u8 => {

lightning/src/ln/async_payments_tests.rs

@@ -60,7 +60,7 @@ use crate::sign::NodeSigner;
 use crate::sync::Mutex;
 use crate::types::features::Bolt12InvoiceFeatures;
 use crate::types::payment::{PaymentHash, PaymentPreimage, PaymentSecret};
-use crate::util::config::UserConfig;
+use crate::util::config::{HTLCInterceptionFlags, UserConfig};
 use crate::util::ser::Writeable;
 use bitcoin::constants::ChainHash;
 use bitcoin::network::Network;
@@ -3063,7 +3063,7 @@ fn intercepted_hold_htlc() {
 	recipient_cfg.channel_handshake_limits.force_announced_channel_preference = false;
 
 	let mut lsp_cfg = test_default_channel_config();
-	lsp_cfg.accept_intercept_htlcs = true;
+	lsp_cfg.htlc_interception_flags = HTLCInterceptionFlags::ToInterceptSCIDs as u8;
 	lsp_cfg.accept_forwards_to_priv_channels = true;
 	lsp_cfg.enable_htlc_hold = true;
 

lightning/src/ln/blinded_payment_tests.rs

@@ -32,7 +32,7 @@ use crate::routing::router::{
 use crate::sign::{NodeSigner, PeerStorageKey, ReceiveAuthKey, Recipient};
 use crate::types::features::{BlindedHopFeatures, ChannelFeatures, NodeFeatures};
 use crate::types::payment::{PaymentHash, PaymentSecret};
-use crate::util::config::UserConfig;
+use crate::util::config::{HTLCInterceptionFlags, UserConfig};
 use crate::util::ser::{WithoutLength, Writeable};
 use crate::util::test_utils::{self, bytes_from_hex, pubkey_from_hex, secret_from_hex};
 use bitcoin::hex::DisplayHex;
@@ -769,7 +769,8 @@ fn do_blinded_intercept_payment(intercept_node_fails: bool) {
 	let chanmon_cfgs = create_chanmon_cfgs(3);
 	let node_cfgs = create_node_cfgs(3, &chanmon_cfgs);
 	let mut intercept_forwards_config = test_default_channel_config();
-	intercept_forwards_config.accept_intercept_htlcs = true;
+	intercept_forwards_config.htlc_interception_flags =
+		HTLCInterceptionFlags::ToInterceptSCIDs as u8;
 	let node_chanmgrs = create_node_chanmgrs(3, &node_cfgs, &[None, Some(intercept_forwards_config), None]);
 	let nodes = create_network(3, &node_cfgs, &node_chanmgrs);
 	create_announced_chan_between_nodes_with_value(&nodes, 0, 1, 1_000_000, 0);