feat(offers): add BOLT 12 payer proof primitives

Add the payer proof types, selective disclosure merkle support,
parsing, and tests for constructing and validating BOLT 12 payer
proofs from invoices. This implements the payer proof extension to
BOLT 12 as specified in lightning/bolts#1295.

Missing hashes in a proof are emitted in the DFS traversal order
defined by the spec. The BOLT 12 payer proof spec test vectors from
bolt12/payer-proof-test.json (full disclosure, minimal disclosure,
with payer note, and left-subtree omitted) validate the end-to-end
output.

The parser rejects unknown even TLVs in every sub-stream range
(offer, invoice request, invoice, payer-proof/signature, and the
three experimental ranges) via the `tlv_stream!` macro's unknown-even
fallback, and rejects types in the unused gap between the signature
range and the experimental ranges via the all-bytes-consumed check in
`ParsedMessage::try_from`.

Co-Authored-By: Rusty Russell <rusty@rustcorp.com.au>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 3 people

lightning/src/ln/offers_tests.rs

@@ -61,6 +61,8 @@ use crate::offers::invoice_error::InvoiceError;
 use crate::offers::invoice_request::{InvoiceRequest, InvoiceRequestFields, InvoiceRequestVerifiedFromOffer};
 use crate::offers::nonce::Nonce;
 use crate::offers::parse::Bolt12SemanticError;
+use crate::offers::payer_proof::{self, Bolt12InvoiceType, PayerProof, PayerProofError};
+use crate::types::payment::PaymentPreimage;
 use crate::onion_message::messenger::{DefaultMessageRouter, Destination, MessageSendInstructions, NodeIdMessageRouter, NullMessageRouter, PeeledOnion, DUMMY_HOPS_PATH_LENGTH, QR_CODED_DUMMY_HOPS_PATH_LENGTH};
 use crate::onion_message::offers::OffersMessage;
 use crate::routing::gossip::{NodeAlias, NodeId};
@@ -264,6 +266,21 @@ fn extract_offer_nonce<'a, 'b, 'c>(node: &Node<'a, 'b, 'c>, message: &OnionMessa
 	}
 }
 
+/// Extract the payer's nonce from an invoice onion message received by the payer.
+///
+/// When the payer receives an invoice through their reply path, the blinded path context
+/// contains the nonce originally used for deriving their payer signing key. This nonce is
+/// needed to build a [`PayerProof`] using [`payer_proof::PaidBolt12Invoice::prove_payer_derived`].
+fn extract_payer_context<'a, 'b, 'c>(node: &Node<'a, 'b, 'c>, message: &OnionMessage) -> (PaymentId, Nonce) {
+	match node.onion_messenger.peel_onion_message(message) {
+		Ok(PeeledOnion::Offers(_, Some(OffersContext::OutboundPaymentForOffer { payment_id, nonce, .. }), _)) => (payment_id, nonce),
+		Ok(PeeledOnion::Offers(_, context, _)) => panic!("Expected OutboundPaymentForOffer context, got: {:?}", context),
+		Ok(PeeledOnion::Forward(_, _)) => panic!("Unexpected onion message forward"),
+		Ok(_) => panic!("Unexpected onion message"),
+		Err(e) => panic!("Failed to process onion message {:?}", e),
+	}
+}
+
 pub(super) fn extract_invoice_request<'a, 'b, 'c>(
 	node: &Node<'a, 'b, 'c>, message: &OnionMessage
 ) -> (InvoiceRequest, BlindedMessagePath) {
@@ -2667,3 +2684,246 @@ fn creates_and_pays_for_phantom_offer() {
 		assert!(nodes[0].onion_messenger.next_onion_message_for_peer(node_c_id).is_none());
 	}
 }
+
+/// Tests the full payer proof lifecycle: offer -> invoice_request -> invoice -> payment ->
+/// proof creation with derived key signing -> verification -> bech32 round-trip.
+///
+/// This exercises the primary API path where a wallet pays a BOLT 12 offer and then creates
+/// a payer proof using the derived signing key (same key derivation as the invoice request).
+#[test]
+fn creates_and_verifies_payer_proof_after_offer_payment() {
+	let chanmon_cfgs = create_chanmon_cfgs(2);
+	let node_cfgs = create_node_cfgs(2, &chanmon_cfgs);
+	let node_chanmgrs = create_node_chanmgrs(2, &node_cfgs, &[None, None]);
+	let nodes = create_network(2, &node_cfgs, &node_chanmgrs);
+
+	create_announced_chan_between_nodes_with_value(&nodes, 0, 1, 10_000_000, 1_000_000_000);
+
+	let alice = &nodes[0]; // recipient (offer creator)
+	let alice_id = alice.node.get_our_node_id();
+	let bob = &nodes[1]; // payer
+	let bob_id = bob.node.get_our_node_id();
+
+	// Alice creates an offer
+	let offer = alice.node
+		.create_offer_builder().unwrap()
+		.amount_msats(10_000_000)
+		.build().unwrap();
+
+	// Bob initiates payment
+	let payment_id = PaymentId([1; 32]);
+	bob.node.pay_for_offer(&offer, None, payment_id, Default::default()).unwrap();
+	expect_recent_payment!(bob, RecentPaymentDetails::AwaitingInvoice, payment_id);
+
+	// Bob sends invoice request to Alice
+	let onion_message = bob.onion_messenger.next_onion_message_for_peer(alice_id).unwrap();
+	alice.onion_messenger.handle_onion_message(bob_id, &onion_message);
+
+	let (invoice_request, _) = extract_invoice_request(alice, &onion_message);
+
+	// Alice sends invoice back to Bob
+	let onion_message = alice.onion_messenger.next_onion_message_for_peer(bob_id).unwrap();
+	bob.onion_messenger.handle_onion_message(alice_id, &onion_message);
+
+	let (invoice, _) = extract_invoice(bob, &onion_message);
+	assert_eq!(invoice.amount_msats(), 10_000_000);
+
+	// Extract the payer nonce and payment_id from Bob's reply path context. In a real wallet,
+	// these would be persisted alongside the payment for later payer proof creation.
+	let (context_payment_id, payer_nonce) = extract_payer_context(bob, &onion_message);
+	assert_eq!(context_payment_id, payment_id);
+
+	// Route the payment
+	route_bolt12_payment(bob, &[alice], &invoice);
+	expect_recent_payment!(bob, RecentPaymentDetails::Pending, payment_id);
+
+	// Get the payment preimage from Alice's PaymentClaimable event and claim it.
+	// In a real wallet, the payer receives the preimage via Event::PaymentSent after the
+	// recipient claims. For the test, we extract it from the recipient's claimable event.
+	let payment_preimage = match get_event!(alice, Event::PaymentClaimable) {
+		Event::PaymentClaimable { purpose, .. } => {
+			match &purpose {
+				PaymentPurpose::Bolt12OfferPayment { payment_context, .. } => {
+					assert_eq!(payment_context.offer_id, offer.id());
+					assert_eq!(
+						payment_context.invoice_request.payer_signing_pubkey,
+						invoice_request.payer_signing_pubkey(),
+					);
+				},
+				_ => panic!("Expected Bolt12OfferPayment purpose"),
+			}
+			purpose.preimage().unwrap()
+		},
+		_ => panic!("Expected Event::PaymentClaimable"),
+	};
+
+	claim_payment(bob, &[alice], payment_preimage);
+	expect_recent_payment!(bob, RecentPaymentDetails::Fulfilled, payment_id);
+
+	// --- Payer Proof Creation ---
+	// Bob (the payer) creates a proof-of-payment with selective disclosure.
+	// He includes the offer description and invoice amount, but omits other fields for privacy.
+	let expanded_key = bob.keys_manager.get_expanded_key();
+	let secp_ctx = Secp256k1::new();
+	let paid_invoice = payer_proof::PaidBolt12Invoice::new(
+		Bolt12InvoiceType::Bolt12Invoice(invoice.clone()),
+		payment_preimage,
+		Some(payer_nonce),
+	);
+	let proof = paid_invoice
+		.prove_payer_derived(&expanded_key, payment_id, &secp_ctx).unwrap()
+		.include_offer_description()
+		.include_invoice_amount()
+		.include_invoice_created_at()
+		.build_and_sign(None)
+		.unwrap();
+
+	// Check proof contents match the original payment
+	assert_eq!(proof.payment_preimage(), payment_preimage);
+	assert_eq!(proof.payment_hash(), invoice.payment_hash());
+	assert_eq!(proof.payer_signing_pubkey(), invoice.payer_signing_pubkey());
+	assert_eq!(proof.issuer_signing_pubkey(), invoice.signing_pubkey());
+	assert!(proof.payer_note().is_none());
+
+	// --- Serialization Round-Trip ---
+	// The proof can be serialized to a bech32 string (lnp...) for sharing.
+	let encoded = proof.to_string();
+	assert!(encoded.starts_with("lnp1"));
+
+	// Round-trip through TLV bytes: re-parse the raw bytes (verification happens at parse time).
+	let decoded = PayerProof::try_from(proof.bytes().to_vec()).unwrap();
+	assert_eq!(decoded.payment_preimage(), proof.payment_preimage());
+	assert_eq!(decoded.payment_hash(), proof.payment_hash());
+	assert_eq!(decoded.payer_signing_pubkey(), proof.payer_signing_pubkey());
+	assert_eq!(decoded.issuer_signing_pubkey(), proof.issuer_signing_pubkey());
+	assert_eq!(decoded.merkle_root(), proof.merkle_root());
+}
+
+/// Tests payer proof creation with a payer note, selective disclosure of specific invoice
+/// fields, and error cases. Verifies that:
+/// - A wrong preimage is rejected
+/// - A minimal proof (required fields only) works
+/// - Selective disclosure with a payer note works
+/// - The proof survives a bech32 round-trip with the note intact
+#[test]
+fn creates_payer_proof_with_note_and_selective_disclosure() {
+	let chanmon_cfgs = create_chanmon_cfgs(2);
+	let node_cfgs = create_node_cfgs(2, &chanmon_cfgs);
+	let node_chanmgrs = create_node_chanmgrs(2, &node_cfgs, &[None, None]);
+	let nodes = create_network(2, &node_cfgs, &node_chanmgrs);
+
+	create_announced_chan_between_nodes_with_value(&nodes, 0, 1, 10_000_000, 1_000_000_000);
+
+	let alice = &nodes[0];
+	let alice_id = alice.node.get_our_node_id();
+	let bob = &nodes[1];
+	let bob_id = bob.node.get_our_node_id();
+
+	// Alice creates an offer with a description
+	let offer = alice.node
+		.create_offer_builder().unwrap()
+		.amount_msats(5_000_000)
+		.description("Coffee beans - 1kg".into())
+		.build().unwrap();
+
+	// Bob pays for the offer
+	let payment_id = PaymentId([2; 32]);
+	bob.node.pay_for_offer(&offer, None, payment_id, Default::default()).unwrap();
+	expect_recent_payment!(bob, RecentPaymentDetails::AwaitingInvoice, payment_id);
+
+	// Exchange messages
+	let onion_message = bob.onion_messenger.next_onion_message_for_peer(alice_id).unwrap();
+	alice.onion_messenger.handle_onion_message(bob_id, &onion_message);
+	let (invoice_request, _) = extract_invoice_request(alice, &onion_message);
+
+	let onion_message = alice.onion_messenger.next_onion_message_for_peer(bob_id).unwrap();
+	bob.onion_messenger.handle_onion_message(alice_id, &onion_message);
+
+	let (invoice, _) = extract_invoice(bob, &onion_message);
+	let (context_payment_id, payer_nonce) = extract_payer_context(bob, &onion_message);
+	assert_eq!(context_payment_id, payment_id);
+
+	// Route and claim the payment, extracting the preimage
+	route_bolt12_payment(bob, &[alice], &invoice);
+	expect_recent_payment!(bob, RecentPaymentDetails::Pending, payment_id);
+
+	let payment_preimage = match get_event!(alice, Event::PaymentClaimable) {
+		Event::PaymentClaimable { purpose, .. } => {
+			match &purpose {
+				PaymentPurpose::Bolt12OfferPayment { payment_context, .. } => {
+					assert_eq!(payment_context.offer_id, offer.id());
+					assert_eq!(
+						payment_context.invoice_request.payer_signing_pubkey,
+						invoice_request.payer_signing_pubkey(),
+					);
+				},
+				_ => panic!("Expected Bolt12OfferPayment purpose"),
+			}
+			purpose.preimage().unwrap()
+		},
+		_ => panic!("Expected Event::PaymentClaimable"),
+	};
+
+	claim_payment(bob, &[alice], payment_preimage);
+	expect_recent_payment!(bob, RecentPaymentDetails::Fulfilled, payment_id);
+
+	// --- Test 1: Wrong preimage is rejected ---
+	let wrong_preimage = PaymentPreimage([0xDE; 32]);
+	let wrong_paid = payer_proof::PaidBolt12Invoice::new(
+		Bolt12InvoiceType::Bolt12Invoice(invoice.clone()), wrong_preimage, Some(payer_nonce),
+	);
+	assert!(matches!(wrong_paid.prove_payer(), Err(PayerProofError::PreimageMismatch)));
+
+	// --- Test 2: Wrong payment_id causes key derivation failure ---
+	let expanded_key = bob.keys_manager.get_expanded_key();
+	let secp_ctx = Secp256k1::new();
+	let paid_invoice = payer_proof::PaidBolt12Invoice::new(
+		Bolt12InvoiceType::Bolt12Invoice(invoice.clone()),
+		payment_preimage,
+		Some(payer_nonce),
+	);
+	let wrong_payment_id = PaymentId([0xFF; 32]);
+	let result = paid_invoice.prove_payer_derived(&expanded_key, wrong_payment_id, &secp_ctx);
+	assert!(matches!(result, Err(PayerProofError::KeyDerivationFailed)));
+
+	// --- Test 3: Wrong nonce causes key derivation failure ---
+	let wrong_nonce = Nonce::from_entropy_source(&chanmon_cfgs[0].keys_manager);
+	let wrong_nonce_paid = payer_proof::PaidBolt12Invoice::new(
+		Bolt12InvoiceType::Bolt12Invoice(invoice.clone()), payment_preimage, Some(wrong_nonce),
+	);
+	let result = wrong_nonce_paid.prove_payer_derived(&expanded_key, payment_id, &secp_ctx);
+	assert!(matches!(result, Err(PayerProofError::KeyDerivationFailed)));
+
+	// --- Test 4: Minimal proof (only required fields) ---
+	let minimal_proof = paid_invoice
+		.prove_payer_derived(&expanded_key, payment_id, &secp_ctx).unwrap()
+		.build_and_sign(None)
+		.unwrap();
+	// --- Test 5: Proof with selective disclosure and payer note ---
+	let proof_with_note = paid_invoice
+		.prove_payer_derived(&expanded_key, payment_id, &secp_ctx).unwrap()
+		.include_offer_description()
+		.include_offer_issuer()
+		.include_invoice_amount()
+		.include_invoice_created_at()
+		.build_and_sign(Some("Paid for coffee".into()))
+		.unwrap();
+	assert_eq!(proof_with_note.payer_note().map(|p| p.0), Some("Paid for coffee"));
+
+	// Both proofs should verify and have the same core fields
+	assert_eq!(minimal_proof.payment_preimage(), proof_with_note.payment_preimage());
+	assert_eq!(minimal_proof.payment_hash(), proof_with_note.payment_hash());
+	assert_eq!(minimal_proof.payer_signing_pubkey(), proof_with_note.payer_signing_pubkey());
+	assert_eq!(minimal_proof.issuer_signing_pubkey(), proof_with_note.issuer_signing_pubkey());
+
+	// The merkle roots are the same since both reconstruct from the same invoice
+	assert_eq!(minimal_proof.merkle_root(), proof_with_note.merkle_root());
+
+	// --- Test 6: Round-trip the proof with note through TLV bytes ---
+	let encoded = proof_with_note.to_string();
+	assert!(encoded.starts_with("lnp1"));
+
+	let decoded = PayerProof::try_from(proof_with_note.bytes().to_vec()).unwrap();
+	assert_eq!(decoded.payer_note().map(|p| p.0), Some("Paid for coffee"));
+	assert_eq!(decoded.payment_preimage(), payment_preimage);
+}

lightning/src/offers/invoice.rs

@@ -985,6 +985,11 @@ impl Bolt12Invoice {
 		self.signature
 	}
 
+	/// The raw serialized bytes of the invoice.
+	pub(super) fn invoice_bytes(&self) -> &[u8] {
+		&self.bytes
+	}
+
 	/// Hash that was used for signing the invoice.
 	pub fn signable_hash(&self) -> [u8; 32] {
 		self.tagged_hash.as_digest().as_ref().clone()
@@ -1035,9 +1040,6 @@ impl Bolt12Invoice {
 
 	/// Re-derives the payer's signing keypair for payer proof creation.
 	///
-	/// This performs the same key derivation that occurs during invoice request creation
-	/// with `deriving_signing_pubkey`, allowing the payer to recover their signing keypair.
-	///
 	/// The `nonce` and `payment_id` must be the same ones used when creating the original
 	/// invoice request. In the common proof-of-payment flow, callers can instead use
 	/// `PaidBolt12Invoice::prove_payer_derived` together with the `payment_id` from
@@ -1557,16 +1559,31 @@ impl TryFrom<Vec<u8>> for Bolt12Invoice {
 /// Valid type range for invoice TLV records.
 pub(super) const INVOICE_TYPES: core::ops::Range<u64> = 160..240;
 
+/// TLV record type for the invoice creation timestamp.
+pub(super) const INVOICE_CREATED_AT_TYPE: u64 = 164;
+
+/// TLV record type for [`Bolt12Invoice::payment_hash`].
+pub(super) const INVOICE_PAYMENT_HASH_TYPE: u64 = 168;
+
+/// TLV record type for [`Bolt12Invoice::amount_msats`].
+pub(super) const INVOICE_AMOUNT_TYPE: u64 = 170;
+
+/// TLV record type for [`Bolt12Invoice::invoice_features`].
+pub(super) const INVOICE_FEATURES_TYPE: u64 = 174;
+
+/// TLV record type for [`Bolt12Invoice::signing_pubkey`].
+pub(super) const INVOICE_NODE_ID_TYPE: u64 = 176;
+
 tlv_stream!(InvoiceTlvStream, InvoiceTlvStreamRef<'a>, INVOICE_TYPES, {
 	(160, paths: (Vec<BlindedPath>, WithoutLength, Iterable<'a, BlindedPathIter<'a>, BlindedPath>)),
 	(162, blindedpay: (Vec<BlindedPayInfo>, WithoutLength, Iterable<'a, BlindedPayInfoIter<'a>, BlindedPayInfo>)),
-	(164, created_at: (u64, HighZeroBytesDroppedBigSize)),
+	(INVOICE_CREATED_AT_TYPE, created_at: (u64, HighZeroBytesDroppedBigSize)),
 	(166, relative_expiry: (u32, HighZeroBytesDroppedBigSize)),
-	(168, payment_hash: PaymentHash),
-	(170, amount: (u64, HighZeroBytesDroppedBigSize)),
+	(INVOICE_PAYMENT_HASH_TYPE, payment_hash: PaymentHash),
+	(INVOICE_AMOUNT_TYPE, amount: (u64, HighZeroBytesDroppedBigSize)),
 	(172, fallbacks: (Vec<FallbackAddress>, WithoutLength)),
-	(174, features: (Bolt12InvoiceFeatures, WithoutLength)),
-	(176, node_id: PublicKey),
+	(INVOICE_FEATURES_TYPE, features: (Bolt12InvoiceFeatures, WithoutLength)),
+	(INVOICE_NODE_ID_TYPE, node_id: PublicKey),
 	// Only present in `StaticInvoice`s.
 	(236, held_htlc_available_paths: (Vec<BlindedMessagePath>, WithoutLength)),
 });