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

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

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

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.

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

No issues found.

I re-reviewed the full current state of the PR at head commit a83d765. The production code in this PR — lsps2/router.rs (new), lsps2/event.rs, lsps2/msgs.rs, and lsps2/service.rs — is identical to the design I reviewed clean in prior passes, and the integration tests now use u16 consistently throughout (the earlier type-mismatch concern is resolved).

What I verified this pass:

router.rs — create_blinded_payment_paths is correct: async-offer early Err(()) guard, delegates to the inner router, appends LSPS2 paths with continue on BlindedPaymentPath::new failure, guards an empty path set with Err(()), and grows max_cltv_expiry by the forwarding delta in the correct direction. cltv_expiry_delta is u16, so the as u32 in saturating_add is lossless. The () and Fn blanket decoder impls don't conflict.
u32→u16 narrowing is consistent across LSPS2ClientEvent, the LSPS2BuyResponse wire struct, the service API, and the tests; it aligns with PaymentRelay.cltv_expiry_delta (u16) and the BOLT route-hint width.
pending_changelog/4463-LSPS2-BOLT12.txt has been rewritten and now correctly references OnionMessenger::new_with_offline_peer_interception and makes an accurate, scoped backward-compat claim (manually-persisted OnionMessageIntercepted events carrying NextMessageHop::ShortChannelId fail to deserialize on older versions). This addresses my prior changelog comment.
Security: decoded payment metadata is authored by the recipient and authenticated via the offer/reply-path context HMAC, so a payer cannot inject malicious LSP parameters.

One low-confidence observation I deliberately did not file (consistent with prior passes): router.rs:240 uses plain MIN_FINAL_CLTV_EXPIRY_DELTA, whereas the BOLT11 route-hint path uses MIN_FINAL_CLTV_EXPIRY_DELTA + 2. The end-to-end test (bolt12_lsps2_end_to_end_test) completes with the client claiming, so the plain value is functionally sufficient for the blinded-path case and this is not a demonstrable defect.

No inline comments posted this pass.

codecov · 2026-03-24T16:53:41Z

Codecov Report

❌ Patch coverage is 88.38174% with 56 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.13%. Comparing base (2313bd5) to head (4342483).
⚠️ Report is 169 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning-liquidity/src/lsps2/router.rs	93.39%	27 Missing ⚠️
lightning/src/ln/channelmanager.rs	32.00%	16 Missing and 1 partial ⚠️
lightning/src/events/mod.rs	33.33%	5 Missing and 1 partial ⚠️
lightning/src/offers/flow.rs	66.66%	2 Missing and 1 partial ⚠️
lightning/src/onion_message/messenger.rs	86.66%	2 Missing ⚠️
lightning/src/util/test_utils.rs	92.30%	1 Missing ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #4463 +/- ##
==========================================
+ Coverage 87.08% 87.13% +0.04% 
==========================================
Files 161 162 +1 Lines 109255 109707 +452 Branches 109255 109707 +452 ==========================================
+ Hits 95147 95589 +442 - Misses 11627 11632 +5 - Partials 2481 2486 +5

Flag	Coverage Δ
fuzzing-fake-hashes	`31.10% <7.35%> (+0.12%)`	⬆️
fuzzing-real-hashes	`22.79% <4.41%> (+0.13%)`	⬆️
tests	`86.20% <88.38%> (+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.

ldk-reviews-bot · 2026-06-13T11:36:47Z

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

ldk-reviews-bot · 2026-06-15T11:37:38Z

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

Let BOLT12 blinded payment paths include LSPS2 parameters decoded from payment metadata, so JIT-channel paths work without router state for the intercepted SCID. Co-Authored-By: HAL 9000

Fail async static-invoice path creation when no LSPS2 metadata exists. This prevents automatic refreshes from uploading unusable invoices. Co-Authored-By: HAL 9000

Allow offer metadata maps to key entries directly by offer id without wrapping the identifier. Co-Authored-By: HAL 9000

Let async recipients refresh receive offers explicitly, wait for readiness, and preserve payment metadata across static-invoice refreshes. Co-Authored-By: HAL 9000

Return a completed future when an async receive offer is already ready. Drop redundant public wrappers now covered by lower-level APIs. Co-Authored-By: HAL 9000

ldk-reviews-bot · 2026-06-17T11:38:31Z

🔔 4th Reminder

Hey @TheBlueMatt @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-06-20T00:00:32Z

🔔 5th Reminder

Hey @TheBlueMatt @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-06-20T00:00:46Z

🔔 1st Reminder

Hey @TheBlueMatt @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-06-22T00:01:43Z

🔔 6th Reminder

Hey @TheBlueMatt @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-06-22T00:01:57Z

🔔 2nd Reminder

Hey @TheBlueMatt @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-06-24T00:02:54Z

🔔 7th Reminder

Hey @TheBlueMatt @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-06-24T00:03:00Z

🔔 3rd Reminder

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

Co-Authored-By: HAL 9000

Align LSPS2 CLTV deltas with the wire format and LDK routing types. Co-Authored-By: HAL 9000

Clarify how LSPS2 invoice parameters relate to BOLT11 route hints and BOLT12 blinded payment path creation. Co-Authored-By: HAL 9000

Let integration tests force specific blinded payment paths, so LSPS2 BOLT12 routing behavior can be exercised deterministically. Co-Authored-By: HAL 9000

Exercise decoder-provided LSPS2 parameters across custom-router, end-to-end, compact message path, and async-payment BOLT12 flows. Co-Authored-By: HAL 9000

Assert no static invoice is uploaded before LSPS2 metadata is ready. Keep LSPS2 integration tests compiling with current upstream types. Co-Authored-By: HAL 9000

Record the new LSPS2 BOLT12 routing support and its compatibility note for the next release notes. Co-Authored-By: HAL 9000

ldk-reviews-bot · 2026-06-27T00:00:18Z

🔔 8th Reminder

Hey @TheBlueMatt @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-07-03T20:34:25Z

Hi @tnull,

Thanks for your contributions to rust-lightning!

After too many struggles with bugs, outages, contributor bans, and, finally, a multi-week CI ban, the rust-lightning project is moving off of GitHub for day-to-day development.

You can still file issues and access the git tree here, but PRs will now take place exclusively at https://git.rust-bitcoin.org/. As such, this PR has been migrated to https://git.rust-bitcoin.org/lightningdevkit/rust-lightning/pulls/4463

If you log in using GitHub (or otherwise link your GitHub account from https://git.rust-bitcoin.org/user/settings/security), ownership of your PRs, issues, and comments will automatically transfer. To push updates to this PR, you'll need to use git push git@gitea-ssh.bitcoin.ninja:lightningdevkit/rust-lightning YOUR_LOCAL_COMMIT_OR_BRANCH:tnull/2026-03-lsps2-bolt12-alt. This may require a permissions change - if it doesn't work initially just leave a comment and we'll get you access.

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 25ab3bcCompare March 5, 2026 14:05

TheBlueMatt reviewed Mar 5, 2026
View reviewed changes

Comment threadlightning/src/onion_message/messenger.rs Outdated
Comment threadlightning-liquidity/src/lsps2/router.rs Outdated
Comment threadlightning/src/onion_message/messenger.rs Outdated

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

Comment threadlightning-liquidity/src/lsps2/router.rs

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

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

Comment threadlightning-liquidity/src/lsps2/service.rs Outdated

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

Comment threadlightning-liquidity/src/lsps2/router.rs Outdated

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

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

Comment threadlightning-liquidity/src/lsps2/service.rs Outdated

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

Comment threadlightning-liquidity/tests/lsps2_integration_tests.rs Outdated

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

tnull force-pushed the 2026-03-lsps2-bolt12-alt branch from 7ca886d to 2ff16d7Compare March 25, 2026 08:23

ldk-claude-review-bot reviewed Mar 25, 2026
View reviewed changes

Comment threadlightning-liquidity/src/lsps2/service.rs Outdated

tnull force-pushed the 2026-03-lsps2-bolt12-alt branch 4 times, most recently from bcc4e10 to 5602e07Compare March 25, 2026 12:27

ldk-claude-review-bot reviewed Mar 25, 2026
View reviewed changes

Comment threadlightning-liquidity/src/lsps2/service.rs Outdated

tnull force-pushed the 2026-03-lsps2-bolt12-alt branch 2 times, most recently from ea05389 to 3acf915Compare March 25, 2026 13:24

tnull mentioned this pull request Jun 11, 2026
Report the sending peer in Event::OnionMessageIntercepted#4682
Merged

tnull added 5 commits June 17, 2026 09:07

Add an LSPS2-aware BOLT12 router wrapper
afcc599
Let BOLT12 blinded payment paths include LSPS2 parameters decoded from payment metadata, so JIT-channel paths work without router state for the intercepted SCID. Co-Authored-By: HAL 9000

f - Reject invalid async LSPS2 static invoices
92c14f4
Fail async static-invoice path creation when no LSPS2 metadata exists. This prevents automatic refreshes from uploading unusable invoices. Co-Authored-By: HAL 9000

Derive Hash for OfferId
fd5bbd6
Allow offer metadata maps to key entries directly by offer id without wrapping the identifier. Co-Authored-By: HAL 9000

Add async offer refresh readiness APIs
1bbfd6f
Let async recipients refresh receive offers explicitly, wait for readiness, and preserve payment metadata across static-invoice refreshes. Co-Authored-By: HAL 9000

f - Make async offer readiness race-free
ab50d44
Return a completed future when an async receive offer is already ready. Drop redundant public wrappers now covered by lower-level APIs. Co-Authored-By: HAL 9000

tnull force-pushed the 2026-03-lsps2-bolt12-alt branch from 26da1dd to abdecc2Compare June 17, 2026 10:30

tnull requested a review from TheBlueMatt June 17, 2026 10:35

TheBlueMatt reviewed Jun 25, 2026
View reviewed changes

Comment threadlightning/src/ln/channelmanager.rs

tnull added 7 commits June 26, 2026 16:18

f - Document async metadata refresh
59ace37
Co-Authored-By: HAL 9000

Make cltv_expiry_delta u16
3fc208c
Align LSPS2 CLTV deltas with the wire format and LDK routing types. Co-Authored-By: HAL 9000

Document the LSPS2 BOLT12 router flow
1b361e1
Clarify how LSPS2 invoice parameters relate to BOLT11 route hints and BOLT12 blinded payment path creation. Co-Authored-By: HAL 9000

Add blinded path override to test utilities
44f353a
Let integration tests force specific blinded payment paths, so LSPS2 BOLT12 routing behavior can be exercised deterministically. Co-Authored-By: HAL 9000

Cover LSPS2 BOLT12 JIT-channel flows
ef51fb4
Exercise decoder-provided LSPS2 parameters across custom-router, end-to-end, compact message path, and async-payment BOLT12 flows. Co-Authored-By: HAL 9000

f - Cover LSPS2 async invoice gating
e6de553
Assert no static invoice is uploaded before LSPS2 metadata is ready. Keep LSPS2 integration tests compiling with current upstream types. Co-Authored-By: HAL 9000

Add LSPS2 BOLT12 pending changelog entry
a83d765
Record the new LSPS2 BOLT12 routing support and its compatibility note for the next release notes. Co-Authored-By: HAL 9000

tnull force-pushed the 2026-03-lsps2-bolt12-alt branch from abdecc2 to a83d765Compare June 26, 2026 14:53

tnull requested a review from TheBlueMatt June 26, 2026 14:54

ldk-reviews-bot closed this Jul 3, 2026

Uh oh!

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!

Uh oh!

Uh oh!

Uh oh!

ldk-reviews-bot commented Mar 7, 2026

Uh oh!

ldk-reviews-bot commented Mar 9, 2026

Uh oh!

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!

Uh oh!

Uh oh!

Uh oh!

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

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

ldk-reviews-bot commented Jun 13, 2026

Uh oh!

ldk-reviews-bot commented Jun 15, 2026

Uh oh!

ldk-reviews-bot commented Jun 17, 2026

Uh oh!

ldk-reviews-bot commented Jun 20, 2026

Uh oh!

ldk-reviews-bot commented Jun 20, 2026

Uh oh!

ldk-reviews-bot commented Jun 22, 2026

Uh oh!

ldk-reviews-bot commented Jun 22, 2026

Uh oh!

ldk-reviews-bot commented Jun 24, 2026

Uh oh!

ldk-reviews-bot commented Jun 24, 2026

Uh oh!

Uh oh!

ldk-reviews-bot commented Jun 27, 2026

Uh oh!

ldk-reviews-bot commented Jul 3, 2026

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

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

codecovBot commented Mar 24, 2026•
edited
Loading