Add BOLT12 LSPS2 JIT receive support by tnull · Pull Request #999 · lightningdevkit/ldk-node

tnull · 2026-07-22T08:33:47Z

Based on https://git.rust-bitcoin.org/lightningdevkit/rust-lightning/pulls/4819.

This adds BOLT12 receive support over LSPS2 JIT channels using a node-local OffersMessageHandler and OffersMessageFlow. Offers retain ordinary blinded message paths and never contain an intercept SCID, allowing them to outlive individual PaymentLeases.

Single-use PaymentLeases are persisted through DataStore, while a bounded LRU persists fixed-amount and variable LeaseCacheTargets. Leases are restored and prefilled at startup, replenished after consumption, and periodically pruned when stale or close to expiry. Cache misses negotiate on demand with serialized requests, retries, and multi-LSP failover. BOLT11 uses the same cache.

Every BOLT12 offer is eligible for JIT fallback when LSPS2 is configured. We first try ordinary payment paths and omit the JIT path entirely when existing inbound liquidity is sufficient. Otherwise, we consume or negotiate a lease and include a JIT path constrained to the full payment amount. Fixed invoices advertise MPP, variable invoices disable it, and PaymentMetadata retains the fee policy needed to validate the LSP skim.

Potential follow-ups:

Currently we by-default include JIT paths whenever an LSPS2-enabled LSP is configured. Likewise, we're automatically auto-renegotiating leases. We should consider whether/how (read: best API) to give users more control here.

ldk-reviews-bot · 2026-07-22T08:33:50Z

👋 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-07-22T13:24:31Z

+			Ok(InvreqResponseInstructions::SendStaticInvoice { .. }) | Err(()) => return None,
+		};
+
+		let allow_mpp = invoice_request.amount().is_some();


Shouldn't this always be true for the first (non-LSP) attempt here?

Ah, yes, it seems for the first build_invoice call we'll want always true. Will add a fixup.

TheBlueMatt · 2026-07-22T13:25:59Z

+			Some(pending_request) => pending_request,
+			None => {
+				return Some((
+					OffersMessage::InvoiceError(InvoiceError::from_string(


Should we not consider duplicatively returning an existing LSPS2 cached negotiation here? In cases where the LSP over-allocated liquidity and we have enough for a second payment, or where we're getting DoS'd and most of the invreqs will not result in a payment, returning something might actually get us the payment.

FWIW if we do this it might be worth considering a marginally different router design, which might be cleaner - rather than deciding on which lease to use and then adding it to the metadata and using that metadata to tell the router what to inject, give the router a reference to the LSPS2 lease store and have it simply ask for the latest (potentially-unused) lease for a payment, then inject the metadata it wants.

Hmm, in my mind both of these fall in the category 'further optimizations', i.e., I'd lean towards taking a new look at them in a follow-up rather than trying to land all of it in this initial implementation.

In particular I had considered doing something along the line of what you describe in the second paragraph to avoid transferring all of the parameters via the payment metadata, but for simplicity's sake (though nothing is really simple here) for now opted to keep it in the metadata for now as that makes it at least easier to reason about compared to introducing yet-another side channel that could race if we're not super careful.

That's fine with me, I only raised it because it would likely imply a refactor of the router, so if we want to do that refactor ideally we should do it now rather than rewriting the code later. The feature itself would be nice but could be a followup.

jkczyz · 2026-07-29T04:42:37Z

+
+		let (negotiated_lease, min_total_fee_msat, cheapest_lsp) =
+			self.negotiate_fixed_lease(amount_msat, connection_manager).await?;
+		let lease = self.consume_lease(&negotiated_lease.id).await?;


Won't this re-fetch through valid() and reject the lease we just bought if its validity is under 24h? Likewise in acquire_variable_lease.

Done in cf21770

jkczyz · 2026-07-29T04:51:27Z

+			lease,
+			move |lease| async move { lease_store.remove(&lease.id).await },
+			|lease| {
+				self.lease_state.lock().expect("lock").remove(&lease.id);


Can't two concurrent requests both select the same lease? Both callers would get the same single-use intercept SCID.

jkczyz@70e350e

Hmm, good catch. It seems this is a regression as originally we had a slightly different design there that would have made this impossible. Will fix.

jkczyz · 2026-07-29T05:15:37Z

+			let _pending_request = pending_request;
+			let response =
+				lsps2_client.prepare_invoice_response(jit_request, connection_manager).await;
+			let (message, instructions) = match response {
+				Ok(JitInvoiceResponse { payment_metadata: jit_metadata, allow_mpp }) => {
+					debug_assert_eq!(allow_mpp, jit_request.allow_mpp());
+					let mut merged_metadata = payment_metadata.unwrap_or_default();
+					merged_metadata.extend(jit_metadata);
+					match build_invoice(
+						flow.as_ref(),
+						channel_manager.as_ref(),
+						keys_manager.as_ref(),
+						router.as_ref(),
+						secp_ctx.as_ref(),
+						&invoice_request,
+						Some(merged_metadata),
+						allow_mpp,
+						payment_info.as_ref(),
+					) {
+						Ok((invoice, context)) => (
+							OffersMessage::Invoice(invoice),
+							responder.respond_with_reply_path(context),
+						),
+						Err(error) => (
+							OffersMessage::InvoiceError(error.into_invoice_error()),
+							responder.respond(),
+						),
+					}
+				},


A payer may send many invoice requests (for robustness) but only pay one. Won't this cause us to acquire too many leases / is a DoS vector?

Well, discussed this quite a bit with Matt before. Yes, it's not ideal, but we'll have to make sure to not reuse leases/intercept SCIDs as otherwise subsequent payments will not trigger channel opens. This is unfortunately a limitation of the bLIP-52/LSPS2 spec that we can't really work around. One follow-up we could consider is to add rate-limiting and more user control, e.g., via an event-based flow in LDK Node (also see the TODO mentioned in OP).

jkczyz · 2026-07-29T05:27:09Z

+	}
+}
+
+fn build_invoice(


Ideally, LDK provides some abstraction so we don't need to repeat much of this logic.

Yeah, possibly, but at least for v0.3 that ship has sailed I'm afraid.

jkczyz · 2026-07-29T05:29:44Z

I had Claude review this and it came up with quite a few issues. I already left comments for ones that I was able to verify. But there some others here: https://gist.github.com/jkczyz/3324c2914601a2728605a49294f25bc9. Failing tests in this branch: https://github.com/jkczyz/ldk-node/tree/claude/pr-999-edge-cases-725f70

tnull · 2026-07-29T15:51:06Z

I had Claude review this and it came up with quite a few issues. I already left comments for ones that I was able to verify. But there some others here: https://gist.github.com/jkczyz/3324c2914601a2728605a49294f25bc9. Failing tests in this branch: https://github.com/jkczyz/ldk-node/tree/claude/pr-999-edge-cases-725f70

Still have to go through the list fully. Some seem valid, some bogus.

tnull · 2026-08-07T10:02:52Z

I had Claude review this and it came up with quite a few issues. I already left comments for ones that I was able to verify. But there some others here: https://gist.github.com/jkczyz/3324c2914601a2728605a49294f25bc9. Failing tests in this branch: https://github.com/jkczyz/ldk-node/tree/claude/pr-999-edge-cases-725f70

Still have to go through the list fully. Some seem valid, some bogus.

Addressed most of the points now. @jkczyz please let me know what you think.

tnull · 2026-08-07T10:05:00Z

Rebased to address minor conflicts.

Co-Authored-By: HAL 9000

Limit concurrently pending JIT invoice requests so an onion-message storm cannot create an unbounded number of lease negotiations. Hold a permit while requests wait for an offer lock or an LSP response. Co-Authored-By: HAL 9000

Keep built-in service parameters usable beyond the client cache safety margin so freshly negotiated leases are not rejected due to timing. Co-Authored-By: HAL 9000

Read fee limits from BOLT12 payment context metadata and reject unsupported withholding. Record accepted fees on inbound offer payments. Co-Authored-By: HAL 9000

Make same-amount and variable callers wait for one in-flight LSPS2 request, then recheck the shared cache before negotiating. Co-Authored-By: HAL 9000

Keep one usable lease ready after fixed or variable receive flows consume cached parameters. Foreground callers share the refill lock and reuse its result when it completes. Co-Authored-By: HAL 9000

Co-Authored-By: HAL 9000

After startup discovery, refill persisted fixed-amount and variable lease cache targets. Reuse valid leases and renegotiate only missing or stale entries so receiving can resume promptly after restart. Co-Authored-By: HAL 9000

Try the next eligible provider when a selected LSP rejects or times out, and retry bounded whole rounds for transient failures. Preserve immediate errors for fee limits and unavailable liquidity sources. Co-Authored-By: HAL 9000

Use resolved BOLT12 amounts to reject variable leases outside the payment range or total fee policy. Keep BOLT11 selection amountless until payment, while recording the exact BOLT12 fee limit. Co-Authored-By: HAL 9000

Co-Authored-By: HAL 9000

Treat the one-day margin as a cache policy while allowing freshly negotiated leases to cover only the invoice being built. Keep on-demand leases caller-owned and persist only leases intended for reuse. Co-Authored-By: HAL 9000

Co-Authored-By: HAL 9000

The margin test derived its boundary from the margin constant and only acquired cached leases, so it kept passing without any margin and with negotiation ignoring it. Use fixed offsets around the margin and also cover freshly negotiated fixed- and variable-amount leases. Co-Authored-By: HAL 9000

Cover fixed and variable BOLT12 offers through a real LSPS2 service. Verify node-ID offer addressing, fee withholding, fresh JIT channels, and the variable-amount single-path behavior. Co-Authored-By: HAL 9000

Extend the order-independent fee-selection scenario through a real BOLT12 payment. Also prove that BOLT11 consumption and BOLT12 response handling share the same replenished lease pool. Co-Authored-By: HAL 9000

Co-Authored-By: HAL 9000

Rebuild the receiver from its persisted store and pay the same long-lived offer again. Verify the pending offer survives and the exact cached lease is consumed before its replacement is negotiated. Co-Authored-By: HAL 9000

Pin the direct lease serialization format and ensure fixed-amount and variable-amount caches remain isolated. These focused checks complement the end-to-end BOLT11 and BOLT12 coverage. Co-Authored-By: HAL 9000

Only count inbound capacity from graph-known counterparties with usable forwarding parameters. Otherwise a direct-recipient fallback can hide the JIT path even though the payer cannot use that capacity. Co-Authored-By: HAL 9000

Inbound capacity only counted towards a direct recipient path if the counterparty's forwarding parameters also fit a blinded hop. Payers reach a direct path over the public graph though, where a large CLTV expiry delta is no obstacle, so such capacity was ignored and invoice creation failed without a lease despite sufficient public inbound. Only require the counterparty to advertise the channel. Co-Authored-By: HAL 9000

Co-Authored-By: HAL 9000

`UnifiedPayment::receive` applied `expiry_sec` only to the BOLT 11 invoice, while the BOLT 12 offer in the same URI never expired. Besides contradicting the documented meaning of the parameter, this left every unified receive needing a JIT channel with a permanent LSPS2 lease cache target, for which leases were re-negotiated indefinitely. Apply the expiry to the offer as well, so that all Lightning payment methods of a URI lapse together and lease cache targets registered for unified offers are pruned once the URI can no longer be paid. Co-Authored-By: HAL 9000

tnull · 2026-11-13T10:49:10Z

Possible directions: bound cached leases per LSP well below the LSP's limit, skip refills for one-off BOLT11 amounts, back off and retry on LSPS0_CLIENT_REJECTED instead of treating it as permanent, or shorten the validity window. Happy to split the LSP-side half into an upstream issue if that's useful.

We now skip refills for one-off BOLT11 amounts. Other than that it might make sense to address anything else as a follow-up, given this seems to be a never-ending PR if we try to address all edge cases from the start.

jkczyz

LGTM. Just some minor comments, but feel free to squash.

🤖 Two commit messages worth adjusting when squashing, both made stale by the refill removal: "Refill consumed payment leases" still says a lease is kept ready after fixed or variable receive flows consume cached parameters (now only registered BOLT12 targets are refilled), and "Test multi-LSP BOLT12 selection" still says the test proves BOLT11 consumption and BOLT12 response handling share the same replenished lease pool.

jkczyz · 2026-11-13T15:50:03Z

+	///
+	/// This limit applies to all configured LSPS2 liquidity sources in addition to the fee negotiated
+	/// for a payment. Once the payment amount is known, fees exceeding it are never accepted, whether
+	/// or not this limit is set. If unset, payments of a yet unknown amount use the negotiated


🤖 "payments of a yet unknown amount" is now too narrow: after the last fixup, a variable-amount BOLT12 payment also uses the negotiated proportional fee as its limit even though its amount is known, because the payer may deliver more than requested. Maybe "payments over variable-amount leases"?

jkczyz · 2026-11-13T15:51:20Z

 						return Ok(());
 					};

 					if counterparty_skimmed_fee_msat > max_total_opening_fee_msat {


🤖 Neither refusal branch here has a test: the allowance computation is unit-tested, but nothing drives a claim into fail_claimable_payment — not a skim exceeding the allowance, and not a skimmed payment without the LSPS2 metadata. An LSP withholding more than negotiated is the case this limit exists to catch, so it'd be good to see the refusal actually fire. Fine as a follow-up if staging a misbehaving LSP is too awkward here.

This was referenced Jul 22, 2026

Support BOLT12 LSPS2 JIT-channel receives #990

Closed

Add BOLT12 support to LSPS2 flow #817

Closed

BOLT12 LSPS2 Support via persisted BOLT12 state #964

Closed

Cache LSPS2 get_info responses #977

Closed

tnull requested review from TheBlueMatt and jkczyz July 22, 2026 08:43

tnull force-pushed the 2026-07-bolt12-lsps2-ng-alt branch 3 times, most recently from fc05da7 to badf902 Compare July 22, 2026 09:41

tnull added this to the 0.8 milestone Jul 22, 2026

tnull force-pushed the 2026-07-bolt12-lsps2-ng-alt branch 2 times, most recently from f83b7ed to f872ce4 Compare July 22, 2026 12:54

TheBlueMatt reviewed Jul 22, 2026

View reviewed changes

tnull force-pushed the 2026-07-bolt12-lsps2-ng-alt branch from f872ce4 to 621fd3d Compare July 28, 2026 13:22

jkczyz reviewed Jul 29, 2026

View reviewed changes

tnull force-pushed the 2026-07-bolt12-lsps2-ng-alt branch 2 times, most recently from b6c726d to 7d4f5be Compare July 29, 2026 15:12

tnull requested a review from jkczyz July 29, 2026 15:14

Jolah1 mentioned this pull request Aug 3, 2026

Consider setting min_value_msat in LSPS2's create_inbound_payment #609

Closed

tnull force-pushed the 2026-07-bolt12-lsps2-ng-alt branch from 7d4f5be to 7b456df Compare August 7, 2026 09:59

tnull force-pushed the 2026-07-bolt12-lsps2-ng-alt branch from 7b456df to 03260f1 Compare August 7, 2026 10:04

tnull force-pushed the 2026-07-bolt12-lsps2-ng-alt branch 2 times, most recently from 27c34ef to f56fa41 Compare August 10, 2026 09:59

f3r10 mentioned this pull request Aug 10, 2026

PoC: bolt12 lsps2 jit f3r10/lightning-ecommerce#65

Open

6 tasks

tnull added 26 commits November 13, 2026 11:07

f Cap targets of long-lived offers too

1e5c462

Co-Authored-By: HAL 9000

f Stop passing the lease expiry to the router

daeae83

Co-Authored-By: HAL 9000

bolt12: Bound pending JIT requests

5a5cba1

Limit concurrently pending JIT invoice requests so an onion-message storm cannot create an unbounded number of lease negotiations. Hold a permit while requests wait for an offer lock or an LSP response. Co-Authored-By: HAL 9000

lsps2: Extend opening parameter validity

aa47049

Keep built-in service parameters usable beyond the client cache safety margin so freshly negotiated leases are not rejected due to timing. Co-Authored-By: HAL 9000

bolt12: Validate LSPS2 opening fees

20707d0

Read fee limits from BOLT12 payment context metadata and reject unsupported withholding. Record accepted fees on inbound offer payments. Co-Authored-By: HAL 9000

lsps2: Serialize lease negotiation

9ead31f

Make same-amount and variable callers wait for one in-flight LSPS2 request, then recheck the shared cache before negotiating. Co-Authored-By: HAL 9000

lsps2: Refill consumed payment leases

4e592ea

Keep one usable lease ready after fixed or variable receive flows consume cached parameters. Foreground callers share the refill lock and reuse its result when it completes. Co-Authored-By: HAL 9000

f Persist dropped cache targets after their leases

9f3a4a7

Co-Authored-By: HAL 9000

f Skip refills after BOLT11 receives

816bfc2

Co-Authored-By: HAL 9000

lsps2: Restore cached payment leases

0d4d6c8

After startup discovery, refill persisted fixed-amount and variable lease cache targets. Reuse valid leases and renegotiate only missing or stale entries so receiving can resume promptly after restart. Co-Authored-By: HAL 9000

lsps2: Retry lease negotiation failures

505e654

Try the next eligible provider when a selected LSP rejects or times out, and retry bounded whole rounds for transient failures. Preserve immediate errors for fee limits and unavailable liquidity sources. Co-Authored-By: HAL 9000

lsps2: Match variable leases to payments

10e99fe

Use resolved BOLT12 amounts to reject variable leases outside the payment range or total fee policy. Keep BOLT11 selection amountless until payment, while recording the exact BOLT12 fee limit. Co-Authored-By: HAL 9000

f Test fee caps of negotiated leases

b0f0fe7

Co-Authored-By: HAL 9000

f Bound variable BOLT12 fees by the lease rate

21451d9

Co-Authored-By: HAL 9000

lsps2: Separate cache lease validity

c3379f6

Treat the one-day margin as a cache policy while allowing freshly negotiated leases to cover only the invoice being built. Keep on-demand leases caller-owned and persist only leases intended for reuse. Co-Authored-By: HAL 9000

f Leave a margin between invoice and lease expiry

624f3b8

Co-Authored-By: HAL 9000

lsps2: Test BOLT12 JIT payments

e6cd599

Cover fixed and variable BOLT12 offers through a real LSPS2 service. Verify node-ID offer addressing, fee withholding, fresh JIT channels, and the variable-amount single-path behavior. Co-Authored-By: HAL 9000

lsps2: Test multi-LSP BOLT12 selection

9a8eaa8

Extend the order-independent fee-selection scenario through a real BOLT12 payment. Also prove that BOLT11 consumption and BOLT12 response handling share the same replenished lease pool. Co-Authored-By: HAL 9000

f Describe the multi-LSP test without a refill

bb6a65a

Co-Authored-By: HAL 9000

lsps2: Test restored BOLT12 leases

d190f5b

Rebuild the receiver from its persisted store and pay the same long-lived offer again. Verify the pending offer survives and the exact cached lease is consumed before its replacement is negotiated. Co-Authored-By: HAL 9000

lsps2: Test payment lease state

4f67c28

Pin the direct lease serialization format and ensure fixed-amount and variable-amount caches remain isolated. These focused checks complement the end-to-end BOLT11 and BOLT12 coverage. Co-Authored-By: HAL 9000

lsps2: Filter direct fallback capacity

6156a23

Only count inbound capacity from graph-known counterparties with usable forwarding parameters. Otherwise a direct-recipient fallback can hide the JIT path even though the payer cannot use that capacity. Co-Authored-By: HAL 9000

f Drop the lease expiry from fallback tests

51413fc

Co-Authored-By: HAL 9000

tnull requested a review from jkczyz November 13, 2026 10:49

tnull force-pushed the 2026-07-bolt12-lsps2-ng-alt branch from 68ee684 to 4213056 Compare November 13, 2026 10:52

jkczyz reviewed Nov 13, 2026

View reviewed changes

Conversation

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

Uh oh!

Potential follow-ups:

Uh oh!

ldk-reviews-bot commented Jul 22, 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!

Choose a reason for hiding this comment

Uh oh!

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!

jkczyz commented Jul 29, 2026

Uh oh!

tnull commented Jul 29, 2026

Uh oh!

tnull commented Aug 7, 2026

Uh oh!

tnull commented Aug 7, 2026

Uh oh!

tnull commented Nov 13, 2026

Uh oh!

jkczyz 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!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

tnull commented Jul 22, 2026 •

edited

Loading

ldk-reviews-bot commented Jul 22, 2026 •

edited

Loading