Add BOLT12 support to LSPS2 via custom `Router` implementation by tnull · Pull Request #4463 · lightningdevkit/rust-lightning

tnull · 2026-03-05T13:36:46Z

Closes #4272.

This is an alternative approach to #4394 which leverages a custom Router implementation on the client side to inject the respective.

LDK Node integration PR over at lightningdevkit/ldk-node#817

ldk-reviews-bot · 2026-03-05T13:36:49Z

👋 Thanks for assigning @jkczyz 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.

TheBlueMatt · 2026-03-05T14:05:35Z

lightning/src/onion_message/messenger.rs

 	dns_resolver_handler: DRH,
 	custom_handler: CMH,
 	intercept_messages_for_offline_peers: bool,
+	peers_registered_for_interception: Mutex<HashSet<PublicKey>>,


Why not just ignore the events for peers that are offline? Not quite sure I get why we need to move the filtering logic into OnionMessenger.

Wouldn't we need this for example for LSPS5? I.e., we'd need to intercept the messages, then wake up the the peer via notification, then forward the messages?

TheBlueMatt · 2026-03-05T14:12:14Z

lightning-liquidity/src/lsps2/router.rs

+		&self, payment_context: &PaymentContext,
+	) -> Option<LSPS2Bolt12InvoiceParameters> {
+		// We intentionally only match `Bolt12Offer` here and not `AsyncBolt12Offer`, as LSPS2
+		// JIT channels are not applicable to async (always-online) BOLT12 offer flows.


I don't think this is true? We need to support JIT opening for async offers as well.

Yes, should have formulated that better, but IMO that is a next/follow-up step somewhat orthogonal to this PR?

We can do it in a separate PR indeed, but I'm not really sure LSPS2 support for BOLT12 only for always-online nodes is nearly as useful has for async recipients. ISTM the second part is the more important usecase.

The big difference is that there are other LSPS2 (client and service) implementations out there that LSPs are running, while async payments isn't deployed at all yet, and will require both sides to be LDK for the time being.

I mean that's fair but are there other LSPS servers that support intercepting blinded paths and doing a JIT channel? I imagine we'll in practice require LDK for both ends for that as well.

In any case my point is that both sides are a similar priority, not that they have to happen in one PR.

Explored this further, but it seems there might be a conflict between approaches here:

No receive_async_via_jit_channel() API — receive_async() creates offers via ChannelManager::get_async_receive_offer() which bypasses the LSPS2 router entirely. The static invoice's payment paths don't use the intercept SCID.

So to add BOLT12-async-payments-via-LSPS2-JIT support we might need to reconsider how we could inject the respective data into the blinded paths. Not sure if @valentinewallace would have an opinion here.

Also, to quote Claude:

The simplest approach: the LSPS2 buy dance happens on the client side, before the static invoice is created. The client:

Calls an LSPS2 buy request to get intercept_scid + cltv_expiry_delta

Calls router.register_offer_nonce(offer_nonce, params)

Then triggers the static invoice creation flow

Since the LSPS2BOLT12Router is both the payment router and the message router, when create_static_invoice_for_server() calls router.create_blinded_payment_paths() with AsyncBolt12OfferContext { offer_nonce }, the router finds the registered nonce and injects the intercept SCID.

But there's a problem: the static invoice is created on the server side (LSP), not the client side. The server calls create_static_invoice_for_server() which calls its own router. The client's router registration is irrelevant — it's the server's router that builds the payment paths.

So either:

(A) The server (LSP) needs to know about the LSPS2 intercept SCID for this client and register it on its own router before creating the static invoice. This means the LSPS2 buy flow needs to complete before static invoice creation, and the server must register the result on its router.

(B) The client creates the static invoice itself (not the server), but that's not how async payments work.

(C) Add a callback/hook in create_static_invoice_for_server() that lets the server inject custom payment paths.

Option (A) seems most natural: the LSP (as LSPS2 service) already knows about the client's intercept SCIDs. When the server creates the static invoice for a client, it could register the intercept SCID on its router so the payment paths go through the JIT channel. But this requires the LSP
to proactively register offer nonces for each client's async offers.

TheBlueMatt · 2026-03-05T14:14:00Z

lightning/src/onion_message/messenger.rs

 			.entry(next_node_id)
 			.or_insert_with(|| OnionMessageRecipient::ConnectedPeer(VecDeque::new()));

+		let should_intercept = self.intercept_messages_for_offline_peers


Shoulnd't we also expand interception to unknown SCIDs for blinded message path creation prior to channel open? I guess its not critical for this to work but it would make the generated offers much smaller as we'd be able to use the SCID encoding rather than pubkey encoding.

Didn't go this way for now, but we do allow registering intercept SCIDs now. Note that a wildcard intercept without having the user pre-register a publickey won't work without breaking the Event::OnionMessageIntercepted API.

ldk-reviews-bot · 2026-03-07T13:37:42Z

🔔 1st Reminder

Hey @jkczyz! 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-03-09T13:38:41Z

🔔 2nd Reminder

Hey @jkczyz! 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.

jkczyz · 2026-03-09T20:00:20Z

lightning-liquidity/src/lsps2/router.rs

+pub struct LSPS2Bolt12InvoiceParameters {
+	/// The LSP node id to use as the blinded path introduction node.
+	pub counterparty_node_id: PublicKey,
+	/// The LSPS2 intercept short channel id.
+	pub intercept_scid: u64,
+	/// The CLTV expiry delta the LSP requires for forwarding over `intercept_scid`.
+	pub cltv_expiry_delta: u32,
+}


Would it be too expensive to store this in the Offer's blinded path? Though I suppose the Router doesn't have access to that, so we'd have to provide it the MessageContext.

I imagine it would be. Adding yet another 45 bytes might be a bit much w.r.t. to QR encoding?

Right, that would be and additional 72 bytes more when encoded as bech32.

Maybe a compact representation (SCID and direction) could be used similar to what we do in blinded paths? That would use 9 bytes instead of 33 for the pubkey, so 21 bytes instead of 45. Encoded that would be 33/34 more bytes instead of 72.

Could you expand on what exactly you imagine we store? And is this mostly around not requiring the client to remember anything outside the offer locally?

Add `register_peer_for_interception()` and `deregister_peer_for_interception()` methods to `OnionMessenger`, allowing specific peers to be registered for onion message interception without enabling blanket interception for all offline peers. When a registered peer is offline and an onion message needs to be forwarded to them, `Event::OnionMessageIntercepted` is emitted. When a registered peer connects, `Event::OnionMessagePeerConnected` is emitted. This works alongside the existing global `new_with_offline_peer_interception()` flag — if either the global flag is set or the peer is specifically registered, interception occurs. This enables LSPS2 services to intercept onion messages only for peers with active JIT channel sessions, rather than intercepting messages for all offline peers. Co-Authored-By: HAL 9000

lightning-liquidity/src/lsps2/service.rs

lightning-liquidity/src/lsps2/router.rs

ldk-claude-review-bot · 2026-03-24T14:38:31Z

Review Summary

Previously flagged issues — status update

Deadlock in htlc_intercepted — FIXED. The read lock on peer_by_intercept_scid is now properly dropped before the if let block body by using .copied() at lines 1043-1044.
Unused BestBlock import — FIXED. Removed from the imports.
values().find() ambiguity in create_blinded_paths MessageRouter impl (router.rs:220) — Still applicable. When multiple offers share the same LSP but different intercept SCIDs, values().find() picks an arbitrary one.

New finding (cross-cutting, not on a diff line)

Missing cleanup_intercept_scids call in channel_open_abandoned — service.rs:1373 removes the intercept SCID from per-peer outbound_channels_by_intercept_scid but doesn't call cleanup_intercept_scids. This means:

The peer_by_intercept_scid handler-level map entry leaks (pre-existing issue).
The onion message interceptor registration for that SCID leaks (new issue introduced by this PR, since the PR registers SCIDs on the interceptor at line 966-972 in buy_response but doesn't deregister them here).

The fix would be to add a cleanup_intercept_scids call after line 1375, similar to the error path in htlc_intercepted at line 1106. Since this code isn't in the diff, I couldn't post an inline comment.

A similar gap exists in prune_expired_request_state (line 636), though that case is partially mitigated by full peer cleanup in do_persist when the peer eventually becomes prunable.

ldk-claude-review-bot · 2026-03-24T15:03:44Z

lightning-liquidity/src/lsps2/service.rs

+								let has_remaining =
+									!peer_state.outbound_channels_by_intercept_scid.is_empty();
+								self.cleanup_intercept_scids(
+									counterparty_node_id,
+									&[intercept_scid],
+									has_remaining,
+								);


Bug: Deadlock — The RwLockReadGuard from self.peer_by_intercept_scid.read() at the enclosing if let (line 1043-1044) has its lifetime extended to the end of the if let block because counterparty_node_id is a &PublicKey borrowed from it. When this error path calls cleanup_intercept_scids, that method attempts to acquire self.peer_by_intercept_scid.write() (line 804). Since the read lock is still held on the same thread, this will deadlock.

Fix: copy the PublicKey out of the read guard so the guard can be dropped before entering the block body. Change the if let at line 1043-1044 to:

let counterparty_node_id = self.peer_by_intercept_scid.read().unwrap().get(&intercept_scid).copied(); if let Some(counterparty_node_id) = counterparty_node_id {

Then update all *counterparty_node_id dereferences to just counterparty_node_id inside the block (it's already a PublicKey rather than &PublicKey).

ldk-claude-review-bot · 2026-03-24T15:03:52Z

lightning-liquidity/tests/lsps2_integration_tests.rs

+	Bolt12OfferContext, PaymentConstraints, PaymentContext, ReceiveTlvs,
+};
+use lightning::blinded_path::NodeIdLookUp;
+use lightning::chain::BestBlock;


Unused import — BestBlock is imported but never used in this file. This will produce a compiler warning (and may fail CI depending on configuration).

Define the `OnionMessageInterceptor` trait with `register_peer_for_interception()` and `deregister_peer_for_interception()` methods, and implement it for `OnionMessenger`. This allows external components to register peers for onion message interception via a trait object, without needing to know the concrete `OnionMessenger` type. Wire the trait into `LSPS2ServiceHandler` as an optional `Arc<dyn OnionMessageInterceptor>`. When provided: - On init, all peers with active intercept SCIDs are registered - In `invoice_parameters_generated()`, the counterparty is registered when a new intercept SCID is assigned This ensures that onion messages for LSPS2 clients with active JIT channel sessions are intercepted when those clients are offline, enabling the LSP to store and forward messages when the client reconnects. Co-Authored-By: HAL 9000

Introduce a router wrapper that maps BOLT12 offer ids to LSPS2 invoice parameters and injects intercept-SCID blinded payment paths while delegating all other routing logic to an inner router. Co-Authored-By: HAL 9000

Clarify that InvoiceParametersReady supports BOLT11 route hints and BOLT12 offer flows via LSPS2BOLT12Router registration. Co-Authored-By: HAL 9000

Exercise the LSPS2 buy flow and assert that a registered `OfferId` produces a blinded payment path whose first forwarding hop uses the negotiated intercept `SCID`. This validates the custom-router wiring used for LSPS2 + `BOLT12`. Co-Authored-By: HAL 9000

Allow tests to provide a override that receives the caller's , enabling custom blinded-path generation while preserving valid bindings. Co-Authored-By: HAL 9000

Exercise the full flow through onion-message invoice exchange, , JIT channel opening, and settlement to confirm paths integrate with LSPS2 service handling. Co-Authored-By: HAL 9000

tnull requested review from TheBlueMatt and jkczyz March 5, 2026 13:36

tnull force-pushed the 2026-03-lsps2-bolt12-alt branch from 2cb0546 to 25ab3bc Compare March 5, 2026 14:05

TheBlueMatt reviewed Mar 5, 2026

View reviewed changes

tnull added this to Weekly Goals Mar 5, 2026

tnull moved this to Goal: Merge in Weekly Goals Mar 5, 2026

tnull self-assigned this Mar 5, 2026

jkczyz reviewed Mar 9, 2026

View reviewed changes

tnull force-pushed the 2026-03-lsps2-bolt12-alt branch from 25ab3bc to 5786409 Compare March 24, 2026 14:34

ldk-claude-review-bot reviewed Mar 24, 2026

View reviewed changes

lightning-liquidity/src/lsps2/service.rs Show resolved Hide resolved

ldk-claude-review-bot reviewed Mar 24, 2026

View reviewed changes

lightning-liquidity/src/lsps2/router.rs Outdated Show resolved Hide resolved

tnull force-pushed the 2026-03-lsps2-bolt12-alt branch from 5786409 to 98a9e9d Compare March 24, 2026 14:50

ldk-claude-review-bot reviewed Mar 24, 2026

View reviewed changes

tnull added 6 commits March 24, 2026 16:09

Add LSPS2 BOLT12 custom router

c80beb6

Introduce a router wrapper that maps BOLT12 offer ids to LSPS2 invoice parameters and injects intercept-SCID blinded payment paths while delegating all other routing logic to an inner router. Co-Authored-By: HAL 9000

Document LSPS2 BOLT12 router flow

f0e592f

Clarify that InvoiceParametersReady supports BOLT11 route hints and BOLT12 offer flows via LSPS2BOLT12Router registration. Co-Authored-By: HAL 9000

Add override for blinded path creation

97b2f06

Allow tests to provide a override that receives the caller's , enabling custom blinded-path generation while preserving valid bindings. Co-Authored-By: HAL 9000

Add LSPS2 BOLT12 end-to-end integration test

7ca886d

Exercise the full flow through onion-message invoice exchange, , JIT channel opening, and settlement to confirm paths integrate with LSPS2 service handling. Co-Authored-By: HAL 9000

tnull force-pushed the 2026-03-lsps2-bolt12-alt branch 2 times, most recently from 8800d48 to 7ca886d Compare March 24, 2026 15:14

Conversation

tnull commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

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!

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 Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tnull Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ldk-reviews-bot commented Mar 7, 2026

Uh oh!

ldk-reviews-bot commented Mar 9, 2026

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!

Uh oh!

Uh oh!

ldk-claude-review-bot commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review Summary

Previously flagged issues — status update

New finding (cross-cutting, not on a diff line)

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

tnull commented Mar 5, 2026 •

edited

Loading

ldk-reviews-bot commented Mar 5, 2026 •

edited

Loading

tnull Mar 24, 2026 •

edited

Loading

tnull Mar 24, 2026 •

edited

Loading

ldk-claude-review-bot commented Mar 24, 2026 •

edited

Loading