feat: BOLT12 receive via LSPS4 JIT channels

Add LSPS4Router that wraps DefaultRouter and creates LSPS4 blinded
payment paths when LSPS4 config is set. This enables BOLT12 offers to
work with LSPS4 JIT channels for nodes with no existing channels.

Also switches MessageRouter from DefaultMessageRouter to
NodeIdMessageRouter to avoid compact SCID introduction nodes that
mobile wallets (Phoenix etc) can't resolve with filtered gossip.

Author: martinsaposnic

src/builder.rs

@@ -71,6 +71,7 @@ use crate::logger::{log_error, LdkLogger, LogLevel, LogWriter, Logger};
 use crate::message_handler::NodeCustomMessageHandler;
 use crate::payment::asynchronous::om_mailbox::OnionMessageMailbox;
 use crate::peer_store::PeerStore;
+use crate::router::{LSPS4BlindedPathConfig, LSPS4Router};
 use crate::runtime::Runtime;
 use crate::tx_broadcaster::TransactionBroadcaster;
 use crate::types::{
@@ -1606,12 +1607,22 @@ 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,
+	);
+
+	// Create shared LSPS4 config state for the router
+	let lsps4_blinded_path_config: Arc<RwLock<Option<LSPS4BlindedPathConfig>>> =
+		Arc::new(RwLock::new(None));
+
+	let router = Arc::new(LSPS4Router::new(
+		inner_router,
+		Arc::clone(&lsps4_blinded_path_config),
+		Arc::clone(&keys_manager),
 	));
 
 	let mut user_config = default_user_config(&config);
@@ -1813,6 +1824,7 @@ fn build_with_store_internal(
 				Arc::clone(&config),
 				Arc::clone(&logger),
 				Arc::clone(&event_queue),
+				Arc::clone(&lsps4_blinded_path_config),
 			);
 
 			lsc.lsps1_client.as_ref().map(|config| {

src/lib.rs

@@ -96,6 +96,7 @@ pub mod logger;
 mod message_handler;
 pub mod payment;
 mod peer_store;
+mod router;
 mod runtime;
 mod scoring;
 mod tx_broadcaster;
@@ -880,8 +881,12 @@ impl Node {
 	#[cfg(not(feature = "uniffi"))]
 	pub fn bolt12_payment(&self) -> Bolt12Payment {
 		Bolt12Payment::new(
+			Arc::clone(&self.runtime),
 			Arc::clone(&self.channel_manager),
+			Arc::clone(&self.connection_manager),
+			self.liquidity_source.clone(),
 			Arc::clone(&self.payment_store),
+			Arc::clone(&self.peer_store),
 			Arc::clone(&self.config),
 			Arc::clone(&self.is_running),
 			Arc::clone(&self.logger),
@@ -895,8 +900,12 @@ impl Node {
 	#[cfg(feature = "uniffi")]
 	pub fn bolt12_payment(&self) -> Arc<Bolt12Payment> {
 		Arc::new(Bolt12Payment::new(
+			Arc::clone(&self.runtime),
 			Arc::clone(&self.channel_manager),
+			Arc::clone(&self.connection_manager),
+			self.liquidity_source.clone(),
 			Arc::clone(&self.payment_store),
+			Arc::clone(&self.peer_store),
 			Arc::clone(&self.config),
 			Arc::clone(&self.is_running),
 			Arc::clone(&self.logger),

src/liquidity.rs

@@ -46,6 +46,7 @@ use tokio::sync::oneshot;
 use crate::builder::BuildError;
 use crate::chain::ChainSource;
 use crate::connection::ConnectionManager;
+use crate::router::LSPS4BlindedPathConfig;
 use crate::event::EventQueue;
 use crate::logger::{log_debug, log_error, log_info, Logger};
 use crate::runtime::Runtime;
@@ -199,6 +200,7 @@ where
 	lsps2_service: Option<LSPS2Service>,
 	lsps4_client: Option<LSPS4Client>,
 	lsps4_service: Option<LSPS4Service>,
+	lsps4_blinded_path_config: Arc<RwLock<Option<LSPS4BlindedPathConfig>>>,
 	wallet: Arc<Wallet>,
 	channel_manager: Arc<ChannelManager>,
 	keys_manager: Arc<KeysManager>,
@@ -218,6 +220,7 @@ where
 		wallet: Arc<Wallet>, channel_manager: Arc<ChannelManager>, keys_manager: Arc<KeysManager>,
 		chain_source: Arc<ChainSource>, tx_broadcaster: Arc<Broadcaster>, kv_store: Arc<DynStore>,
 		config: Arc<Config>, logger: L, event_queue: Arc<EventQueue<L>>,
+		lsps4_blinded_path_config: Arc<RwLock<Option<LSPS4BlindedPathConfig>>>,
 	) -> Self {
 		let lsps1_client = None;
 		let lsps2_client = None;
@@ -230,6 +233,7 @@ where
 			lsps2_service,
 			lsps4_client,
 			lsps4_service,
+			lsps4_blinded_path_config,
 			wallet,
 			channel_manager,
 			keys_manager,
@@ -358,6 +362,7 @@ where
 			lsps2_service: self.lsps2_service,
 			lsps4_client: self.lsps4_client,
 			lsps4_service: self.lsps4_service,
+			lsps4_blinded_path_config: self.lsps4_blinded_path_config,
 			wallet: self.wallet,
 			channel_manager: self.channel_manager,
 			peer_manager: RwLock::new(None),
@@ -379,6 +384,7 @@ where
 	lsps2_service: Option<LSPS2Service>,
 	lsps4_client: Option<LSPS4Client>,
 	lsps4_service: Option<LSPS4Service>,
+	lsps4_blinded_path_config: Arc<RwLock<Option<LSPS4BlindedPathConfig>>>,
 	wallet: Arc<Wallet>,
 	channel_manager: Arc<ChannelManager>,
 	peer_manager: RwLock<Option<Arc<PeerManager>>>,
@@ -397,6 +403,33 @@ where
 		*self.peer_manager.write().unwrap() = Some(peer_manager);
 	}
 
+	/// Updates the LSPS4 blinded path config used by the router for BOLT12 offers.
+	///
+	/// This is called after successful LSPS4 registration to enable BOLT12 offers
+	/// to create blinded payment paths through the LSP.
+	pub(crate) fn set_lsps4_blinded_path_config(
+		&self, lsp_node_id: PublicKey, intercept_scid: u64, cltv_expiry_delta: u32,
+	) {
+		let config = LSPS4BlindedPathConfig { lsp_node_id, intercept_scid, cltv_expiry_delta };
+		*self.lsps4_blinded_path_config.write().unwrap() = Some(config);
+		log_info!(
+			self.logger,
+			"LSPS4 blinded path config set: lsp_node_id={}, intercept_scid={}, cltv_expiry_delta={}",
+			lsp_node_id,
+			intercept_scid,
+			cltv_expiry_delta
+		);
+	}
+
+	/// Clears the LSPS4 blinded path config.
+	///
+	/// Call this after a JIT channel has been opened so that subsequent BOLT12 offers
+	/// use normal blinded paths through the existing channel instead of LSPS4.
+	pub(crate) fn clear_lsps4_blinded_path_config(&self) {
+		*self.lsps4_blinded_path_config.write().unwrap() = None;
+		log_info!(self.logger, "LSPS4 blinded path config cleared");
+	}
+
 	pub(crate) fn liquidity_manager(&self) -> Arc<LiquidityManager<L>> {
 		Arc::clone(&self.liquidity_manager)
 	}
@@ -1656,7 +1689,7 @@ where
 		}
 		log_info!(self.logger, "TIMING: lsps4_register_node() sent request, waiting for response...");
 
-		let result = tokio::time::timeout(
+		let response = tokio::time::timeout(
 			Duration::from_secs(LIQUIDITY_REQUEST_TIMEOUT_SECS),
 			register_node_receiver,
 		)
@@ -1668,10 +1701,26 @@ where
 		.map_err(|e| {
 			log_error!(self.logger, "Failed to handle response from liquidity service: {}", e);
 			Error::LiquidityRequestFailed
-		});
+		})?;
+
+		// Update the LSPS4 blinded path config for BOLT12 offers
+		self.set_lsps4_blinded_path_config(
+			lsps4_client.lsp_node_id,
+			response.intercept_scid,
+			response.cltv_expiry_delta,
+		);
 
 		log_info!(self.logger, "TIMING: lsps4_register_node() TOTAL took {}ms", fn_start.elapsed().as_millis());
-		result
+		Ok(response)
+	}
+
+	/// Registers with LSPS4 for BOLT12 offer creation.
+	///
+	/// This populates the LSPS4 blinded path config used by the router when creating
+	/// blinded payment paths for BOLT12 offers.
+	pub(crate) async fn lsps4_register_for_bolt12(&self) -> Result<(), Error> {
+		self.lsps4_register_node().await?;
+		Ok(())
 	}
 
 	pub(crate) async fn lsps4_receive_to_jit_channel(

src/payment/bolt12.rs

@@ -24,10 +24,14 @@ use lightning_types::string::UntrustedString;
 use rand::RngCore;
 
 use crate::config::{AsyncPaymentsRole, Config, LDK_PAYMENT_RETRY_TIMEOUT};
+use crate::connection::ConnectionManager;
 use crate::error::Error;
 use crate::ffi::{maybe_deref, maybe_wrap};
+use crate::liquidity::LiquiditySource;
 use crate::logger::{log_error, log_info, LdkLogger, Logger};
 use crate::payment::store::{PaymentDetails, PaymentDirection, PaymentKind, PaymentStatus};
+use crate::peer_store::{PeerInfo, PeerStore};
+use crate::runtime::Runtime;
 use crate::types::{ChannelManager, PaymentStore};
 
 #[cfg(not(feature = "uniffi"))]
@@ -52,8 +56,12 @@ type Refund = Arc<crate::ffi::Refund>;
 /// [BOLT 12]: https://github.com/lightning/bolts/blob/master/12-offer-encoding.md
 /// [`Node::bolt12_payment`]: crate::Node::bolt12_payment
 pub struct Bolt12Payment {
+	runtime: Arc<Runtime>,
 	channel_manager: Arc<ChannelManager>,
+	connection_manager: Arc<ConnectionManager<Arc<Logger>>>,
+	liquidity_source: Option<Arc<LiquiditySource<Arc<Logger>>>>,
 	payment_store: Arc<PaymentStore>,
+	peer_store: Arc<PeerStore<Arc<Logger>>>,
 	config: Arc<Config>,
 	is_running: Arc<RwLock<bool>>,
 	logger: Arc<Logger>,
@@ -62,11 +70,25 @@ pub struct Bolt12Payment {
 
 impl Bolt12Payment {
 	pub(crate) fn new(
-		channel_manager: Arc<ChannelManager>, payment_store: Arc<PaymentStore>,
+		runtime: Arc<Runtime>, channel_manager: Arc<ChannelManager>,
+		connection_manager: Arc<ConnectionManager<Arc<Logger>>>,
+		liquidity_source: Option<Arc<LiquiditySource<Arc<Logger>>>>,
+		payment_store: Arc<PaymentStore>, peer_store: Arc<PeerStore<Arc<Logger>>>,
 		config: Arc<Config>, is_running: Arc<RwLock<bool>>, logger: Arc<Logger>,
 		async_payments_role: Option<AsyncPaymentsRole>,
 	) -> Self {
-		Self { channel_manager, payment_store, config, is_running, logger, async_payments_role }
+		Self {
+			runtime,
+			channel_manager,
+			connection_manager,
+			liquidity_source,
+			payment_store,
+			peer_store,
+			config,
+			is_running,
+			logger,
+			async_payments_role,
+		}
 	}
 
 	/// Send a payment given an offer.
@@ -368,6 +390,93 @@ impl Bolt12Payment {
 		Ok(maybe_wrap(offer))
 	}
 
+	/// Returns a payable offer that can be used to request and receive a payment of the amount
+	/// given via a newly created just-in-time (JIT) channel.
+	///
+	/// When the returned offer is paid, the configured LSPS4-compliant LSP will open a channel
+	/// to us, supplying just-in-time inbound liquidity.
+	///
+	/// This is useful for nodes that have no channels but want to receive BOLT12 payments.
+	/// The offer will contain blinded payment paths that route through the LSP.
+	pub fn receive_via_lsps4_jit_channel(
+		&self, amount_msat: u64, description: &str, expiry_secs: Option<u32>,
+		quantity: Option<u64>,
+	) -> Result<Offer, Error> {
+		let liquidity_source =
+			self.liquidity_source.as_ref().ok_or(Error::LiquiditySourceUnavailable)?;
+
+		let (node_id, address) =
+			liquidity_source.get_lsps4_lsp_details().ok_or(Error::LiquiditySourceUnavailable)?;
+
+		let peer_info = PeerInfo { node_id, address };
+
+		let con_node_id = peer_info.node_id;
+		let con_addr = peer_info.address.clone();
+		let con_cm = Arc::clone(&self.connection_manager);
+
+		// Connect to LSP
+		self.runtime.block_on(async move {
+			con_cm.connect_peer_if_necessary(con_node_id, con_addr).await
+		})?;
+
+		log_info!(self.logger, "Connected to LSP {}@{}. ", peer_info.node_id, peer_info.address);
+
+		// Register with LSPS4 to populate the blinded path config
+		let liquidity_source = Arc::clone(&liquidity_source);
+		self.runtime.block_on(async move { liquidity_source.lsps4_register_for_bolt12().await })?;
+
+		// Now create the offer - the LSPS4Router will use the config to create blinded payment paths
+		let offer = self.receive_inner(amount_msat, description, expiry_secs, quantity)?;
+
+		// Persist LSP peer to make sure we reconnect on restart.
+		self.peer_store.add_peer(peer_info)?;
+
+		Ok(maybe_wrap(offer))
+	}
+
+	/// Returns a payable offer that can be used to request and receive a payment for which the
+	/// amount is to be determined by the user via a newly created just-in-time (JIT) channel.
+	///
+	/// When the returned offer is paid, the configured LSPS4-compliant LSP will open a channel
+	/// to us, supplying just-in-time inbound liquidity.
+	///
+	/// This is useful for nodes that have no channels but want to receive BOLT12 payments.
+	/// The offer will contain blinded payment paths that route through the LSP.
+	pub fn receive_variable_amount_via_lsps4_jit_channel(
+		&self, description: &str, expiry_secs: Option<u32>,
+	) -> Result<Offer, Error> {
+		let liquidity_source =
+			self.liquidity_source.as_ref().ok_or(Error::LiquiditySourceUnavailable)?;
+
+		let (node_id, address) =
+			liquidity_source.get_lsps4_lsp_details().ok_or(Error::LiquiditySourceUnavailable)?;
+
+		let peer_info = PeerInfo { node_id, address };
+
+		let con_node_id = peer_info.node_id;
+		let con_addr = peer_info.address.clone();
+		let con_cm = Arc::clone(&self.connection_manager);
+
+		// Connect to LSP
+		self.runtime.block_on(async move {
+			con_cm.connect_peer_if_necessary(con_node_id, con_addr).await
+		})?;
+
+		log_info!(self.logger, "Connected to LSP {}@{}. ", peer_info.node_id, peer_info.address);
+
+		// Register with LSPS4 to populate the blinded path config
+		let liquidity_source = Arc::clone(&liquidity_source);
+		self.runtime.block_on(async move { liquidity_source.lsps4_register_for_bolt12().await })?;
+
+		// Now create the offer - the LSPS4Router will use the config to create blinded payment paths
+		let offer = self.receive_variable_amount(description, expiry_secs)?;
+
+		// Persist LSP peer to make sure we reconnect on restart.
+		self.peer_store.add_peer(peer_info)?;
+
+		Ok(offer)
+	}
+
 	/// Requests a refund payment for the given [`Refund`].
 	///
 	/// The returned [`Bolt12Invoice`] is for informational purposes only (i.e., isn't needed to