Expose BOLT 12 payer proofs

Add payer-proof creation to the gRPC, CLI, and MCP interfaces. Include
the preimage and invoice in successful-payment events because stateless
proof creation requires both values.

AI assistance: OpenAI Codex was used to rebase and verify this change.

Author: benthecarman

docs/api-guide.md

@@ -130,8 +130,9 @@ when the invoice is paid.
 
 | RPC             | Description                                                             |
 |-----------------|-------------------------------------------------------------------------|
-| `Bolt12Receive` | Create a BOLT12 offer (fixed or variable amount)                        |
-| `Bolt12Send`    | Pay a BOLT12 offer (with optional quantity, payer note, routing config) |
+| `Bolt12Receive`            | Create a BOLT12 offer (fixed or variable amount)                        |
+| `Bolt12Send`               | Pay a BOLT12 offer (with optional quantity, payer note, routing config) |
+| `Bolt12CreatePayerProof`   | Create a BOLT 12 payer proof from a successful payment                  |
 
 ### Spontaneous and Unified Send
 

e2e-tests/tests/e2e.rs

@@ -995,6 +995,55 @@ async fn test_cli_bolt12_send() {
 	assert!(!output["payment_id"].as_str().unwrap().is_empty());
 }
 
+#[tokio::test(flavor = "multi_thread", worker_threads = 1)]
+async fn test_cli_bolt12_create_payer_proof() {
+	let bitcoind = TestBitcoind::new();
+	let server_a = LdkServerHandle::start(&bitcoind).await;
+	let server_b = LdkServerHandle::start(&bitcoind).await;
+
+	let mut events_a = server_a.client().subscribe_events().await.unwrap();
+
+	setup_funded_channel(&bitcoind, &server_a, &server_b, 100_000).await;
+
+	let offer_resp = server_b
+		.client()
+		.bolt12_receive(Bolt12ReceiveRequest {
+			description: "payer proof offer".to_string(),
+			amount_msat: Some(10_000_000),
+			expiry_secs: None,
+			quantity: None,
+		})
+		.await
+		.unwrap();
+
+	let send_output = run_cli(&server_a, &["bolt12-send", &offer_resp.offer]);
+	let send_payment_id = send_output["payment_id"].as_str().unwrap();
+	assert!(!send_payment_id.is_empty());
+
+	let event_a = wait_for_event(&mut events_a, |e| matches!(e, Event::PaymentSuccessful(_))).await;
+	let Some(Event::PaymentSuccessful(successful)) = &event_a.event else {
+		panic!("expected PaymentSuccessful");
+	};
+	assert_eq!(successful.payment_id, send_payment_id);
+	let payment_preimage = successful.payment_preimage.as_ref().expect("preimage");
+	let invoice = successful.bolt12_invoice.as_ref().expect("bolt12 invoice");
+
+	let proof_output = run_cli(
+		&server_a,
+		&[
+			"bolt12-create-payer-proof",
+			send_payment_id,
+			payment_preimage,
+			invoice,
+			"--include-offer-description",
+			"--include-invoice-amount",
+			"--note",
+			"Paid in full",
+		],
+	);
+	assert!(!proof_output["payer_proof"].as_str().unwrap().is_empty());
+}
+
 #[tokio::test(flavor = "multi_thread", worker_threads = 1)]
 async fn test_cli_spontaneous_send() {
 	let bitcoind = TestBitcoind::new();

ldk-server-cli/src/main.rs

@@ -29,26 +29,27 @@ use ldk_server_client::ldk_server_grpc::api::{
 	Bolt11ReceiveRequest, Bolt11ReceiveResponse, Bolt11ReceiveVariableAmountViaJitChannelRequest,
 	Bolt11ReceiveVariableAmountViaJitChannelResponse, Bolt11ReceiveViaJitChannelRequest,
 	Bolt11ReceiveViaJitChannelResponse, Bolt11SendRequest, Bolt11SendResponse,
-	Bolt11SendUnderpayingRequest, Bolt11SendUnderpayingResponse, Bolt12ReceiveRequest,
-	Bolt12ReceiveResponse, Bolt12SendRequest, Bolt12SendResponse, CloseChannelRequest,
-	CloseChannelResponse, ConnectPeerRequest, ConnectPeerResponse, DecodeInvoiceRequest,
-	DecodeInvoiceResponse, DecodeOfferRequest, DecodeOfferResponse, DisconnectPeerRequest,
-	DisconnectPeerResponse, ExportPathfindingScoresRequest, ForceCloseChannelRequest,
-	ForceCloseChannelResponse, GetBalancesRequest, GetBalancesResponse, GetNodeInfoRequest,
-	GetNodeInfoResponse, GetPaymentDetailsRequest, GetPaymentDetailsResponse,
-	GraphGetChannelRequest, GraphGetChannelResponse, GraphGetNodeRequest, GraphGetNodeResponse,
-	GraphListChannelsRequest, GraphListChannelsResponse, GraphListNodesRequest,
-	GraphListNodesResponse, ListChannelsRequest, ListChannelsResponse,
-	ListForwardedPaymentsRequest, ListPaymentsRequest, ListPeersRequest, ListPeersResponse,
-	OnchainReceiveRequest, OnchainReceiveResponse, OnchainSendRequest, OnchainSendResponse,
-	OpenChannelRequest, OpenChannelResponse, SignMessageRequest, SignMessageResponse,
-	SpliceInRequest, SpliceInResponse, SpliceOutRequest, SpliceOutResponse, SpontaneousSendRequest,
-	SpontaneousSendResponse, UnifiedSendRequest, UnifiedSendResponse, UpdateChannelConfigRequest,
-	UpdateChannelConfigResponse, VerifySignatureRequest, VerifySignatureResponse,
+	Bolt11SendUnderpayingRequest, Bolt11SendUnderpayingResponse, Bolt12CreatePayerProofRequest,
+	Bolt12CreatePayerProofResponse, Bolt12ReceiveRequest, Bolt12ReceiveResponse, Bolt12SendRequest,
+	Bolt12SendResponse, CloseChannelRequest, CloseChannelResponse, ConnectPeerRequest,
+	ConnectPeerResponse, DecodeInvoiceRequest, DecodeInvoiceResponse, DecodeOfferRequest,
+	DecodeOfferResponse, DisconnectPeerRequest, DisconnectPeerResponse,
+	ExportPathfindingScoresRequest, ForceCloseChannelRequest, ForceCloseChannelResponse,
+	GetBalancesRequest, GetBalancesResponse, GetNodeInfoRequest, GetNodeInfoResponse,
+	GetPaymentDetailsRequest, GetPaymentDetailsResponse, GraphGetChannelRequest,
+	GraphGetChannelResponse, GraphGetNodeRequest, GraphGetNodeResponse, GraphListChannelsRequest,
+	GraphListChannelsResponse, GraphListNodesRequest, GraphListNodesResponse, ListChannelsRequest,
+	ListChannelsResponse, ListForwardedPaymentsRequest, ListPaymentsRequest, ListPeersRequest,
+	ListPeersResponse, OnchainReceiveRequest, OnchainReceiveResponse, OnchainSendRequest,
+	OnchainSendResponse, OpenChannelRequest, OpenChannelResponse, SignMessageRequest,
+	SignMessageResponse, SpliceInRequest, SpliceInResponse, SpliceOutRequest, SpliceOutResponse,
+	SpontaneousSendRequest, SpontaneousSendResponse, UnifiedSendRequest, UnifiedSendResponse,
+	UpdateChannelConfigRequest, UpdateChannelConfigResponse, VerifySignatureRequest,
+	VerifySignatureResponse,
 };
 use ldk_server_client::ldk_server_grpc::types::{
 	bolt11_invoice_description, Bolt11InvoiceDescription, ChannelConfig, CustomTlvRecord,
-	PageToken, RouteParametersConfig,
+	PageToken, PayerProofOptions, RouteParametersConfig,
 };
 use ldk_server_client::{
 	DEFAULT_EXPIRY_SECS, DEFAULT_MAX_CHANNEL_SATURATION_POWER_OF_HALF, DEFAULT_MAX_PATH_COUNT,
@@ -315,6 +316,27 @@ enum Commands {
 		)]
 		max_channel_saturation_power_of_half: Option<u32>,
 	},
+	#[command(about = "Create a BOLT 12 payer proof for a payment this node made")]
+	Bolt12CreatePayerProof {
+		#[arg(help = "The hex-encoded payment id from PaymentSuccessful")]
+		payment_id: String,
+		#[arg(help = "The hex-encoded 32-byte payment preimage from PaymentSuccessful")]
+		payment_preimage: String,
+		#[arg(help = "The hex-encoded BOLT 12 invoice from PaymentSuccessful")]
+		invoice: String,
+		#[arg(long, help = "Optional note to attach to the payer proof")]
+		note: Option<String>,
+		#[arg(long, help = "Disclose the offer description in the proof")]
+		include_offer_description: bool,
+		#[arg(long, help = "Disclose the offer issuer in the proof")]
+		include_offer_issuer: bool,
+		#[arg(long, help = "Disclose the invoice amount in the proof")]
+		include_invoice_amount: bool,
+		#[arg(long, help = "Disclose the invoice creation timestamp in the proof")]
+		include_invoice_created_at: bool,
+		#[arg(long, help = "Additional TLV types to disclose")]
+		extra_tlv_types: Vec<u64>,
+	},
 	#[command(about = "Send a spontaneous payment (keysend) to a node")]
 	SpontaneousSend {
 		#[arg(help = "The hex-encoded public key of the node to send the payment to")]
@@ -868,6 +890,36 @@ async fn main() {
 					.await,
 			);
 		},
+		Commands::Bolt12CreatePayerProof {
+			payment_id,
+			payment_preimage,
+			invoice,
+			note,
+			include_offer_description,
+			include_offer_issuer,
+			include_invoice_amount,
+			include_invoice_created_at,
+			extra_tlv_types,
+		} => {
+			let options = PayerProofOptions {
+				note,
+				include_offer_description,
+				include_offer_issuer,
+				include_invoice_amount,
+				include_invoice_created_at,
+				extra_tlv_types,
+			};
+			handle_response_result::<_, Bolt12CreatePayerProofResponse>(
+				client
+					.bolt12_create_payer_proof(Bolt12CreatePayerProofRequest {
+						payment_id,
+						payment_preimage,
+						invoice,
+						options: Some(options),
+					})
+					.await,
+			);
+		},
 		Commands::SpontaneousSend {
 			node_id,
 			amount,

ldk-server-client/src/client.rs

@@ -21,13 +21,14 @@ use ldk_server_grpc::api::{
 	Bolt11ReceiveRequest, Bolt11ReceiveResponse, Bolt11ReceiveVariableAmountViaJitChannelRequest,
 	Bolt11ReceiveVariableAmountViaJitChannelResponse, Bolt11ReceiveViaJitChannelRequest,
 	Bolt11ReceiveViaJitChannelResponse, Bolt11SendRequest, Bolt11SendResponse,
-	Bolt11SendUnderpayingRequest, Bolt11SendUnderpayingResponse, Bolt12ReceiveRequest,
-	Bolt12ReceiveResponse, Bolt12SendRequest, Bolt12SendResponse, CloseChannelRequest,
-	CloseChannelResponse, ConnectPeerRequest, ConnectPeerResponse, DecodeInvoiceRequest,
-	DecodeInvoiceResponse, DecodeOfferRequest, DecodeOfferResponse, DisconnectPeerRequest,
-	DisconnectPeerResponse, ExportPathfindingScoresRequest, ExportPathfindingScoresResponse,
-	ForceCloseChannelRequest, ForceCloseChannelResponse, GetBalancesRequest, GetBalancesResponse,
-	GetNodeInfoRequest, GetNodeInfoResponse, GetPaymentDetailsRequest, GetPaymentDetailsResponse,
+	Bolt11SendUnderpayingRequest, Bolt11SendUnderpayingResponse, Bolt12CreatePayerProofRequest,
+	Bolt12CreatePayerProofResponse, Bolt12ReceiveRequest, Bolt12ReceiveResponse, Bolt12SendRequest,
+	Bolt12SendResponse, CloseChannelRequest, CloseChannelResponse, ConnectPeerRequest,
+	ConnectPeerResponse, DecodeInvoiceRequest, DecodeInvoiceResponse, DecodeOfferRequest,
+	DecodeOfferResponse, DisconnectPeerRequest, DisconnectPeerResponse,
+	ExportPathfindingScoresRequest, ExportPathfindingScoresResponse, ForceCloseChannelRequest,
+	ForceCloseChannelResponse, GetBalancesRequest, GetBalancesResponse, GetNodeInfoRequest,
+	GetNodeInfoResponse, GetPaymentDetailsRequest, GetPaymentDetailsResponse,
 	GraphGetChannelRequest, GraphGetChannelResponse, GraphGetNodeRequest, GraphGetNodeResponse,
 	GraphListChannelsRequest, GraphListChannelsResponse, GraphListNodesRequest,
 	GraphListNodesResponse, ListChannelsRequest, ListChannelsResponse,
@@ -44,10 +45,10 @@ use ldk_server_grpc::endpoints::{
 	BOLT11_CLAIM_FOR_ID_PATH, BOLT11_FAIL_FOR_ID_PATH, BOLT11_RECEIVE_FOR_HASH_PATH,
 	BOLT11_RECEIVE_PATH, BOLT11_RECEIVE_VARIABLE_AMOUNT_VIA_JIT_CHANNEL_PATH,
 	BOLT11_RECEIVE_VIA_JIT_CHANNEL_PATH, BOLT11_SEND_PATH, BOLT11_SEND_UNDERPAYING_PATH,
-	BOLT12_RECEIVE_PATH, BOLT12_SEND_PATH, CLOSE_CHANNEL_PATH, CONNECT_PEER_PATH,
-	DECODE_INVOICE_PATH, DECODE_OFFER_PATH, DISCONNECT_PEER_PATH, EXPORT_PATHFINDING_SCORES_PATH,
-	FORCE_CLOSE_CHANNEL_PATH, GET_BALANCES_PATH, GET_METRICS_PATH, GET_NODE_INFO_PATH,
-	GET_PAYMENT_DETAILS_PATH, GRAPH_GET_CHANNEL_PATH, GRAPH_GET_NODE_PATH,
+	BOLT12_CREATE_PAYER_PROOF_PATH, BOLT12_RECEIVE_PATH, BOLT12_SEND_PATH, CLOSE_CHANNEL_PATH,
+	CONNECT_PEER_PATH, DECODE_INVOICE_PATH, DECODE_OFFER_PATH, DISCONNECT_PEER_PATH,
+	EXPORT_PATHFINDING_SCORES_PATH, FORCE_CLOSE_CHANNEL_PATH, GET_BALANCES_PATH, GET_METRICS_PATH,
+	GET_NODE_INFO_PATH, GET_PAYMENT_DETAILS_PATH, GRAPH_GET_CHANNEL_PATH, GRAPH_GET_NODE_PATH,
 	GRAPH_LIST_CHANNELS_PATH, GRAPH_LIST_NODES_PATH, GRPC_SERVICE_PREFIX, LIST_CHANNELS_PATH,
 	LIST_FORWARDED_PAYMENTS_PATH, LIST_PAYMENTS_PATH, LIST_PEERS_PATH, ONCHAIN_RECEIVE_PATH,
 	ONCHAIN_SEND_PATH, OPEN_CHANNEL_PATH, SIGN_MESSAGE_PATH, SPLICE_IN_PATH, SPLICE_OUT_PATH,
@@ -269,6 +270,13 @@ impl LdkServerClient {
 		self.grpc_unary(&request, BOLT12_SEND_PATH).await
 	}
 
+	/// Create a BOLT 12 payer proof for a payment this node made.
+	pub async fn bolt12_create_payer_proof(
+		&self, request: Bolt12CreatePayerProofRequest,
+	) -> Result<Bolt12CreatePayerProofResponse, LdkServerError> {
+		self.grpc_unary(&request, BOLT12_CREATE_PAYER_PROOF_PATH).await
+	}
+
 	/// Creates a new outbound channel.
 	pub async fn open_channel(
 		&self, request: OpenChannelRequest,

ldk-server-grpc/src/api.rs

@@ -491,6 +491,40 @@ pub struct Bolt12SendResponse {
 	#[prost(string, tag = "1")]
 	pub payment_id: ::prost::alloc::string::String,
 }
+/// Create a BOLT 12 payer proof for a payment this node made.
+/// Inputs come from `PaymentSuccessful`: `payment_id`, `payment_preimage`, and `bolt12_invoice`.
+/// See more: <https://docs.rs/ldk-node/latest/ldk_node/payment/struct.Bolt12Payment.html#method.create_payer_proof>
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
+#[cfg_attr(feature = "serde", serde(default))]
+#[allow(clippy::derive_partial_eq_without_eq)]
+#[derive(Clone, PartialEq, ::prost::Message)]
+pub struct Bolt12CreatePayerProofRequest {
+	/// The local identifier used to track the payment, in hex-encoded form.
+	#[prost(string, tag = "1")]
+	pub payment_id: ::prost::alloc::string::String,
+	/// The hex-encoded 32-byte payment preimage from `PaymentSuccessful`.
+	#[prost(string, tag = "2")]
+	pub payment_preimage: ::prost::alloc::string::String,
+	/// The hex-encoded BOLT 12 invoice from `PaymentSuccessful.bolt12_invoice`.
+	/// Static invoices used for async payments cannot be proven.
+	#[prost(string, tag = "3")]
+	pub invoice: ::prost::alloc::string::String,
+	/// Controls which optional invoice fields the proof discloses.
+	#[prost(message, optional, tag = "4")]
+	pub options: ::core::option::Option<super::types::PayerProofOptions>,
+}
+/// The response for the `Bolt12CreatePayerProof` RPC. On failure, a gRPC error status is returned.
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
+#[cfg_attr(feature = "serde", serde(default))]
+#[allow(clippy::derive_partial_eq_without_eq)]
+#[derive(Clone, PartialEq, ::prost::Message)]
+pub struct Bolt12CreatePayerProofResponse {
+	/// The bech32-encoded payer proof.
+	#[prost(string, tag = "1")]
+	pub payer_proof: ::prost::alloc::string::String,
+}
 /// Send a spontaneous payment, also known as "keysend", to a node.
 /// See more: <https://docs.rs/ldk-node/latest/ldk_node/payment/struct.SpontaneousPayment.html#method.send>
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]

ldk-server-grpc/src/endpoints.rs

@@ -25,6 +25,7 @@ pub const BOLT11_SEND_PATH: &str = "Bolt11Send";
 pub const BOLT11_SEND_UNDERPAYING_PATH: &str = "Bolt11SendUnderpaying";
 pub const BOLT12_RECEIVE_PATH: &str = "Bolt12Receive";
 pub const BOLT12_SEND_PATH: &str = "Bolt12Send";
+pub const BOLT12_CREATE_PAYER_PROOF_PATH: &str = "Bolt12CreatePayerProof";
 pub const OPEN_CHANNEL_PATH: &str = "OpenChannel";
 pub const SPLICE_IN_PATH: &str = "SpliceIn";
 pub const SPLICE_OUT_PATH: &str = "SpliceOut";

ldk-server-grpc/src/events.rs

@@ -170,6 +170,13 @@ pub struct PaymentSuccessful {
 	/// The payment details for the payment in event.
 	#[prost(message, optional, tag = "2")]
 	pub payment: ::core::option::Option<super::types::Payment>,
+	/// The hex-encoded payment preimage. Needed to build a BOLT 12 payer proof.
+	#[prost(string, optional, tag = "3")]
+	pub payment_preimage: ::core::option::Option<::prost::alloc::string::String>,
+	/// The hex-encoded paid BOLT 12 invoice, when the payment was for a standard BOLT 12 invoice.
+	/// Unset for non-BOLT12 payments and for static invoices used in async payments.
+	#[prost(string, optional, tag = "4")]
+	pub bolt12_invoice: ::core::option::Option<::prost::alloc::string::String>,
 }
 /// PaymentFailed indicates a sent payment has failed.
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]

ldk-server-grpc/src/proto/api.proto

@@ -378,6 +378,30 @@ message Bolt12SendResponse {
   string payment_id = 1;
 }
 
+// Create a BOLT 12 payer proof for a payment this node made.
+// Inputs come from `PaymentSuccessful`: `payment_id`, `payment_preimage`, and `bolt12_invoice`.
+// See more: https://docs.rs/ldk-node/latest/ldk_node/payment/struct.Bolt12Payment.html#method.create_payer_proof
+message Bolt12CreatePayerProofRequest {
+  // The local identifier used to track the payment, in hex-encoded form.
+  string payment_id = 1;
+
+  // The hex-encoded 32-byte payment preimage from `PaymentSuccessful`.
+  string payment_preimage = 2;
+
+  // The hex-encoded BOLT 12 invoice from `PaymentSuccessful.bolt12_invoice`.
+  // Static invoices used for async payments cannot be proven.
+  string invoice = 3;
+
+  // Controls which optional invoice fields the proof discloses.
+  optional types.PayerProofOptions options = 4;
+}
+
+// The response for the `Bolt12CreatePayerProof` RPC. On failure, a gRPC error status is returned.
+message Bolt12CreatePayerProofResponse {
+  // The bech32-encoded payer proof.
+  string payer_proof = 1;
+}
+
 // Send a spontaneous payment, also known as "keysend", to a node.
 // See more: https://docs.rs/ldk-node/latest/ldk_node/payment/struct.SpontaneousPayment.html#method.send
 message SpontaneousSendRequest {
@@ -972,6 +996,8 @@ service LightningNode {
   rpc Bolt12Receive(Bolt12ReceiveRequest) returns (Bolt12ReceiveResponse);
   // Send a payment for a BOLT12 offer.
   rpc Bolt12Send(Bolt12SendRequest) returns (Bolt12SendResponse);
+  // Create a BOLT 12 payer proof for a payment this node made.
+  rpc Bolt12CreatePayerProof(Bolt12CreatePayerProofRequest) returns (Bolt12CreatePayerProofResponse);
   // Send a spontaneous payment (keysend).
   rpc SpontaneousSend(SpontaneousSendRequest) returns (SpontaneousSendResponse);
   // Create a new outbound channel.

ldk-server-grpc/src/proto/events.proto

@@ -108,6 +108,11 @@ message PaymentSuccessful {
   string payment_id = 1;
   // The payment details for the payment in event.
   types.Payment payment = 2;
+  // The hex-encoded payment preimage. Needed to build a BOLT 12 payer proof.
+  optional string payment_preimage = 3;
+  // The hex-encoded paid BOLT 12 invoice, when the payment was for a standard BOLT 12 invoice.
+  // Unset for non-BOLT12 payments and for static invoices used in async payments.
+  optional string bolt12_invoice = 4;
 }
 
 // PaymentFailed indicates a sent payment has failed.

ldk-server-grpc/src/proto/types.proto

@@ -29,6 +29,28 @@ message Payment {
   uint64 latest_update_timestamp = 6;
 }
 
+// Options that control which BOLT 12 invoice fields a payer proof discloses.
+// See more: https://docs.rs/ldk-node/latest/ldk_node/payment/struct.PayerProofOptions.html
+message PayerProofOptions {
+  // An optional note to attach to the payer proof itself.
+  optional string note = 1;
+
+  // Whether to disclose the offer description.
+  bool include_offer_description = 2;
+
+  // Whether to disclose the offer issuer.
+  bool include_offer_issuer = 3;
+
+  // Whether to disclose the invoice amount.
+  bool include_invoice_amount = 4;
+
+  // Whether to disclose the invoice creation timestamp.
+  bool include_invoice_created_at = 5;
+
+  // Additional TLV types to disclose, for fields not covered by the flags above.
+  repeated uint64 extra_tlv_types = 6;
+}
+
 message PaymentKind {
   oneof kind {
     Onchain onchain = 1;