Receive BOLT12 payments through LSPS2 JIT channels

Wrap the default router with the LSPS2-aware `LSPS2Router` and wire it
to the LSPS2 client handler, so JIT-channel blinded payment paths are
injected into BOLT12 invoices based on the latest invoice parameters
negotiated with our configured LSPs.

If liquidity sources are configured, we negotiate the parameters with
the cheapest LSP once at startup. From then on they simply apply to all
BOLT12 receives, i.e., any offer created via the regular receive APIs
will have JIT-channel paths injected into its invoices, and we force a
refresh of any static invoices stored with a static invoice server so
they include the new paths, too. As the router encodes the used
parameters in the paths' payment metadata, they are available again
upon receipt and used to verify any skimmed channel opening fee against
what was negotiated.

Parameters previously negotiated with LSPs that are no longer
configured are wiped early during node building, before the node could
create any invoices or connect to peers.

The BOLT11 JIT receive flows are refactored to share the same
negotiation logic.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: Matt Corallo

src/builder.rs

@@ -43,6 +43,7 @@ use lightning::util::persist::{
 use lightning::util::ser::ReadableArgs;
 use lightning::util::sweep::OutputSweeper;
 use lightning_dns_resolver::OMDomainResolver;
+use lightning_liquidity::lsps2::router::LSPS2Router;
 use vss_client::headers::VssHeaderProvider;
 
 use crate::chain::ChainSource;
@@ -70,7 +71,7 @@ use crate::io::{
 };
 use crate::liquidity::{LSPS2ServiceConfig, LiquiditySourceBuilder, LspConfig};
 use crate::lnurl_auth::LnurlAuth;
-use crate::logger::{log_error, LdkLogger, LogLevel, LogWriter, Logger};
+use crate::logger::{log_error, log_info, LdkLogger, LogLevel, LogWriter, Logger};
 use crate::message_handler::NodeCustomMessageHandler;
 use crate::payment::asynchronous::om_mailbox::OnionMessageMailbox;
 use crate::peer_store::PeerStore;
@@ -1762,13 +1763,17 @@ fn build_with_store_internal(
 	}
 
 	let scoring_fee_params = ProbabilisticScoringFeeParameters::default();
-	let router = Arc::new(DefaultRouter::new(
+	let inner_router = DefaultRouter::new(
 		Arc::clone(&network_graph),
 		Arc::clone(&logger),
 		Arc::clone(&keys_manager),
 		Arc::clone(&scorer),
 		scoring_fee_params,
-	));
+	);
+	// Wrap the default router to inject LSPS2 JIT-channel blinded payment paths into BOLT12
+	// invoices based on the latest invoice parameters negotiated with our configured LSPs. The
+	// LSPS2 client handler is wired up below, once the liquidity source is built.
+	let router = Arc::new(LSPS2Router::new(inner_router));
 
 	let mut user_config = default_user_config(&config);
 
@@ -1993,6 +1998,50 @@ fn build_with_store_internal(
 		let custom_message_handler =
 			Arc::new(NodeCustomMessageHandler::new(Arc::clone(&liquidity_source)));
 
+		// Wire up the LSPS2 client handler, having the router inject JIT-channel blinded payment
+		// paths based on the latest invoice parameters negotiated with our configured LSPs.
+		//
+		// Beforehand, wipe any parameters previously negotiated with LSPs that are no longer
+		// configured, making sure the router won't have payments routed through them anymore.
+		if let Some(lsps2_client_handler) =
+			liquidity_source.liquidity_manager().lsps2_client_handler_arc()
+		{
+			let stale_lsp_node_ids = lsps2_client_handler
+				.latest_invoice_params()
+				.into_iter()
+				.map(|invoice_params| invoice_params.counterparty_node_id)
+				.filter(|counterparty_node_id| {
+					!liquidity_source_config.map_or(false, |lsc| {
+						lsc.lsp_nodes.iter().any(|n| n.node_id == *counterparty_node_id)
+					})
+				})
+				.collect::<Vec<_>>();
+
+			for counterparty_node_id in stale_lsp_node_ids {
+				let wipe_handler = Arc::clone(&lsps2_client_handler);
+				let wipe_logger = Arc::clone(&logger);
+				runtime.spawn_background_task(async move {
+					log_info!(
+						wipe_logger,
+						"Wiping LSPS2 invoice parameters previously negotiated with now-unconfigured LSP {}",
+						counterparty_node_id,
+					);
+					if let Err(e) =
+						wipe_handler.clear_latest_invoice_params(&counterparty_node_id).await
+					{
+						log_error!(
+							wipe_logger,
+							"Failed to wipe LSPS2 invoice parameters for LSP {}: {:?}",
+							counterparty_node_id,
+							e
+						);
+					}
+				});
+			}
+
+			router.set_lsps2_client_handler(lsps2_client_handler);
+		}
+
 		(liquidity_source, custom_message_handler)
 	};
 

src/event.rs

@@ -7,7 +7,7 @@
 
 use core::future::Future;
 use core::task::{Poll, Waker};
-use std::collections::VecDeque;
+use std::collections::{BTreeMap, VecDeque};
 use std::ops::Deref;
 use std::sync::{Arc, Mutex};
 
@@ -30,6 +30,8 @@ use lightning::util::errors::APIError;
 use lightning::util::persist::KVStore;
 use lightning::util::ser::{Readable, ReadableArgs, Writeable, Writer};
 use lightning::{impl_ser_tlv_based, impl_ser_tlv_based_enum};
+use lightning_liquidity::lsps2::client::LSPS2InvoiceParameters;
+use lightning_liquidity::lsps2::router::LSPS2_PAYMENT_METADATA_KEY;
 use lightning_liquidity::lsps2::utils::compute_opening_fee;
 use lightning_types::payment::{PaymentHash, PaymentPreimage};
 
@@ -611,6 +613,21 @@ where
 		})
 	}
 
+	fn lsps2_max_total_opening_fee_msat_from_bolt12_metadata(
+		payment_metadata: Option<&BTreeMap<u64, Vec<u8>>>, payment_size_msat: u64,
+	) -> Option<u64> {
+		// For BOLT12 payments, the router encoded the negotiated LSPS2 invoice parameters in the
+		// payment metadata of any JIT-channel blinded payment paths it constructed. Recompute the
+		// maximum acceptable opening fee from the negotiated opening fee parameters.
+		let encoded_params = payment_metadata?.get(&LSPS2_PAYMENT_METADATA_KEY)?;
+		let invoice_params = LSPS2InvoiceParameters::read(&mut &encoded_params[..]).ok()?;
+		compute_opening_fee(
+			payment_size_msat,
+			invoice_params.opening_fee_params.min_fee_msat,
+			invoice_params.opening_fee_params.proportional as u64,
+		)
+	}
+
 	pub async fn handle_event(&self, event: LdkEvent) -> Result<(), ReplayEvent> {
 		match event {
 			LdkEvent::FundingGenerationReady {
@@ -798,13 +815,19 @@ where
 							.and_then(|metadata| {
 								Self::lsps2_max_total_opening_fee_msat(metadata, amount_msat)
 							}),
+						PaymentPurpose::Bolt12OfferPayment { payment_context, .. } => {
+							Self::lsps2_max_total_opening_fee_msat_from_bolt12_metadata(
+								payment_context.payment_metadata.as_ref(),
+								amount_msat + counterparty_skimmed_fee_msat,
+							)
+						},
 						_ => None,
 					};
 
 					let Some(max_total_opening_fee_msat) = max_total_opening_fee_msat else {
 						log_info!(
 							self.logger,
-							"Refusing inbound payment with hash {} as the counterparty withheld {}msat without valid BOLT11 LSPS2 payment metadata",
+							"Refusing inbound payment with hash {} as the counterparty withheld {}msat without valid LSPS2 payment metadata",
 							hex_utils::to_string(&payment_hash.0),
 							counterparty_skimmed_fee_msat,
 						);
@@ -828,18 +851,24 @@ where
 						match &info.kind {
 							PaymentKind::Bolt11 { .. } => {
 								let update = PaymentDetailsUpdate {
-									counterparty_skimmed_fee_msat: Some(Some(counterparty_skimmed_fee_msat)),
+									counterparty_skimmed_fee_msat: Some(Some(
+										counterparty_skimmed_fee_msat,
+									)),
 									..PaymentDetailsUpdate::new(payment_id)
 								};
 								match self.payment_store.update(update).await {
 									Ok(_) => (),
 									Err(e) => {
-										log_error!(self.logger, "Failed to access payment store: {}", e);
+										log_error!(
+											self.logger,
+											"Failed to access payment store: {}",
+											e
+										);
 										return Err(ReplayEvent());
 									},
 								};
 							},
-							_ => debug_assert!(false, "We only expect the counterparty to get away with withholding fees for BOLT11 payments."),
+							_ => {},
 						}
 					}
 				}
@@ -1948,6 +1977,72 @@ mod tests {
 		);
 	}
 
+	#[test]
+	fn lsps2_bolt12_payment_metadata_decodes_fee_limit() {
+		use lightning_liquidity::lsps0::ser::LSPSDateTime;
+		use lightning_liquidity::lsps2::msgs::LSPS2OpeningFeeParams;
+
+		use bitcoin::secp256k1::{PublicKey, Secp256k1, SecretKey};
+
+		use std::str::FromStr;
+
+		let counterparty_node_id = PublicKey::from_secret_key(
+			&Secp256k1::new(),
+			&SecretKey::from_slice(&[42; 32]).unwrap(),
+		);
+		let invoice_params = LSPS2InvoiceParameters {
+			counterparty_node_id,
+			intercept_scid: 42,
+			cltv_expiry_delta: 144,
+			opening_fee_params: LSPS2OpeningFeeParams {
+				min_fee_msat: 21_000,
+				proportional: 10_000,
+				valid_until: LSPSDateTime::from_str("2035-05-20T08:30:45Z").unwrap(),
+				min_lifetime: 144,
+				max_client_to_self_delay: 128,
+				min_payment_size_msat: 1,
+				max_payment_size_msat: 100_000_000,
+				promise: "promise".to_string(),
+			},
+		};
+
+		let mut payment_metadata = BTreeMap::new();
+		payment_metadata.insert(LSPS2_PAYMENT_METADATA_KEY, invoice_params.encode());
+
+		// max(min_fee_msat, proportional * payment_size / 1_000_000) = max(21_000, 10_000_000)
+		assert_eq!(
+			EventHandler::<Arc<TestLogger>>::lsps2_max_total_opening_fee_msat_from_bolt12_metadata(
+				Some(&payment_metadata),
+				1_000_000_000,
+			),
+			Some(10_000_000)
+		);
+
+		// Missing metadata, missing key, or malformed parameters are rejected.
+		assert_eq!(
+			EventHandler::<Arc<TestLogger>>::lsps2_max_total_opening_fee_msat_from_bolt12_metadata(
+				None, 1_000_000,
+			),
+			None
+		);
+		assert_eq!(
+			EventHandler::<Arc<TestLogger>>::lsps2_max_total_opening_fee_msat_from_bolt12_metadata(
+				Some(&BTreeMap::new()),
+				1_000_000,
+			),
+			None
+		);
+		let mut malformed_metadata = BTreeMap::new();
+		malformed_metadata.insert(LSPS2_PAYMENT_METADATA_KEY, vec![0xff]);
+		assert_eq!(
+			EventHandler::<Arc<TestLogger>>::lsps2_max_total_opening_fee_msat_from_bolt12_metadata(
+				Some(&malformed_metadata),
+				1_000_000,
+			),
+			None
+		);
+	}
+
 	#[test]
 	fn lsps2_payment_metadata_missing_or_malformed_limit_is_rejected() {
 		let empty_metadata = PaymentMetadata { lsps2_parameters: None }.encode();

src/lib.rs

@@ -746,6 +746,49 @@ impl Node {
 			}
 		});
 
+		// If we have configured liquidity sources, negotiate LSPS2 JIT-channel invoice parameters
+		// with the cheapest LSP once at startup. The negotiated parameters are stored in the
+		// LSPS2 client handler and will be used by our router to inject JIT-channel blinded
+		// payment paths into all BOLT12 invoices going forward.
+		if !self.liquidity_source.get_all_lsp_details().is_empty() {
+			let negotiation_liquidity_source = Arc::clone(&self.liquidity_source);
+			let negotiation_cm = Arc::clone(&self.connection_manager);
+			let negotiation_chan_man = Arc::clone(&self.channel_manager);
+			let negotiation_peer_store = Arc::clone(&self.peer_store);
+			let negotiation_logger = Arc::clone(&self.logger);
+			self.runtime.spawn_background_task(async move {
+				match negotiation_liquidity_source
+					.lsps2_client()
+					.lsps2_negotiate_variable_amount_jit_invoice_params(None, negotiation_cm)
+					.await
+				{
+					Ok((_, _, chosen_lsp)) => {
+						let peer_info =
+							PeerInfo { node_id: chosen_lsp.node_id, address: chosen_lsp.address };
+						if let Err(e) = negotiation_peer_store.add_peer(peer_info).await {
+							log_error!(
+								negotiation_logger,
+								"Failed to add LSP to peer store: {}",
+								e
+							);
+						}
+
+						// Any static invoices stored with a static invoice server were built
+						// before the newly-negotiated parameters were available. Force a refresh
+						// so they include the JIT-channel payment paths going forward.
+						negotiation_chan_man.refresh_static_invoices();
+					},
+					Err(e) => {
+						log_error!(
+							negotiation_logger,
+							"Failed to negotiate LSPS2 JIT-channel parameters for BOLT12 receives: {}",
+							e
+						);
+					},
+				}
+			});
+		}
+
 		log_info!(self.logger, "Startup complete.");
 		*is_running_lock = true;
 		Ok(())