Skip to content

Add BOLT12 support to LSPS2 via custom Router implementation#4463

Open
tnull wants to merge 14 commits intolightningdevkit:mainfrom
tnull:2026-03-lsps2-bolt12-alt
Open

Add BOLT12 support to LSPS2 via custom Router implementation#4463
tnull wants to merge 14 commits intolightningdevkit:mainfrom
tnull:2026-03-lsps2-bolt12-alt

Conversation

@tnull
Copy link
Copy Markdown
Contributor

@tnull tnull commented Mar 5, 2026

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

@tnull tnull requested review from TheBlueMatt and jkczyz March 5, 2026 13:36
@ldk-reviews-bot
Copy link
Copy Markdown

ldk-reviews-bot commented Mar 5, 2026

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

@tnull tnull force-pushed the 2026-03-lsps2-bolt12-alt branch from 2cb0546 to 25ab3bc Compare March 5, 2026 14:05
&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.
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Contributor Author

@tnull tnull Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

  1. Calls an LSPS2 buy request to get intercept_scid + cltv_expiry_delta
  2. Calls router.register_offer_nonce(offer_nonce, params)
  3. 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.

@tnull tnull moved this to Goal: Merge in Weekly Goals Mar 5, 2026
@tnull tnull self-assigned this Mar 5, 2026
@ldk-reviews-bot
Copy link
Copy Markdown

🔔 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
Copy link
Copy Markdown

🔔 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.

Comment on lines +33 to +40
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,
}
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Copy Markdown
Contributor

@jkczyz jkczyz Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I was thinking we wouldn't need to make a custom Router or use any additional storage for Offer registration. Instead, it would be something like:

  • Include LSPS2Bolt12InvoiceParameters in an Offer's blinded paths using MessageContext when building the Offer.
  • When InvoiceRequest is received, extract the parameters from the MessageContext if set.
  • Use them to determine how to build the BlindedPaymentPaths.

(Alternatively, given the InvoiceRequest contains the Offer's message paths, if the LSP is the introduction node, we can use that directly instead of storing it in the MessageContext. Then, we'd just need the intercept_scid and cltv_expiry_delta as additional data.)

For the last step, we could either (a) bypass the Router entirely and directly build the BlindedPaymentPath from the parameters, (b) pass Option<MessageContext> to Router and implement DefaultRouter to recognize it, or (c) something similar but with a different interface (e.g., passing Option<LSPS2Bolt12InvoiceParameters> instead).

We could use the IntroductionNode::DirectedShortChannelId directly in the BlindedPaymentPath, too, or look it up and use IntroductionNode::NodeId. I believe we currently support routing over the former but don't yet support creating them unlike for BlindedMessagePath.

@tnull tnull force-pushed the 2026-03-lsps2-bolt12-alt branch from 25ab3bc to 5786409 Compare March 24, 2026 14:34
@ldk-claude-review-bot
Copy link
Copy Markdown
Collaborator

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

The tests look well-structured. I notice the compact message path test (bolt12_lsps2_compact_message_path_test) only verifies that the HTLC gets intercepted at the end. It doesn't complete the full payment flow (unlike bolt12_lsps2_end_to_end_test). That's fine as a test — it's specifically testing the message interception path, not the full payment flow.

Now I've completed my thorough review. Let me post any NEW inline comments and the summary. Based on my analysis:

Issues already posted in prior reviews that are still valid:

  1. router.rs:52-54 — Wrong event reference (HTLCInterceptedOnionMessageIntercepted) for message paths
  2. router.rs:213-214 — Same wrong event in code comment
  3. router.rs:220-222 — Nondeterministic HashMap iteration

Issues from prior reviews that are now resolved:

  • events/mod.rs typo "unkown" and stale reference — fixed
  • events/mod.rs grammar — fixed
  • router.rs broken rustdoc link — doesn't exist in current code (was in older version)
  • service.rs issues (cleanup_intercept_scids, deadlock, SCID leak) — method doesn't exist in current code

New issues found in this review:
None. The code is well-structured and the serialization compatibility is correctly handled.

Since all my prior inline comments about the current code issues are still posted and valid, I should not re-post them. My instructions say "Do NOT repeat these."

Review Summary

No new issues found in this review pass. All previously identified issues that are still valid have been posted as inline comments in prior passes.

Previously posted issues (still applicable)

  • lightning-liquidity/src/lsps2/router.rs:52-54 — Wrong event reference: Event::HTLCIntercepted should be Event::OnionMessageIntercepted for message blinded paths
  • lightning-liquidity/src/lsps2/router.rs:213-214 — Same wrong event reference in code comment
  • lightning-liquidity/src/lsps2/router.rs:220-222 — Nondeterministic HashMap::values().find() when multiple offers share the same LSP

Previously posted issues (now resolved in current code)

  • lightning/src/events/mod.rs:1726-1728 — Typo "unkown" and stale peer_node_id reference: fixed
  • lightning/src/events/mod.rs:2968 — Grammar issue: fixed
  • lightning-liquidity/src/lsps2/router.rs:55-58 — Broken rustdoc link: no longer present
  • lightning-liquidity/src/lsps2/service.rs (cleanup_intercept_scids dead code, deadlock, SCID leak) — method no longer exists in current code

Cross-cutting observations

  • The LSPS2BOLT12Router's MessageRouter::create_blinded_paths implementation (lines 209-240) has zero test coverage. Both the E2E test and the compact message path test configure TestMessageRouter directly for message blinded paths and only use the LSPS2 router for payment blinded paths via the override_create_blinded_payment_paths hook.
  • Event serialization backward/forward compatibility for OnionMessageIntercepted is correctly implemented and well-covered by upgrade/downgrade tests.
  • The NextMessageHop TLV-based enum serialization (variants 0=NodeId, 2=ShortChannelId) is correctly defined.

@tnull tnull force-pushed the 2026-03-lsps2-bolt12-alt branch from 5786409 to 98a9e9d Compare March 24, 2026 14:50
@tnull tnull force-pushed the 2026-03-lsps2-bolt12-alt branch 2 times, most recently from 8800d48 to 7ca886d Compare March 24, 2026 15:14
@codecov
Copy link
Copy Markdown

codecov bot commented Mar 24, 2026

Codecov Report

❌ Patch coverage is 76.81564% with 83 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.17%. Comparing base (12edb7d) to head (5d6e7c4).
⚠️ Report is 21 commits behind head on main.

Files with missing lines Patch % Lines
lightning-liquidity/src/lsps2/router.rs 77.63% 72 Missing ⚠️
lightning/src/events/mod.rs 23.07% 9 Missing and 1 partial ⚠️
lightning/src/onion_message/messenger.rs 90.00% 1 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main    #4463      +/-   ##
==========================================
- Coverage   86.20%   86.17%   -0.03%     
==========================================
  Files         160      161       +1     
  Lines      107545   108760    +1215     
  Branches   107545   108760    +1215     
==========================================
+ Hits        92707    93726    +1019     
- Misses      12214    12399     +185     
- Partials     2624     2635      +11     
Flag Coverage Δ
tests 86.17% <76.81%> (-0.03%) ⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@tnull tnull force-pushed the 2026-03-lsps2-bolt12-alt branch from 7ca886d to 2ff16d7 Compare March 25, 2026 08:23
@tnull tnull force-pushed the 2026-03-lsps2-bolt12-alt branch 4 times, most recently from bcc4e10 to 5602e07 Compare March 25, 2026 12:27
@tnull tnull force-pushed the 2026-03-lsps2-bolt12-alt branch 2 times, most recently from ea05389 to 3acf915 Compare March 25, 2026 13:24
Copy link
Copy Markdown
Contributor

@jkczyz jkczyz left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, this could be a gap in my knowledge, but as mentioned in some of the comments, why do we need onion message interception for this? The rationale doesn't appear to be clearly spelled out anywhere.

/// 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,
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can this be u16?

Comment on lines +33 to +40
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,
}
Copy link
Copy Markdown
Contributor

@jkczyz jkczyz Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I was thinking we wouldn't need to make a custom Router or use any additional storage for Offer registration. Instead, it would be something like:

  • Include LSPS2Bolt12InvoiceParameters in an Offer's blinded paths using MessageContext when building the Offer.
  • When InvoiceRequest is received, extract the parameters from the MessageContext if set.
  • Use them to determine how to build the BlindedPaymentPaths.

(Alternatively, given the InvoiceRequest contains the Offer's message paths, if the LSP is the introduction node, we can use that directly instead of storing it in the MessageContext. Then, we'd just need the intercept_scid and cltv_expiry_delta as additional data.)

For the last step, we could either (a) bypass the Router entirely and directly build the BlindedPaymentPath from the parameters, (b) pass Option<MessageContext> to Router and implement DefaultRouter to recognize it, or (c) something similar but with a different interface (e.g., passing Option<LSPS2Bolt12InvoiceParameters> instead).

We could use the IntroductionNode::DirectedShortChannelId directly in the BlindedPaymentPath, too, or look it up and use IntroductionNode::NodeId. I believe we currently support routing over the former but don't yet support creating them unlike for BlindedMessagePath.

Comment on lines +46 to +47
/// A router wrapper that injects LSPS2-specific BOLT12 blinded paths for registered offer ids
/// while delegating all other routing behavior to the inner routers.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should be more specific that this is for blinded path creation operations. Path finding is not affected.

Comment on lines +49 to +50
/// For **payment** blinded paths (in invoices), it injects the intercept SCID as the forwarding
/// hop so that the LSP can intercept the HTLC and open a JIT channel.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"injects" is probably not the right terminology. IIUC, it bypasses the wrapped router entirely, unlike the one for message paths.

///
/// [`OnionMessageInterceptor::register_scid_for_interception`]: lightning::onion_message::messenger::OnionMessageInterceptor::register_scid_for_interception
pub struct LSPS2BOLT12Router<R: Router, MR: MessageRouter, ES: EntropySource + Send + Sync> {
inner_router: R,
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wrapping NullMessageRouter essentially makes the wrapper a no-opt. That's fine since we can't support the "no blinded path" use case, but may not be obvious.

}
peer
})
.collect()
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No need to re-allocate. We can modify in-place instead.

@TheBlueMatt
Copy link
Copy Markdown
Collaborator

Ok, this could be a gap in my knowledge, but as mentioned in some of the comments, why do we need onion message interception for this?

If the peer is offline and we receive an invoice-request, we need to be able to use LSPS5 to send a notification to the client and wake them up to get them to respond.

@tnull tnull force-pushed the 2026-03-lsps2-bolt12-alt branch from e7047c5 to 8a2e30a Compare March 27, 2026 14:20
tnull added 3 commits March 27, 2026 15:41
We extend the `OnionMessenger` capabilities to also intercept onion
messages if they are for unknown SCIDs.

Co-Authored-By: HAL 9000
@tnull tnull force-pushed the 2026-03-lsps2-bolt12-alt branch 3 times, most recently from 88e98ae to ade41b1 Compare March 27, 2026 15:11
tnull added 2 commits March 27, 2026 16:12
Add `intercept_unknown_scid_oms` test that verifies the
`OnionMessenger` correctly generates `OnionMessageIntercepted` events
with a `ShortChannelId` next hop when a blinded path uses an
unresolvable SCID. This complements the existing
`intercept_offline_peer_oms` test which only covers the `NodeId`
variant (offline peer case).

Co-Authored-By: HAL 9000
@tnull tnull force-pushed the 2026-03-lsps2-bolt12-alt branch from ade41b1 to 8d04200 Compare March 27, 2026 15:12
tnull added 3 commits March 27, 2026 16:17
Add backwards compatibility tests for `Event::OnionMessageIntercepted`
serialization to verify that:

- Events serialized by LDK 0.2 (with `peer_node_id` in TLV field 0)
  can be deserialized by the current version as
  `NextMessageHop::NodeId`.
- Events with `NodeId` next hop serialized by the current version can
  be deserialized by LDK 0.2 (which reads `peer_node_id` from field
  0).
- Events with `ShortChannelId` next hop (which omit TLV field 0)
  correctly fail to deserialize in LDK 0.2, since the `peer_node_id`
  field is required there.

Co-Authored-By: HAL 9000
Introduce `LSPS2BOLT12Router` to map registered offers to LSPS2 invoice
parameters and build blinded payment paths through the negotiated
intercept `SCID`. All other routing behavior still delegates to the
wrapped router.

Co-Authored-By: HAL 9000
@tnull tnull force-pushed the 2026-03-lsps2-bolt12-alt branch from 8d04200 to 720e739 Compare March 27, 2026 15:17
tnull added 6 commits March 27, 2026 16:29
Signed-off-by: Elias Rohrer <dev@tnull.de>
Describe how `InvoiceParametersReady` feeds both the existing `BOLT11`
route-hint flow and the new `LSPS2BOLT12Router` registration path for
`BOLT12` offers.

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`.

Co-Authored-By: HAL 9000
Signed-off-by: Elias Rohrer <dev@tnull.de>
Allow tests to inject a custom `create_blinded_payment_paths` hook while
preserving the normal `ReceiveTlvs` bindings. This makes it possible to
exercise LSPS2-specific `BOLT12` path construction in integration tests.

Co-Authored-By: HAL 9000
Cover the full offer-payment flow from onion-message invoice exchange
through HTLC interception, JIT channel opening, and settlement. This
confirms the LSPS2 router and service handler work together in the
integrated path.

Co-Authored-By: HAL 9000
@tnull tnull force-pushed the 2026-03-lsps2-bolt12-alt branch from 720e739 to 5d6e7c4 Compare March 27, 2026 15:29
@tnull tnull requested a review from TheBlueMatt March 27, 2026 16:38
@ldk-reviews-bot
Copy link
Copy Markdown

🔔 1st Reminder

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Goal: Merge

Development

Successfully merging this pull request may close these issues.

BOLT 12 support for bLIP-52/LSPS2

5 participants