Refactor liquidity source to support multiple LSP nodes by Camillarhi · Pull Request #792 · lightningdevkit/ldk-node

Camillarhi · 2026-02-12T10:42:34Z

The current setup ties you to a single LSP per protocol via set_liquidity_source_lsps1 / set_liquidity_source_lsps2. This refactor replaces that with a unified Vec<LspNode> model where LSP nodes are added via add_lsp() and protocol support is discovered at runtime through LSPS0 list_protocols. Multi-LSP support has been requested previously in #529.

Deprecated set_liquidity_source_lsps1 / set_liquidity_source_lsps2 in favor of add_lsp()
Replaced the per-protocol LSPS1Client / LSPS2Client with global pending request maps keyed by LSPSRequestId
Added LSPS0 protocol discovery with event handling for ListProtocolsResponse
Background discovery task spawns on Node::start()
LSPS2 JIT channels now query all LSPS2-capable LSPs and automatically select the cheapest fee offer
Added request_channel_from_lsp() for explicit LSPS1 LSP selection
Updated event handling to use is_lsps_node() for multi-LSP counterparty checks

This sets the foundation for LSPS5 support currently being worked on in #729

ldk-reviews-bot · 2026-02-12T10:42:38Z

👋 Thanks for assigning @tnull as a reviewer!
I'll wait for their review and will help manage the review process.
Once they submit their review, I'll check if a second reviewer would be helpful.

Camillarhi · 2026-02-12T10:45:04Z

@tnull Early draft up for review, would appreciate feedback on the general API direction

tnull

Thanks! Some initial questions..

tnull · 2026-02-25T10:26:40Z

+					supported_protocols: Mutex::new(None),
+				})
+				.collect(),
+			pending_lsps1_opening_params_requests: Mutex::new(HashMap::new()),


Uh, no, I don't think we should just merge all into one. Especially given that we intend to add more logic on a per-spec basis, this will be will become even more confusing going forward. If anything, we should maybe start the refactoring by first moving the LSPS1/LSPS2 specific parts to src/liquidity/{lsps1,lsps2}.rs, or maybe even to client/service specific sub-modules like src/liquidity/{client,service}/{lsps1,lsps2}.rs.

Alright, I will move the LSPS1/LSPS2 specific parts

tnull · 2026-02-25T10:29:54Z

 	pub(crate) async fn lsps1_request_channel(
 		&self, lsp_balance_sat: u64, client_balance_sat: u64, channel_expiry_blocks: u32,
-		announce_channel: bool, refund_address: bitcoin::Address,
+		announce_channel: bool, refund_address: bitcoin::Address, node_id: &PublicKey,


Hmm, I do wonder if it would make sense to create something like an struct ServiceProvider and move the API methods to there. Then, each registered LSP would have a corresponding ServiceProvider that exposes a bunch of public and internal APIs, which would make the modularization cleaner and would avoid having to give node_id everywhere?

Makes sense, I will have a look and see

Camillarhi · 2026-03-26T00:47:38Z

Hello @tnull, apologies for the delay. This is ready for another round of review

tnull

Cool, already looks pretty good! Did a first higher-level pass, have yet to look into the details.

tnull · 2026-03-27T08:02:00Z

@@ -1,1542 +0,0 @@
-// This file is Copyright its original authors, visible in version control history.


Would be good to structure this PR in a way that (as far as possible) makes any code moves dedicated commits that can be picked up by git diff --color-moved --patience, as otherwise reviewing this in detail will be very hard.

tnull · 2026-03-27T08:11:47Z

+					}
+				}
+
+				discovery_ls.discover_all_lsp_protocols().await;


I think it would be good to make this part of the background task above? Also, can we spawn the discovery tasks in parallel rather than doing them sequentially?

tnull · 2026-03-27T08:15:51Z

 	}
+
+	/// Configures the [`Node`] instance to source inbound liquidity from the given LSP at runtime,
+	/// without specifying the exact protocol used (e.g., LSPS1 or LSPS2).


I think we can drop the remark regarding 'without specifying the exact protocol' here and elsewhere, as the API already communicates that due to being generic. I do however wonder if we'd want to move this method to an API-extension object similar to what we do for the payment types? I.e., retrieve the API object via Node::liquidity()?

Thanks. I will remove the remark and move this to a Node::liquidity() API-extension

tnull · 2026-03-27T08:16:53Z

+/// [`Bolt11Payment::receive_via_jit_channel`]: crate::payment::Bolt11Payment::receive_via_jit_channel
+#[derive(Clone)]
+#[cfg_attr(feature = "uniffi", derive(uniffi::Object))]
+pub struct LSPS1Liquidity {


It seems this is currently not exposed in the API anymore?

tnull · 2026-03-27T08:17:50Z

 	/// 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
+	#[deprecated(note = "Use `add_lsp` instead")]


Hmm, I think so far we've been fine with just breaking the APIs without deprecating them first. If we find a better API I'd be fine with just dropping the old ones to clean up.

tnull

Cool. Docs CI is currently failing.

Would be great if you try once more to breakup the second commit into smaller chunks, but let me know if it's too cumbersome/impossible.

Feel free to mark ready for review then.

ldk-reviews-bot · 2026-04-02T16:09:13Z

🔔 1st Reminder

Hey @tnull @valentinewallace! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2026-04-02T16:45:26Z

🔔 1st Reminder

Hey @tnull @valentinewallace! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2026-04-04T16:09:41Z

🔔 2nd Reminder

Hey @tnull @valentinewallace! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2026-04-04T16:45:53Z

🔔 2nd Reminder

Hey @tnull @valentinewallace! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2026-04-06T16:10:41Z

🔔 3rd Reminder

Hey @tnull @valentinewallace! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2026-04-06T16:46:54Z

🔔 3rd Reminder

Hey @tnull @valentinewallace! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2026-04-08T16:11:42Z

🔔 4th Reminder

Hey @tnull @valentinewallace! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2026-04-08T16:47:56Z

🔔 4th Reminder

Hey @tnull @valentinewallace! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

tnull

Seems CI is unfortunately failing right now (CLN failure is unrelated though).

Camillarhi · 2026-05-07T13:04:02Z

Seems CI is unfortunately failing right now (CLN failure is unrelated though).

The failing CI has been resolved

ldk-reviews-bot · 2026-05-09T13:04:36Z

🔔 1st Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2026-05-11T13:04:50Z

🔔 2nd Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2026-05-13T13:04:56Z

🔔 3rd Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

f3r10

Great work. Still trying to understand all the changes.

f3r10 · 2026-05-14T17:51:33Z

+	/// The channel will be opened after one of the returned payment options has successfully been
+	/// paid.
+	///
+	/// If `node_id` is `None` and multiple LSPs support LSPS1, the first one registered


I have one question: Was best-price comparison across multiple LSPS1 providers considered? LSPS2 queries all providers and picks the cheapest, but LSPS1 falls back to the first registered. Is there a reason for this asymmetry, or is price comparison for LSPS1 planned for the future?

The behavioral difference is intentional and rests on two things:

The API exposure, LSPS1Liquidity::request_channel takes node_id: Option<PublicKey> and is the user's primary entry point, while lsps2_receive_to_jit_channel for example is invoked internally from Bolt11Payment::receive_via_jit_channel, therefore the choice is automated

The Protocol shape, LSPS2 has a request_opening_params which returns a fee menu, so cost is computable. LSPS1 has a request_supported_options which returns only capability ranges , no fee fields. The price will only materialize from create_order, which commits to a specific order with a specific LSP.

f3r10 · 2026-05-14T17:59:13Z

+					allow_0conf = allow_0conf || lsp.trust_peer_0conf;
+				}
+
+				if self.liquidity_source.get_lsp_config(&counterparty_node_id, Some(2)).is_some() {


If an LSPS2-capable LSP opens a channel before its discovery completes (i.e. supported_protocols is still None), get_lsp_config(Some(2)) returns None and accept_underpaying_htlcs is never enabled. Could this silently break the JIT channel flow for fast LSPs?

Thanks for pointing this out, discovery_done wait was not covered here. It has been updated

ldk-reviews-bot · 2026-05-16T00:00:42Z

🔔 4th Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2026-05-18T00:01:42Z

🔔 5th Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2026-05-20T00:02:16Z

🔔 6th Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2026-05-23T00:00:47Z

🔔 7th Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

Replace per-protocol single-LSP configuration `LSPS1Client` and `LSPS2Client` with a unified `Vec<LspNode>` model where users configure LSP nodes via `add_liquidity_source()` at build time or runtime and per-LSP protocol support is discovered via the LSPS0 `list_protocols`. - Introduce a per-LSP `trust_peer_0conf` flag to `LspConfig`/`LspNode` structs that controls whether 0-conf channels from that LSP are accepted - Add LSPS0 protocol discovery `discover_lsp_protocols` with event handling for `ListProtocolsResponse` - Update events to also use each LSP's `trust_peer_0conf` flag when deciding whether to allow 0-conf channels - Replace `set_liquidity_source_lsps1` and `set_liquidity_source_lsps2` builder methods with a single `add_liquidity_source()` that takes a `trust_peer_0conf` flag - Rename `set_liquidity_provider_lsps2` to `enable_liquidity_provider` - LSPS2 JIT channels now query all LSPS2-capable LSPs and automatically select the cheapest fee offer across all of them - Spawn background discovery task on `Node::start()` and expose a watch channel so dependent flows can wait for discovery to complete - Add a new `Liquidity` handler `Node::liquidity()` exposing `add_liquidity_source()` API for adding LSPs at runtime, and `lsps1()` for the existing LSPS1 surface

Remove the `Ignoring` variant now that the liquidity source is always built, so the enum and its match arms are now pure overhead. Replace it with a struct that holds the `LiquiditySource` directly and have each trait method delegate straight to `liquidity_manager()`.

ldk-reviews-bot · 2026-05-25T00:01:55Z

🔔 8th Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

tnull self-requested a review February 24, 2026 16:28

tnull reviewed Feb 25, 2026

View reviewed changes

Camillarhi force-pushed the multi-lsp-support branch 2 times, most recently from 3cda7f7 to 8bbf55a Compare March 26, 2026 00:46

Camillarhi requested a review from tnull March 26, 2026 00:47

Camillarhi force-pushed the multi-lsp-support branch from 8bbf55a to ea93afe Compare March 26, 2026 01:18

tnull reviewed Mar 27, 2026

View reviewed changes

Camillarhi force-pushed the multi-lsp-support branch 2 times, most recently from 6061c6d to a560764 Compare March 30, 2026 16:32

Camillarhi requested a review from tnull March 30, 2026 16:32

tnull reviewed Mar 31, 2026

View reviewed changes

Camillarhi force-pushed the multi-lsp-support branch from a560764 to c430e51 Compare March 31, 2026 16:07

Camillarhi marked this pull request as ready for review March 31, 2026 16:07

ldk-reviews-bot requested a review from valentinewallace March 31, 2026 16:08

Camillarhi requested a review from tnull March 31, 2026 16:45

tnull mentioned this pull request Apr 1, 2026

LSPS5 Notifications for Pending HTLCs #762

Open

Camillarhi force-pushed the multi-lsp-support branch 2 times, most recently from 22da16c to 2cda868 Compare April 9, 2026 15:16

valentinewallace removed their request for review April 9, 2026 15:37

Camillarhi force-pushed the multi-lsp-support branch from 606bcf2 to a55f8b3 Compare May 5, 2026 15:11

Camillarhi requested a review from tnull May 5, 2026 15:29

tnull reviewed May 6, 2026

View reviewed changes

Camillarhi force-pushed the multi-lsp-support branch 3 times, most recently from b5a5fa4 to 3c80fdc Compare May 7, 2026 12:18

Camillarhi requested a review from tnull May 7, 2026 13:04

f3r10 reviewed May 14, 2026

View reviewed changes

Camillarhi force-pushed the multi-lsp-support branch from 3c80fdc to 1a449ef Compare May 15, 2026 17:41

Camillarhi force-pushed the multi-lsp-support branch from 1a449ef to d39186a Compare May 20, 2026 09:03

Camillarhi added 9 commits May 24, 2026 22:30

Move liquidity.rs to liquidity/mod.rs module directory

6d66d99

Move LSPS1 client logic into liquidity/client/lsps1.rs

1fd0cd3

Move LSPS1 client event handling into liquidity/client/lsps1.rs

501a203

Move LSPS2 client logic into liquidity/client/lsps2.rs

4076d8a

Move LSPS2 client event handling into liquidity/client/lsps2.rs

c50ada4

Move LSPS2 service logic into liquidity/service/lsps2.rs

60b3e93

Move LSPS2 service event handling into liquidity/service/lsps2.rs

0ed14ba

Camillarhi force-pushed the multi-lsp-support branch from d39186a to 51e3f54 Compare May 24, 2026 21:43

		@@ -1,1542 +0,0 @@
		// This file is Copyright its original authors, visible in version control history.

Conversation

Camillarhi commented Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ldk-reviews-bot commented Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Camillarhi commented Feb 12, 2026

Uh oh!

tnull left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Camillarhi commented Mar 26, 2026

Uh oh!

tnull left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tnull left a comment

Choose a reason for hiding this comment

Uh oh!

ldk-reviews-bot commented Apr 2, 2026

Uh oh!

ldk-reviews-bot commented Apr 2, 2026

Uh oh!

ldk-reviews-bot commented Apr 4, 2026

Uh oh!

ldk-reviews-bot commented Apr 4, 2026

Uh oh!

ldk-reviews-bot commented Apr 6, 2026

Uh oh!

ldk-reviews-bot commented Apr 6, 2026

Uh oh!

ldk-reviews-bot commented Apr 8, 2026

Uh oh!

ldk-reviews-bot commented Apr 8, 2026

Uh oh!

tnull left a comment

Choose a reason for hiding this comment

Uh oh!

Camillarhi commented May 7, 2026

Uh oh!

ldk-reviews-bot commented May 9, 2026

Uh oh!

ldk-reviews-bot commented May 11, 2026

Uh oh!

ldk-reviews-bot commented May 13, 2026

Uh oh!

f3r10 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Camillarhi May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Camillarhi commented Feb 12, 2026 •

edited

Loading

ldk-reviews-bot commented Feb 12, 2026 •

edited

Loading

Camillarhi May 15, 2026 •

edited

Loading