Refactor liquidity source to support multiple LSP nodes

Replace per-protocol single-LSP configuration `LSPS1Client, LSPS2Client`
with a unified `Vec<LspNode>` model where users configure LSP nodes via
`add_lsp()` and protocol support is discovered at runtime via LSPS0
`list_protocols`.

- Replace separate `LSPS1Client/LSPS2Client` with global pending request
  maps keyed by `LSPSRequestId`
- Add LSPS0 protocol discovery `discover_lsp_protocols` with event
  handling for `ListProtocolsResponse`
- Update events to use is_lsps_node() for multi-LSP counterparty
  checks
- Deprecate `set_liquidity_source_lsps1/lsps2` builder methods in favor
  of `add_lsp()`
- LSPS2 JIT channels now query all LSPS2-capable LSPs and automatically
  select the cheapest fee offer across all of them
- Add `request_channel_from_lsp()` for explicit LSPS1 LSP selection
- Spawn background discovery task on `Node::start()`

Author: Camillarhi

bindings/ldk_node.udl

@@ -43,8 +43,7 @@ interface Builder {
 	void set_gossip_source_p2p();
 	void set_gossip_source_rgs(string rgs_server_url);
 	void set_pathfinding_scores_source(string url);
-	void set_liquidity_source_lsps1(PublicKey node_id, SocketAddress address, string? token);
-	void set_liquidity_source_lsps2(PublicKey node_id, SocketAddress address, string? token);
+	void add_liquidity_source(PublicKey node_id, SocketAddress address, string? token);
 	void set_storage_dir_path(string storage_dir_path);
 	void set_filesystem_logger(string? log_file_path, LogLevel? max_log_level);
 	void set_log_facade_logger();
@@ -97,7 +96,7 @@ interface Node {
 	SpontaneousPayment spontaneous_payment();
 	OnchainPayment onchain_payment();
 	UnifiedPayment unified_payment();
-	LSPS1Liquidity lsps1_liquidity();
+	Liquidity liquidity();
 	[Throws=NodeError]
 	void lnurl_auth(string lnurl);
 	[Throws=NodeError]
@@ -165,7 +164,7 @@ interface FeeRate {
 
 typedef interface UnifiedPayment;
 
-typedef interface LSPS1Liquidity;
+typedef interface Liquidity;
 
 [Error]
 enum NodeError {
@@ -229,6 +228,7 @@ enum NodeError {
 	"LnurlAuthFailed",
 	"LnurlAuthTimeout",
 	"InvalidLnurl",
+	"DuplicateLspNode",
 };
 
 typedef dictionary NodeStatus;

src/builder.rs

@@ -65,9 +65,7 @@ use crate::io::{
 	PENDING_PAYMENT_INFO_PERSISTENCE_PRIMARY_NAMESPACE,
 	PENDING_PAYMENT_INFO_PERSISTENCE_SECONDARY_NAMESPACE,
 };
-use crate::liquidity::{
-	LSPS1ClientConfig, LSPS2ClientConfig, LSPS2ServiceConfig, LiquiditySourceBuilder,
-};
+use crate::liquidity::{LSPS2ServiceConfig, LiquiditySourceBuilder, LspConfig};
 use crate::lnurl_auth::LnurlAuth;
 use crate::logger::{log_error, LdkLogger, LogLevel, LogWriter, Logger};
 use crate::message_handler::NodeCustomMessageHandler;
@@ -120,10 +118,8 @@ struct PathfindingScoresSyncConfig {
 
 #[derive(Debug, Clone, Default)]
 struct LiquiditySourceConfig {
-	// Act as an LSPS1 client connecting to the given service.
-	lsps1_client: Option<LSPS1ClientConfig>,
-	// Act as an LSPS2 client connecting to the given service.
-	lsps2_client: Option<LSPS2ClientConfig>,
+	// Acts for both LSPS1 and LSPS2 clients connecting to the given service.
+	lsp_nodes: Vec<LspConfig>,
 	// Act as an LSPS2 service.
 	lsps2_service: Option<LSPS2ServiceConfig>,
 }
@@ -435,45 +431,24 @@ impl NodeBuilder {
 		self
 	}
 
-	/// Configures the [`Node`] instance to source inbound liquidity from the given
-	/// [bLIP-51 / LSPS1] service.
-	///
-	/// Will mark the LSP as trusted for 0-confirmation channels, see [`Config::trusted_peers_0conf`].
-	///
-	/// The given `token` will be used by the LSP to authenticate the user.
-	///
-	/// [bLIP-51 / LSPS1]: https://github.com/lightning/blips/blob/master/blip-0051.md
-	pub fn set_liquidity_source_lsps1(
-		&mut self, node_id: PublicKey, address: SocketAddress, token: Option<String>,
-	) -> &mut Self {
-		// Mark the LSP as trusted for 0conf
-		self.config.trusted_peers_0conf.push(node_id.clone());
-
-		let liquidity_source_config =
-			self.liquidity_source_config.get_or_insert(LiquiditySourceConfig::default());
-		let lsps1_client_config = LSPS1ClientConfig { node_id, address, token };
-		liquidity_source_config.lsps1_client = Some(lsps1_client_config);
-		self
-	}
-
-	/// Configures the [`Node`] instance to source just-in-time inbound liquidity from the given
-	/// [bLIP-52 / LSPS2] service.
+	/// Configures the [`Node`] instance to source inbound liquidity from the given LSP, without specifying
+	/// the exact protocol used (e.g., LSPS1 or LSPS2).
 	///
 	/// Will mark the LSP as trusted for 0-confirmation channels, see [`Config::trusted_peers_0conf`].
 	///
 	/// The given `token` will be used by the LSP to authenticate the user.
-	///
-	/// [bLIP-52 / LSPS2]: https://github.com/lightning/blips/blob/master/blip-0052.md
-	pub fn set_liquidity_source_lsps2(
+	/// This method is useful when the user wants to connect to an LSP but does not want to be concerned with
+	///  the specific protocol used for liquidity provision. The node will automatically detect and use the
+	/// appropriate protocol supported by the LSP.
+	pub fn add_liquidity_source(
 		&mut self, node_id: PublicKey, address: SocketAddress, token: Option<String>,
 	) -> &mut Self {
 		// Mark the LSP as trusted for 0conf
-		self.config.trusted_peers_0conf.push(node_id.clone());
+		self.config.trusted_peers_0conf.push(node_id);
 
 		let liquidity_source_config =
 			self.liquidity_source_config.get_or_insert(LiquiditySourceConfig::default());
-		let lsps2_client_config = LSPS2ClientConfig { node_id, address, token };
-		liquidity_source_config.lsps2_client = Some(lsps2_client_config);
+		liquidity_source_config.lsp_nodes.push(LspConfig { node_id, address, token });
 		self
 	}
 
@@ -483,12 +458,12 @@ impl NodeBuilder {
 	/// **Caution**: LSP service support is in **alpha** and is considered an experimental feature.
 	///
 	/// [LSPS2]: https://github.com/BitcoinAndLightningLayerSpecs/lsp/blob/main/LSPS2/README.md
-	pub fn set_liquidity_provider_lsps2(
-		&mut self, service_config: LSPS2ServiceConfig,
+	pub fn enable_liquidity_provider(
+		&mut self, lsps2_service_config: LSPS2ServiceConfig,
 	) -> &mut Self {
 		let liquidity_source_config =
 			self.liquidity_source_config.get_or_insert(LiquiditySourceConfig::default());
-		liquidity_source_config.lsps2_service = Some(service_config);
+		liquidity_source_config.lsps2_service = Some(lsps2_service_config);
 		self
 	}
 
@@ -956,32 +931,18 @@ impl ArcedNodeBuilder {
 		self.inner.write().expect("lock").set_pathfinding_scores_source(url);
 	}
 
-	/// Configures the [`Node`] instance to source inbound liquidity from the given
-	/// [bLIP-51 / LSPS1] service.
+	/// Configures the [`Node`] instance to source inbound liquidity from the given LSP.
 	///
 	/// Will mark the LSP as trusted for 0-confirmation channels, see [`Config::trusted_peers_0conf`].
 	///
 	/// The given `token` will be used by the LSP to authenticate the user.
-	///
-	/// [bLIP-51 / LSPS1]: https://github.com/lightning/blips/blob/master/blip-0051.md
-	pub fn set_liquidity_source_lsps1(
+	/// This method is useful when the user wants to connect to an LSP but does not want to be concerned with
+	///  the specific protocol used for liquidity provision. The node will automatically detect and use the
+	/// appropriate protocol supported by the LSP.
+	pub fn add_liquidity_source(
 		&self, node_id: PublicKey, address: SocketAddress, token: Option<String>,
 	) {
-		self.inner.write().expect("lock").set_liquidity_source_lsps1(node_id, address, token);
-	}
-
-	/// Configures the [`Node`] instance to source just-in-time inbound liquidity from the given
-	/// [bLIP-52 / LSPS2] service.
-	///
-	/// Will mark the LSP as trusted for 0-confirmation channels, see [`Config::trusted_peers_0conf`].
-	///
-	/// The given `token` will be used by the LSP to authenticate the user.
-	///
-	/// [bLIP-52 / LSPS2]: https://github.com/lightning/blips/blob/master/blip-0052.md
-	pub fn set_liquidity_source_lsps2(
-		&self, node_id: PublicKey, address: SocketAddress, token: Option<String>,
-	) {
-		self.inner.write().expect("lock").set_liquidity_source_lsps2(node_id, address, token);
+		self.inner.write().expect("lock").add_liquidity_source(node_id, address, token);
 	}
 
 	/// Configures the [`Node`] instance to provide an [LSPS2] service, issuing just-in-time
@@ -990,8 +951,8 @@ impl ArcedNodeBuilder {
 	/// **Caution**: LSP service support is in **alpha** and is considered an experimental feature.
 	///
 	/// [LSPS2]: https://github.com/BitcoinAndLightningLayerSpecs/lsp/blob/main/LSPS2/README.md
-	pub fn set_liquidity_provider_lsps2(&self, service_config: LSPS2ServiceConfig) {
-		self.inner.write().expect("lock").set_liquidity_provider_lsps2(service_config);
+	pub fn enable_liquidity_provider(&self, lsps2_service_config: LSPS2ServiceConfig) {
+		self.inner.write().expect("lock").enable_liquidity_provider(lsps2_service_config);
 	}
 
 	/// Sets the used storage directory path.
@@ -1806,21 +1767,7 @@ fn build_with_store_internal(
 				Arc::clone(&logger),
 			);
 
-			lsc.lsps1_client.as_ref().map(|config| {
-				liquidity_source_builder.lsps1_client(
-					config.node_id,
-					config.address.clone(),
-					config.token.clone(),
-				)
-			});
-
-			lsc.lsps2_client.as_ref().map(|config| {
-				liquidity_source_builder.lsps2_client(
-					config.node_id,
-					config.address.clone(),
-					config.token.clone(),
-				)
-			});
+			liquidity_source_builder.set_lsp_nodes(lsc.lsp_nodes.clone());
 
 			let promise_secret = {
 				let lsps_xpriv = derive_xprv(
@@ -1889,7 +1836,9 @@ fn build_with_store_internal(
 		}
 	}));
 
-	liquidity_source.as_ref().map(|l| l.set_peer_manager(Arc::downgrade(&peer_manager)));
+	liquidity_source
+		.as_ref()
+		.map(|l| l.lsps2_service().set_peer_manager(Arc::downgrade(&peer_manager)));
 
 	let connection_manager = Arc::new(ConnectionManager::new(
 		Arc::clone(&peer_manager),

src/error.rs

@@ -137,6 +137,8 @@ pub enum Error {
 	LnurlAuthTimeout,
 	/// The provided lnurl is invalid.
 	InvalidLnurl,
+	/// An LSP with the given node id has already been added.
+	DuplicateLspNode,
 }
 
 impl fmt::Display for Error {
@@ -222,6 +224,9 @@ impl fmt::Display for Error {
 			Self::LnurlAuthFailed => write!(f, "LNURL-auth authentication failed."),
 			Self::LnurlAuthTimeout => write!(f, "LNURL-auth authentication timed out."),
 			Self::InvalidLnurl => write!(f, "The provided lnurl is invalid."),
+			Self::DuplicateLspNode => {
+				write!(f, "An LSP with the given node id has already been added.")
+			},
 		}
 	}
 }

src/event.rs

@@ -581,15 +581,15 @@ where
 					Ok(final_tx) => {
 						let needs_manual_broadcast =
 							self.liquidity_source.as_ref().map_or(false, |ls| {
-								ls.as_ref().lsps2_channel_needs_manual_broadcast(
+								ls.as_ref().lsps2_service().lsps2_channel_needs_manual_broadcast(
 									counterparty_node_id,
 									user_channel_id,
 								)
 							});
 
 						let result = if needs_manual_broadcast {
 							self.liquidity_source.as_ref().map(|ls| {
-								ls.lsps2_store_funding_transaction(
+								ls.lsps2_service().lsps2_store_funding_transaction(
 									user_channel_id,
 									counterparty_node_id,
 									final_tx.clone(),
@@ -653,7 +653,8 @@ where
 			},
 			LdkEvent::FundingTxBroadcastSafe { user_channel_id, counterparty_node_id, .. } => {
 				self.liquidity_source.as_ref().map(|ls| {
-					ls.lsps2_funding_tx_broadcast_safe(user_channel_id, counterparty_node_id);
+					ls.lsps2_service()
+						.lsps2_funding_tx_broadcast_safe(user_channel_id, counterparty_node_id);
 				});
 			},
 			LdkEvent::PaymentClaimable {
@@ -1162,7 +1163,10 @@ where
 			LdkEvent::ProbeFailed { .. } => {},
 			LdkEvent::HTLCHandlingFailed { failure_type, .. } => {
 				if let Some(liquidity_source) = self.liquidity_source.as_ref() {
-					liquidity_source.handle_htlc_handling_failed(failure_type).await;
+					liquidity_source
+						.lsps2_service()
+						.handle_htlc_handling_failed(failure_type)
+						.await;
 				}
 			},
 			LdkEvent::SpendableOutputs { outputs, channel_id, counterparty_node_id } => {
@@ -1263,31 +1267,30 @@ where
 						.try_into()
 						.expect("slice is exactly 16 bytes"),
 				);
-				let allow_0conf = self.config.trusted_peers_0conf.contains(&counterparty_node_id);
-				let mut channel_override_config = None;
-				if let Some((lsp_node_id, _)) = self
+				let is_lsp_node = self
 					.liquidity_source
 					.as_ref()
-					.and_then(|ls| ls.as_ref().get_lsps2_lsp_details())
-				{
-					if lsp_node_id == counterparty_node_id {
-						// When we're an LSPS2 client, allow claiming underpaying HTLCs as the LSP will skim off some fee. We'll
-						// check that they don't take too much before claiming.
-						//
-						// We also set maximum allowed inbound HTLC value in flight
-						// to 100%. We should eventually be able to set this on a per-channel basis, but for
-						// now we just bump the default for all channels.
-						channel_override_config = Some(ChannelConfigOverrides {
-							handshake_overrides: Some(ChannelHandshakeConfigUpdate {
-								max_inbound_htlc_value_in_flight_percent_of_channel: Some(100),
-								..Default::default()
-							}),
-							update_overrides: Some(ChannelConfigUpdate {
-								accept_underpaying_htlcs: Some(true),
-								..Default::default()
-							}),
-						});
-					}
+					.map_or(false, |ls| ls.as_ref().is_lsps_node(&counterparty_node_id));
+				let allow_0conf =
+					self.config.trusted_peers_0conf.contains(&counterparty_node_id) || is_lsp_node;
+				let mut channel_override_config = None;
+				if is_lsp_node {
+					// When we're an LSPS2 client, allow claiming underpaying HTLCs as the LSP will skim off some fee. We'll
+					// check that they don't take too much before claiming.
+					//
+					// We also set maximum allowed inbound HTLC value in flight
+					// to 100%. We should eventually be able to set this on a per-channel basis, but for
+					// now we just bump the default for all channels.
+					channel_override_config = Some(ChannelConfigOverrides {
+						handshake_overrides: Some(ChannelHandshakeConfigUpdate {
+							max_inbound_htlc_value_in_flight_percent_of_channel: Some(100),
+							..Default::default()
+						}),
+						update_overrides: Some(ChannelConfigUpdate {
+							accept_underpaying_htlcs: Some(true),
+							..Default::default()
+						}),
+					});
 				}
 				let res = if allow_0conf {
 					self.channel_manager.accept_inbound_channel_from_trusted_peer(
@@ -1416,6 +1419,7 @@ where
 				if let Some(liquidity_source) = self.liquidity_source.as_ref() {
 					let skimmed_fee_msat = skimmed_fee_msat.unwrap_or(0);
 					liquidity_source
+						.lsps2_service()
 						.handle_payment_forwarded(Some(next_htlc.channel_id), skimmed_fee_msat)
 						.await;
 				}
@@ -1529,6 +1533,7 @@ where
 
 				if let Some(liquidity_source) = self.liquidity_source.as_ref() {
 					liquidity_source
+						.lsps2_service()
 						.handle_channel_ready(user_channel_id, &channel_id, &counterparty_node_id)
 						.await;
 				}
@@ -1600,6 +1605,7 @@ where
 			} => {
 				if let Some(liquidity_source) = self.liquidity_source.as_ref() {
 					liquidity_source
+						.lsps2_service()
 						.handle_htlc_intercepted(
 							requested_next_hop_scid,
 							intercept_id,