Support BOLT12 LSPS2 JIT-channel receives#990
Draft
tnull wants to merge 29 commits into
Draft
Conversation
|
👋 Hi! This PR is now in draft status. |
tnull
marked this pull request as draft
July 16, 2026 16:56
Prepare the LSPS2 client for dedicated state and storage modules. Co-Authored-By: HAL 9000
Track negotiated parameters as expiring leases so intercept identifiers cannot be reused across payments. Co-Authored-By: HAL 9000
Load cached leases in parallel at startup and remove entries that are expired or too close to expiry for safe reuse. Co-Authored-By: HAL 9000
Remove unusable leases hourly so persisted cache data cannot grow without bound. Co-Authored-By: HAL 9000
Persist negotiated parameters before making them available and consume them before constructing existing BOLT11 invoices. Co-Authored-By: HAL 9000
Prefer the cheapest eligible cached lease across configured LSPs and negotiate only when the cache has no suitable parameters. Co-Authored-By: HAL 9000
Delete an available lease from durable storage before removing its in-memory copy. A failed store removal now leaves the lease available for retry instead of allowing it to reappear only after restart. Co-Authored-By: HAL 9000
Build against the Rust Lightning revision providing deferred BOLT12 invoice responses and LSPS2 routing support. Keep manual invoice requests disabled until the node response handler lands. Co-Authored-By: HAL 9000
Retain long-lived JIT offer descriptors across restarts so invoice requests can negotiate fresh payment parameters independently of offer creation. Bound the registry with configurable LRU eviction and remove expired entries during startup and periodic maintenance. Co-Authored-By: HAL 9000
Build JIT offers with the standard node-addressed message paths and persist only a receive descriptor keyed by OfferId. This keeps offer validity independent from short-lived LSPS2 payment parameters and avoids contacting an LSP during offer construction. Co-Authored-By: HAL 9000
Move shared payment metadata out of the BOLT11 module. This lets other protocols reuse it without a BOLT11 dependency. Co-Authored-By: HAL 9000
Define metadata for single-use BOLT12 lease routing. Retain fee limits for payment-claim validation. Co-Authored-By: HAL 9000
Install the LSPS2-aware router in node construction. Allow BOLT12 responses to append negotiated JIT paths. Co-Authored-By: HAL 9000
Reuse one cached-or-negotiated lease path across invoice formats. Keep BOLT11 selection and fee-limit behavior unchanged. Co-Authored-By: HAL 9000
Consume one lease for each deferred JIT invoice response. Preserve normal offer responses while LSPS2 negotiation runs in a separate task. 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
After startup discovery, schedule refills for persisted BOLT12 offer descriptors. Reuse valid persisted leases and renegotiate only missing or stale cache entries. Co-Authored-By: HAL 9000
Retry transient LSPS2 request failures for foreground acquisition and background cache refills. Preserve immediate errors for fee limits and unavailable liquidity sources. Co-Authored-By: HAL 9000
Keep JIT offers independent of ephemeral LSPS2 leases and available when the receiver does not yet have any channels. Negotiate payment paths only after an invoice request arrives. Co-Authored-By: HAL 9000
Base proportional fee limits on the amount sent by the payer. The claimable amount excludes the LSP's withheld fee and otherwise rejects a valid fee at the configured limit. 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
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
Restart the selected provider after offer creation and prove that the variable-amount invoice request and JIT payment still complete. This retains the restart coverage from the earlier integration approach. Co-Authored-By: HAL 9000
Try the next eligible provider when a selected LSP rejects or times out during the buy request. Skip remaining fee-menu entries from a failed provider while preserving bounded whole-round retries. 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
tnull
force-pushed
the
2026-07-bolt12-lsps2-ng
branch
from
July 16, 2026 17:00
251706d to
27c34ef
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This adds LSPS2 JIT-channel support for long-lived BOLT12 offers without tying offers to expiring intercept SCIDs. LDK Node persists pending offers and safely reusable payment leases, restores sufficiently long-lived leases at startup, negotiates and replenishes them on demand, and consumes each lease at most once when responding to an invoice request. The same lease machinery is shared with BOLT11, including multi-LSP selection, retry and failover handling, and opening-fee validation.
Unlike #817 negotiated parameters are not embedded into an offer’s blinded message paths. Unlike #964 the implementation does not apply one globally cached parameter set to every BOLT12 receive (which is non-spec compliant and doesn't support fixed amount offers); leases are selected by LSP and payment mode or amount, consumed once, and refreshed independently while offers remain node-ID-addressed.
Based on https://git.rust-bitcoin.org/lightningdevkit/rust-lightning/pulls/4809