Decode BOLT12 invoices in the DecodeInvoice API

The `DecodeInvoice` RPC previously accepted only a BOLT11 invoice
string. It now also accepts a hex-encoded BOLT12 invoice, and the
response carries a new `kind` field ("bolt11" or "bolt12") identifying
which was decoded.

Unlike offers and BOLT11 invoices, a BOLT12 invoice has no
human-readable string encoding -- it is exchanged as raw bytes over
onion messages -- so the input is expected to be hex-encoded, and LDK's
`Bolt12Invoice` is parsed via `TryFrom<Vec<u8>>` accordingly. Per the
minimal scope here, only `kind` is populated for a BOLT12 invoice; the
remaining fields continue to apply to BOLT11 invoices.

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

Author: vincenzopalazzo

e2e-tests/tests/e2e.rs

@@ -193,6 +193,7 @@ async fn test_cli_decode_invoice() {
 	assert!(decoded["timestamp"].as_u64().unwrap() > 0);
 	assert!(decoded["min_final_cltv_expiry_delta"].as_u64().unwrap() > 0);
 	assert_eq!(decoded["is_expired"], false);
+	assert_eq!(decoded["kind"], "bolt11");
 
 	// Verify features — LDK BOLT11 invoices always set VariableLengthOnion, PaymentSecret,
 	// and BasicMPP.

e2e-tests/tests/mcp.rs

@@ -84,4 +84,5 @@ async fn test_mcp_live_tool_calls() {
 	assert_eq!(decode_invoice_json["destination"], server.node_id());
 	assert_eq!(decode_invoice_json["description"], "mcp decode");
 	assert_eq!(decode_invoice_json["amount_msat"], 50_000_000u64);
+	assert_eq!(decode_invoice_json["kind"], "bolt11");
 }

ldk-server-cli/src/main.rs

@@ -341,9 +341,9 @@ enum Commands {
 		)]
 		max_channel_saturation_power_of_half: Option<u32>,
 	},
-	#[command(about = "Decode a BOLT11 invoice and display its fields")]
+	#[command(about = "Decode a BOLT11 or BOLT12 invoice and display its fields")]
 	DecodeInvoice {
-		#[arg(help = "The BOLT11 invoice string to decode")]
+		#[arg(help = "A BOLT11 invoice string or a hex-encoded BOLT12 invoice to decode")]
 		invoice: String,
 	},
 	#[command(about = "Decode a BOLT12 offer and display its fields")]

ldk-server-client/src/client.rs

@@ -351,7 +351,7 @@ impl LdkServerClient {
 		self.grpc_unary(&request, UNIFIED_SEND_PATH).await
 	}
 
-	/// Decode a BOLT11 invoice and return its parsed fields.
+	/// Decode a BOLT11 or BOLT12 invoice and return its parsed fields.
 	pub async fn decode_invoice(
 		&self, request: DecodeInvoiceRequest,
 	) -> Result<DecodeInvoiceResponse, LdkServerError> {

ldk-server-grpc/src/api.rs

@@ -1109,19 +1109,20 @@ 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.
+/// Decode a BOLT11 or BOLT12 invoice and return its parsed fields.
+/// This does not require a running node — it only parses the invoice.
 #[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 DecodeInvoiceRequest {
-	/// The BOLT11 invoice string to decode.
+	/// The invoice to decode: either a BOLT11 invoice string or a hex-encoded BOLT12 invoice.
 	#[prost(string, tag = "1")]
 	pub invoice: ::prost::alloc::string::String,
 }
 /// The response for the `DecodeInvoice` RPC. On failure, a gRPC error status is returned.
+/// For a BOLT12 invoice only `kind` is populated; all other fields apply to BOLT11 invoices.
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
 #[cfg_attr(feature = "serde", serde(default))]
@@ -1173,6 +1174,9 @@ pub struct DecodeInvoiceResponse {
 	/// Whether the invoice has expired.
 	#[prost(bool, tag = "15")]
 	pub is_expired: bool,
+	/// The kind of decoded invoice: "bolt11" or "bolt12".
+	#[prost(string, tag = "16")]
+	pub kind: ::prost::alloc::string::String,
 }
 /// Decode a BOLT12 offer and return its parsed fields.
 /// This does not require a running node — it only parses the offer string.

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

@@ -795,14 +795,15 @@ message GraphGetNodeResponse {
   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.
+// Decode a BOLT11 or BOLT12 invoice and return its parsed fields.
+// This does not require a running node — it only parses the invoice.
 message DecodeInvoiceRequest {
-  // The BOLT11 invoice string to decode.
+  // The invoice to decode: either a BOLT11 invoice string or a hex-encoded BOLT12 invoice.
   string invoice = 1;
 }
 
 // The response for the `DecodeInvoice` RPC. On failure, a gRPC error status is returned.
+// For a BOLT12 invoice only `kind` is populated; all other fields apply to BOLT11 invoices.
 message DecodeInvoiceResponse {
   // The hex-encoded public key of the destination node.
   string destination = 1;
@@ -848,6 +849,9 @@ message DecodeInvoiceResponse {
 
   // Whether the invoice has expired.
   bool is_expired = 15;
+
+  // The kind of decoded invoice: "bolt11" or "bolt12".
+  string kind = 16;
 }
 
 // Decode a BOLT12 offer and return its parsed fields.
@@ -962,7 +966,7 @@ service LightningNode {
   rpc ExportPathfindingScores(ExportPathfindingScoresRequest) returns (ExportPathfindingScoresResponse);
   // Send a payment given a BIP 21 URI or BIP 353 Human-Readable Name.
   rpc UnifiedSend(UnifiedSendRequest) returns (UnifiedSendResponse);
-  // Decode a BOLT11 invoice and return its parsed fields.
+  // Decode a BOLT11 or BOLT12 invoice and return its parsed fields.
   rpc DecodeInvoice(DecodeInvoiceRequest) returns (DecodeInvoiceResponse);
   // Decode a BOLT12 offer and return its parsed fields.
   rpc DecodeOffer(DecodeOfferRequest) returns (DecodeOfferResponse);

ldk-server-mcp/src/tools/mod.rs

@@ -243,7 +243,7 @@ pub fn build_tool_registry() -> ToolRegistry {
 		),
 		tool_spec(
 			"decode_invoice",
-			"Decode a BOLT11 invoice and return its parsed fields",
+			"Decode a BOLT11 or BOLT12 invoice and return its parsed fields",
 			schema::decode_invoice_schema,
 			|client, args| Box::pin(handlers::handle_decode_invoice(client, args)),
 		),

ldk-server-mcp/src/tools/schema.rs

@@ -615,7 +615,7 @@ pub fn decode_invoice_schema() -> Value {
 		"properties": {
 			"invoice": {
 				"type": "string",
-				"description": "The BOLT11 invoice string to decode"
+				"description": "A BOLT11 invoice string or a hex-encoded BOLT12 invoice to decode"
 			}
 		},
 		"required": ["invoice"]

ldk-server/src/api/decode_invoice.rs

@@ -11,6 +11,7 @@ use std::str::FromStr;
 use std::sync::Arc;
 
 use hex::prelude::*;
+use ldk_node::lightning::offers::invoice::Bolt12Invoice;
 use ldk_node::lightning_invoice::Bolt11Invoice;
 use ldk_node::lightning_types::features::Bolt11InvoiceFeatures;
 use ldk_server_grpc::api::{DecodeInvoiceRequest, DecodeInvoiceResponse};
@@ -20,12 +21,40 @@ use crate::api::decode_features;
 use crate::api::error::LdkServerError;
 use crate::service::Context;
 
+const INVOICE_KIND_BOLT11: &str = "bolt11";
+const INVOICE_KIND_BOLT12: &str = "bolt12";
+
 pub(crate) async fn handle_decode_invoice_request(
 	_context: Arc<Context>, request: DecodeInvoiceRequest,
 ) -> Result<DecodeInvoiceResponse, LdkServerError> {
-	let invoice = Bolt11Invoice::from_str(request.invoice.as_str())
-		.map_err(|_| ldk_node::NodeError::InvalidInvoice)?;
+	decode_invoice(request.invoice.as_str())
+}
+
+/// Decodes either a BOLT11 invoice string or a hex-encoded BOLT12 invoice.
+fn decode_invoice(invoice: &str) -> Result<DecodeInvoiceResponse, LdkServerError> {
+	if let Ok(bolt11_invoice) = Bolt11Invoice::from_str(invoice) {
+		return Ok(decode_bolt11_invoice(&bolt11_invoice));
+	}
+
+	if let Some(response) = decode_bolt12_invoice(invoice) {
+		return Ok(response);
+	}
+
+	Err(ldk_node::NodeError::InvalidInvoice.into())
+}
+
+/// Attempts to decode `invoice` as a hex-encoded BOLT12 invoice.
+///
+/// Unlike offers and BOLT11 invoices, a BOLT12 invoice has no human-readable string
+/// encoding — it is exchanged as raw bytes — so the input is expected to be hex-encoded.
+/// Only the `kind` field is populated for a BOLT12 invoice.
+fn decode_bolt12_invoice(invoice: &str) -> Option<DecodeInvoiceResponse> {
+	let bytes = Vec::<u8>::from_hex(invoice).ok()?;
+	Bolt12Invoice::try_from(bytes).ok()?;
+	Some(DecodeInvoiceResponse { kind: INVOICE_KIND_BOLT12.to_string(), ..Default::default() })
+}
 
+fn decode_bolt11_invoice(invoice: &Bolt11Invoice) -> DecodeInvoiceResponse {
 	let destination = invoice.get_payee_pub_key().to_string();
 	let payment_hash = invoice.payment_hash().0.to_lower_hex_string();
 	let amount_msat = invoice.amount_milli_satoshis();
@@ -85,7 +114,7 @@ pub(crate) async fn handle_decode_invoice_request(
 
 	let is_expired = invoice.is_expired();
 
-	Ok(DecodeInvoiceResponse {
+	DecodeInvoiceResponse {
 		destination,
 		payment_hash,
 		amount_msat,
@@ -101,5 +130,81 @@ pub(crate) async fn handle_decode_invoice_request(
 		currency,
 		payment_metadata,
 		is_expired,
-	})
+		kind: INVOICE_KIND_BOLT11.to_string(),
+	}
+}
+
+#[cfg(test)]
+mod tests {
+	use ldk_node::lightning::bitcoin::secp256k1::{Keypair, PublicKey, Secp256k1, SecretKey};
+	use ldk_node::lightning::blinded_path::payment::{BlindedPayInfo, BlindedPaymentPath};
+	use ldk_node::lightning::blinded_path::BlindedHop;
+	use ldk_node::lightning::offers::invoice::UnsignedBolt12Invoice;
+	use ldk_node::lightning::offers::refund::RefundBuilder;
+	use ldk_node::lightning::types::features::BlindedHopFeatures;
+	use ldk_node::lightning::types::payment::PaymentHash;
+	use ldk_node::lightning::util::ser::Writeable;
+
+	use super::*;
+
+	fn pubkey(byte: u8) -> PublicKey {
+		let secp = Secp256k1::new();
+		PublicKey::from_secret_key(&secp, &SecretKey::from_slice(&[byte; 32]).unwrap())
+	}
+
+	/// Builds a signed BOLT12 invoice and returns it hex-encoded, matching how a BOLT12
+	/// invoice would be supplied to `DecodeInvoice`.
+	fn sample_bolt12_invoice_hex() -> String {
+		let secp = Secp256k1::new();
+		let keys = Keypair::from_secret_key(&secp, &SecretKey::from_slice(&[43; 32]).unwrap());
+
+		let payment_paths = vec![BlindedPaymentPath::from_blinded_path_and_payinfo(
+			pubkey(40),
+			pubkey(41),
+			vec![
+				BlindedHop { blinded_node_id: pubkey(43), encrypted_payload: vec![0; 43] },
+				BlindedHop { blinded_node_id: pubkey(44), encrypted_payload: vec![0; 44] },
+			],
+			BlindedPayInfo {
+				fee_base_msat: 1,
+				fee_proportional_millionths: 1_000,
+				cltv_expiry_delta: 42,
+				htlc_minimum_msat: 100,
+				htlc_maximum_msat: 1_000_000_000_000,
+				features: BlindedHopFeatures::empty(),
+			},
+		)];
+
+		let refund = RefundBuilder::new(vec![1; 32], pubkey(42), 1_000).unwrap().build().unwrap();
+		let invoice = refund
+			.respond_with(payment_paths, PaymentHash([42; 32]), keys.public_key())
+			.unwrap()
+			.build()
+			.unwrap()
+			.sign(|message: &UnsignedBolt12Invoice| {
+				Ok::<_, ()>(secp.sign_schnorr_no_aux_rand(message.as_ref().as_digest(), &keys))
+			})
+			.unwrap();
+
+		let mut buffer = Vec::new();
+		invoice.write(&mut buffer).unwrap();
+		buffer.to_lower_hex_string()
+	}
+
+	#[test]
+	fn rejects_unparseable_input() {
+		assert!(decode_invoice("not an invoice").is_err());
+	}
+
+	#[test]
+	fn rejects_hex_that_is_not_a_bolt12_invoice() {
+		// Valid hex, but not a BOLT12 invoice TLV stream.
+		assert!(decode_invoice("00010203").is_err());
+	}
+
+	#[test]
+	fn decodes_bolt12_invoice_with_bolt12_kind() {
+		let response = decode_invoice(&sample_bolt12_invoice_hex()).unwrap();
+		assert_eq!(response.kind, INVOICE_KIND_BOLT12);
+	}
 }