add the bolt12 invoice to the PaymentSend event

vincenzopalazzo · vincenzopalazzo · commit 1da76cda946f · 2025-03-13T20:48:54.000+01:00
To enable proof of payment, we need to share the bolt12 invoice with the library user. This is already possible if we `manually_handle_bolt12_invoices`, but this approach requires a significant amount of work from the user. This commit adds the bolt12 invoice to the PaymentSend event when the payment is completed. This allows the user to always have the option to perform proof of payment. Link: lightningdevkit#3344 Signed-off-by: Vincenzo Palazzo <vincenzopalazzodev@gmail.com>
diff --git a/lightning/src/events/mod.rs b/lightning/src/events/mod.rs
@@ -1563,14 +1563,15 @@ impl Writeable for Event {
 					(13, payment_id, option),
 				});
 			},
-			&Event::PaymentSent { ref payment_id, ref payment_preimage, ref payment_hash, ref amount_msat, ref fee_paid_msat } => {
+			&Event::PaymentSent { ref payment_id, ref payment_preimage, ref payment_hash, ref amount_msat, ref fee_paid_msat, ref bolt12_invoice } => {
 				2u8.write(writer)?;
 				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),
 				});
 			},
 			&Event::PaymentPathFailed {
@@ -1905,12 +1906,14 @@ 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;
 					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),
 					});
 					if payment_hash.is_none() {
 						payment_hash = Some(PaymentHash(Sha256::hash(&payment_preimage.0[..]).to_byte_array()));
@@ -1921,6 +1924,7 @@ impl MaybeReadable for Event {
 						payment_hash: payment_hash.unwrap(),
 						amount_msat,
 						fee_paid_msat,
+						bolt12_invoice,
 					}))
 				};
 				f()
@@ -2445,3 +2449,19 @@ impl<T: EventHandler> EventHandler for Arc<T> {
 		self.deref().handle_event(event)
 	}
 }
+
+/// Wrapper time to move the bolt12 invoice and the static
+/// invoice across the same event as a unique type.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum PaidInvoice {
+	/// Bolt12 invoice
+	Bolt12Invoice(crate::offers::invoice::Bolt12Invoice),
+	/// Static invoice
+	StaticInvoice(crate::offers::static_invoice::StaticInvoice),
+ }
+
+impl_writeable_tlv_based_enum_legacy!(PaidInvoice,
+	;
+	(0, Bolt12Invoice),
+	(2, StaticInvoice)
+);
diff --git a/lightning/src/ln/functional_test_utils.rs b/lightning/src/ln/functional_test_utils.rs
@@ -35,6 +35,7 @@ use crate::util::test_channel_signer::SignerOp;
 use crate::util::test_utils;
 use crate::util::test_utils::{TestChainMonitor, TestScorer, TestKeysInterface};
 use crate::util::ser::{ReadableArgs, Writeable};
+use crate::offers::invoice::Bolt12Invoice;
 
 use bitcoin::{Weight, WPubkeyHash};
 use bitcoin::amount::Amount;
diff --git a/lightning/src/ln/offers_tests.rs b/lightning/src/ln/offers_tests.rs
@@ -168,7 +168,7 @@ fn route_bolt12_payment<'a, 'b, 'c>(
 }
 
 fn claim_bolt12_payment<'a, 'b, 'c>(
-	node: &Node<'a, 'b, 'c>, path: &[&Node<'a, 'b, 'c>], expected_payment_context: PaymentContext
+	node: &Node<'a, 'b, 'c>, path: &[&Node<'a, 'b, 'c>], expected_payment_context: PaymentContext, invoice: &Bolt12Invoice
 ) {
 	let recipient = &path[path.len() - 1];
 	let payment_purpose = match get_event!(recipient, Event::PaymentClaimable) {
@@ -601,7 +601,7 @@ fn creates_and_pays_for_offer_using_two_hop_blinded_path() {
 	route_bolt12_payment(david, &[charlie, bob, alice], &invoice);
 	expect_recent_payment!(david, RecentPaymentDetails::Pending, payment_id);
 
-	claim_bolt12_payment(david, &[charlie, bob, alice], payment_context);
+	claim_bolt12_payment(david, &[charlie, bob, alice], payment_context, &invoice);
 	expect_recent_payment!(david, RecentPaymentDetails::Fulfilled, payment_id);
 }
 
@@ -684,7 +684,7 @@ fn creates_and_pays_for_refund_using_two_hop_blinded_path() {
 	route_bolt12_payment(david, &[charlie, bob, alice], &invoice);
 	expect_recent_payment!(david, RecentPaymentDetails::Pending, payment_id);
 
-	claim_bolt12_payment(david, &[charlie, bob, alice], payment_context);
+	claim_bolt12_payment(david, &[charlie, bob, alice], payment_context, &invoice);
 	expect_recent_payment!(david, RecentPaymentDetails::Fulfilled, payment_id);
 }
 
@@ -751,7 +751,7 @@ fn creates_and_pays_for_offer_using_one_hop_blinded_path() {
 	route_bolt12_payment(bob, &[alice], &invoice);
 	expect_recent_payment!(bob, RecentPaymentDetails::Pending, payment_id);
 
-	claim_bolt12_payment(bob, &[alice], payment_context);
+	claim_bolt12_payment(bob, &[alice], payment_context, &invoice);
 	expect_recent_payment!(bob, RecentPaymentDetails::Fulfilled, payment_id);
 }
 
@@ -807,7 +807,7 @@ fn creates_and_pays_for_refund_using_one_hop_blinded_path() {
 	route_bolt12_payment(bob, &[alice], &invoice);
 	expect_recent_payment!(bob, RecentPaymentDetails::Pending, payment_id);
 
-	claim_bolt12_payment(bob, &[alice], payment_context);
+	claim_bolt12_payment(bob, &[alice], payment_context, &invoice);
 	expect_recent_payment!(bob, RecentPaymentDetails::Fulfilled, payment_id);
 }
 
@@ -861,7 +861,7 @@ fn pays_for_offer_without_blinded_paths() {
 	route_bolt12_payment(bob, &[alice], &invoice);
 	expect_recent_payment!(bob, RecentPaymentDetails::Pending, payment_id);
 
-	claim_bolt12_payment(bob, &[alice], payment_context);
+	claim_bolt12_payment(bob, &[alice], payment_context, &invoice);
 	expect_recent_payment!(bob, RecentPaymentDetails::Fulfilled, payment_id);
 }
 
@@ -904,7 +904,7 @@ fn pays_for_refund_without_blinded_paths() {
 	route_bolt12_payment(bob, &[alice], &invoice);
 	expect_recent_payment!(bob, RecentPaymentDetails::Pending, payment_id);
 
-	claim_bolt12_payment(bob, &[alice], payment_context);
+	claim_bolt12_payment(bob, &[alice], payment_context, &invoice);
 	expect_recent_payment!(bob, RecentPaymentDetails::Fulfilled, payment_id);
 }
 
@@ -1142,7 +1142,7 @@ fn creates_and_pays_for_offer_with_retry() {
 	}
 	route_bolt12_payment(bob, &[alice], &invoice);
 	expect_recent_payment!(bob, RecentPaymentDetails::Pending, payment_id);
-	claim_bolt12_payment(bob, &[alice], payment_context);
+	claim_bolt12_payment(bob, &[alice], payment_context, &invoice);
 	expect_recent_payment!(bob, RecentPaymentDetails::Fulfilled, payment_id);
 }
 
@@ -1213,7 +1213,7 @@ fn pays_bolt12_invoice_asynchronously() {
 	route_bolt12_payment(bob, &[alice], &invoice);
 	expect_recent_payment!(bob, RecentPaymentDetails::Pending, payment_id);
 
-	claim_bolt12_payment(bob, &[alice], payment_context);
+	claim_bolt12_payment(bob, &[alice], payment_context, &invoice);
 	expect_recent_payment!(bob, RecentPaymentDetails::Fulfilled, payment_id);
 
 	assert_eq!(
@@ -1293,7 +1293,7 @@ fn creates_offer_with_blinded_path_using_unannounced_introduction_node() {
 	route_bolt12_payment(bob, &[alice], &invoice);
 	expect_recent_payment!(bob, RecentPaymentDetails::Pending, payment_id);
 
-	claim_bolt12_payment(bob, &[alice], payment_context);
+	claim_bolt12_payment(bob, &[alice], payment_context, &invoice);
 	expect_recent_payment!(bob, RecentPaymentDetails::Fulfilled, payment_id);
 }
 
@@ -2149,7 +2149,7 @@ fn fails_paying_invoice_more_than_once() {
 	assert!(david.node.get_and_clear_pending_msg_events().is_empty());
 
 	// Complete paying the first invoice
-	claim_bolt12_payment(david, &[charlie, bob, alice], payment_context);
+	claim_bolt12_payment(david, &[charlie, bob, alice], payment_context, &invoice1);
 	expect_recent_payment!(david, RecentPaymentDetails::Fulfilled, payment_id);
 }
 
diff --git a/lightning/src/ln/outbound_payment.rs b/lightning/src/ln/outbound_payment.rs
@@ -15,29 +15,27 @@ use bitcoin::secp256k1::{self, Secp256k1, SecretKey};
 use lightning_invoice::Bolt11Invoice;
 
 use crate::blinded_path::{IntroductionNode, NodeIdLookUp};
-use crate::events::{self, PaymentFailureReason};
-use crate::types::payment::{PaymentHash, PaymentPreimage, PaymentSecret};
+use crate::events::{self, PaidInvoice, PaymentFailureReason};
 use crate::ln::channel_state::ChannelDetails;
 use crate::ln::channelmanager::{EventCompletionAction, HTLCSource, PaymentId};
-use crate::types::features::Bolt12InvoiceFeatures;
 use crate::ln::onion_utils;
 use crate::ln::onion_utils::{DecodedOnionFailure, HTLCFailReason};
 use crate::offers::invoice::Bolt12Invoice;
 use crate::offers::invoice_request::InvoiceRequest;
 use crate::offers::nonce::Nonce;
-use crate::routing::router::{BlindedTail, InFlightHtlcs, RouteParametersConfig, Path, PaymentParameters, Route, RouteParameters, Router};
+use crate::offers::static_invoice::StaticInvoice;
+use crate::routing::router::{BlindedTail, InFlightHtlcs, Path, PaymentParameters, Route, RouteParameters, RouteParametersConfig, Router};
 use crate::sign::{EntropySource, NodeSigner, Recipient};
+use crate::types::features::Bolt12InvoiceFeatures;
+use crate::types::payment::{PaymentHash, PaymentPreimage, PaymentSecret};
 use crate::util::errors::APIError;
 use crate::util::logger::Logger;
 #[cfg(feature = "std")]
 use crate::util::time::Instant;
 use crate::util::ser::ReadableArgs;
 
 #[cfg(async_payments)]
-use {
-	crate::offers::invoice::{DerivedSigningPubkey, InvoiceBuilder},
-	crate::offers::static_invoice::StaticInvoice,
-};
+use crate::offers::invoice::{DerivedSigningPubkey, InvoiceBuilder};
 
 use core::fmt::{self, Display, Formatter};
 use core::ops::Deref;
@@ -108,7 +106,7 @@ pub(crate) enum PendingOutboundPayment {
 		invoice_request: Option<InvoiceRequest>,
 		// Storing the bolt12 invoice here to allow Proof of Payment after
 		// the payment is made.
-		bolt12_invoice: Option<Bolt12Invoice>,
+		bolt12_invoice: Option<PaidInvoice>,
 		custom_tlvs: Vec<(u64, Vec<u8>)>,
 		pending_amt_msat: u64,
 		/// Used to track the fee paid. Present iff the payment was serialized on 0.0.103+.
@@ -158,7 +156,7 @@ impl_writeable_tlv_based!(RetryableInvoiceRequest, {
 });
 
 impl PendingOutboundPayment {
-	fn bolt12_invoice(&self) -> Option<&Bolt12Invoice> {
+	fn bolt12_invoice(&self) -> Option<&PaidInvoice> {
 		match self {
 			PendingOutboundPayment::Retryable { bolt12_invoice, .. } => bolt12_invoice.as_ref(),
 			_ => None,
@@ -967,8 +965,9 @@ impl OutboundPayments {
 		if let Some(max_fee_msat) = params_config.max_total_routing_fee_msat {
 			route_params.max_total_routing_fee_msat = Some(max_fee_msat);
 		}
+		let invoice = PaidInvoice::Bolt12Invoice(invoice.clone());
 		self.send_payment_for_bolt12_invoice_internal(
-			payment_id, payment_hash, None, None, Some(invoice), route_params, retry_strategy, router, first_hops,
+			payment_id, payment_hash, None, None, Some(&invoice), route_params, retry_strategy, router, first_hops,
 			inflight_htlcs, entropy_source, node_signer, node_id_lookup, secp_ctx, best_block_height,
 			logger, pending_events, send_payment_along_path
 		)
@@ -979,7 +978,7 @@ impl OutboundPayments {
 	>(
 		&self, payment_id: PaymentId, payment_hash: PaymentHash,
 		keysend_preimage: Option<PaymentPreimage>, invoice_request: Option<&InvoiceRequest>,
-		bolt12_invoice: Option<&Bolt12Invoice>,
+		bolt12_invoice: Option<&PaidInvoice>,
 		mut route_params: RouteParameters, retry_strategy: Retry, router: &R,
 		first_hops: Vec<ChannelDetails>, inflight_htlcs: IH, entropy_source: &ES, node_signer: &NS,
 		node_id_lookup: &NL, secp_ctx: &Secp256k1<secp256k1::All>, best_block_height: u32, logger: &L,
@@ -1726,7 +1725,7 @@ impl OutboundPayments {
 		&self, payment_hash: PaymentHash, recipient_onion: RecipientOnionFields, payment_id: PaymentId,
 		keysend_preimage: Option<PaymentPreimage>, route: &Route, retry_strategy: Option<Retry>,
 		payment_params: Option<PaymentParameters>, entropy_source: &ES, best_block_height: u32,
-		bolt12_invoice: Option<Bolt12Invoice>
+		bolt12_invoice: Option<PaidInvoice>
 	) -> Result<Vec<[u8; 32]>, PaymentSendFailure> where ES::Target: EntropySource {
 		let mut pending_outbounds = self.pending_outbound_payments.lock().unwrap();
 		match pending_outbounds.entry(payment_id) {
@@ -1745,7 +1744,7 @@ impl OutboundPayments {
 	fn create_pending_payment<ES: Deref>(
 		payment_hash: PaymentHash, recipient_onion: RecipientOnionFields,
 		keysend_preimage: Option<PaymentPreimage>, invoice_request: Option<InvoiceRequest>,
-		bolt12_invoice: Option<Bolt12Invoice>, route: &Route, retry_strategy: Option<Retry>,
+		bolt12_invoice: Option<PaidInvoice>, route: &Route, retry_strategy: Option<Retry>,
 		payment_params: Option<PaymentParameters>, entropy_source: &ES, best_block_height: u32
 	) -> (PendingOutboundPayment, Vec<[u8; 32]>)
 	where
@@ -2028,6 +2027,7 @@ impl OutboundPayments {
 					payment_hash,
 					amount_msat,
 					fee_paid_msat,
+					bolt12_invoice: payment.get().bolt12_invoice().cloned(),
 				}, Some(ev_completion_action.clone())));
 				payment.get_mut().mark_fulfilled();
 			}
diff --git a/lightning/src/offers/invoice_request.rs b/lightning/src/offers/invoice_request.rs
@@ -86,7 +86,7 @@ use crate::onion_message::dns_resolution::HumanReadableName;
 use crate::types::features::InvoiceRequestFeatures;
 use crate::types::payment::PaymentHash;
 use crate::util::ser::{
-	CursorReadable, HighZeroBytesDroppedBigSize, LengthLimitedRead, LengthReadable, Readable,
+	CursorReadable, HighZeroBytesDroppedBigSize, LengthRead, LengthReadable, Readable,
 	WithoutLength, Writeable, Writer,
 };
 use crate::util::string::{PrintableString, UntrustedString};
@@ -1121,8 +1121,10 @@ impl Writeable for InvoiceRequestContents {
 }
 
 impl LengthReadable for InvoiceRequest {
-	fn read_from_fixed_length_buffer<R: LengthLimitedRead>(r: &mut R) -> Result<Self, DecodeError> {
-		let bytes: WithoutLength<Vec<u8>> = LengthReadable::read_from_fixed_length_buffer(r)?;
+	fn read_from_fixed_length_buffer<R: LengthLimitedRead>(
+		reader: &mut R,
+	) -> Result<Self, DecodeError> {
+		let bytes: WithoutLength<Vec<u8>> = LengthReadable::read_from_fixed_length_buffer(reader)?;
 		Self::try_from(bytes.0).map_err(|_| DecodeError::InvalidValue)
 	}
 }
diff --git a/lightning/src/offers/static_invoice.rs b/lightning/src/offers/static_invoice.rs
@@ -33,7 +33,7 @@ use crate::offers::offer::{
 };
 use crate::offers::parse::{Bolt12ParseError, Bolt12SemanticError, ParsedMessage};
 use crate::types::features::{Bolt12InvoiceFeatures, OfferFeatures};
-use crate::util::ser::{CursorReadable, Iterable, WithoutLength, Writeable, Writer};
+use crate::util::ser::{CursorReadable, Iterable, Readable, WithoutLength, Writeable, Writer};
 use crate::util::string::PrintableString;
 use bitcoin::address::Address;
 use bitcoin::constants::ChainHash;
@@ -70,6 +70,14 @@ pub struct StaticInvoice {
 	signature: Signature,
 }
 
+impl PartialEq for StaticInvoice {
+	fn eq(&self, other: &Self) -> bool {
+		self.bytes.eq(&other.bytes)
+	}
+}
+
+impl Eq for StaticInvoice {}
+
 /// The contents of a [`StaticInvoice`] for responding to an [`Offer`].
 ///
 /// [`Offer`]: crate::offers::offer::Offer
@@ -535,6 +543,13 @@ impl Writeable for StaticInvoice {
 	}
 }
 
+impl Readable for StaticInvoice {
+	fn read<R: io::Read>(reader: &mut R) -> Result<Self, DecodeError> {
+		let bytes: WithoutLength<Vec<u8>> = Readable::read(reader)?;
+		Self::try_from(bytes.0).map_err(|_| DecodeError::InvalidValue)
+	}
+}
+
 impl TryFrom<Vec<u8>> for StaticInvoice {
 	type Error = Bolt12ParseError;
 
diff --git a/lightning/src/offers/test_utils.rs b/lightning/src/offers/test_utils.rs
@@ -12,8 +12,10 @@
 use bitcoin::secp256k1::schnorr::Signature;
 use bitcoin::secp256k1::{Keypair, PublicKey, Secp256k1, SecretKey};
 
+use crate::blinded_path::message::BlindedMessagePath;
 use crate::blinded_path::payment::{BlindedPayInfo, BlindedPaymentPath};
 use crate::blinded_path::BlindedHop;
+use crate::ln::inbound_payment::ExpandedKey;
 use crate::offers::merkle::TaggedHash;
 use crate::sign::EntropySource;
 use crate::types::features::BlindedHopFeatures;
@@ -23,6 +25,10 @@ use core::time::Duration;
 #[allow(unused_imports)]
 use crate::prelude::*;
 
+use super::nonce::Nonce;
+use super::offer::OfferBuilder;
+use super::static_invoice::{StaticInvoice, StaticInvoiceBuilder};
+
 pub(crate) fn fail_sign<T: AsRef<TaggedHash>>(_message: &T) -> Result<Signature, ()> {
 	Err(())
 }
@@ -120,3 +126,42 @@ impl EntropySource for FixedEntropy {
 		[42; 32]
 	}
 }
+
+pub fn blinded_path() -> BlindedMessagePath {
+	BlindedMessagePath::from_raw(
+		pubkey(40),
+		pubkey(41),
+		vec![
+			BlindedHop { blinded_node_id: pubkey(42), encrypted_payload: vec![0; 43] },
+			BlindedHop { blinded_node_id: pubkey(43), encrypted_payload: vec![0; 44] },
+		],
+	)
+}
+
+pub fn dummy_static_invoice() -> StaticInvoice {
+	let node_id = recipient_pubkey();
+	let payment_paths = payment_paths();
+	let now = now();
+	let expanded_key = ExpandedKey::new([42; 32]);
+	let entropy = FixedEntropy {};
+	let nonce = Nonce::from_entropy_source(&entropy);
+	let secp_ctx = Secp256k1::new();
+
+	let offer = OfferBuilder::deriving_signing_pubkey(node_id, &expanded_key, nonce, &secp_ctx)
+		.path(blinded_path())
+		.build()
+		.unwrap();
+
+	StaticInvoiceBuilder::for_offer_using_derived_keys(
+		&offer,
+		payment_paths.clone(),
+		vec![blinded_path()],
+		now,
+		&expanded_key,
+		nonce,
+		&secp_ctx,
+	)
+	.unwrap()
+	.build_and_sign(&secp_ctx)
+	.unwrap()
+}
