Add DecodeInvoice RPC

Adds a new DecodeInvoice endpoint that parses a BOLT11 invoice string
and returns its fields (destination, payment_hash, amount, timestamp,
expiry, description, route_hints, features, currency, etc.), similar
to lncli's decodepayreq needed for thunderhub and zeus.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: benthecarman

e2e-tests/tests/e2e.rs

@@ -148,6 +148,70 @@ async fn test_cli_bolt11_receive() {
 	assert_eq!(invoice.payment_secret().0, payment_secret);
 }
 
+#[tokio::test]
+async fn test_cli_decode_invoice() {
+	let bitcoind = TestBitcoind::new();
+	let server = LdkServerHandle::start(&bitcoind).await;
+
+	// Create a BOLT11 invoice with known parameters
+	let output =
+		run_cli(&server, &["bolt11-receive", "50000sat", "-d", "decode test", "-e", "3600"]);
+	let invoice_str = output["invoice"].as_str().unwrap();
+
+	// Decode it
+	let decoded = run_cli(&server, &["decode-invoice", invoice_str]);
+
+	// Verify fields match
+	assert_eq!(decoded["destination"], server.node_id());
+	assert_eq!(decoded["payment_hash"], output["payment_hash"]);
+	assert_eq!(decoded["amount_msat"], 50_000_000);
+	assert_eq!(decoded["description"], "decode test");
+	assert!(decoded.get("description_hash").is_none() || decoded["description_hash"].is_null());
+	assert_eq!(decoded["expiry"], 3600);
+	assert_eq!(decoded["currency"], "regtest");
+	assert_eq!(decoded["payment_secret"], output["payment_secret"]);
+	assert!(decoded["timestamp"].as_u64().unwrap() > 0);
+	assert!(decoded["min_final_cltv_expiry_delta"].as_u64().unwrap() > 0);
+	assert_eq!(decoded["is_expired"], false);
+
+	// Verify features — LDK BOLT11 invoices always set VariableLengthOnion, PaymentSecret,
+	// and BasicMPP.
+	let features = decoded["features"].as_object().unwrap();
+	assert!(!features.is_empty(), "Expected at least one feature");
+
+	let feature_names: Vec<&str> = features.values().filter_map(|f| f["name"].as_str()).collect();
+	assert!(
+		feature_names.contains(&"VariableLengthOnion"),
+		"Expected VariableLengthOnion in features: {:?}",
+		feature_names
+	);
+	assert!(
+		feature_names.contains(&"PaymentSecret"),
+		"Expected PaymentSecret in features: {:?}",
+		feature_names
+	);
+	assert!(
+		feature_names.contains(&"BasicMPP"),
+		"Expected BasicMPP in features: {:?}",
+		feature_names
+	);
+
+	// Every entry should have the expected structure
+	for (bit, feature) in features {
+		assert!(bit.parse::<u32>().is_ok(), "Feature key should be a bit number: {}", bit);
+		assert!(feature.get("name").is_some(), "Feature missing name field");
+		assert!(feature.get("is_required").is_some(), "Feature missing is_required field");
+		assert!(feature.get("is_known").is_some(), "Feature missing is_known field");
+	}
+
+	// Also test a variable-amount invoice
+	let output_var = run_cli(&server, &["bolt11-receive", "-d", "no amount"]);
+	let decoded_var =
+		run_cli(&server, &["decode-invoice", output_var["invoice"].as_str().unwrap()]);
+	assert!(decoded_var.get("amount_msat").is_none() || decoded_var["amount_msat"].is_null());
+	assert_eq!(decoded_var["description"], "no amount");
+}
+
 #[tokio::test]
 async fn test_cli_bolt12_receive() {
 	let bitcoind = TestBitcoind::new();

ldk-server-cli/src/main.rs

@@ -29,18 +29,19 @@ use ldk_server_client::ldk_server_protos::api::{
 	Bolt11ReceiveViaJitChannelResponse, Bolt11SendRequest, Bolt11SendResponse,
 	Bolt12ReceiveRequest, Bolt12ReceiveResponse, Bolt12SendRequest, Bolt12SendResponse,
 	CloseChannelRequest, CloseChannelResponse, ConnectPeerRequest, ConnectPeerResponse,
-	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,
+	DecodeInvoiceRequest, DecodeInvoiceResponse, 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_protos::types::{
 	bolt11_invoice_description, Bolt11InvoiceDescription, ChannelConfig, PageToken,
@@ -338,6 +339,11 @@ enum Commands {
 		)]
 		max_channel_saturation_power_of_half: Option<u32>,
 	},
+	#[command(about = "Decode a BOLT11 invoice and display its fields")]
+	DecodeInvoice {
+		#[arg(help = "The BOLT11 invoice string to decode")]
+		invoice: String,
+	},
 	#[command(about = "Cooperatively close the channel specified by the given channel ID")]
 	CloseChannel {
 		#[arg(help = "The local user_channel_id of this channel")]
@@ -862,6 +868,11 @@ async fn main() {
 					.await,
 			);
 		},
+		Commands::DecodeInvoice { invoice } => {
+			handle_response_result::<_, DecodeInvoiceResponse>(
+				client.decode_invoice(DecodeInvoiceRequest { invoice }).await,
+			);
+		},
 		Commands::CloseChannel { user_channel_id, counterparty_node_id } => {
 			handle_response_result::<_, CloseChannelResponse>(
 				client

ldk-server-client/src/client.rs

@@ -19,31 +19,32 @@ use ldk_server_protos::api::{
 	Bolt11ReceiveViaJitChannelResponse, Bolt11SendRequest, Bolt11SendResponse,
 	Bolt12ReceiveRequest, Bolt12ReceiveResponse, Bolt12SendRequest, Bolt12SendResponse,
 	CloseChannelRequest, CloseChannelResponse, ConnectPeerRequest, ConnectPeerResponse,
-	DisconnectPeerRequest, DisconnectPeerResponse, ExportPathfindingScoresRequest,
-	ExportPathfindingScoresResponse, ForceCloseChannelRequest, ForceCloseChannelResponse,
-	GetBalancesRequest, GetBalancesResponse, GetNodeInfoRequest, GetNodeInfoResponse,
-	GetPaymentDetailsRequest, GetPaymentDetailsResponse, GraphGetChannelRequest,
-	GraphGetChannelResponse, GraphGetNodeRequest, GraphGetNodeResponse, GraphListChannelsRequest,
-	GraphListChannelsResponse, GraphListNodesRequest, GraphListNodesResponse, ListChannelsRequest,
-	ListChannelsResponse, ListForwardedPaymentsRequest, ListForwardedPaymentsResponse,
-	ListPaymentsRequest, ListPaymentsResponse, ListPeersRequest, ListPeersResponse,
-	OnchainReceiveRequest, OnchainReceiveResponse, OnchainSendRequest, OnchainSendResponse,
-	OpenChannelRequest, OpenChannelResponse, SignMessageRequest, SignMessageResponse,
-	SpliceInRequest, SpliceInResponse, SpliceOutRequest, SpliceOutResponse, SpontaneousSendRequest,
+	DecodeInvoiceRequest, DecodeInvoiceResponse, DisconnectPeerRequest, DisconnectPeerResponse,
+	ExportPathfindingScoresRequest, ExportPathfindingScoresResponse, ForceCloseChannelRequest,
+	ForceCloseChannelResponse, GetBalancesRequest, GetBalancesResponse, GetNodeInfoRequest,
+	GetNodeInfoResponse, GetPaymentDetailsRequest, GetPaymentDetailsResponse,
+	GraphGetChannelRequest, GraphGetChannelResponse, GraphGetNodeRequest, GraphGetNodeResponse,
+	GraphListChannelsRequest, GraphListChannelsResponse, GraphListNodesRequest,
+	GraphListNodesResponse, ListChannelsRequest, ListChannelsResponse,
+	ListForwardedPaymentsRequest, ListForwardedPaymentsResponse, ListPaymentsRequest,
+	ListPaymentsResponse, 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_protos::endpoints::{
 	BOLT11_CLAIM_FOR_HASH_PATH, BOLT11_FAIL_FOR_HASH_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, BOLT12_RECEIVE_PATH, BOLT12_SEND_PATH,
-	CLOSE_CHANNEL_PATH, CONNECT_PEER_PATH, DISCONNECT_PEER_PATH, EXPORT_PATHFINDING_SCORES_PATH,
-	FORCE_CLOSE_CHANNEL_PATH, GET_BALANCES_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,
-	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, SPONTANEOUS_SEND_PATH, UNIFIED_SEND_PATH, UPDATE_CHANNEL_CONFIG_PATH,
-	VERIFY_SIGNATURE_PATH,
+	CLOSE_CHANNEL_PATH, CONNECT_PEER_PATH, DECODE_INVOICE_PATH, DISCONNECT_PEER_PATH,
+	EXPORT_PATHFINDING_SCORES_PATH, FORCE_CLOSE_CHANNEL_PATH, GET_BALANCES_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, 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,
+	SPONTANEOUS_SEND_PATH, UNIFIED_SEND_PATH, UPDATE_CHANNEL_CONFIG_PATH, VERIFY_SIGNATURE_PATH,
 };
 use ldk_server_protos::error::{ErrorCode, ErrorResponse};
 use prost::Message;
@@ -364,6 +365,15 @@ impl LdkServerClient {
 		self.post_request(&request, &url).await
 	}
 
+	/// Decode a BOLT11 invoice and return its parsed fields.
+	/// For API contract/usage, refer to docs for [`DecodeInvoiceRequest`] and [`DecodeInvoiceResponse`].
+	pub async fn decode_invoice(
+		&self, request: DecodeInvoiceRequest,
+	) -> Result<DecodeInvoiceResponse, LdkServerError> {
+		let url = format!("https://{}/{DECODE_INVOICE_PATH}", self.base_url);
+		self.post_request(&request, &url).await
+	}
+
 	/// Sign a message with the node's secret key.
 	/// For API contract/usage, refer to docs for [`SignMessageRequest`] and [`SignMessageResponse`].
 	pub async fn sign_message(

ldk-server-protos/src/api.rs

@@ -1067,3 +1067,67 @@ pub struct GraphGetNodeResponse {
 	#[prost(message, optional, tag = "1")]
 	pub node: ::core::option::Option<super::types::GraphNode>,
 }
+/// Decode a BOLT11 invoice and return its parsed fields.
+/// This does not require a running node — it only parses the invoice string.
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
+#[allow(clippy::derive_partial_eq_without_eq)]
+#[derive(Clone, PartialEq, ::prost::Message)]
+pub struct DecodeInvoiceRequest {
+	/// The BOLT11 invoice string to decode.
+	#[prost(string, tag = "1")]
+	pub invoice: ::prost::alloc::string::String,
+}
+/// The response `content` for the `DecodeInvoice` API, when HttpStatusCode is OK (200).
+/// When HttpStatusCode is not OK (non-200), the response `content` contains a serialized `ErrorResponse`.
+#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
+#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
+#[allow(clippy::derive_partial_eq_without_eq)]
+#[derive(Clone, PartialEq, ::prost::Message)]
+pub struct DecodeInvoiceResponse {
+	/// The hex-encoded public key of the destination node.
+	#[prost(string, tag = "1")]
+	pub destination: ::prost::alloc::string::String,
+	/// The hex-encoded 32-byte payment hash.
+	#[prost(string, tag = "2")]
+	pub payment_hash: ::prost::alloc::string::String,
+	/// The amount in millisatoshis, if specified in the invoice.
+	#[prost(uint64, optional, tag = "3")]
+	pub amount_msat: ::core::option::Option<u64>,
+	/// The creation timestamp in seconds since the UNIX epoch.
+	#[prost(uint64, tag = "4")]
+	pub timestamp: u64,
+	/// The invoice expiry time in seconds.
+	#[prost(uint64, tag = "5")]
+	pub expiry: u64,
+	/// The invoice description, if a direct description was provided.
+	#[prost(string, optional, tag = "6")]
+	pub description: ::core::option::Option<::prost::alloc::string::String>,
+	/// The hex-encoded SHA-256 hash of the description, if a description hash was used.
+	#[prost(string, optional, tag = "14")]
+	pub description_hash: ::core::option::Option<::prost::alloc::string::String>,
+	/// The fallback on-chain address, if any.
+	#[prost(string, optional, tag = "7")]
+	pub fallback_address: ::core::option::Option<::prost::alloc::string::String>,
+	/// The minimum final CLTV expiry delta.
+	#[prost(uint64, tag = "8")]
+	pub min_final_cltv_expiry_delta: u64,
+	/// The hex-encoded 32-byte payment secret.
+	#[prost(string, tag = "9")]
+	pub payment_secret: ::prost::alloc::string::String,
+	/// Route hints for finding a path to the payee.
+	#[prost(message, repeated, tag = "10")]
+	pub route_hints: ::prost::alloc::vec::Vec<super::types::Bolt11RouteHint>,
+	/// Feature bits advertised in the invoice, keyed by bit number.
+	#[prost(map = "uint32, message", tag = "11")]
+	pub features: ::std::collections::HashMap<u32, super::types::Bolt11Feature>,
+	/// The currency or network (e.g., "bitcoin", "testnet", "signet", "regtest").
+	#[prost(string, tag = "12")]
+	pub currency: ::prost::alloc::string::String,
+	/// The payment metadata, hex-encoded. Only present if the invoice includes payment metadata.
+	#[prost(string, optional, tag = "13")]
+	pub payment_metadata: ::core::option::Option<::prost::alloc::string::String>,
+	/// Whether the invoice has expired.
+	#[prost(bool, tag = "15")]
+	pub is_expired: bool,
+}

ldk-server-protos/src/endpoints.rs

@@ -43,3 +43,4 @@ pub const GRAPH_LIST_CHANNELS_PATH: &str = "GraphListChannels";
 pub const GRAPH_GET_CHANNEL_PATH: &str = "GraphGetChannel";
 pub const GRAPH_LIST_NODES_PATH: &str = "GraphListNodes";
 pub const GRAPH_GET_NODE_PATH: &str = "GraphGetNode";
+pub const DECODE_INVOICE_PATH: &str = "DecodeInvoice";

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

@@ -822,3 +822,59 @@ message GraphGetNodeResponse {
   // The node information.
   types.GraphNode node = 1;
 }
+
+// Decode a BOLT11 invoice and return its parsed fields.
+// This does not require a running node — it only parses the invoice string.
+message DecodeInvoiceRequest {
+  // The BOLT11 invoice string to decode.
+  string invoice = 1;
+}
+
+// The response `content` for the `DecodeInvoice` API, when HttpStatusCode is OK (200).
+// When HttpStatusCode is not OK (non-200), the response `content` contains a serialized `ErrorResponse`.
+message DecodeInvoiceResponse {
+  // The hex-encoded public key of the destination node.
+  string destination = 1;
+
+  // The hex-encoded 32-byte payment hash.
+  string payment_hash = 2;
+
+  // The amount in millisatoshis, if specified in the invoice.
+  optional uint64 amount_msat = 3;
+
+  // The creation timestamp in seconds since the UNIX epoch.
+  uint64 timestamp = 4;
+
+  // The invoice expiry time in seconds.
+  uint64 expiry = 5;
+
+  // The invoice description, if a direct description was provided.
+  optional string description = 6;
+
+  // The hex-encoded SHA-256 hash of the description, if a description hash was used.
+  optional string description_hash = 14;
+
+  // The fallback on-chain address, if any.
+  optional string fallback_address = 7;
+
+  // The minimum final CLTV expiry delta.
+  uint64 min_final_cltv_expiry_delta = 8;
+
+  // The hex-encoded 32-byte payment secret.
+  string payment_secret = 9;
+
+  // Route hints for finding a path to the payee.
+  repeated types.Bolt11RouteHint route_hints = 10;
+
+  // Feature bits advertised in the invoice, keyed by bit number.
+  map<uint32, types.Bolt11Feature> features = 11;
+
+  // The currency or network (e.g., "bitcoin", "testnet", "signet", "regtest").
+  string currency = 12;
+
+  // The payment metadata, hex-encoded. Only present if the invoice includes payment metadata.
+  optional string payment_metadata = 13;
+
+  // Whether the invoice has expired.
+  bool is_expired = 15;
+}

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

@@ -818,3 +818,39 @@ message GraphNode {
   // a channel announcement, but before receiving a node announcement.
   GraphNodeAnnouncement announcement_info = 2;
 }
+
+// Route hint for finding a path to the payee in a BOLT11 invoice.
+message Bolt11RouteHint {
+  // The hops in this route hint.
+  repeated Bolt11HopHint hop_hints = 1;
+}
+
+// A hop in a BOLT11 route hint.
+message Bolt11HopHint {
+  // The hex-encoded public key of the node at this hop.
+  string node_id = 1;
+
+  // The short channel ID.
+  uint64 short_channel_id = 2;
+
+  // The base fee in millisatoshis charged for routing through this hop.
+  uint32 fee_base_msat = 3;
+
+  // Fee proportional millionths charged for routing through this hop.
+  uint32 fee_proportional_millionths = 4;
+
+  // The CLTV expiry delta for this hop.
+  uint32 cltv_expiry_delta = 5;
+}
+
+// A feature bit advertised in a BOLT11 invoice.
+message Bolt11Feature {
+  // Human-readable feature name.
+  string name = 1;
+
+  // Whether this feature is required.
+  bool is_required = 2;
+
+  // Whether this feature is known.
+  bool is_known = 3;
+}