[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 93.25114% with 104 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.07%. Comparing base (12edb7d) to head (564682f).
⚠️ Report is 77 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning/src/offers/payer_proof.rs	91.82%	39 Missing and 44 partials ⚠️
lightning/src/offers/merkle.rs	97.19%	7 Missing and 3 partials ⚠️
lightning/src/ln/channelmanager.rs	87.50%	4 Missing ⚠️
lightning/src/ln/outbound_payment.rs	87.87%	3 Missing and 1 partial ⚠️
lightning/src/ln/functional_test_utils.rs	0.00%	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   86.20%   87.07%   +0.87%     
==========================================
  Files         160      164       +4     
  Lines      107545   110162    +2617     
  Branches   107545   110162    +2617     
==========================================
+ Hits        92707    95927    +3220     
+ Misses      12214    11706     -508     
+ Partials     2624     2529      -95

Flag	Coverage Δ
fuzzing	`39.78% <4.12%> (?)`
tests	`86.18% <93.25%> (-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.

TheBlueMatt

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

lightning/src/offers/payer_proof.rs

lightning/src/offers/merkle.rs

lightning/src/offers/payer_proof.rs

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

lightning/src/offers/payer_proof.rs

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.

vincenzopalazzo · 2026-04-01T17:48:52Z

Thanks @jkczyz I should have addressed everything that you asked me!

ldk-reviews-bot · 2026-04-04T00: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-04-04T00:00:48Z

🔔 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-04-06T00:01:47Z

🔔 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-04-06T00:01:48Z

🔔 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-04-08T00:02:25Z

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

ldk-reviews-bot · 2026-04-08T00:02:27Z

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

lightning/src/events/mod.rs

lightning/src/offers/invoice.rs

lightning/src/offers/merkle.rs

TheBlueMatt · 2026-04-09T15:37:40Z

lightning/src/offers/merkle.rs

+		}
+	}
+
+	missing_with_types.sort_by_key(|(min_type, _)| *min_type);


This is wrong, right? https://github.com/lightning/bolts/pull/1295/changes#diff-cff1283072dc12a9b5d36cb2086aa18fbed57df0852ca1e2372c9e69329f7f9eR1139

Yeah, we iterate with Rusty over the spec (probably the diff was introduced inside the last fixup), and I already implemented it vincenzopalazzo#85

I shared it with @jkczyz because I was able to reduce some allocation by avoiding recursion, but assuming the DFS visit order will not allow me to simplify the code further, so some allocation remains.

For this reason, I kept it as a separate PR on my branch to avoid introducing big changes to code that is kind of in good shape.

So, wondering what your thoughts are on this, I was thinking that since there is no user of this API, we could make a follow-up PR during the beta?

No, I don't think we should land something that's wrong just because the code has been looked at some - let's fix it and get it right.

Ok, fixing your early review and merging my PR by keeping the change in a different commit that will make it easy to review only the part changed

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.

Add the payer proof types, selective disclosure merkle support, parsing, and tests for constructing and validating BOLT 12 payer proofs from invoices.

Rename the old PaidBolt12Invoice enum to Bolt12InvoiceType, move it out of events, and update outbound payment plumbing to store the renamed invoice type directly.

Encapsulate invoice, preimage, and nonce in PaidBolt12Invoice and surface it in PaymentSent. Rework builder to return UnsignedPayerProof with SignFn/sign_message integration, use encode_tlv_stream! for serialization, move helpers to DisclosedFields methods, and address naming conventions and TLV validation feedback. Co-Authored-By: Jeffrey Czyz <jkczyz@gmail.com> Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

vincenzopalazzo · 2026-04-09T19:04:07Z

Ok, I should have addressed all the review comments of @TheBlueMatt, and I also pushed the changes that are in sync with the last update of the spec, including the test vectors that are not landed inside the spec. I left them as two separate commits for easy review.

I tried to minimise the allocation as much as I could, but now the order of the missing hashes is based on DFS traversal, and this introduces some allocation here and there

ldk-claude-review-bot · 2026-04-09T19:06:45Z

lightning/src/offers/payer_proof.rs

+			assert_eq!(
+				proof.to_string(),
+				vector.bech32,
+				"{}: bech32 mismatch",
+				vector.name
+			);
+		}


The spec vector test verifies encoding (produce proof → compare bech32 output) but never verifies decoding (parse the expected bech32 string → verify fields). This is the most valuable test for cross-implementation interoperability: if another implementation produces a payer proof matching the spec vector bech32, you need to confirm your parser can consume it.

Consider adding decoding verification for each vector:

Suggested change

assert_eq!(

proof.to_string(),

vector.bech32,

"{}: bech32 mismatch",

vector.name

);

}

assert_eq!(

proof.to_string(),

vector.bech32,

"{}: bech32 mismatch",

vector.name

);

// Verify the decode path also works with the spec vector bech32 string.

let decoded = PayerProof::from_bech32_str(vector.bech32)

.unwrap_or_else(|e| panic!("{}: bech32 decode failed: {:?}", vector.name, e));

assert_eq!(decoded.preimage(), proof.preimage(), "{}: decoded preimage mismatch", vector.name);

assert_eq!(decoded.merkle_root(), proof.merkle_root(), "{}: decoded merkle_root mismatch", vector.name);

assert_eq!(decoded.payer_id(), proof.payer_id(), "{}: decoded payer_id mismatch", vector.name);

ldk-claude-review-bot · 2026-04-09T19:06:59Z

lightning/src/offers/merkle.rs

+		// The spec example only shows 3, but that appears to be incomplete
+		// (missing hash for type 60). Our implementation should produce 4.


This comment claims disagreement with the spec ("The spec example only shows 3, but that appears to be incomplete"), but the new check_against_spec_vectors test in payer_proof.rs now passes against official BOLT 12 test vectors — which means the implementation matches the current spec. This comment is now outdated/misleading and should be updated or removed to avoid confusing future readers into thinking there's a known spec divergence.

Note: this is a synthetic test with different TLV types than the spec vectors, so the "4 missing hashes" assertion here is correct for this tree structure. The comment about spec disagreement is what's stale.

jkczyz · 2026-04-09T23:02:47Z

@vincenzopalazzo Not sure what happened to the branch, but it looks like a lot of the earlier fixes have been dropped. Is it related to #4297 (comment)?

Don't require payer proof missing hashes to remain TLV-sorted now that the spec uses DFS traversal order. (cherry picked from commit 334bb05)

Embed the latest payer proof vectors and keep the test harness aligned with the current unsigned builder and signing flow. (cherry picked from commit 3a500c8)

vincenzopalazzo · 2026-04-10T08:29:17Z

Thanks for the catch @jkczyz need to remind myself not to work with git magic command late at night, so I should have restored the old history with the changes requested in the last review from you and Matt.

Thanks!

ldk-reviews-bot · 2026-04-11T00:00:30Z

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

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

lightning/src/offers/merkle.rs Outdated Show resolved Hide resolved

lightning/src/offers/merkle.rs Outdated Show resolved Hide resolved

lightning/src/offers/payer_proof.rs Outdated Show resolved Hide resolved

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 b52a5f3 to c836395 Compare April 1, 2026 17:12

vincenzopalazzo requested review from TheBlueMatt and jkczyz April 1, 2026 17:48

TheBlueMatt reviewed Apr 9, 2026

View reviewed changes

vincenzopalazzo added 2 commits April 9, 2026 19:24

refactor(offers): extract payer key derivation helpers

384ce7b

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.

feat(offers): add BOLT 12 payer proof primitives

7257a02

Add the payer proof types, selective disclosure merkle support, parsing, and tests for constructing and validating BOLT 12 payer proofs from invoices.

vincenzopalazzo force-pushed the macros/proof-of-payment-bolt12-spec branch from 24f97b7 to c62ce8b Compare April 9, 2026 17:38

vincenzopalazzo and others added 2 commits April 9, 2026 19:53

refactor(offers): move Bolt12InvoiceType into payer_proof

5fa4995

Rename the old PaidBolt12Invoice enum to Bolt12InvoiceType, move it out of events, and update outbound payment plumbing to store the renamed invoice type directly.

vincenzopalazzo force-pushed the macros/proof-of-payment-bolt12-spec branch 3 times, most recently from 9f488d7 to 7468188 Compare April 9, 2026 19:01

ldk-claude-review-bot reviewed Apr 9, 2026

View reviewed changes

vincenzopalazzo force-pushed the macros/proof-of-payment-bolt12-spec branch from 8202ad0 to 3a500c8 Compare April 9, 2026 19:19

rustyrussell added 2 commits April 10, 2026 08:36

fix(offers): use DFS order for payer proof missing hashes

1db500a

Don't require payer proof missing hashes to remain TLV-sorted now that the spec uses DFS traversal order. (cherry picked from commit 334bb05)

test(offers): add latest BOLT12 payer proof vectors

564682f

Embed the latest payer proof vectors and keep the test harness aligned with the current unsigned builder and signing flow. (cherry picked from commit 3a500c8)

vincenzopalazzo force-pushed the macros/proof-of-payment-bolt12-spec branch from 3a500c8 to 564682f Compare April 10, 2026 07:23

		// The spec example only shows 3, but that appears to be incomplete
		// (missing hash for type 60). Our implementation should produce 4.

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!

vincenzopalazzo commented Apr 1, 2026

Uh oh!

ldk-reviews-bot commented Apr 4, 2026

Uh oh!

ldk-reviews-bot commented Apr 4, 2026

Uh oh!

ldk-reviews-bot commented Apr 6, 2026

Uh oh!

ldk-reviews-bot commented Apr 6, 2026

Uh oh!

ldk-reviews-bot commented Apr 8, 2026

Uh oh!

ldk-reviews-bot commented Apr 8, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

TheBlueMatt Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

vincenzopalazzo Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

TheBlueMatt Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

vincenzopalazzo Apr 9, 2026

Choose a reason for hiding this comment

ldk-reviews-bot commented Jan 5, 2026 •

edited

Loading

codecov bot commented Jan 5, 2026 •

edited

Loading