Persist the paid BOLT 12 invoice in the payment details

Add a `bolt12_invoice` field to `PaymentKind::Bolt12Offer` and
`PaymentKind::Bolt12Refund`, and set it from `Event::PaymentSent` when a
BOLT 12 payment succeeds.

Besides being useful on its own, this gives us everything we need to
build a payer proof for a past payment without keeping any additional
state around: the invoice is persisted alongside the payment and thus
survives restarts.

This commit was written with AI assistance.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: vincenzopalazzo

src/event.rs

@@ -1129,6 +1129,7 @@ where
 								offer_id,
 								payer_note,
 								quantity,
+								bolt12_invoice: None,
 							};
 
 							let payment = PaymentDetails::new(
@@ -1178,6 +1179,7 @@ where
 								secret: Some(payment_secret),
 								payer_note: None,
 								quantity: None,
+								bolt12_invoice: None,
 							};
 
 							let payment = PaymentDetails::new(
@@ -1331,6 +1333,7 @@ where
 							offer_id: payment_context.offer_id,
 							payer_note: payment_context.invoice_request.payer_note_truncated,
 							quantity: payment_context.invoice_request.quantity,
+							bolt12_invoice: None,
 						};
 						let update = PaymentDetailsUpdate {
 							preimage: Some(payment_preimage),
@@ -1352,6 +1355,7 @@ where
 							secret: Some(payment_secret),
 							payer_note: None,
 							quantity: None,
+							bolt12_invoice: None,
 						};
 						let update = PaymentDetailsUpdate {
 							preimage: Some(payment_preimage),
@@ -1442,12 +1446,16 @@ where
 					debug_assert!(false, "payment_id should always be set.");
 					return Ok(());
 				};
+				let bolt12_invoice = bolt12_invoice.map(Into::into);
 
+				// Only set the field if the event actually carried an invoice, to avoid
+				// overriding any previously-stored invoice with `None`.
 				let update = PaymentDetailsUpdate {
 					hash: Some(Some(payment_hash)),
 					preimage: Some(Some(payment_preimage)),
 					fee_paid_msat: Some(fee_paid_msat),
 					status: Some(PaymentStatus::Succeeded),
+					bolt12_invoice: bolt12_invoice.clone().map(Some),
 					..PaymentDetailsUpdate::new(payment_id)
 				};
 
@@ -1482,7 +1490,7 @@ where
 					payment_hash,
 					payment_preimage: Some(payment_preimage),
 					fee_paid_msat,
-					bolt12_invoice: bolt12_invoice.map(Into::into),
+					bolt12_invoice,
 				};
 
 				match self.event_queue.add_event(event).await {

src/payment/bolt12.rs

@@ -158,6 +158,7 @@ impl Bolt12Payment {
 					offer_id: offer.id(),
 					payer_note: payer_note.map(UntrustedString),
 					quantity,
+					bolt12_invoice: None,
 				};
 				let payment = PaymentDetails::new(
 					payment_id,
@@ -183,6 +184,7 @@ impl Bolt12Payment {
 							offer_id: offer.id(),
 							payer_note: payer_note.map(UntrustedString),
 							quantity,
+							bolt12_invoice: None,
 						};
 						let payment = PaymentDetails::new(
 							payment_id,
@@ -320,6 +322,7 @@ impl Bolt12Payment {
 					offer_id: offer.id(),
 					payer_note: payer_note.map(UntrustedString),
 					quantity,
+					bolt12_invoice: None,
 				};
 				let payment = PaymentDetails::new(
 					payment_id,
@@ -345,6 +348,7 @@ impl Bolt12Payment {
 							offer_id: offer.id(),
 							payer_note: payer_note.map(UntrustedString),
 							quantity,
+							bolt12_invoice: None,
 						};
 						let payment = PaymentDetails::new(
 							payment_id,
@@ -498,6 +502,7 @@ impl Bolt12Payment {
 			secret: None,
 			payer_note: payer_note.map(|note| UntrustedString(note)),
 			quantity,
+			bolt12_invoice: None,
 		};
 		let payment = PaymentDetails::new(
 			payment_id,

src/payment/store.rs

@@ -10,6 +10,8 @@ use std::time::{Duration, SystemTime, UNIX_EPOCH};
 use bitcoin::secp256k1::PublicKey;
 use bitcoin::{BlockHash, Txid};
 use lightning::chain::chaininterface::TransactionType as LdkTransactionType;
+#[cfg(not(feature = "uniffi"))]
+use lightning::events::PaidBolt12Invoice;
 use lightning::ln::channelmanager::PaymentId;
 use lightning::ln::msgs::DecodeError;
 use lightning::ln::types::ChannelId;
@@ -23,6 +25,8 @@ use lightning_types::payment::{PaymentHash, PaymentPreimage, PaymentSecret};
 use lightning_types::string::UntrustedString;
 
 use crate::data_store::{StorableObject, StorableObjectId, StorableObjectUpdate};
+#[cfg(feature = "uniffi")]
+use crate::ffi::PaidBolt12Invoice;
 use crate::hex_utils;
 
 /// Represents a payment.
@@ -251,6 +255,18 @@ impl StorableObject for PaymentDetails {
 			update_if_necessary!(self.fee_paid_msat, fee_paid_msat_opt);
 		}
 
+		if let Some(ref bolt12_invoice_opt) = update.bolt12_invoice {
+			match self.kind {
+				PaymentKind::Bolt12Offer { ref mut bolt12_invoice, .. } => {
+					update_if_necessary!(*bolt12_invoice, bolt12_invoice_opt.clone());
+				},
+				PaymentKind::Bolt12Refund { ref mut bolt12_invoice, .. } => {
+					update_if_necessary!(*bolt12_invoice, bolt12_invoice_opt.clone());
+				},
+				_ => {},
+			}
+		}
+
 		if let Some(skimmed_fee_msat) = update.counterparty_skimmed_fee_msat {
 			match self.kind {
 				PaymentKind::Bolt11 { ref mut counterparty_skimmed_fee_msat, .. } => {
@@ -559,6 +575,15 @@ pub enum PaymentKind {
 		///
 		/// This will always be `None` for payments serialized with version `v0.3.0`.
 		quantity: Option<u64>,
+		/// The BOLT 12 invoice that was paid, set once the payment succeeded.
+		///
+		/// Only set for successful outbound payments, allowing to build a payer proof for the
+		/// payment via [`Bolt12Payment::create_payer_proof`].
+		///
+		/// This will always be `None` for payments serialized with version `v0.7.0` or prior.
+		///
+		/// [`Bolt12Payment::create_payer_proof`]: crate::payment::Bolt12Payment::create_payer_proof
+		bolt12_invoice: Option<PaidBolt12Invoice>,
 	},
 	/// A [BOLT 12] 'refund' payment, i.e., a payment for a [`Refund`].
 	///
@@ -586,6 +611,15 @@ pub enum PaymentKind {
 		///
 		/// This will always be `None` for payments serialized with version `v0.3.0`.
 		quantity: Option<u64>,
+		/// The BOLT 12 invoice that was paid, set once the payment succeeded.
+		///
+		/// Only set for successful outbound payments, allowing to build a payer proof for the
+		/// payment via [`Bolt12Payment::create_payer_proof`].
+		///
+		/// This will always be `None` for payments serialized with version `v0.7.0` or prior.
+		///
+		/// [`Bolt12Payment::create_payer_proof`]: crate::payment::Bolt12Payment::create_payer_proof
+		bolt12_invoice: Option<PaidBolt12Invoice>,
 	},
 	/// A spontaneous ("keysend") payment.
 	Spontaneous {
@@ -625,6 +659,7 @@ impl_writeable_tlv_based_enum!(PaymentKind,
 		(3, quantity, option),
 		(4, secret, option),
 		(6, offer_id, required),
+		(8, bolt12_invoice, option),
 	},
 	(8, Spontaneous) => {
 		(0, hash, required),
@@ -636,6 +671,7 @@ impl_writeable_tlv_based_enum!(PaymentKind,
 		(2, preimage, option),
 		(3, quantity, option),
 		(4, secret, option),
+		(6, bolt12_invoice, option),
 	}
 );
 
@@ -698,6 +734,7 @@ pub(crate) struct PaymentDetailsUpdate {
 	pub direction: Option<PaymentDirection>,
 	pub status: Option<PaymentStatus>,
 	pub confirmation_status: Option<ConfirmationStatus>,
+	pub bolt12_invoice: Option<Option<PaidBolt12Invoice>>,
 	pub txid: Option<Txid>,
 	pub tx_type: Option<Option<TransactionType>>,
 }
@@ -715,6 +752,7 @@ impl PaymentDetailsUpdate {
 			direction: None,
 			status: None,
 			confirmation_status: None,
+			bolt12_invoice: None,
 			txid: None,
 			tx_type: None,
 		}
@@ -723,12 +761,18 @@ impl PaymentDetailsUpdate {
 
 impl From<&PaymentDetails> for PaymentDetailsUpdate {
 	fn from(value: &PaymentDetails) -> Self {
-		let (hash, preimage, secret) = match value.kind {
-			PaymentKind::Bolt11 { hash, preimage, secret, .. } => (Some(hash), preimage, secret),
-			PaymentKind::Bolt12Offer { hash, preimage, secret, .. } => (hash, preimage, secret),
-			PaymentKind::Bolt12Refund { hash, preimage, secret, .. } => (hash, preimage, secret),
-			PaymentKind::Spontaneous { hash, preimage, .. } => (Some(hash), preimage, None),
-			_ => (None, None, None),
+		let (hash, preimage, secret, bolt12_invoice) = match &value.kind {
+			PaymentKind::Bolt11 { hash, preimage, secret, .. } => {
+				(Some(*hash), *preimage, *secret, None)
+			},
+			PaymentKind::Bolt12Offer { hash, preimage, secret, bolt12_invoice, .. } => {
+				(*hash, *preimage, *secret, Some(bolt12_invoice.clone()))
+			},
+			PaymentKind::Bolt12Refund { hash, preimage, secret, bolt12_invoice, .. } => {
+				(*hash, *preimage, *secret, Some(bolt12_invoice.clone()))
+			},
+			PaymentKind::Spontaneous { hash, preimage, .. } => (Some(*hash), *preimage, None, None),
+			_ => (None, None, None, None),
 		};
 
 		let (confirmation_status, txid, tx_type) = match &value.kind {
@@ -738,9 +782,9 @@ impl From<&PaymentDetails> for PaymentDetailsUpdate {
 			_ => (None, None, None),
 		};
 
-		let counterparty_skimmed_fee_msat = match value.kind {
+		let counterparty_skimmed_fee_msat = match &value.kind {
 			PaymentKind::Bolt11 { counterparty_skimmed_fee_msat, .. } => {
-				Some(counterparty_skimmed_fee_msat)
+				Some(*counterparty_skimmed_fee_msat)
 			},
 			_ => None,
 		};
@@ -756,6 +800,7 @@ impl From<&PaymentDetails> for PaymentDetailsUpdate {
 			direction: Some(value.direction),
 			status: Some(value.status),
 			confirmation_status,
+			bolt12_invoice,
 			txid,
 			tx_type,
 		}

tests/integration_tests_rust.rs

@@ -2329,12 +2329,14 @@ async fn simple_bolt12_send_receive() {
 			offer_id,
 			quantity: ref qty,
 			payer_note: ref note,
+			bolt12_invoice: ref invoice,
 		} => {
 			assert!(hash.is_some());
 			assert!(preimage.is_some());
 			assert_eq!(offer_id, offer.id());
 			assert_eq!(&expected_quantity, qty);
 			assert_eq!(expected_payer_note.unwrap(), note.clone().unwrap().0);
+			assert!(invoice.is_some());
 			// TODO: We should eventually set and assert the secret sender-side, too, but the BOLT12
 			// API currently doesn't allow to do that.
 		},
@@ -2396,12 +2398,14 @@ async fn simple_bolt12_send_receive() {
 			offer_id,
 			quantity: ref qty,
 			payer_note: ref note,
+			bolt12_invoice: ref invoice,
 		} => {
 			assert!(hash.is_some());
 			assert!(preimage.is_some());
 			assert_eq!(offer_id, offer.id());
 			assert_eq!(&expected_quantity, qty);
 			assert_eq!(expected_payer_note.unwrap(), note.clone().unwrap().0);
+			assert!(invoice.is_some());
 			// TODO: We should eventually set and assert the secret sender-side, too, but the BOLT12
 			// API currently doesn't allow to do that.
 		},
@@ -2467,11 +2471,13 @@ async fn simple_bolt12_send_receive() {
 			secret: _,
 			quantity: ref qty,
 			payer_note: ref note,
+			bolt12_invoice: ref invoice,
 		} => {
 			assert!(hash.is_some());
 			assert!(preimage.is_some());
 			assert_eq!(&expected_quantity, qty);
-			assert_eq!(expected_payer_note.unwrap(), note.clone().unwrap().0)
+			assert_eq!(expected_payer_note.unwrap(), note.clone().unwrap().0);
+			assert!(invoice.is_some());
 			// TODO: We should eventually set and assert the secret sender-side, too, but the BOLT12
 			// API currently doesn't allow to do that.
 		},