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

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

Codecov Report

❌ Patch coverage is 97.13262% with 16 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.81%. Comparing base (ee456a8) to head (45cf45c).
⚠️ Report is 17 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning/src/offers/merkle.rs	97.11%	7 Missing and 4 partials ⚠️
lightning/src/ln/channelmanager.rs	92.85%	1 Missing and 1 partial ⚠️
lightning/src/ln/outbound_payment.rs	97.72%	1 Missing ⚠️
lightning/src/offers/invoice.rs	97.91%	1 Missing ⚠️
lightning/src/offers/signer.rs	97.29%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##             main    #4297       +/-   ##
===========================================
+ Coverage   28.02%   86.81%   +58.79%     
===========================================
  Files         126      160       +34     
  Lines       69960   112368    +42408     
  Branches    69960   112368    +42408     
===========================================
+ Hits        19606    97555    +77949     
+ Misses      49020    12249    -36771     
- Partials     1334     2564     +1230

Flag	Coverage Δ
fuzzing-fake-hashes	`7.59% <0.00%> (+0.97%)`	⬆️
fuzzing-real-hashes	`25.18% <8.20%> (+1.93%)`	⬆️
tests	`86.37% <97.13%> (?)`

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.

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.

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

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-02-02T00:00:56Z

🔔 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-02-04T00:01:26Z

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

ldk-reviews-bot · 2026-02-07T00:00:11Z

🔔 4th 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-02-09T00:00:34Z

🔔 5th 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-02-11T00:01:00Z

🔔 6th 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-02-14T00:00:53Z

🔔 7th 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-02-16T00:02:07Z

🔔 8th 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-02-18T00:02:28Z

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

Move the invoice/refund payer key derivation logic into reusable helpers so payer proofs can derive the same signing keys without duplicating the metadata and signer flow.

Extend the BOLT 12 merkle module with selective-disclosure support: build the full merkle tree from a TLV stream, compute the omitted-TLV markers and the minimal set of missing hashes for omitted subtrees, and reconstruct the merkle root from a partial disclosure. These are the primitives a payer proof is built on. Co-Authored-By: Rusty Russell <rusty@rustcorp.com.au> Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Co-Authored-By: OpenAI Codex <codex@openai.com>

Add the `payer_proof` module: `PayerProof`/`UnsignedPayerProof`, the `PayerProofBuilder` (with selective disclosure and a derived-key path), bech32 `lnp` encoding, and parse-time verification, implementing the payer proof extension to BOLT 12 (lightning/bolts#1295). Also exposes the offer/invoice TLV-type constants and an invoice-bytes accessor used to build proofs, and a `Sha256` `Writeable`/`Readable` impl for the proof hashes. Co-Authored-By: Rusty Russell <rusty@rustcorp.com.au> Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Co-Authored-By: OpenAI Codex <codex@openai.com>

Carry the paid `Bolt12Invoice` through the outbound payment so it survives restarts, and surface it as a `PaidBolt12Invoice` on `Event::PaymentSent` so the payer can build a payer proof. The payer signing key is re-derived from the invoice's own payer metadata, so no extra key material is stored. `PaidBolt12Invoice` now lives in `offers::payer_proof`; existing async payment tests and a test helper are updated to construct it via the new API. Adds an end-to-end test that pays a BOLT 12 offer and builds + verifies a payer proof from the resulting `Event::PaymentSent`. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Throw arbitrary bytes at `PayerProof::try_from` to exercise the merkle-root reconstruction and the deserialization path together. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Co-Authored-By: OpenAI Codex <codex@openai.com>

jkczyz · 2026-06-18T23:07:40Z

+	while inc_idx < included_types.len() || mrk_idx < omitted_markers.len() {
+		if mrk_idx >= omitted_markers.len() {
+			// No more markers, remaining positions are included
+			positions.push(true);
+			inc_idx += 1;
+		} else if inc_idx >= included_types.len() {
+			// No more included types, remaining positions are omitted
+			positions.push(false);
+			prev_marker = omitted_markers[mrk_idx];
+			mrk_idx += 1;
+		} else {
+			let marker = omitted_markers[mrk_idx];
+			let inc_type = included_types[inc_idx];
+
+			if marker == next_marker(prev_marker) {
+				// Continuation of current run → this position is omitted
+				positions.push(false);
+				prev_marker = marker;
+				mrk_idx += 1;
+			} else {
+				// Jump detected! An included TLV comes before this marker.
+				// After the included type, prev_marker resets to that type,
+				// so the marker will be processed as a continuation next iteration.
+				positions.push(true);
+				prev_marker = inc_type;
+				inc_idx += 1;
+				// Don't advance mrk_idx - same marker will be continuation next
+			}
+		}


Can't this drift from what's essentially the same loop in reconstruct_merkle_root? We should DRY this up.

What do you think about this solution? 564d463

jkczyz · 2026-06-18T23:26:58Z

+
+#[inline]
+pub fn do_test<Out: test_logger::Output>(data: &[u8], _out: Out) {
+	if let Ok(payer_proof) = PayerProof::try_from(data.to_vec()) {


We should also update the invoice fuzzer to build a payer proof, just like how the offer fuzzer builds an invoice request and how the invoice request fuzzer builds an invoice.

The preimage gate makes this a no-op if I put it in invoice_deser. Building a proof requires SHA256(preimage) == invoice.payment_hash(), and invoice_deser parses arbitrary invoices, so we never hold a matching preimage. prove_payer() returns PreimageMismatch before any of the interesting code runs (build_unsigned doesn't even re-check the invoice signature, the preimage is the only gate), so we'd just be exercising the early error return.

Claude help me find the place where we actually control the payment hash is invoice_request_deser, since it builds the invoice itself via respond_with(paths, payment_hash). If I set payment_hash = SHA256(known_preimage) there, I can chain a full payer proof build+sign right after the invoice is signed, which exercises the selective disclosure, merkle tree, and proof signing for real.

Want me to add it in invoice_request_deser that way? Or do you still want the call in invoice_deser even though it only ever hits PreimageMismatch?

ldk-reviews-bot · 2026-06-24T21:44:32Z

🔔 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-24T21:44:34Z

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

TheBlueMatt

Didn't get through payer_proof.rs but I'm happy with everything else with these comments addressed.

TheBlueMatt · 2026-06-24T22:47:31Z

 	let (res, _) =
 		claim_payment_along_route(ClaimAlongRouteArgs::new(sender, route, keysend_preimage));
-	assert_eq!(res, Some(PaidBolt12Invoice::StaticInvoice(static_invoice.clone())));
+	assert_eq!(res.as_ref().and_then(|paid| paid.static_invoice()), Some(&static_invoice));


I think the diff in this file can be dropped.

Done. Dropped the unnecessary diff in this file; the PR diff no longer changes async_payments_tests.rs for this cleanup.

TheBlueMatt · 2026-06-24T22:47:41Z

 		match self {
 			Self::OutboundRoute {
-				bolt12_invoice: Some(PaidBolt12Invoice::StaticInvoice(inv)),
+				bolt12_invoice: Some(PaidBolt12Invoice::StaticInvoice(invoice)),


This looks like unnecessary diff.

Done. Dropped the unnecessary diff in this file; the PR diff no longer changes channelmanager.rs for this cleanup.

TheBlueMatt · 2026-06-24T22:55:02Z

-	let (inv, _) = claim_payment_along_route(args);
-	assert_eq!(inv, Some(PaidBolt12Invoice::Bolt12Invoice(invoice.clone())));
+	let (paid_invoice, _) = claim_payment_along_route(args);
+	assert_eq!(paid_invoice.as_ref().and_then(|paid| paid.bolt12_invoice()), Some(invoice));


Also unnecessary diff.

Done. Dropped the unnecessary assertion churn at this helper; the remaining diff in this file is needed by the payer-proof round-trip test.

TheBlueMatt · 2026-06-24T22:58:16Z


 use crate::blinded_path::{IntroductionNode, NodeIdLookUp};
-use crate::events::{self, PaidBolt12Invoice, PaymentFailureReason};
+use crate::events::{self, PaymentFailureReason};


I believe all the diff in this file aside from the test at the end can probably be dropped.

Done. Dropped the non-test churn; the remaining diff here is the retryable paid-invoice serialization round-trip test.

TheBlueMatt · 2026-06-25T00:28:36Z

+
+	let num_omitted_markers = tlv_data
+		.iter()
+		.filter(|data| !data.is_included && data.tlv_type != PAYER_METADATA_TYPE)


nit: honestly this constant is weird (and in compute_omitted_markers). Should we instead just require the higher-level (more BOLT12-aware) code always include PAYER_METADATA_TYPE?

Good point. I agree the generic merkle code shouldn’t know about PAYER_METADATA_TYPE.

One clarification: in this code “included” means disclosed in the payer proof, and I don’t think we want to disclose the payer metadata TLV. But the BOLT12-aware payer-proof layer should own that policy instead of having merkle.rs special-case type 0.

I’ll rework this so payer-proof construction handles PAYER_METADATA_TYPE as the implicit/always-omitted payer metadata record, while keeping the merkle/selective-disclosure helper generic. Does that match what you had in mind?

TheBlueMatt · 2026-06-25T00:44:46Z

+/// the encoding from [`compute_omitted_markers`] and is the single source of truth shared by
+/// merkle-root reconstruction and the position map used in tests, so the two cannot drift.
+///
+/// `prev_marker` tracks the previous run value: a marker equal to [`next_marker`] of it continues


nit: weird to document the function's internal operation in its docs.

Done. Trimmed the docs so they describe the decoded position map instead of walking through the loop internals.

TheBlueMatt · 2026-06-25T00:55:42Z

+fn build_tree_with_disclosure(
+	tlv_data: &[TlvMerkleData], branch_tag: &sha256::HashEngine,
+) -> (sha256::Hash, Vec<sha256::Hash>) {
+	debug_assert!(!tlv_data.is_empty(), "TLV stream must contain at least one record");


We'll inf loop in build_tree_dfs anyway, so this isn't gonna do anything.

Done. Removed the redundant debug_assert; the non-empty TLV invariant is already checked before entering the tree builder.

TheBlueMatt · 2026-06-25T00:57:26Z

+) -> Result<sha256::Hash, SelectiveDisclosureError> {
+	debug_assert!({
+		let included_types: BTreeSet<u64> = included_records.iter().map(|r| r.r#type).collect();
+		validate_omitted_markers(omitted_markers, &included_types).is_ok()


dont we need to do this and actually fail in case the omitted markers are wrong? IMO we at least need to fail if the omitted markers aren't always the next marker required, cause we want to be really strict about people screwing that up on the generation side.

TheBlueMatt · 2026-06-25T00:59:16Z

+		// X sits between the previous position and `marker` with `next_marker(X) == marker`.
+		if marker != expected_next {
+			let mut found = false;
+			for inc_type in inc_iter.by_ref() {


if we start doing this in non-debug, it might be worth keeping a single iterator of the included types, rather than building anew iterator for each marker - this should be doable because we only care about included types < marker.

TheBlueMatt · 2026-06-25T01:06:25Z

+	signing_pubkey: PublicKey, tlv_stream: impl core::iter::Iterator<Item = TlvRecord<'a>>,
+	secp_ctx: &Secp256k1<T>,
+) -> Result<Keypair, ()> {
+	if metadata.len() < PaymentId::LENGTH {


nit: move this into verify_payer_metadata_inner.

Done. Moved the metadata length check into verify_payer_metadata_inner, so both callers go through the same validation path.

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

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

Co-Authored-By: OpenAI Codex <codex@openai.com>

jkczyz assigned vincenzopalazzo Jan 8, 2026

TheBlueMatt reviewed Jan 11, 2026

View reviewed changes

vincenzopalazzo marked this pull request as ready for review January 20, 2026 17:00

ldk-reviews-bot requested a review from valentinewallace January 20, 2026 17:01

vincenzopalazzo force-pushed the macros/proof-of-payment-bolt12-spec branch 2 times, most recently from 2324361 to 9f84e19 Compare January 20, 2026 17:42

jkczyz added this to Weekly Goals Jan 22, 2026

TheBlueMatt reviewed Jan 23, 2026

View reviewed changes

Comment thread lightning/src/offers/merkle.rs Outdated

Comment thread lightning/src/offers/merkle.rs Outdated

Comment thread lightning/src/offers/payer_proof.rs Outdated

valentinewallace removed their request for review January 26, 2026 17:25

jkczyz self-requested a review January 27, 2026 18:59

TheBlueMatt added this to the 0.3 milestone Feb 18, 2026

vincenzopalazzo force-pushed the macros/proof-of-payment-bolt12-spec branch 5 times, most recently from fb8c68c to 9ad5c35 Compare February 24, 2026 18:13

vincenzopalazzo force-pushed the macros/proof-of-payment-bolt12-spec branch 2 times, most recently from 93f4104 to 73eea68 Compare June 15, 2026 20:25

ldk-claude-review-bot reviewed Jun 15, 2026

View reviewed changes

Comment thread lightning/src/offers/invoice.rs

vincenzopalazzo force-pushed the macros/proof-of-payment-bolt12-spec branch 2 times, most recently from 8d543ce to 5aedb03 Compare June 15, 2026 20:50

jkczyz reviewed Jun 17, 2026

View reviewed changes

vincenzopalazzo mentioned this pull request Jun 18, 2026

use a separate module for the SelectiveDisclosure-related types and methods, importing these and any methods from merkle there. #4711

Open

refactor(offers): extract payer key derivation helpers

f1eb03b

Move the invoice/refund payer key derivation logic into reusable helpers so payer proofs can derive the same signing keys without duplicating the metadata and signer flow.

jkczyz reviewed Jun 18, 2026

View reviewed changes

Comment thread lightning/src/offers/merkle.rs Outdated

Comment thread lightning/src/offers/merkle.rs Outdated

vincenzopalazzo and others added 5 commits June 18, 2026 17:57

fuzz: add a payer proof deserialization target

56ab271

Throw arbitrary bytes at `PayerProof::try_from` to exercise the merkle-root reconstruction and the deserialization path together. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

fixup! offers: add merkle selective-disclosure primitives

7d2749c

Co-Authored-By: OpenAI Codex <codex@openai.com>

jkczyz reviewed Jun 18, 2026

View reviewed changes

vincenzopalazzo added 6 commits June 22, 2026 18:47

fixup! ln: persist the paid BOLT 12 invoice and build payer proofs

91e0be8

fixup! offers: add BOLT 12 payer proof primitives

b551b2b

fixup! fuzz: add a payer proof deserialization target

7025881

fixup! offers: add merkle selective-disclosure primitives

15f658f

fixup! offers: add BOLT 12 payer proof primitives

f579ade

fixup! offers: add merkle selective-disclosure primitives

564d463

TheBlueMatt reviewed Jun 25, 2026

View reviewed changes

vincenzopalazzo mentioned this pull request Jun 26, 2026

js: exclude payer-proof data-range TLVs from invoice reconstruction rustyrussell/bolt12#33

Merged

3 tasks

vincenzopalazzo and others added 4 commits June 29, 2026 19:12

fixup! ln: persist the paid BOLT 12 invoice and build payer proofs

679de69

Co-Authored-By: OpenAI Codex <codex@openai.com>

fixup! offers: add merkle selective-disclosure primitives

e06b2eb

Co-Authored-By: OpenAI Codex <codex@openai.com>

fixup! fixup! offers: add merkle selective-disclosure primitives

aced065

Co-Authored-By: OpenAI Codex <codex@openai.com>

fixup! refactor(offers): extract payer key derivation helpers

7c0b296

Co-Authored-By: OpenAI Codex <codex@openai.com>

Uh oh!

Conversation

vincenzopalazzo commented Jan 5, 2026

Uh oh!

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

Uh oh!

Uh oh!

codecov Bot commented Jan 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

TheBlueMatt left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ldk-reviews-bot commented Jan 22, 2026

Uh oh!

TheBlueMatt left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ldk-reviews-bot commented Jan 26, 2026

Uh oh!

ldk-reviews-bot commented Jan 29, 2026

Uh oh!

ldk-reviews-bot commented Feb 2, 2026

Uh oh!

ldk-reviews-bot commented Feb 4, 2026

Uh oh!

ldk-reviews-bot commented Feb 7, 2026

Uh oh!

ldk-reviews-bot commented Feb 9, 2026

Uh oh!

ldk-reviews-bot commented Feb 11, 2026

Uh oh!

ldk-reviews-bot commented Feb 14, 2026

Uh oh!

ldk-reviews-bot commented Feb 16, 2026

Uh oh!

ldk-reviews-bot commented Feb 18, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ldk-reviews-bot commented Jun 24, 2026

Uh oh!

ldk-reviews-bot commented Jun 24, 2026

ldk-reviews-bot commented Jan 5, 2026 •

edited

Loading

codecov Bot commented Jan 5, 2026 •

edited

Loading