[RFC] Add BOLT 12 payer proof primitives

[vincenzopalazzo]

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]

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

Codecov Report

❌ Patch coverage is 93.77806% with 97 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.12%. Comparing base (4c398bb) to head (6f58300).
⚠️ Report is 36 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning/src/offers/payer_proof.rs	92.37%	32 Missing and 48 partials ⚠️
lightning/src/offers/merkle.rs	96.70%	7 Missing and 4 partials ⚠️
lightning/src/ln/channelmanager.rs	88.46%	3 Missing ⚠️
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   86.99%   87.12%   +0.12%     
==========================================
  Files         163      162       -1     
  Lines      108706   110487    +1781     
  Branches   108706   110487    +1781     
==========================================
+ Hits        94571    96260    +1689     
- Misses      11655    11690      +35     
- Partials     2480     2537      +57     

Flag	Coverage Δ
fuzzing	39.10% <2.70%> (-1.17%)	⬇️
tests	86.24% <93.77%> (+0.15%)	⬆️

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.

[ldk-reviews-bot]

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

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

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

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

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

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

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

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

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

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

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

[ldk-claude-review-bot]

Nit: This filter is dead code. PAYER_METADATA_TYPE is 0, and INVOICE_REQUEST_TYPES is 80..160. Type 0 can never appear in range 80..160, so the filter never matches. Additionally, the producer (serialize_payer_proof) never emits type 0 since include_type rejects it, so even the OFFER_TYPES range (1..80) wouldn't contain it.

Suggested change

	.filter(|record| record.r#type != PAYER_METADATA_TYPE);
	let invoice_request_records = TlvStream::new(bytes)
	.range(INVOICE_REQUEST_TYPES);

[jkczyz]

Not done

[jkczyz]

Not done.

[jkczyz]

Some of the commits mixup changes. And the tests don't compile in two of the commits. Not sure why check_commits missed this. Here's a summary from Claude:

PR 4297 — commit split review

Analysis of which changes in commit 4 logically belong in earlier commits on the pr/4297 branch.

Branch commits

1. 489e64322 refactor(offers): extract payer key derivation helpers
2. 97832a449 feat(offers): add BOLT 12 payer proof primitives
3. 464b8f75c refactor(offers): move Bolt12InvoiceType into payer_proof
4. 78aa605d7 refactor(offers): bundle paid invoice data for payer proofs
5. 6f58300515 fix(offers): use DFS order for payer proof missing hashes

Commits 2 and 3 fail to compile (cargo +1.75.0 check --tests -p lightning). Commits 1, 4, and 5 compile cleanly.

Belongs in commit 2 (97832a449 "add BOLT 12 payer proof primitives")

1. Named TLV constants in tlv_stream! macros

lightning/src/offers/offer.rs and lightning/src/offers/invoice.rs:

• Commit 2 introduces OFFER_DESCRIPTION_TYPE, OFFER_ISSUER_TYPE, INVOICE_CREATED_AT_TYPE, INVOICE_PAYMENT_HASH_TYPE, INVOICE_AMOUNT_TYPE, INVOICE_FEATURES_TYPE, INVOICE_NODE_ID_TYPE but leaves the literal integers (10, 18, 164, 168, ...) in the adjacent tlv_stream! macros.
• Commit 4 replaces them with the named constants. Purely cosmetic; belongs with the constant introduction.

2. Fix the broken offers_tests.rs API

lightning/src/ln/offers_tests.rs:

• Commit 2 adds tests that reference PayerProofBuilder::build_with_derived_key(...), PayerProof::preimage(), and PayerProof::payer_id(). None of those exist in the payer_proof.rs that commit 2 itself adds — the real names are build_and_sign, payment_preimage, payer_signing_pubkey.
• This is the direct cause of the commit‑2 compile failure (5 E0599 errors on build_with_derived_key).
• The entry‑point rewrite from invoice.payer_proof_builder(preimage) to paid_invoice.prove_payer_derived(...) could also land in commit 2: the PaidBolt12Invoice struct and its prove_payer/prove_payer_derived methods already exist in commit 2's payer_proof.rs (lines 91–). Only the fact that PaidBolt12Invoice is surfaced through PaymentSent depends on commit 4.

Belongs in commit 3 (464b8f75c "move Bolt12InvoiceType into payer_proof")

3. Finish the PaidBolt12Invoice → Bolt12InvoiceType rename

lightning/src/ln/async_payments_tests.rs line 3624:

assert_eq!(res, Some(PaidBolt12Invoice::StaticInvoice(static_invoice)));

Every other Bolt12InvoiceType::StaticInvoice(...) in that file got renamed in commit 3; this one was missed. It's what makes commit 3 fail with error[E0433]: use of undeclared type PaidBolt12Invoice.

Genuinely belongs in commit 4

The actual "bundle paid invoice data" work:

• Add payment_nonce: Option<Nonce> to HTLCSource::OutboundRoute, SendAlongPathArgs, PendingOutboundPayment::Retryable (plus TLV fields 9/17 on serialization) and plumb it through send_payment_for_bolt12_invoice{,_verified,_internal}, pay_route_internal, create_pending_payment, claim_htlc.
• Extract payment_nonce from OffersContext::Outbound{ForOffer,ForRefund} in channelmanager.rs.
• Change Event::PaymentSent::bolt12_invoice type from Option<Bolt12InvoiceType> to Option<PaidBolt12Invoice>, splitting serialization into (9, invoice_type) + (11, payment_nonce) and reconstructing on read.
• Update expect_payment_sent / claim_payment{,_along_route} return types in functional_test_utils.rs and the async-payments test assertions that peek into the returned PaidBolt12Invoice.
• Corresponding test‑site construction fixes in channel.rs, onion_utils.rs, fuzz/src/process_onion_failure.rs.

Commit 4 message is inaccurate

The commit 4 message claims it "rework[s] builder to return UnsignedPayerProof with SignFn/sign_message integration, use[s] encode_tlv_stream! for serialization, move[s] helpers to DisclosedFields methods." Commit 4 doesn't touch payer_proof.rs at all — those pieces are already in commit 2 (and encode_tlv_stream! is never used there). The message should be rewritten to describe only the PaidBolt12Invoice / payment_nonce plumbing it actually performs.