storage: persist paid BOLT12 invoices in payment details

vincenzopalazzo · vincenzopalazzo · commit e11c5aba8b0d · 2026-03-26T18:31:24.000+01:00
Store the paid BOLT12 invoice in BOLT12 offer and refund payment records so successful outbound payments retain the invoice in persisted payment details.

This keeps invoice storage separate from payer-proof support and extends the existing BOLT12 integration coverage.

AI-assisted-by: Codex
diff --git a/src/event.rs b/src/event.rs
@@ -860,6 +860,7 @@ where
 							offer_id,
 							payer_note,
 							quantity,
+							bolt12_invoice: None,
 						};
 
 						let payment = PaymentDetails::new(
@@ -1073,12 +1074,14 @@ where
 					debug_assert!(false, "payment_id should always be set.");
 					return Ok(());
 				};
+				let bolt12_invoice = bolt12_invoice.map(Into::into);
 
 				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: Some(bolt12_invoice.clone()),
 					..PaymentDetailsUpdate::new(payment_id)
 				};
 
@@ -1110,7 +1113,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 {
diff --git a/src/payment/bolt12.rs b/src/payment/bolt12.rs
@@ -14,6 +14,7 @@ use std::sync::{Arc, RwLock};
 use std::time::{Duration, SystemTime, UNIX_EPOCH};
 
 use lightning::blinded_path::message::BlindedMessagePath;
+use lightning::events::PaidBolt12Invoice as LdkPaidBolt12Invoice;
 use lightning::ln::channelmanager::{OptionalOfferPaymentParams, PaymentId};
 use lightning::ln::outbound_payment::Retry;
 use lightning::offers::offer::{Amount, Offer as LdkOffer, OfferFromHrn, Quantity};
@@ -154,6 +155,7 @@ impl Bolt12Payment {
 					offer_id: offer.id(),
 					payer_note: payer_note.map(UntrustedString),
 					quantity,
+					bolt12_invoice: None,
 				};
 				let payment = PaymentDetails::new(
 					payment_id,
@@ -179,6 +181,7 @@ impl Bolt12Payment {
 							offer_id: offer.id(),
 							payer_note: payer_note.map(UntrustedString),
 							quantity,
+							bolt12_invoice: None,
 						};
 						let payment = PaymentDetails::new(
 							payment_id,
@@ -314,6 +317,7 @@ impl Bolt12Payment {
 					offer_id: offer.id(),
 					payer_note: payer_note.map(UntrustedString),
 					quantity,
+					bolt12_invoice: None,
 				};
 				let payment = PaymentDetails::new(
 					payment_id,
@@ -339,6 +343,7 @@ impl Bolt12Payment {
 							offer_id: offer.id(),
 							payer_note: payer_note.map(UntrustedString),
 							quantity,
+							bolt12_invoice: None,
 						};
 						let payment = PaymentDetails::new(
 							payment_id,
@@ -444,6 +449,7 @@ impl Bolt12Payment {
 			secret: None,
 			payer_note: refund.payer_note().map(|note| UntrustedString(note.0.to_string())),
 			quantity: refund.quantity(),
+			bolt12_invoice: Some(LdkPaidBolt12Invoice::Bolt12Invoice(invoice.clone()).into()),
 		};
 
 		let payment = PaymentDetails::new(
@@ -514,6 +520,7 @@ impl Bolt12Payment {
 			secret: None,
 			payer_note: payer_note.map(|note| UntrustedString(note)),
 			quantity,
+			bolt12_invoice: None,
 		};
 		let payment = PaymentDetails::new(
 			payment_id,
diff --git a/src/payment/store.rs b/src/payment/store.rs
@@ -8,6 +8,8 @@
 use std::time::{Duration, SystemTime, UNIX_EPOCH};
 
 use bitcoin::{BlockHash, Txid};
+#[cfg(not(feature = "uniffi"))]
+use lightning::events::PaidBolt12Invoice;
 use lightning::ln::channelmanager::PaymentId;
 use lightning::ln::msgs::DecodeError;
 use lightning::offers::offer::OfferId;
@@ -20,6 +22,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.
@@ -267,6 +271,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::Bolt11Jit { ref mut counterparty_skimmed_fee_msat, .. } => {
@@ -428,6 +444,8 @@ pub enum PaymentKind {
 		///
 		/// This will always be `None` for payments serialized with version `v0.3.0`.
 		quantity: Option<u64>,
+		/// The BOLT12 invoice associated with the payment, once available.
+		bolt12_invoice: Option<PaidBolt12Invoice>,
 	},
 	/// A [BOLT 12] 'refund' payment, i.e., a payment for a [`Refund`].
 	///
@@ -448,6 +466,8 @@ pub enum PaymentKind {
 		///
 		/// This will always be `None` for payments serialized with version `v0.3.0`.
 		quantity: Option<u64>,
+		/// The BOLT12 invoice associated with the payment, once available.
+		bolt12_invoice: Option<PaidBolt12Invoice>,
 	},
 	/// A spontaneous ("keysend") payment.
 	Spontaneous {
@@ -482,6 +502,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),
@@ -493,6 +514,7 @@ impl_writeable_tlv_based_enum!(PaymentKind,
 		(2, preimage, option),
 		(3, quantity, option),
 		(4, secret, option),
+		(6, bolt12_invoice, option),
 	}
 );
 
@@ -555,6 +577,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>,
 }
 
@@ -571,30 +594,39 @@ impl PaymentDetailsUpdate {
 			direction: None,
 			status: None,
 			confirmation_status: None,
+			bolt12_invoice: None,
 			txid: None,
 		}
 	}
 }
 
 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::Bolt11Jit { 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::Bolt11Jit { 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) = match &value.kind {
 			PaymentKind::Onchain { status, txid, .. } => (Some(*status), Some(*txid)),
 			_ => (None, None),
 		};
 
-		let counterparty_skimmed_fee_msat = match value.kind {
+		let counterparty_skimmed_fee_msat = match &value.kind {
 			PaymentKind::Bolt11Jit { counterparty_skimmed_fee_msat, .. } => {
-				Some(counterparty_skimmed_fee_msat)
+				Some(*counterparty_skimmed_fee_msat)
 			},
 			_ => None,
 		};
@@ -610,6 +642,7 @@ impl From<&PaymentDetails> for PaymentDetailsUpdate {
 			direction: Some(value.direction),
 			status: Some(value.status),
 			confirmation_status,
+			bolt12_invoice,
 			txid,
 		}
 	}
diff --git a/tests/integration_tests_rust.rs b/tests/integration_tests_rust.rs
@@ -1115,12 +1115,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.
 		},
@@ -1182,12 +1184,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.
 			hash.unwrap()
@@ -1255,11 +1259,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.
 		},
