[RFC] Add BOLT 12 payer proof primitives by vincenzopalazzo · Pull Request #4297 · lightningdevkit/rust-lightning

vincenzopalazzo · 2026-01-05T11:51:32Z

This is a first draft implementation of the payer proof extension to BOLT 12 as proposed in lightning/bolts#1295. The goal is to get early feedback on the API design before the spec is finalized.

Payer proofs allow proving that a BOLT 12 invoice was paid by demonstrating possession of:

The payment preimage
A valid invoice signature over a merkle root
The payer's signature

This PR adds the core building blocks:

Extends merkle.rs with selective disclosure primitives that allow creating and reconstructing merkle trees with partial TLV disclosure. This enables proving invoice authenticity while omitting sensitive fields.
Adds payer_proof.rs with PayerProof, PayerProofBuilder, and UnsignedPayerProof types. The builder pattern allows callers to selectively include invoice fields (description, amount, etc.) in the proof.
Implements bech32 encoding/decoding with the lnp prefix and proper TLV stream parsing with validation (ascending order, no duplicates, hash length checks).

This is explicitly a PoC to validate the API surface - the spec itself is still being refined. Looking for feedback on:

Whether the builder pattern makes sense for selective disclosure
The verification API
Integration points with the rest of the offers module

cc @TheBlueMatt @jkczyz

ldk-reviews-bot · 2026-01-05T11:51:34Z

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

codecov · 2026-01-05T13:23:22Z

Codecov Report

❌ Patch coverage is 60.86957% with 378 lines in your changes missing coverage. Please review.
✅ Project coverage is 85.63%. Comparing base (2d2151a) to head (9b3865f).

Files with missing lines	Patch %	Lines
lightning/src/offers/payer_proof.rs	37.99%	347 Missing and 12 partials ⚠️
lightning/src/offers/merkle.rs	95.09%	16 Missing and 3 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4297      +/-   ##
==========================================
- Coverage   85.86%   85.63%   -0.23%     
==========================================
  Files         159      160       +1     
  Lines      104302   105267     +965     
  Branches   104302   105267     +965     
==========================================
+ Hits        89558    90149     +591     
- Misses      12246    12599     +353     
- Partials     2498     2519      +21

Flag	Coverage Δ
tests	`85.63% <60.86%> (-0.23%)`	⬇️

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.

TheBlueMatt

A few notes, though I didn't dig into the code at a particularly low level.

lightning/src/offers/payer_proof.rs

TheBlueMatt · 2026-01-08T17:48:47Z

lightning/src/offers/payer_proof.rs

+		self.included_types.insert(164);
+		self
+	}
+


Probably worth having a generic "select by id" thing (maybe requiring it be in the experimental range?), given we'll add support for custom TLVs eventually.

There's already an include_type(tlv_type: u64) method that allows including any TLV by its type number (except invreq_metadata which is forbidden by spec). Is that what you're looking for, or did you want something more restrictive that only allows experimental types (>= 1,000,000,000)?

Updated in the force-push -- include_type(tlv_type: u64) still exists and accepts any non-zero TLV type. Let me know if you would prefer restricting it to the experimental range.

lightning/src/offers/payer_proof.rs

lightning/src/offers/merkle.rs

TheBlueMatt · 2026-01-11T16:15:40Z

lightning/src/offers/merkle.rs

+	let mut is_included: Vec<bool> = vec![false; num_leaves];
+	let mut min_types: Vec<u64> = vec![u64::MAX; num_leaves];


Would be nice to avoid the unnecessary allocations here.

Addressed in the latest force-push -- the third commit removes nonce_hash from TlvMerkleData (saving 32 bytes per TLV), inlines reconstruct_positions_from_records to eliminate the intermediate Vec<bool>, and pre-allocates missing_with_types/needs_hash with with_capacity(num_omitted).

TheBlueMatt · 2026-01-11T16:16:34Z

lightning/src/offers/merkle.rs

+	let branch_tag = tagged_hash_engine(sha256::Hash::hash("LnBranch".as_bytes()));
+
+	let mut hashes: Vec<Option<sha256::Hash>> = vec![None; num_leaves];
+	let mut is_included: Vec<bool> = vec![false; num_leaves];


Same here, there's lot of allocations that we should be able to avoid.

Same commit as above -- reconstruct_merkle_root now builds TreeNodes directly during position reconstruction instead of first building a Vec<bool> and then a second pass, and needs_hash is pre-allocated with with_capacity.

lightning/src/offers/payer_proof.rs

TheBlueMatt · 2026-01-11T16:20:27Z

lightning/src/offers/payer_proof.rs

+	invoice_created_at: Option<Duration>,
+	#[allow(dead_code)]
+	invoice_features: Option<Bolt12InvoiceFeatures>,
+}


We presumably want a place to store custom included TLVs.

Right now custom included TLVs are used during parsing to reconstruct the merkle root but are not stored in PayerProofContents for later access. We could add a custom_records: BTreeMap<u64, Vec<u8>> field (similar to how Bolt12Invoice handles custom records) so callers can inspect disclosed custom TLVs after parsing. Happy to add that now, or defer until custom TLV support lands more broadly -- let me know.

Add a Rust CLI tool that generates and verifies test vectors for BOLT 12 payer proofs as specified in lightning/bolts#1295. The tool uses the rust-lightning implementation from lightningdevkit/rust-lightning#4297. Features: - Generate deterministic test vectors with configurable seed - Verify test vectors from JSON files - Support for basic proofs, proofs with notes, and invalid test cases - Uses refund flow for explicit payer key control Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

ldk-reviews-bot · 2026-01-22T17:01:48Z

🔔 1st Reminder

Hey @valentinewallace! 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.

TheBlueMatt

Some API comments. I'll review the actual code somewhat later (are we locked on on the spec or is it still in flux at all?), but would be nice to reduce allocations in it first anyway.

lightning/src/offers/merkle.rs

TheBlueMatt · 2026-01-23T15:43:30Z

lightning/src/offers/payer_proof.rs

+	/// The derived key must match the `payer_id` in the original invoice for the signature
+	/// to be valid.
+	pub fn sign_with_derived_key(
+		self, expanded_key: &ExpandedKey, nonce: Nonce, note: Option<&str>,


Hmm, the Nonce is stored in the invoice iirc so it would be nice to not have to pass this back in. Not sure if its better to store the nonce in the unsigned proof or just not have an unsigned proof at all (having the last step of the builder be signing, rather than building). What's the rationale for having separate unsigned + signed types?

Addressed the second part of this — removed the public UnsignedPayerProof type entirely and moved signing into the builder, matching the build_and_sign pattern used by InvoiceRequestBuilder and InvoiceBuilder. The builder now has:

build_and_sign(sign_fn, note) — for explicit signing with a closure

build_and_sign_with_derived_key(expanded_key, nonce, note) — for derived key signing

Regarding the first part (not having to pass the Nonce back in): I may be missing something, but from tracing through the code, I think the nonce isn't actually stored in the invoice's payer metadata for the DerivedSigningPubkey path. When derive_metadata_and_keys runs in signer.rs, it only puts the encrypted_payment_id into the resulting Metadata::Bytes — the nonce is consumed during derivation.

In the ChannelManager flow, the nonce is carried separately through the OffersContext::OutboundPaymentForOffer { payment_id, nonce } in the blinded path context, and verify_using_payer_data reconstructs the metadata from that context rather than reading it from the invoice.

So I kept nonce as a parameter on build_and_sign_with_derived_key. Happy to change this if I'm wrong about the metadata layout though!

Updated in the force-push -- UnsignedPayerProof is now a private internal type. The builder exposes build_and_sign(sign_fn, note) and build_and_sign_with_derived_key(expanded_key, nonce, payment_id, note). The Nonce is still a parameter because in the DerivedSigningPubkey path the payer metadata is an HMAC (not the raw nonce), so we cannot extract it from the invoice. The nonce is available from OffersContext::OutboundPaymentForOffer.

ldk-reviews-bot · 2026-01-26T00:00:26Z

🔔 2nd Reminder

Hey @valentinewallace! 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-01-29T18:59:44Z

🔔 1st Reminder