Add BOLT 12 payer proof support

Expose `Bolt12Payment::create_payer_proof`, which builds a BOLT 12 payer
proof for a previously succeeded outbound BOLT 12 payment, with
`PayerProofOptions` controlling which optional invoice fields are
selectively disclosed.

The proof is built purely from data we already persist in the payment
store: the paid BOLT 12 invoice recorded on `PaymentKind::Bolt12Offer` /
`PaymentKind::Bolt12Refund` and the payment preimage. That means payer
proofs survive restarts and we don't need a second, node-lifetime-only
store to keep the invoice context around.

Payments that completed via a static invoice, i.e., async payments, don't
support payer proofs and are rejected with `PayerProofUnavailable`.

Also wires the new `PayerProof` type and the two new error variants
through the UniFFI surface.

This commit was written with AI assistance.

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

Author: vincenzopalazzo

CHANGELOG.md

@@ -32,6 +32,11 @@
   `ChannelTypeFeatures`.
 - `Config::anchor_channels_config` is no longer optional, hence anchor channels can no longer be
   disabled. We still negotiate legacy channels if the peer does not support anchor channels.
+- The paid BOLT 12 invoice is now persisted on `PaymentKind::Bolt12Offer` and
+  `PaymentKind::Bolt12Refund`, and `Bolt12Payment::create_payer_proof` allows building a BOLT 12
+  payer proof for a previously succeeded outbound BOLT 12 payment. `PayerProofOptions` controls
+  which optional invoice fields are selectively disclosed. Payments that completed via a static
+  invoice, i.e., async payments, do not support payer proofs. (#845)
 
 ## Bug Fixes and Improvements
 - Building a fresh node against a Bitcoin Core RPC or REST chain source that fails to return the

bindings/ldk_node.udl

@@ -206,6 +206,8 @@ enum NodeError {
 	"FeerateEstimationUpdateTimeout",
 	"WalletOperationFailed",
 	"WalletOperationTimeout",
+	"PayerProofCreationFailed",
+	"PayerProofUnavailable",
 	"OnchainTxSigningFailed",
 	"TxSyncFailed",
 	"TxSyncTimeout",
@@ -247,6 +249,7 @@ enum NodeError {
 	"LnurlAuthTimeout",
 	"InvalidLnurl",
 	"ChainSourceNotSupported",
+	"InvalidPayerProof",
 };
 
 typedef dictionary NodeStatus;

src/error.rs

@@ -57,6 +57,10 @@ pub enum Error {
 	WalletOperationFailed,
 	/// A wallet operation timed out.
 	WalletOperationTimeout,
+	/// Creating a payer proof failed.
+	PayerProofCreationFailed,
+	/// A payer proof is unavailable for the requested payment.
+	PayerProofUnavailable,
 	/// A signing operation for transaction failed.
 	OnchainTxSigningFailed,
 	/// A transaction sync operation failed.
@@ -139,6 +143,8 @@ pub enum Error {
 	InvalidLnurl,
 	/// The configured chain source is not supported.
 	ChainSourceNotSupported,
+	/// The provided payer proof is invalid.
+	InvalidPayerProof,
 }
 
 impl fmt::Display for Error {
@@ -170,6 +176,10 @@ impl fmt::Display for Error {
 			},
 			Self::WalletOperationFailed => write!(f, "Failed to conduct wallet operation."),
 			Self::WalletOperationTimeout => write!(f, "A wallet operation timed out."),
+			Self::PayerProofCreationFailed => write!(f, "Failed to create payer proof."),
+			Self::PayerProofUnavailable => {
+				write!(f, "A payer proof is unavailable for the requested payment.")
+			},
 			Self::OnchainTxSigningFailed => write!(f, "Failed to sign given transaction."),
 			Self::TxSyncFailed => write!(f, "Failed to sync transactions."),
 			Self::TxSyncTimeout => write!(f, "Syncing transactions timed out."),
@@ -227,6 +237,7 @@ impl fmt::Display for Error {
 			Self::ChainSourceNotSupported => {
 				write!(f, "The configured chain source is not supported.")
 			},
+			Self::InvalidPayerProof => write!(f, "The provided payer proof is invalid."),
 		}
 	}
 }

src/ffi/types.rs

@@ -23,7 +23,6 @@ use bitcoin::hashes::Hash;
 use bitcoin::secp256k1::PublicKey;
 pub use bitcoin::{Address, BlockHash, 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::channel_state::{ChannelShutdownState, CounterpartyForwardingInfo};
 use lightning::ln::channelmanager::PaymentId;
@@ -32,6 +31,9 @@ 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::payer_proof::{
+	PaidBolt12Invoice as LdkPaidBolt12Invoice, PayerProof as LdkPayerProof,
+};
 use lightning::offers::refund::Refund as LdkRefund;
 use lightning::offers::static_invoice::StaticInvoice as LdkStaticInvoice;
 use lightning::onion_message::dns_resolution::HumanReadableName as LdkHumanReadableName;
@@ -881,6 +883,113 @@ impl Readable for PaidBolt12Invoice {
 	}
 }
 
+/// A cryptographic proof that a BOLT12 invoice was paid by this node.
+#[derive(Debug, Clone, uniffi::Object)]
+#[uniffi::export(Debug, Display)]
+pub struct PayerProof {
+	pub(crate) inner: LdkPayerProof,
+}
+
+#[uniffi::export]
+impl PayerProof {
+	#[uniffi::constructor]
+	pub fn from_bytes(proof_bytes: Vec<u8>) -> Result<Self, Error> {
+		let inner = LdkPayerProof::try_from(proof_bytes).map_err(|_| Error::InvalidPayerProof)?;
+		Ok(Self { inner })
+	}
+
+	/// The payment preimage proving the payment completed.
+	pub fn payment_preimage(&self) -> PaymentPreimage {
+		self.inner.payment_preimage()
+	}
+
+	/// The payment hash committed to by the invoice and proven by the preimage.
+	pub fn payment_hash(&self) -> PaymentHash {
+		self.inner.payment_hash()
+	}
+
+	/// The public key of the payer that authorized the payment.
+	pub fn payer_signing_pubkey(&self) -> PublicKey {
+		self.inner.payer_signing_pubkey()
+	}
+
+	/// The issuer signing public key committed to by the invoice.
+	pub fn issuer_signing_pubkey(&self) -> PublicKey {
+		self.inner.issuer_signing_pubkey()
+	}
+
+	/// The invoice signature bytes.
+	pub fn invoice_signature(&self) -> Vec<u8> {
+		self.inner.invoice_signature().as_ref().to_vec()
+	}
+
+	/// The proof signature bytes.
+	pub fn proof_signature(&self) -> Vec<u8> {
+		self.inner.proof_signature().as_ref().to_vec()
+	}
+
+	/// The offer description, if it was disclosed in the proof.
+	pub fn offer_description(&self) -> Option<String> {
+		self.inner.offer_description().map(|value| value.to_string())
+	}
+
+	/// The offer issuer, if it was disclosed in the proof.
+	pub fn offer_issuer(&self) -> Option<String> {
+		self.inner.offer_issuer().map(|value| value.to_string())
+	}
+
+	/// The invoice amount in millisatoshis, if it was disclosed in the proof.
+	pub fn invoice_amount_msats(&self) -> Option<u64> {
+		self.inner.invoice_amount_msats()
+	}
+
+	/// The invoice creation time, in seconds since the UNIX epoch, if it was disclosed in the
+	/// proof.
+	pub fn invoice_created_at(&self) -> Option<u64> {
+		self.inner.invoice_created_at().map(|value| value.as_secs())
+	}
+
+	/// The optional note attached to the proof.
+	pub fn proof_note(&self) -> Option<String> {
+		self.inner.proof_note().map(|value| value.to_string())
+	}
+
+	/// The Merkle root committed to by the proof.
+	pub fn merkle_root(&self) -> Vec<u8> {
+		self.inner.merkle_root().to_byte_array().to_vec()
+	}
+
+	/// The raw TLV bytes of the proof.
+	pub fn bytes(&self) -> Vec<u8> {
+		self.inner.bytes().to_vec()
+	}
+
+	/// The bech32-encoded string form of the proof.
+	pub fn as_string(&self) -> String {
+		self.inner.to_string()
+	}
+}
+
+impl From<LdkPayerProof> for PayerProof {
+	fn from(inner: LdkPayerProof) -> Self {
+		Self { inner }
+	}
+}
+
+impl Deref for PayerProof {
+	type Target = LdkPayerProof;
+
+	fn deref(&self) -> &Self::Target {
+		&self.inner
+	}
+}
+
+impl std::fmt::Display for PayerProof {
+	fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+		write!(f, "{}", self.inner)
+	}
+}
+
 uniffi::custom_type!(OfferId, String, {
 	remote,
 	try_lift: |val| {

src/payment/bolt12.rs

@@ -18,10 +18,14 @@ use lightning::ln::channelmanager::{OptionalOfferPaymentParams, PaymentId};
 use lightning::ln::outbound_payment::Retry;
 use lightning::offers::offer::{Amount, Offer as LdkOffer, OfferFromHrn, Quantity};
 use lightning::offers::parse::Bolt12SemanticError;
+use lightning::offers::payer_proof::PaidBolt12Invoice as LdkPaidBolt12Invoice;
+#[cfg(not(feature = "uniffi"))]
+use lightning::offers::payer_proof::PayerProof as LdkPayerProof;
 use lightning::routing::router::RouteParametersConfig;
-use lightning::sign::EntropySource;
+use lightning::sign::{EntropySource, NodeSigner};
 #[cfg(feature = "uniffi")]
 use lightning::util::ser::{Readable, Writeable};
+use lightning_types::payment::PaymentPreimage;
 use lightning_types::string::UntrustedString;
 
 use crate::config::{AsyncPaymentsRole, Config, LDK_PAYMENT_RETRY_TIMEOUT};
@@ -52,6 +56,11 @@ type HumanReadableName = lightning::onion_message::dns_resolution::HumanReadable
 #[cfg(feature = "uniffi")]
 type HumanReadableName = Arc<crate::ffi::HumanReadableName>;
 
+#[cfg(not(feature = "uniffi"))]
+type PayerProof = LdkPayerProof;
+#[cfg(feature = "uniffi")]
+type PayerProof = Arc<crate::ffi::PayerProof>;
+
 /// A payment handler allowing to create and pay [BOLT 12] offers and refunds.
 ///
 /// Should be retrieved by calling [`Node::bolt12_payment`].
@@ -70,6 +79,24 @@ pub struct Bolt12Payment {
 	async_payments_role: Option<AsyncPaymentsRole>,
 }
 
+/// Options controlling which optional fields are disclosed in a BOLT12 payer proof.
+#[derive(Clone, Debug, PartialEq, Eq, Default)]
+#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]
+pub struct PayerProofOptions {
+	/// An optional note attached to the payer proof itself.
+	pub note: Option<String>,
+	/// Whether to include the offer description in the proof.
+	pub include_offer_description: bool,
+	/// Whether to include the offer issuer in the proof.
+	pub include_offer_issuer: bool,
+	/// Whether to include the invoice amount in the proof.
+	pub include_invoice_amount: bool,
+	/// Whether to include the invoice creation timestamp in the proof.
+	pub include_invoice_created_at: bool,
+	/// Additional TLV types to include in the selective disclosure set.
+	pub extra_tlv_types: Vec<u64>,
+}
+
 impl Bolt12Payment {
 	pub(crate) fn new(
 		runtime: Arc<Runtime>, channel_manager: Arc<ChannelManager>,
@@ -253,6 +280,33 @@ impl Bolt12Payment {
 			.blinded_paths_for_async_recipient(recipient_id, None)
 			.or(Err(Error::InvalidBlindedPaths))
 	}
+
+	/// Retrieves the persisted payer proof context, i.e., the paid BOLT 12 invoice and the payment
+	/// preimage, for a successful outbound BOLT 12 payment.
+	fn payer_proof_context(
+		&self, payment_id: &PaymentId,
+	) -> Result<(LdkPaidBolt12Invoice, PaymentPreimage), Error> {
+		let payment = self.payment_store.get(payment_id).ok_or(Error::PayerProofUnavailable)?;
+		if payment.direction != PaymentDirection::Outbound
+			|| payment.status != PaymentStatus::Succeeded
+		{
+			return Err(Error::PayerProofUnavailable);
+		}
+
+		match payment.kind {
+			PaymentKind::Bolt12Offer {
+				preimage: Some(preimage),
+				bolt12_invoice: Some(invoice),
+				..
+			}
+			| PaymentKind::Bolt12Refund {
+				preimage: Some(preimage),
+				bolt12_invoice: Some(invoice),
+				..
+			} => Ok((invoice.into(), preimage)),
+			_ => Err(Error::PayerProofUnavailable),
+		}
+	}
 }
 
 #[cfg_attr(feature = "uniffi", uniffi::export)]
@@ -393,6 +447,70 @@ impl Bolt12Payment {
 		Ok(payment_id)
 	}
 
+	/// Create a payer proof for a previously succeeded outbound BOLT 12 payment.
+	///
+	/// This requires a standard BOLT 12 invoice response, which we persist alongside the payment
+	/// in the payment store. Payments that completed via a static invoice, i.e., async payments,
+	/// do not support payer proofs.
+	pub fn create_payer_proof(
+		&self, payment_id: &PaymentId, options: Option<PayerProofOptions>,
+	) -> Result<PayerProof, Error> {
+		let (paid_invoice, preimage) = self.payer_proof_context(payment_id)?;
+
+		let options = options.unwrap_or_default();
+		let expanded_key = self.keys_manager.get_expanded_key();
+		let secp_ctx = bitcoin::secp256k1::Secp256k1::new();
+
+		let mut builder = paid_invoice
+			.prove_payer_derived(preimage, &expanded_key, *payment_id, &secp_ctx)
+			.map_err(|e| {
+				log_error!(
+					self.logger,
+					"Failed to initialize payer proof builder for {}: {:?}",
+					payment_id,
+					e
+				);
+				Error::PayerProofCreationFailed
+			})?;
+
+		for tlv_type in options.extra_tlv_types {
+			builder = builder.include_type(tlv_type).map_err(|e| {
+				log_error!(
+					self.logger,
+					"Failed to include TLV {} in payer proof for {}: {:?}",
+					tlv_type,
+					payment_id,
+					e
+				);
+				Error::PayerProofCreationFailed
+			})?;
+		}
+
+		if options.include_offer_description {
+			builder = builder.include_offer_description();
+		}
+		if options.include_offer_issuer {
+			builder = builder.include_offer_issuer();
+		}
+		if options.include_invoice_amount {
+			builder = builder.include_invoice_amount();
+		}
+		if options.include_invoice_created_at {
+			builder = builder.include_invoice_created_at();
+		}
+
+		if let Some(note) = options.note {
+			builder = builder.with_proof_note(note);
+		}
+
+		let proof = builder.build_and_sign().map_err(|e| {
+			log_error!(self.logger, "Failed to build payer proof for {}: {:?}", payment_id, e);
+			Error::PayerProofCreationFailed
+		})?;
+
+		Ok(maybe_wrap(proof))
+	}
+
 	/// Returns a payable offer that can be used to request and receive a payment of the amount
 	/// given.
 	pub fn receive(

src/payment/mod.rs

@@ -18,7 +18,7 @@ mod unified;
 
 pub use bolt11::Bolt11Payment;
 pub(crate) use bolt11::PaymentMetadata;
-pub use bolt12::Bolt12Payment;
+pub use bolt12::{Bolt12Payment, PayerProofOptions};
 pub use onchain::OnchainPayment;
 pub(crate) use pending_payment_store::{FundingTxCandidate, PendingPaymentDetails};
 pub use spontaneous::SpontaneousPayment;