Add BOLT12 support to LSPS2 via custom Router implementation

[tnull]

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]

👋 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]

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

[tnull]

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

[TheBlueMatt]

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.

[tnull]

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.

[TheBlueMatt]

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.

[TheBlueMatt]

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

[tnull]

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.

[TheBlueMatt]

I think claude is confused. Looking at BOLT12 async payments, for example the path where we build a static invoice when handling an offer path (<ChannelManager as AsyncPaymentsMessageHandler>::handle_offer_paths) we call self.flow.handle_offer_paths(... &*self.router) which calls create_static_invoice_for_server(...router) which calls create_static_invoice_builder(&router...) which calls the same create_blinded_payments_path that is used for every other bolt12 invoice. As long as the router passed through that recognizes the PaymentContext::AsyncBolt12Offer I don't see why it wouldn't work.

[tnull]

It indeed just admitted to me being wrong here. Now have it write a test case for async payments to see what would be necessary to actually get it to work.

[tnull]

Now explored in tnull@b484c6a

[ldk-reviews-bot]

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

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

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.

[tnull]

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

[jkczyz]

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.

[tnull]

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?

[jkczyz]

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]

Hmm, I'm still a bit skeptical regarding the size constraint, especially since we might end up mixing BOLT11, BOLT12 and onchain data in a single QR-encoded BIP21.

It seems this would mostly be useful to avoid the client having to store anything about the JIT-request? But note they already do (i.e., the negotiated LSP fees, so they can check the LSP didn't withhold more when the payment arrives), so it should be fine to also store an additional OfferId? Is there another benefit I'm not seeing?

[jkczyz]

Hmm, I'm still a bit skeptical regarding the size constraint, especially since we might end up mixing BOLT11, BOLT12 and onchain data in a single QR-encoded BIP21.

The alternative approach limits it to 10 bytes per blinded path, plus encoding overhead, FWIW.

It seems this would mostly be useful to avoid the client having to store anything about the JIT-request? But note they already do (i.e., the negotiated LSP fees, so they can check the LSP didn't withhold more when the payment arrives), so it should be fine to also store an additional OfferId? Is there another benefit I'm not seeing?

Is there any reason that data can't be store in the BlindedPaymentPath's ReceiveTlvs / PaymentContext? That data should have been authenticated.

This approach also avoids the behavior around wrapping a MessageRouter / Router, which isn't obvious.

[tnull]

Is there any reason that data can't be store in the BlindedPaymentPath's ReceiveTlvs / PaymentContext? That data should have been authenticated.

Well, yes, for one we also store it in the BOLT11 case which doesn't have those options available?

This approach also avoids the behavior around wrapping a MessageRouter / Router, which isn't obvious.

I guess it would also allow us to more easily resolve the current conflict with async payments, as noted above? #4463 (comment).

It seems this approach would then in parts go back to the approach of #4394, i.e., if we want to get rid of the Router/MessageRouter wrapper we'd need to surface an InvoiceRequestReceived event that the LSPS2-specific logic could act upon?

[tnull]

Now had Claude whip up some commits switching to that approach so we can decide whether we want to go there. Indeed it seems that we're able to drop the custom router wrapper and get async payments to work. Let me know what you think

[jkczyz]

It seems this would mostly be useful to avoid the client having to store anything about the JIT-request? But note they already do (i.e., the negotiated LSP fees, so they can check the LSP didn't withhold more when the payment arrives), so it should be fine to also store an additional OfferId? Is there another benefit I'm not seeing?

Regarding the negotiated LSP fees, where do we check the LSP didn't hold too much? To make it stateless, would we need to store the expected fees in the opaque data such that it could be included in the BlindedPaymentPath?

[ldk-claude-review-bot]

All significant issues in this PR were already flagged in prior review passes. No new bugs or security issues found in this pass.

Review Summary

Prior issues still open (not re-posted as inline comments)

All of the following were posted in previous review passes and remain relevant:

1. lightning-liquidity/src/lsps2/router.rs:52-55 — Doc comment for message blinded paths references Event::HTLCIntercepted and describes "HTLC arrives" — should be Event::OnionMessageIntercepted and "onion message arrives"
2. lightning-liquidity/src/lsps2/router.rs:58 — Broken rustdoc link to non-existent OnionMessageInterceptor::register_scid_for_interception
3. lightning-liquidity/src/lsps2/router.rs:63 — Rustdoc link definition only defines Event::HTLCIntercepted, missing Event::OnionMessageIntercepted
4. lightning-liquidity/src/lsps2/router.rs:175-215 — ? operator in loop discards all previously accumulated valid paths (inner router + earlier LSPS2 paths) when any single registration fails; should continue instead
5. lightning-liquidity/src/lsps2/router.rs:236-237 — Code comment says "emit Event::HTLCIntercepted" but this is the MessageRouter impl; should be Event::OnionMessageIntercepted
6. lightning-liquidity/src/lsps2/router.rs:243 — params.values().find() by counterparty_node_id non-deterministically collapses multiple registrations for the same LSP
7. lightning/src/events/mod.rs:2968 — Grammar: "should always been set" → "should always be set"

No new issues found in this pass

The serialization backward/forward compatibility for OnionMessageIntercepted (event 37) is well-implemented:

• NextMessageHop TLV encoding is correct (field 1, odd = skippable by LDK 0.2)
• NodeId variant writes field 0 for LDK 0.2 compat
• ShortChannelId variant intentionally omits field 0 (correctly fails on LDK 0.2, which can't handle SCID-only events)
• Events are not persisted, so downgrade data loss is limited to in-flight events

The SCID-based onion message interception in OnionMessenger::enqueue_forwarded_onion_message is correct and well-tested via functional tests and integration tests.

[codecov]

Codecov Report

❌ Patch coverage is 77.89116% with 65 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.10%. Comparing base (12edb7d) to head (3ada94e).
⚠️ Report is 44 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning/src/offers/flow.rs	26.31%	42 Missing ⚠️
lightning/src/events/mod.rs	20.00%	11 Missing and 1 partial ⚠️
lightning-liquidity/src/lsps2/router.rs	96.90%	1 Missing and 5 partials ⚠️
lightning/src/offers/invoice_request.rs	0.00%	3 Missing ⚠️
lightning/src/onion_message/messenger.rs	81.81%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4463      +/-   ##
==========================================
+ Coverage   86.20%   87.10%   +0.90%     
==========================================
  Files         160      164       +4     
  Lines      107545   109018    +1473     
  Branches   107545   109018    +1473     
==========================================
+ Hits        92707    94958    +2251     
+ Misses      12214    11570     -644     
+ Partials     2624     2490     -134     

Flag	Coverage Δ
fuzzing	40.11% <0.00%> (?)
tests	86.19% <77.89%> (-0.01%)	⬇️

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.

[jkczyz]

Couldn't the same point me made for the Rotuer implementation?

I don't have a strong opinion on the approach yet, though I do wonder if instead of wrapping we have the user explicitly pass a custom MessageRouter when creating the Offer. They can't easily do the same for payment paths without overriding OffersMessageHandler behavior (i.e., they would need to implement it with custom logic for OffersMessageFlow). But that could be avoided with the alternative mentioned in https://github.com/lightningdevkit/rust-lightning/pull/4463/changes#r2997527775.

[jkczyz]

Partly, yes, but also because we later cast it to u16 using u16::try_from.

[jkczyz]

Hmm, I'm still a bit skeptical regarding the size constraint, especially since we might end up mixing BOLT11, BOLT12 and onchain data in a single QR-encoded BIP21.

The alternative approach limits it to 10 bytes per blinded path, plus encoding overhead, FWIW.

It seems this would mostly be useful to avoid the client having to store anything about the JIT-request? But note they already do (i.e., the negotiated LSP fees, so they can check the LSP didn't withhold more when the payment arrives), so it should be fine to also store an additional OfferId? Is there another benefit I'm not seeing?

Is there any reason that data can't be store in the BlindedPaymentPath's ReceiveTlvs / PaymentContext? That data should have been authenticated.

This approach also avoids the behavior around wrapping a MessageRouter / Router, which isn't obvious.

[jkczyz]

Ah, sorry meant to say NodeIdMessageRouter.

[jkczyz]

Note that when wrapping NodeIdMessageRouter this will be overridden with None. But why do we inject the intercept_scid?

Hmm, that's fine, assuming it still works when we do the override here?

We are delegating to the wrapped router after this override, so no it will be cleared.

[ldk-claude-review-bot]

Bug: Event number 48 is even, breaking backward compatibility if serialized.

All other "never persisted, no body" events use odd numbers (ConnectionNeeded=35, PersistStaticInvoice=45, StaticInvoiceRequested=47, FundingTransactionReadyForSigning=49). Odd numbers are important because the deserialization catch-all at line 3103 skips unknown odd events, while unknown even events at line 3115 return Err(DecodeError::InvalidValue).

InvoiceRequestReceived is pushed to self.pending_events in channelmanager.rs:16973, which IS serialized during ChannelManager persistence (lines 18126-18129). If the ChannelManager is persisted while this event is pending (between push and handler consumption), 48u8 is written to the byte stream. An older version that doesn't recognize event 48 will fail the entire ChannelManager deserialization.

Should use an odd number (e.g., 53 or the next available odd) for consistency and forward safety. Note that even with an odd number, the missing TLV body is a pre-existing pattern issue (same as events 45, 47), but at least the older reader would attempt to skip rather than hard-fail.

[tnull]

Yes, we should change that if we really move forward with the DRAFT commits.

[ldk-claude-review-bot]

Minor: from_context_data does not check that all bytes were consumed. If data has trailing bytes beyond the expected 45 (33 pubkey + 8 u64 + 4 u32), they are silently ignored. This means slightly-corrupt or version-mismatched data could parse successfully into potentially wrong parameters.

Consider adding:

Suggested change

	pub fn from_context_data(data: &[u8]) -> Option<Self> {
	let mut cursor = lightning::io::Cursor::new(data);
	Self::read(&mut cursor).ok()
	}
	pub fn from_context_data(data: &[u8]) -> Option<Self> {
	let mut cursor = lightning::io::Cursor::new(data);
	let result = Self::read(&mut cursor).ok()?;
	if cursor.position() as usize != data.len() {
	return None;
	}
	Some(result)
	}

If forward extensibility is intentional (future versions may append fields), then this is fine as-is but should be documented.

[jkczyz]

We could probably use the existing methods, having the caller pass a custom Router.

[jkczyz]

We could also take this from Offer::paths if they are expected to use the LSP as the introduction node.

That said, I'm not sure how much savings we care about in terms of QR size. Would these offers typically be behind a HBA (or hopefully would be in the future)?

[jkczyz]

Actually I did mean NullMessageRouter. It produces no paths, so requires that the offer's issuer_signing_pubkey is its node id.

[jkczyz]

It seems this would mostly be useful to avoid the client having to store anything about the JIT-request? But note they already do (i.e., the negotiated LSP fees, so they can check the LSP didn't withhold more when the payment arrives), so it should be fine to also store an additional OfferId? Is there another benefit I'm not seeing?

Regarding the negotiated LSP fees, where do we check the LSP didn't hold too much? To make it stateless, would we need to store the expected fees in the opaque data such that it could be included in the BlindedPaymentPath?

[ldk-reviews-bot]

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

[ldk-claude-review-bot]

Bug: ? in loop discards all previously accumulated paths on partial failure.

If multiple LSPS2 params are registered and one has an invalid CLTV delta (line 176) or BlindedPaymentPath::new fails (line 213), the ? operator returns Err(()) for the entire function. This discards:

1. Valid paths from the inner router (collected at lines 161-171)
2. Valid LSPS2 paths from earlier loop iterations

For example, with two registered SCIDs where the second has cltv_expiry_delta > u16::MAX, the first SCID's valid path and any inner router paths are all lost.

Consider skipping invalid registrations with continue instead of ?:

Suggested change

	for lsps2_invoice_params in all_params {
	let payment_relay = PaymentRelay {
	cltv_expiry_delta: u16::try_from(lsps2_invoice_params.cltv_expiry_delta)
	.map_err(|_| ())?,
	fee_proportional_millionths: 0,
	fee_base_msat: 0,
	};
	let payment_constraints = PaymentConstraints {
	max_cltv_expiry: tlvs
	.payment_constraints
	.max_cltv_expiry
	.saturating_add(lsps2_invoice_params.cltv_expiry_delta),
	htlc_minimum_msat: 0,
	};
	let forward_node = PaymentForwardNode {
	tlvs: ForwardTlvs {
	short_channel_id: lsps2_invoice_params.intercept_scid,
	payment_relay,
	payment_constraints,
	features: BlindedHopFeatures::empty(),
	next_blinding_override: None,
	},
	node_id: lsps2_invoice_params.counterparty_node_id,
	htlc_maximum_msat: u64::MAX,
	};
	// We deliberately use `BlindedPaymentPath::new` without dummy hops here. Since
	// the LSP is the introduction node and already knows the recipient, adding dummy
	// hops would not provide meaningful privacy benefits in the LSPS2 JIT channel
	// context.
	let path = BlindedPaymentPath::new(
	&[forward_node],
	recipient,
	local_node_receive_key,
	tlvs.clone(),
	u64::MAX,
	MIN_FINAL_CLTV_EXPIRY_DELTA,
	&self.entropy_source,
	secp_ctx,
	)?;
	paths.push(path);
	}
	for lsps2_invoice_params in all_params {
	let payment_relay = match u16::try_from(lsps2_invoice_params.cltv_expiry_delta) {
	Ok(cltv_expiry_delta) => PaymentRelay {
	cltv_expiry_delta,
	fee_proportional_millionths: 0,
	fee_base_msat: 0,
	},
	Err(_) => continue,
	};
	let payment_constraints = PaymentConstraints {
	max_cltv_expiry: tlvs
	.payment_constraints
	.max_cltv_expiry
	.saturating_add(lsps2_invoice_params.cltv_expiry_delta),
	htlc_minimum_msat: 0,
	};
	let forward_node = PaymentForwardNode {
	tlvs: ForwardTlvs {
	short_channel_id: lsps2_invoice_params.intercept_scid,
	payment_relay,
	payment_constraints,
	features: BlindedHopFeatures::empty(),
	next_blinding_override: None,
	},
	node_id: lsps2_invoice_params.counterparty_node_id,
	htlc_maximum_msat: u64::MAX,
	};
	// We deliberately use `BlindedPaymentPath::new` without dummy hops here. Since
	// the LSP is the introduction node and already knows the recipient, adding dummy
	// hops would not provide meaningful privacy benefits in the LSPS2 JIT channel
	// context.
	let path = match BlindedPaymentPath::new(
	&[forward_node],
	recipient,
	local_node_receive_key,
	tlvs.clone(),
	u64::MAX,
	MIN_FINAL_CLTV_EXPIRY_DELTA,
	&self.entropy_source,
	secp_ctx,
	) {
	Ok(path) => path,
	Err(()) => continue,
	};
	paths.push(path);
	}

Alternatively, validate cltv_expiry_delta in register_intercept_scid so the error can't happen here.

[tnull]

Now updated to not register for onion message interception based on OfferId, but rather intercept scid. Plus we now merge the blinded paths with the ones returned from the inner router, so, in case we have pre-existing channels, only if the payer happens to choose the JIT path the channel will be opened. Will play around with this more on the LDK Node side, and play some more Claude-ping-pong here tomorrow. But would love some conceptual review at least (cc @TheBlueMatt @jkczyz)