storage: store the bolt12invoice invoice

This commit enhances the BOLT12 payment storage capabilities by adding
support for storing the actual BOLT12 invoice along with payment details.

We modify the following components:
- Added `bolt12_invoice` field to `PaymentKind::Bolt12Offer` and
  `PaymentKind::Bolt12Refund` variants in the payment store
- Updated event handling in `event.rs` to capture and store the
  BOLT12 invoice when payments are processed
- Modified BOLT12 payment creation logic to initialize the new field
- Enhanced payment update mechanism to handle BOLT12 invoice updates
- Added comprehensive test coverage for the new invoice storage feature

This improvement allows for proof of payment and to access the BOLT12
invoice details.

Signed-off-by: Vincenzo Palazzo <vincenzopalazzodev@gmail.com>

Author: vincenzopalazzo

src/event.rs

@@ -745,6 +745,7 @@ where
 							offer_id,
 							payer_note,
 							quantity,
+							bolt12_invoice: None,
 						};
 
 						let payment = PaymentDetails::new(
@@ -949,6 +950,7 @@ where
 				payment_preimage,
 				payment_hash,
 				fee_paid_msat,
+				bolt12_invoice,
 				..
 			} => {
 				let payment_id = if let Some(id) = payment_id {
@@ -963,6 +965,7 @@ where
 					preimage: Some(Some(payment_preimage)),
 					fee_paid_msat: Some(fee_paid_msat),
 					status: Some(PaymentStatus::Succeeded),
+					bolt12_invoice: Some(bolt12_invoice),
 					..PaymentDetailsUpdate::new(payment_id)
 				};
 

src/payment/bolt12.rs

@@ -15,6 +15,7 @@ use crate::logger::{log_error, log_info, LdkLogger, Logger};
 use crate::payment::store::{PaymentDetails, PaymentDirection, PaymentKind, PaymentStatus};
 use crate::types::{ChannelManager, PaymentStore};
 
+use lightning::events::PaidBolt12Invoice;
 use lightning::ln::channelmanager::{PaymentId, Retry};
 use lightning::offers::invoice::Bolt12Invoice;
 use lightning::offers::offer::{Amount, Offer, Quantity};
@@ -107,6 +108,7 @@ impl Bolt12Payment {
 					offer_id: offer.id(),
 					payer_note: payer_note.map(UntrustedString),
 					quantity,
+					bolt12_invoice: None,
 				};
 				let payment = PaymentDetails::new(
 					payment_id,
@@ -132,6 +134,7 @@ impl Bolt12Payment {
 							offer_id: offer.id(),
 							payer_note: payer_note.map(UntrustedString),
 							quantity,
+							bolt12_invoice: None,
 						};
 						let payment = PaymentDetails::new(
 							payment_id,
@@ -213,6 +216,7 @@ impl Bolt12Payment {
 					offer_id: offer.id(),
 					payer_note: payer_note.map(UntrustedString),
 					quantity,
+					bolt12_invoice: None,
 				};
 				let payment = PaymentDetails::new(
 					payment_id,
@@ -238,6 +242,7 @@ impl Bolt12Payment {
 							offer_id: offer.id(),
 							payer_note: payer_note.map(UntrustedString),
 							quantity,
+							bolt12_invoice: None,
 						};
 						let payment = PaymentDetails::new(
 							payment_id,
@@ -335,6 +340,7 @@ impl Bolt12Payment {
 			secret: None,
 			payer_note: refund.payer_note().map(|note| UntrustedString(note.0.to_string())),
 			quantity: refund.quantity(),
+			bolt12_invoice: Some(PaidBolt12Invoice::Bolt12Invoice(invoice.clone())),
 		};
 
 		let payment = PaymentDetails::new(
@@ -401,6 +407,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

@@ -5,6 +5,7 @@
 // http://opensource.org/licenses/MIT>, at your option. You may not use this file except in
 // accordance with one or both of these licenses.
 
+use lightning::events::PaidBolt12Invoice;
 use lightning::ln::channelmanager::PaymentId;
 use lightning::ln::msgs::DecodeError;
 use lightning::offers::offer::OfferId;
@@ -293,6 +294,18 @@ impl StorableObject for PaymentDetails {
 			}
 		}
 
+		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 updated {
 			self.latest_update_timestamp = SystemTime::now()
 				.duration_since(UNIX_EPOCH)
@@ -417,6 +430,8 @@ pub enum PaymentKind {
 		///
 		/// This will always be `None` for payments serialized with version `v0.3.0`.
 		quantity: Option<u64>,
+		/// TODO: need to be documented
+		bolt12_invoice: Option<PaidBolt12Invoice>,
 	},
 	/// A [BOLT 12] 'refund' payment, i.e., a payment for a [`Refund`].
 	///
@@ -437,6 +452,8 @@ pub enum PaymentKind {
 		///
 		/// This will always be `None` for payments serialized with version `v0.3.0`.
 		quantity: Option<u64>,
+		/// TODO: need to be documented
+		bolt12_invoice: Option<PaidBolt12Invoice>,
 	},
 	/// A spontaneous ("keysend") payment.
 	Spontaneous {
@@ -471,6 +488,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),
@@ -482,6 +500,7 @@ impl_writeable_tlv_based_enum!(PaymentKind,
 		(2, preimage, option),
 		(3, quantity, option),
 		(4, secret, option),
+		(6, bolt12_invoice, option),
 	}
 );
 
@@ -542,6 +561,7 @@ pub(crate) struct PaymentDetailsUpdate {
 	pub direction: Option<PaymentDirection>,
 	pub status: Option<PaymentStatus>,
 	pub confirmation_status: Option<ConfirmationStatus>,
+	pub bolt12_invoice: Option<Option<PaidBolt12Invoice>>,
 }
 
 impl PaymentDetailsUpdate {
@@ -557,19 +577,20 @@ impl PaymentDetailsUpdate {
 			direction: None,
 			status: None,
 			confirmation_status: None,
+			bolt12_invoice: 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, ref bolt12_invoice, .. } => (hash, preimage, secret, Some(bolt12_invoice)),
+			PaymentKind::Bolt12Refund { hash, preimage, secret, ref bolt12_invoice, .. } => (hash, preimage, secret, Some(bolt12_invoice)),
+			PaymentKind::Spontaneous { hash, preimage, .. } => (Some(hash), preimage, None, None),
+			_ => (None, None, None, None),
 		};
 
 		let confirmation_status = match value.kind {
@@ -595,6 +616,7 @@ impl From<&PaymentDetails> for PaymentDetailsUpdate {
 			direction: Some(value.direction),
 			status: Some(value.status),
 			confirmation_status,
+			bolt12_invoice: bolt12_invoice.cloned(),
 		}
 	}
 }

tests/integration_tests_rust.rs

@@ -817,12 +817,14 @@ 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.
 		},
@@ -883,12 +885,14 @@ 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()
@@ -950,11 +954,13 @@ 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.
 		},