event: expose PaidBolt12Invoice in PaymentSuccessful for proof of payment

Add the `bolt12_invoice` field to the `PaymentSuccessful` event,
enabling users to obtain proof of payment for BOLT12 transactions.

Problem:
After a successful BOLT12 payment, users had no way to access the
paid invoice data. This made it impossible to provide proof of
payment to third parties, who need both the payment preimage and
the original invoice to verify that sha256(preimage) matches the
invoice's payment_hash.

Solution:
Add `bolt12_invoice: Option<PaidBolt12Invoice>` to `PaymentSuccessful`.
With the UniFFI v0.29 upgrade now supporting objects in enum variants,
we can expose the proper `PaidBolt12Invoice` type across both native
Rust and FFI builds without cfg-gating the Event field.

For non-UniFFI builds, LDK's `PaidBolt12Invoice` is re-exported
directly. For UniFFI builds, a wrapper `PaidBolt12Invoice` enum is
defined in ffi/types.rs with `From` conversions and delegating
serialization. A minimal `StaticInvoice` FFI wrapper is also added
to support the `PaidBolt12Invoice::StaticInvoice` variant.

The FFI enum variants are named `Bolt12`/`Static` (rather than
`Bolt12Invoice`/`StaticInvoice`) to avoid Kotlin sealed class name
collisions where inner data classes would shadow top-level types.

TLV tag 7 is used for serialization, maintaining backward
compatibility: older readers silently skip the unknown odd tag,
and newer readers deserialize `None` from events without it.

Closes #757.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: vincenzopalazzo

src/event.rs

@@ -37,6 +37,8 @@ use crate::config::{may_announce_channel, Config};
 use crate::connection::ConnectionManager;
 use crate::data_store::DataStoreUpdateResult;
 use crate::fee_estimator::ConfirmationTarget;
+#[cfg(feature = "uniffi")]
+use crate::ffi::PaidBolt12Invoice;
 use crate::io::{
 	EVENT_QUEUE_PERSISTENCE_KEY, EVENT_QUEUE_PERSISTENCE_PRIMARY_NAMESPACE,
 	EVENT_QUEUE_PERSISTENCE_SECONDARY_NAMESPACE,
@@ -49,6 +51,8 @@ use crate::payment::store::{
 	PaymentDetails, PaymentDetailsUpdate, PaymentDirection, PaymentKind, PaymentStatus,
 };
 use crate::runtime::Runtime;
+#[cfg(not(feature = "uniffi"))]
+use crate::types::PaidBolt12Invoice;
 use crate::types::{
 	CustomTlvRecord, DynStore, KeysManager, OnionMessenger, PaymentStore, Sweeper, Wallet,
 };
@@ -79,6 +83,17 @@ pub enum Event {
 		payment_preimage: Option<PaymentPreimage>,
 		/// The total fee which was spent at intermediate hops in this payment.
 		fee_paid_msat: Option<u64>,
+		/// The BOLT12 invoice that was paid.
+		///
+		/// This is useful for proof of payment. A third party can verify that the payment was made
+		/// by checking that the `payment_hash` in the invoice matches `sha256(payment_preimage)`.
+		///
+		/// Will be `None` for non-BOLT12 payments.
+		///
+		/// Note that static invoices (indicated by [`PaidBolt12Invoice::StaticInvoice`], used for
+		/// async payments) do not support proof of payment as the payment hash is not derived
+		/// from a preimage known only to the recipient.
+		bolt12_invoice: Option<PaidBolt12Invoice>,
 	},
 	/// A sent payment has failed.
 	PaymentFailed {
@@ -268,6 +283,7 @@ impl_writeable_tlv_based_enum!(Event,
 		(1, fee_paid_msat, option),
 		(3, payment_id, option),
 		(5, payment_preimage, option),
+		(7, bolt12_invoice, option),
 	},
 	(1, PaymentFailed) => {
 		(0, payment_hash, option),
@@ -1028,6 +1044,7 @@ where
 				payment_preimage,
 				payment_hash,
 				fee_paid_msat,
+				bolt12_invoice,
 				..
 			} => {
 				let payment_id = if let Some(id) = payment_id {
@@ -1073,6 +1090,7 @@ where
 					payment_hash,
 					payment_preimage: Some(payment_preimage),
 					fee_paid_msat,
+					bolt12_invoice: bolt12_invoice.map(Into::into),
 				};
 
 				match self.event_queue.add_event(event).await {

src/ffi/types.rs

@@ -22,17 +22,20 @@ use bitcoin::hashes::Hash;
 use bitcoin::secp256k1::PublicKey;
 pub use bitcoin::{Address, BlockHash, FeeRate, Network, OutPoint, ScriptBuf, Txid};
 pub use lightning::chain::channelmonitor::BalanceSource;
+use lightning::events::PaidBolt12Invoice as LdkPaidBolt12Invoice;
 pub use lightning::events::{ClosureReason, PaymentFailureReason};
 use lightning::ln::channelmanager::PaymentId;
+use lightning::ln::msgs::DecodeError;
 pub use lightning::ln::types::ChannelId;
 use lightning::offers::invoice::Bolt12Invoice as LdkBolt12Invoice;
 pub use lightning::offers::offer::OfferId;
 use lightning::offers::offer::{Amount as LdkAmount, Offer as LdkOffer};
 use lightning::offers::refund::Refund as LdkRefund;
+use lightning::offers::static_invoice::StaticInvoice as LdkStaticInvoice;
 use lightning::onion_message::dns_resolution::HumanReadableName as LdkHumanReadableName;
 pub use lightning::routing::gossip::{NodeAlias, NodeId, RoutingFees};
 pub use lightning::routing::router::RouteParametersConfig;
-use lightning::util::ser::Writeable;
+use lightning::util::ser::{Readable, Writeable, Writer};
 use lightning_invoice::{Bolt11Invoice as LdkBolt11Invoice, Bolt11InvoiceDescriptionRef};
 pub use lightning_invoice::{Description, SignedRawBolt11Invoice};
 pub use lightning_liquidity::lsps0::ser::LSPSDateTime;
@@ -775,6 +778,100 @@ impl AsRef<LdkBolt12Invoice> for Bolt12Invoice {
 	}
 }
 
+/// A static invoice used for async payments.
+///
+/// Static invoices are a special type of BOLT12 invoice where proof of payment is not possible,
+/// as the payment hash is not derived from a preimage known only to the recipient.
+#[derive(Debug, Clone, PartialEq, Eq, uniffi::Object)]
+pub struct StaticInvoice {
+	pub(crate) inner: LdkStaticInvoice,
+}
+
+#[uniffi::export]
+impl StaticInvoice {
+	/// The amount for a successful payment of the invoice, if specified.
+	pub fn amount(&self) -> Option<OfferAmount> {
+		self.inner.amount().map(|amount| amount.into())
+	}
+}
+
+impl From<LdkStaticInvoice> for StaticInvoice {
+	fn from(invoice: LdkStaticInvoice) -> Self {
+		StaticInvoice { inner: invoice }
+	}
+}
+
+impl Deref for StaticInvoice {
+	type Target = LdkStaticInvoice;
+	fn deref(&self) -> &Self::Target {
+		&self.inner
+	}
+}
+
+impl AsRef<LdkStaticInvoice> for StaticInvoice {
+	fn as_ref(&self) -> &LdkStaticInvoice {
+		self.deref()
+	}
+}
+
+/// The BOLT12 invoice that was paid, surfaced in [`Event::PaymentSuccessful`].
+///
+/// [`Event::PaymentSuccessful`]: crate::Event::PaymentSuccessful
+///
+/// Note: The variant names intentionally differ from their contained types to avoid
+/// name collisions in Kotlin codegen, where sealed class inner classes would shadow
+/// top-level types of the same name.
+#[derive(Debug, Clone, PartialEq, Eq, uniffi::Enum)]
+pub enum PaidBolt12Invoice {
+	/// The BOLT12 invoice, allowing the user to perform proof of payment.
+	Bolt12(Arc<Bolt12Invoice>),
+	/// The static invoice, used in async payments, where the user cannot perform proof of
+	/// payment.
+	Static(Arc<StaticInvoice>),
+}
+
+impl From<LdkPaidBolt12Invoice> for PaidBolt12Invoice {
+	fn from(ldk: LdkPaidBolt12Invoice) -> Self {
+		match ldk {
+			LdkPaidBolt12Invoice::Bolt12Invoice(invoice) => {
+				PaidBolt12Invoice::Bolt12(Arc::new(Bolt12Invoice::from(invoice)))
+			},
+			LdkPaidBolt12Invoice::StaticInvoice(invoice) => {
+				PaidBolt12Invoice::Static(Arc::new(StaticInvoice::from(invoice)))
+			},
+		}
+	}
+}
+
+impl From<PaidBolt12Invoice> for LdkPaidBolt12Invoice {
+	fn from(wrapper: PaidBolt12Invoice) -> Self {
+		match wrapper {
+			PaidBolt12Invoice::Bolt12(invoice) => {
+				LdkPaidBolt12Invoice::Bolt12Invoice(invoice.inner.clone())
+			},
+			PaidBolt12Invoice::Static(invoice) => {
+				LdkPaidBolt12Invoice::StaticInvoice(invoice.inner.clone())
+			},
+		}
+	}
+}
+
+impl Writeable for PaidBolt12Invoice {
+	fn write<W: Writer>(&self, w: &mut W) -> Result<(), lightning::io::Error> {
+		// We clone `self` to convert it into the LDK native type for serialization.
+		// This only runs during event persistence, so the overhead is acceptable.
+		let ldk_type: LdkPaidBolt12Invoice = self.clone().into();
+		ldk_type.write(w)
+	}
+}
+
+impl Readable for PaidBolt12Invoice {
+	fn read<R: lightning::io::Read>(r: &mut R) -> Result<Self, DecodeError> {
+		let ldk_type = LdkPaidBolt12Invoice::read(r)?;
+		Ok(ldk_type.into())
+	}
+}
+
 uniffi::custom_type!(OfferId, String, {
 	remote,
 	try_lift: |val| {

src/payment/mod.rs

@@ -25,3 +25,11 @@ pub use store::{
 	ConfirmationStatus, LSPFeeLimits, PaymentDetails, PaymentDirection, PaymentKind, PaymentStatus,
 };
 pub use unified::{UnifiedPayment, UnifiedPaymentResult};
+
+// We re-export `PaidBolt12Invoice` from different modules depending on the `uniffi` feature.
+// Under UniFFI, enum variants containing non-primitive types must be `Arc`-wrapped, so we use a
+// custom wrapper defined in `ffi::types`. Without UniFFI, we re-export the LDK native type directly.
+#[cfg(feature = "uniffi")]
+pub use crate::ffi::PaidBolt12Invoice;
+#[cfg(not(feature = "uniffi"))]
+pub use crate::types::PaidBolt12Invoice;

src/types.rs

@@ -626,3 +626,6 @@ impl From<&(u64, Vec<u8>)> for CustomTlvRecord {
 }
 
 pub(crate) type PendingPaymentStore = DataStore<PendingPaymentDetails, Arc<Logger>>;
+
+#[cfg(not(feature = "uniffi"))]
+pub use lightning::events::PaidBolt12Invoice;

tests/common/mod.rs

@@ -953,7 +953,17 @@ pub(crate) async fn do_channel_full_cycle<E: ElectrumApi>(
 	});
 	assert_eq!(inbound_payments_b.len(), 1);
 
-	expect_event!(node_a, PaymentSuccessful);
+	// Verify bolt12_invoice is None for BOLT11 payments
+	match node_a.next_event_async().await {
+		ref e @ Event::PaymentSuccessful { ref bolt12_invoice, .. } => {
+			println!("{} got event {:?}", node_a.node_id(), e);
+			assert!(bolt12_invoice.is_none(), "bolt12_invoice should be None for BOLT11 payments");
+			node_a.event_handled().unwrap();
+		},
+		ref e => {
+			panic!("{} got unexpected event!: {:?}", std::stringify!(node_a), e);
+		},
+	}
 	expect_event!(node_b, PaymentReceived);
 	assert_eq!(node_a.payment(&payment_id).unwrap().status, PaymentStatus::Succeeded);
 	assert_eq!(node_a.payment(&payment_id).unwrap().direction, PaymentDirection::Outbound);

tests/integration_tests_rust.rs

@@ -30,13 +30,14 @@ use ldk_node::config::{AsyncPaymentsRole, EsploraSyncConfig};
 use ldk_node::entropy::NodeEntropy;
 use ldk_node::liquidity::LSPS2ServiceConfig;
 use ldk_node::payment::{
-	ConfirmationStatus, PaymentDetails, PaymentDirection, PaymentKind, PaymentStatus,
-	UnifiedPaymentResult,
+	ConfirmationStatus, PaidBolt12Invoice, PaymentDetails, PaymentDirection, PaymentKind,
+	PaymentStatus, UnifiedPaymentResult,
 };
 use ldk_node::{Builder, Event, NodeError};
 use lightning::ln::channelmanager::PaymentId;
 use lightning::routing::gossip::{NodeAlias, NodeId};
 use lightning::routing::router::RouteParametersConfig;
+use lightning::util::ser::{Readable, Writeable};
 use lightning_invoice::{Bolt11InvoiceDescription, Description};
 use lightning_types::payment::{PaymentHash, PaymentPreimage};
 use log::LevelFilter;
@@ -1273,6 +1274,95 @@ async fn simple_bolt12_send_receive() {
 	assert_eq!(node_a_payments.first().unwrap().amount_msat, Some(overpaid_amount));
 }
 
+#[tokio::test(flavor = "multi_thread", worker_threads = 1)]
+async fn bolt12_proof_of_payment() {
+	let (bitcoind, electrsd) = setup_bitcoind_and_electrsd();
+	let chain_source = TestChainSource::Esplora(&electrsd);
+	let (node_a, node_b) = setup_two_nodes(&chain_source, false, true, false);
+
+	let address_a = node_a.onchain_payment().new_address().unwrap();
+	let premine_amount_sat = 5_000_000;
+	premine_and_distribute_funds(
+		&bitcoind.client,
+		&electrsd.client,
+		vec![address_a],
+		Amount::from_sat(premine_amount_sat),
+	)
+	.await;
+
+	node_a.sync_wallets().unwrap();
+	open_channel(&node_a, &node_b, 4_000_000, true, &electrsd).await;
+
+	generate_blocks_and_wait(&bitcoind.client, &electrsd.client, 6).await;
+
+	node_a.sync_wallets().unwrap();
+	node_b.sync_wallets().unwrap();
+
+	expect_channel_ready_event!(node_a, node_b.node_id());
+	expect_channel_ready_event!(node_b, node_a.node_id());
+
+	// Sleep until we broadcasted a node announcement.
+	while node_b.status().latest_node_announcement_broadcast_timestamp.is_none() {
+		tokio::time::sleep(std::time::Duration::from_millis(10)).await;
+	}
+
+	// Sleep one more sec to make sure the node announcement propagates.
+	tokio::time::sleep(std::time::Duration::from_secs(1)).await;
+
+	let expected_amount_msat = 100_000_000;
+	let offer = node_b
+		.bolt12_payment()
+		.receive(expected_amount_msat, "proof of payment test", None, Some(1))
+		.unwrap();
+	let payment_id =
+		node_a.bolt12_payment().send(&offer, Some(1), Some("Test".to_string()), None).unwrap();
+
+	// Wait for payment and verify proof of payment
+	let event = node_a.next_event_async().await;
+	match &event {
+		Event::PaymentSuccessful {
+			payment_id: event_payment_id,
+			payment_hash,
+			payment_preimage,
+			fee_paid_msat: _,
+			bolt12_invoice,
+		} => {
+			assert_eq!(*event_payment_id, Some(payment_id));
+
+			// Verify proof of payment: sha256(preimage) == payment_hash
+			let preimage = payment_preimage.expect("preimage should be present");
+			let computed_hash = Sha256Hash::hash(&preimage.0);
+			assert_eq!(PaymentHash(computed_hash.to_byte_array()), *payment_hash);
+
+			// Verify the BOLT12 invoice is present and contains the correct payment hash
+			let paid_invoice = bolt12_invoice
+				.as_ref()
+				.expect("bolt12_invoice should be present for BOLT12 payments");
+			match paid_invoice {
+				PaidBolt12Invoice::Bolt12Invoice(invoice) => {
+					assert_eq!(invoice.payment_hash(), *payment_hash);
+					assert_eq!(invoice.amount_msats(), expected_amount_msat);
+				},
+				PaidBolt12Invoice::StaticInvoice(_) => {
+					panic!("Expected Bolt12Invoice, got StaticInvoice");
+				},
+			}
+
+			// Verify serialization round-trip (tests TLV tag 7 backward compatibility)
+			let encoded = event.encode();
+			let decoded: Event = Readable::read(&mut std::io::Cursor::new(&encoded)).unwrap();
+			assert_eq!(event, decoded);
+
+			node_a.event_handled().unwrap();
+		},
+		e => {
+			panic!("Unexpected event: {:?}", e);
+		},
+	}
+
+	expect_payment_received_event!(node_b, expected_amount_msat);
+}
+
 #[tokio::test(flavor = "multi_thread", worker_threads = 1)]
 async fn async_payment() {
 	let (bitcoind, electrsd) = setup_bitcoind_and_electrsd();