refactor(offers): bundle paid invoice data for payer proofs

Encapsulate the paid invoice, preimage, and payer nonce in the
PaidBolt12Invoice struct and surface it through
Event::PaymentSent::bolt12_invoice. To support the nonce round-trip,
plumb payment_nonce through HTLCSource::OutboundRoute,
SendAlongPathArgs, PendingOutboundPayment::Retryable and the outbound
payment internals, and extract it from the OffersContext variants so
payers can later re-derive the payer signing key from the same nonce
used for the invoice request.

Update expect_payment_sent, claim_payment, claim_payment_along_route
and the async-payments test assertions to surface and consume the
PaidBolt12Invoice. Also add Writeable/Readable impls for sha256::Hash
in util::ser so PaidBolt12Invoice serialization compiles.

Co-Authored-By: Jeffrey Czyz <jkczyz@gmail.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 3 people

fuzz/src/process_onion_failure.rs

@@ -122,6 +122,7 @@ fn do_test<Out: test_logger::Output>(data: &[u8], out: Out) {
 		first_hop_htlc_msat: 0,
 		payment_id,
 		bolt12_invoice: None,
+		payment_nonce: None,
 	};
 
 	let failure_len = get_u16!();

lightning/src/events/mod.rs

@@ -31,7 +31,9 @@ use crate::ln::outbound_payment::RecipientOnionFields;
 use crate::ln::types::ChannelId;
 use crate::offers::invoice::Bolt12Invoice;
 use crate::offers::invoice_request::InvoiceRequest;
+use crate::offers::nonce::Nonce;
 use crate::offers::payer_proof::Bolt12InvoiceType;
+pub use crate::offers::payer_proof::PaidBolt12Invoice;
 use crate::offers::static_invoice::StaticInvoice;
 use crate::onion_message::messenger::Responder;
 use crate::routing::gossip::NetworkUpdate;
@@ -1090,19 +1092,14 @@ pub enum Event {
 		///
 		/// [`Route::get_total_fees`]: crate::routing::router::Route::get_total_fees
 		fee_paid_msat: Option<u64>,
-		/// The BOLT 12 invoice that was paid. `None` if the payment was a non BOLT 12 payment.
+		/// The paid BOLT 12 invoice bundled with the data needed to construct a
+		/// [`PayerProof`], which selectively discloses invoice fields to prove payment to a
+		/// third party.
 		///
-		/// The BOLT 12 invoice is useful for proof of payment because it contains the
-		/// payment hash. A third party can verify that the payment was made by
-		/// showing the invoice and confirming that the payment hash matches
-		/// the hash of the payment preimage.
+		/// `None` for non-BOLT 12 payments.
 		///
-		/// However, the [`Bolt12InvoiceType`] can also be of type [`StaticInvoice`], which
-		/// is a special [`Bolt12Invoice`] where proof of payment is not possible.
-		///
-		/// [`Bolt12InvoiceType`]: crate::offers::payer_proof::Bolt12InvoiceType
-		/// [`StaticInvoice`]: crate::offers::static_invoice::StaticInvoice
-		bolt12_invoice: Option<Bolt12InvoiceType>,
+		/// [`PayerProof`]: crate::offers::payer_proof::PayerProof
+		bolt12_invoice: Option<PaidBolt12Invoice>,
 	},
 	/// Indicates an outbound payment failed. Individual [`Event::PaymentPathFailed`] events
 	/// provide failure information for each path attempt in the payment, including retries.
@@ -1977,13 +1974,16 @@ impl Writeable for Event {
 				ref bolt12_invoice,
 			} => {
 				2u8.write(writer)?;
+				let invoice_type = bolt12_invoice.as_ref().map(|paid| paid.invoice_type());
+				let payment_nonce = bolt12_invoice.as_ref().and_then(|paid| paid.nonce());
 				write_tlv_fields!(writer, {
 					(0, payment_preimage, required),
 					(1, payment_hash, required),
 					(3, payment_id, option),
 					(5, fee_paid_msat, option),
 					(7, amount_msat, option),
-					(9, bolt12_invoice, option),
+					(9, invoice_type, option),
+					(11, payment_nonce, option),
 				});
 			},
 			&Event::PaymentPathFailed {
@@ -2475,20 +2475,25 @@ impl MaybeReadable for Event {
 					let mut payment_id = None;
 					let mut amount_msat = None;
 					let mut fee_paid_msat = None;
-					let mut bolt12_invoice = None;
+					let mut invoice_type: Option<Bolt12InvoiceType> = None;
+					let mut payment_nonce: Option<Nonce> = None;
 					read_tlv_fields!(reader, {
 						(0, payment_preimage, required),
 						(1, payment_hash, option),
 						(3, payment_id, option),
 						(5, fee_paid_msat, option),
 						(7, amount_msat, option),
-						(9, bolt12_invoice, option),
+						(9, invoice_type, option),
+						(11, payment_nonce, option),
 					});
 					if payment_hash.is_none() {
 						payment_hash = Some(PaymentHash(
 							Sha256::hash(&payment_preimage.0[..]).to_byte_array(),
 						));
 					}
+					let bolt12_invoice = invoice_type.map(|invoice| {
+						PaidBolt12Invoice::new(invoice, payment_preimage, payment_nonce)
+					});
 					Ok(Some(Event::PaymentSent {
 						payment_id,
 						payment_preimage,

lightning/src/ln/async_payments_tests.rs

@@ -42,7 +42,6 @@ use crate::offers::flow::{
 use crate::offers::invoice_request::InvoiceRequest;
 use crate::offers::nonce::Nonce;
 use crate::offers::offer::{Amount, Offer};
-use crate::offers::payer_proof::Bolt12InvoiceType;
 use crate::offers::static_invoice::{
 	StaticInvoice, StaticInvoiceBuilder,
 	DEFAULT_RELATIVE_EXPIRY as STATIC_INVOICE_DEFAULT_RELATIVE_EXPIRY,
@@ -992,7 +991,7 @@ fn ignore_duplicate_invoice() {
 	let keysend_preimage = extract_payment_preimage(&claimable_ev);
 	let (res, _) =
 		claim_payment_along_route(ClaimAlongRouteArgs::new(sender, route, keysend_preimage));
-	assert_eq!(res, Some(Bolt12InvoiceType::StaticInvoice(static_invoice.clone())));
+	assert_eq!(res.as_ref().and_then(|paid| paid.static_invoice()), Some(&static_invoice));
 
 	// After paying the static invoice, check that regular invoice received from async recipient is ignored.
 	match sender.onion_messenger.peel_onion_message(&invoice_om) {
@@ -1077,7 +1076,7 @@ fn ignore_duplicate_invoice() {
 
 	// After paying invoice, check that static invoice is ignored.
 	let res = claim_payment(sender, route[0], payment_preimage);
-	assert_eq!(res, Some(Bolt12InvoiceType::Bolt12Invoice(invoice)));
+	assert_eq!(res.as_ref().and_then(|paid| paid.bolt12_invoice()), Some(&invoice));
 
 	sender.onion_messenger.handle_onion_message(always_online_node_id, &static_invoice_om);
 	let async_pmts_msgs = AsyncPaymentsMessageHandler::release_pending_messages(sender.node);
@@ -1148,7 +1147,7 @@ fn async_receive_flow_success() {
 	let keysend_preimage = extract_payment_preimage(&claimable_ev);
 	let (res, _) =
 		claim_payment_along_route(ClaimAlongRouteArgs::new(&nodes[0], route, keysend_preimage));
-	assert_eq!(res, Some(Bolt12InvoiceType::StaticInvoice(static_invoice)));
+	assert_eq!(res.as_ref().and_then(|paid| paid.static_invoice()), Some(&static_invoice));
 }
 
 #[cfg_attr(feature = "std", ignore)]
@@ -2392,7 +2391,7 @@ fn refresh_static_invoices_for_used_offers() {
 	let claimable_ev = do_pass_along_path(args).unwrap();
 	let keysend_preimage = extract_payment_preimage(&claimable_ev);
 	let res = claim_payment_along_route(ClaimAlongRouteArgs::new(sender, route, keysend_preimage));
-	assert_eq!(res.0, Some(Bolt12InvoiceType::StaticInvoice(updated_invoice)));
+	assert_eq!(res.0.as_ref().and_then(|paid| paid.static_invoice()), Some(&updated_invoice));
 }
 
 #[cfg_attr(feature = "std", ignore)]
@@ -2727,7 +2726,7 @@ fn invoice_server_is_not_channel_peer() {
 	let claimable_ev = do_pass_along_path(args).unwrap();
 	let keysend_preimage = extract_payment_preimage(&claimable_ev);
 	let res = claim_payment_along_route(ClaimAlongRouteArgs::new(sender, route, keysend_preimage));
-	assert_eq!(res.0, Some(Bolt12InvoiceType::StaticInvoice(invoice)));
+	assert_eq!(res.0.as_ref().and_then(|paid| paid.static_invoice()), Some(&invoice));
 }
 
 #[test]
@@ -2970,7 +2969,7 @@ fn async_payment_e2e() {
 	let keysend_preimage = extract_payment_preimage(&claimable_ev);
 	let (res, _) =
 		claim_payment_along_route(ClaimAlongRouteArgs::new(sender, route, keysend_preimage));
-	assert_eq!(res, Some(Bolt12InvoiceType::StaticInvoice(static_invoice)));
+	assert_eq!(res.as_ref().and_then(|paid| paid.static_invoice()), Some(&static_invoice));
 }
 
 #[test]
@@ -3207,7 +3206,7 @@ fn intercepted_hold_htlc() {
 	let keysend_preimage = extract_payment_preimage(&claimable_ev);
 	let (res, _) =
 		claim_payment_along_route(ClaimAlongRouteArgs::new(sender, route, keysend_preimage));
-	assert_eq!(res, Some(Bolt12InvoiceType::StaticInvoice(static_invoice)));
+	assert_eq!(res.as_ref().and_then(|paid| paid.static_invoice()), Some(&static_invoice));
 }
 
 #[test]
@@ -3457,7 +3456,7 @@ fn release_htlc_races_htlc_onion_decode() {
 	let keysend_preimage = extract_payment_preimage(&claimable_ev);
 	let (res, _) =
 		claim_payment_along_route(ClaimAlongRouteArgs::new(sender, route, keysend_preimage));
-	assert_eq!(res, Some(Bolt12InvoiceType::StaticInvoice(static_invoice)));
+	assert_eq!(res.as_ref().and_then(|paid| paid.static_invoice()), Some(&static_invoice));
 }
 
 #[test]
@@ -3621,5 +3620,5 @@ fn async_payment_e2e_release_before_hold_registered() {
 	let keysend_preimage = extract_payment_preimage(&claimable_ev);
 	let (res, _) =
 		claim_payment_along_route(ClaimAlongRouteArgs::new(sender, route, keysend_preimage));
-	assert_eq!(res, Some(Bolt12InvoiceType::StaticInvoice(static_invoice)));
+	assert_eq!(res.as_ref().and_then(|paid| paid.static_invoice()), Some(&static_invoice));
 }

lightning/src/ln/channel.rs

@@ -17060,6 +17060,7 @@ mod tests {
 				first_hop_htlc_msat: 548,
 				payment_id: PaymentId([42; 32]),
 				bolt12_invoice: None,
+			payment_nonce: None,
 			},
 			skimmed_fee_msat: None,
 			blinding_point: None,
@@ -17553,6 +17554,7 @@ mod tests {
 			first_hop_htlc_msat: 0,
 			payment_id: PaymentId([42; 32]),
 			bolt12_invoice: None,
+			payment_nonce: None,
 		};
 		let dummy_outbound_output = OutboundHTLCOutput {
 			htlc_id: 0,

lightning/src/ln/channelmanager.rs

@@ -819,10 +819,20 @@ mod fuzzy_channelmanager {
 			/// doing a double-pass on route when we get a failure back
 			first_hop_htlc_msat: u64,
 			payment_id: PaymentId,
-			/// The BOLT12 invoice associated with this payment, if any. This is stored here to ensure
-			/// we can provide proof-of-payment details in payment claim events even after a restart
-			/// with a stale ChannelManager state.
+			/// The BOLT 12 invoice associated with this payment, if any. Stored here so it can
+			/// be bundled into [`PaidBolt12Invoice`] in [`Event::PaymentSent`] even after a
+			/// restart with a stale `ChannelManager` state.
+			///
+			/// [`PaidBolt12Invoice`]: crate::offers::payer_proof::PaidBolt12Invoice
+			/// [`Event::PaymentSent`]: crate::events::Event::PaymentSent
 			bolt12_invoice: Option<Bolt12InvoiceType>,
+			/// The [`Nonce`] used when the BOLT 12 [`InvoiceRequest`] was created. Stored here so
+			/// it can be bundled into [`PaidBolt12Invoice`] for building payer proofs, even after
+			/// a restart with a stale `ChannelManager` state.
+			///
+			/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
+			/// [`PaidBolt12Invoice`]: crate::offers::payer_proof::PaidBolt12Invoice
+			payment_nonce: Option<Nonce>,
 		},
 	}
 
@@ -896,6 +906,7 @@ impl core::hash::Hash for HTLCSource {
 				payment_id,
 				first_hop_htlc_msat,
 				bolt12_invoice,
+				..
 			} => {
 				1u8.hash(hasher);
 				path.hash(hasher);
@@ -930,6 +941,7 @@ impl HTLCSource {
 			first_hop_htlc_msat: 0,
 			payment_id: PaymentId([2; 32]),
 			bolt12_invoice: None,
+			payment_nonce: None,
 		}
 	}
 
@@ -958,9 +970,9 @@ impl HTLCSource {
 	pub(crate) fn static_invoice(&self) -> Option<StaticInvoice> {
 		match self {
 			Self::OutboundRoute {
-				bolt12_invoice: Some(Bolt12InvoiceType::StaticInvoice(inv)),
+				bolt12_invoice: Some(Bolt12InvoiceType::StaticInvoice(invoice)),
 				..
-			} => Some(inv.clone()),
+			} => Some(invoice.clone()),
 			_ => None,
 		}
 	}
@@ -5348,6 +5360,7 @@ impl<
 			keysend_preimage,
 			invoice_request: None,
 			bolt12_invoice: None,
+			payment_nonce: None,
 			session_priv_bytes,
 			hold_htlc_at_next_hop: false,
 		})
@@ -5363,6 +5376,7 @@ impl<
 			keysend_preimage,
 			invoice_request,
 			bolt12_invoice,
+			payment_nonce,
 			session_priv_bytes,
 			hold_htlc_at_next_hop,
 		} = args;
@@ -5439,6 +5453,7 @@ impl<
 							first_hop_htlc_msat: htlc_msat,
 							payment_id,
 							bolt12_invoice: bolt12_invoice.cloned(),
+							payment_nonce,
 						};
 						let send_res = chan.send_htlc_and_commit(
 							htlc_msat,
@@ -5732,21 +5747,29 @@ impl<
 	pub fn send_payment_for_bolt12_invoice(
 		&self, invoice: &Bolt12Invoice, context: Option<&OffersContext>,
 	) -> Result<(), Bolt12PaymentError> {
+		let nonce = context.and_then(|ctx| match ctx {
+			OffersContext::OutboundPaymentForOffer { nonce, .. }
+			| OffersContext::OutboundPaymentForRefund { nonce, .. } => Some(*nonce),
+			_ => None,
+		});
 		match self.flow.verify_bolt12_invoice(invoice, context) {
-			Ok(payment_id) => self.send_payment_for_verified_bolt12_invoice(invoice, payment_id),
+			Ok(payment_id) => {
+				self.send_payment_for_verified_bolt12_invoice(invoice, payment_id, nonce)
+			},
 			Err(()) => Err(Bolt12PaymentError::UnexpectedInvoice),
 		}
 	}
 
 	fn send_payment_for_verified_bolt12_invoice(
-		&self, invoice: &Bolt12Invoice, payment_id: PaymentId,
+		&self, invoice: &Bolt12Invoice, payment_id: PaymentId, payment_nonce: Option<Nonce>,
 	) -> Result<(), Bolt12PaymentError> {
 		let best_block_height = self.best_block.read().unwrap().height;
 		let _persistence_guard = PersistenceNotifierGuard::notify_on_drop(self);
 		let features = self.bolt12_invoice_features();
 		self.pending_outbound_payments.send_payment_for_bolt12_invoice(
 			invoice,
 			payment_id,
+			payment_nonce,
 			&self.router,
 			self.list_usable_channels(),
 			features,
@@ -9964,7 +9987,12 @@ This indicates a bug inside LDK. Please report this error at https://github.com/
 		let htlc_id = SentHTLCId::from_source(&source);
 		match source {
 			HTLCSource::OutboundRoute {
-				session_priv, payment_id, path, bolt12_invoice, ..
+				session_priv,
+				payment_id,
+				path,
+				bolt12_invoice,
+				payment_nonce,
+				..
 			} => {
 				debug_assert!(!startup_replay,
 					"We don't support claim_htlc claims during startup - monitors may not be available yet");
@@ -9996,6 +10024,7 @@ This indicates a bug inside LDK. Please report this error at https://github.com/
 					payment_id,
 					payment_preimage,
 					bolt12_invoice,
+					payment_nonce,
 					session_priv,
 					path,
 					from_onchain,
@@ -17036,7 +17065,12 @@ impl<
 					return None;
 				}
 
-				let res = self.send_payment_for_verified_bolt12_invoice(&invoice, payment_id);
+				let payment_nonce = context.as_ref().and_then(|ctx| match ctx {
+					OffersContext::OutboundPaymentForOffer { nonce, .. }
+					| OffersContext::OutboundPaymentForRefund { nonce, .. } => Some(*nonce),
+					_ => None,
+				});
+				let res = self.send_payment_for_verified_bolt12_invoice(&invoice, payment_id, payment_nonce);
 				handle_pay_invoice_res!(res, invoice, logger);
 			},
 			OffersMessage::StaticInvoice(invoice) => {
@@ -17677,6 +17711,7 @@ impl Readable for HTLCSource {
 				let mut payment_params: Option<PaymentParameters> = None;
 				let mut blinded_tail: Option<BlindedTail> = None;
 				let mut bolt12_invoice: Option<Bolt12InvoiceType> = None;
+				let mut payment_nonce: Option<Nonce> = None;
 				read_tlv_fields!(reader, {
 					(0, session_priv, required),
 					(1, payment_id, option),
@@ -17685,6 +17720,7 @@ impl Readable for HTLCSource {
 					(5, payment_params, (option: ReadableArgs, 0)),
 					(6, blinded_tail, option),
 					(7, bolt12_invoice, option),
+					(9, payment_nonce, option),
 				});
 				if payment_id.is_none() {
 					// For backwards compat, if there was no payment_id written, use the session_priv bytes
@@ -17708,6 +17744,7 @@ impl Readable for HTLCSource {
 					path,
 					payment_id: payment_id.unwrap(),
 					bolt12_invoice,
+					payment_nonce,
 				})
 			}
 			1 => Ok(HTLCSource::PreviousHopData(Readable::read(reader)?)),
@@ -17727,6 +17764,7 @@ impl Writeable for HTLCSource {
 				ref path,
 				payment_id,
 				bolt12_invoice,
+				payment_nonce,
 			} => {
 				0u8.write(writer)?;
 				let payment_id_opt = Some(payment_id);
@@ -17739,6 +17777,7 @@ impl Writeable for HTLCSource {
 				   (5, None::<PaymentParameters>, option), // payment_params in LDK versions prior to 0.0.115
 				   (6, path.blinded_tail, option),
 				   (7, bolt12_invoice, option),
+				   (9, payment_nonce, option),
 				});
 			},
 			HTLCSource::PreviousHopData(ref field) => {
@@ -19603,6 +19642,7 @@ impl<
 								session_priv,
 								path,
 								bolt12_invoice,
+								payment_nonce,
 								..
 							} => {
 								if let Some(preimage) = preimage_opt {
@@ -19620,6 +19660,7 @@ impl<
 										payment_id,
 										preimage,
 										bolt12_invoice,
+										payment_nonce,
 										session_priv,
 										path,
 										true,