Move BOLT11 JIT params to payment metadata by tnull · Pull Request #899 · lightningdevkit/ldk-node

tnull · 2026-05-06T12:09:25Z

Context

We recently found that for the intended BOLT12-JIT flow we'll have to encode the LSPS2 parameters in the payment metadata (based on lightningdevkit/rust-lightning#4584). As a prefactor to that (and to simplify things for #811, rather than add yet another store type there, just to revert once we get to the BOLT12-JIT changes), we here switch to store the LSPS2 parameters in the BOLT11 payment_metadata rather than persisting them on-disk. To make this safe we'll also need lightningdevkit/rust-lightning#4528, as otherwise the payer could collude with the LSP to rob the payee.

Summary

This moves LSPS2/JIT-channel receive parameters out of dedicated payment-store
state and into the BOLT11 invoice payment_metadata, so the payment store no
longer needs a PaymentKind::Bolt11Jit variant for new payments.

Changes

Rename LSPFeeLimits to LSPS2Parameters.
Add Bolt11PaymentMetadata in bolt11.rs with TLV-based encoding.
Encode LSPS2Parameters into BOLT11 payment_metadata when creating JIT
invoices.
Store new JIT receives as PaymentKind::Bolt11.
Decode legacy PaymentKind::Bolt11Jit records as PaymentKind::Bolt11.
Reject skimmed inbound payments unless valid BOLT11 payment_metadata proves
the LSPS2 fee is within the negotiated limit.
Drop the stale top-level PaymentDetails field-1 JIT metadata reader, while
keeping the released legacy PaymentKind::Bolt11Jit decoder.
Add a changelog note that pending JIT payments may fail after upgrade because
prior JIT state is not migrated.

The values describe the `LSPS2` parameters negotiated for JIT-channel receives, not a fee-limit concept owned by the payment store. Rename the public type and internal references while preserving the existing fields, TLV encoding, and `PaymentKind::Bolt11Jit` storage shape for the follow-up refactor. Co-Authored-By: HAL 9000

ldk-reviews-bot · 2026-05-06T12:09:28Z

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

joostjager

PR looks great. I like the offloading of state to clients. And ofc happy to see usage of lightning/bolts#912 😄

joostjager · 2026-05-07T12:13:21Z

 		let payment_hash = invoice.payment_hash();
 		let payment_secret = invoice.payment_secret();
-		let lsp_fee_limits = LSPFeeLimits {
+		let lsp_fee_limits = LSPS2Parameters {


Not sure if this rename is strictly better. Parameters sounds broader than what it is.

Yes, that's intentional as we might add more fields in the BOLT12 context that are not 'fee limits'. Sorry, maybe should have given that rationale in the commit description.

Which parameters are that?

Which parameters are that?

See https://github.com/lightningdevkit/rust-lightning/pull/4463/changes#diff-dd4e4cab42ecc909f892759965a0ef44080f865dcae8173f084d960f296406b5R32-R39

joostjager · 2026-05-07T12:40:28Z

 	let client_payment = client_node.payment(&client_payment_id).unwrap();
 	match client_payment.kind {
-		PaymentKind::Bolt11Jit { counterparty_skimmed_fee_msat, .. } => {
+		PaymentKind::Bolt11 { counterparty_skimmed_fee_msat, .. } => {


Would it be worth to add some coverage for "skimmed fee with missing/malformed metadata" failing?

I added a small fixup that basically asserts that, let me know if you deem this sufficient. Note that asserting handle_event behavior overall is a bit tricky, and we don't have a good way to create integration tests that feature LSPs maliciously withholding funds.

tnull · 2026-05-08T11:31:31Z

Now updated and included a commit that allows us to de/encrypt PaymentMetadata, as we should do that given that otherwise the payer will see whatever we put into that. Currently the LSP parameters aren't super sensitive, but especially given we're adding the general struct for expandibility, we want to make sure encrypt from the start to avoid any privacy leakage.

joostjager · 2026-05-08T12:18:21Z

+		}
+	}
+
+	fn nonce(&self, payment_hash: &PaymentHash, payment_secret: &PaymentSecret) -> [u8; 12] {


Is it totally ruled out that payment hash and secret are never reused, also not in some manual flow for example? Perhaps defensively picking a random nonce and storing it in the metadata is safer?

Yes, pretty much. If we reuse the payment hash for example we have worse issues than just privacy leakage at our hands. Happy to store the nonce if you insist, but note that we try to keep invoices as small as possible, in particular for QR encoding.

Still I think it is better to not rely on that, but might be worth getting a 2nd opinion.

Related question: if size is important, is the current scheme minimal? Perhaps the double tlv wrapper and/or u64 can be shaved down too.

And with lightningdevkit/rust-lightning#4528, perhaps the tag isn't needed anymore for auth, because auth is already on the rust-lightning level?

Related question: if size is important, is the current scheme minimal? Perhaps the double tlv wrapper and/or u64 can be shaved down too.

We want the wrapper for clean extensibility, and I'd rather not go down the road of using something besides u64 for msat values, as we're very consistent about that, and we soon want to switch to a LightningAmount type that will be serialized as u64, so hopefully we can just use that everywhere in-place.

tnull · 2026-05-19T08:35:11Z

@joostjager Let me know if you have any other questions, otherwise it would be good to land this soon to keep moving.

joostjager

Only open item for me is a 2nd reviewer opinion on the nonce generation

tnull requested a review from joostjager May 6, 2026 12:09

tnull mentioned this pull request May 6, 2026

Commit to payment_metadata in inbound payment HMAC lightningdevkit/rust-lightning#4528

Merged

joostjager reviewed May 7, 2026

View reviewed changes

tnull added 3 commits May 8, 2026 13:08

Add encrypted payment metadata helpers

ec1b601

Move JIT parameters to encrypted payment metadata

ac6b669

Stop reading unused PaymentDetails JIT TLV field

40f11e6

tnull force-pushed the 2026-05-move-jit-params-to-payment-metadata branch from 7d41d4f to 40f11e6 Compare May 8, 2026 11:29

tnull requested a review from joostjager May 8, 2026 11:31

joostjager reviewed May 8, 2026

View reviewed changes

tnull mentioned this pull request May 15, 2026

Add a payment_metadata map in blinded * path contexts lightningdevkit/rust-lightning#4584

Open

tnull requested a review from joostjager May 19, 2026 08:32

joostjager reviewed May 19, 2026

View reviewed changes

Conversation

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

Uh oh!

Context

Summary

Changes

Uh oh!

ldk-reviews-bot commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tnull commented May 8, 2026

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!

Uh oh!

Uh oh!

tnull commented May 19, 2026

Uh oh!

joostjager left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

tnull commented May 6, 2026 •

edited

Loading

ldk-reviews-bot commented May 6, 2026 •

edited

Loading