Add DecodeOffer RPC

Adds a new DecodeOffer endpoint that parses a BOLT12 offer string and
returns its fields: offer_id, description, issuer, amount (bitcoin or
currency), issuer_signing_pubkey, absolute_expiry, supported_quantity,
blinded paths, features, chains, metadata, and expiry status.

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

Author: benthecarman

e2e-tests/tests/e2e.rs

@@ -229,6 +229,52 @@ async fn test_cli_bolt12_receive() {
 	assert_eq!(offer.id().0, offer_id);
 }
 
+#[tokio::test]
+async fn test_cli_decode_offer() {
+	let bitcoind = TestBitcoind::new();
+	let server_a = LdkServerHandle::start(&bitcoind).await;
+	let server_b = LdkServerHandle::start(&bitcoind).await;
+	// BOLT12 offers need announced channels for blinded reply paths
+	setup_funded_channel(&bitcoind, &server_a, &server_b, 100_000).await;
+
+	// Create a BOLT12 offer with known parameters
+	let output = run_cli(&server_a, &["bolt12-receive", "decode offer test"]);
+	let offer_str = output["offer"].as_str().unwrap();
+
+	// Decode it
+	let decoded = run_cli(&server_a, &["decode-offer", offer_str]);
+
+	// Verify fields match
+	assert_eq!(decoded["offer_id"], output["offer_id"]);
+	assert_eq!(decoded["description"], "decode offer test");
+	assert_eq!(decoded["is_expired"], false);
+
+	// Chains should include regtest
+	let chains = decoded["chains"].as_array().unwrap();
+	assert!(chains.iter().any(|c| c == "regtest"), "Expected regtest in chains: {:?}", chains);
+
+	// Paths should be present (BOLT12 offers with blinded paths)
+	let paths = decoded["paths"].as_array().unwrap();
+	assert!(!paths.is_empty(), "Expected at least one blinded path");
+	for path in paths {
+		assert!(path["num_hops"].as_u64().unwrap() > 0);
+		assert!(!path["blinding_point"].as_str().unwrap().is_empty());
+	}
+
+	// Features — OfferContext has no known features in LDK, so this should be empty
+	let features = decoded["features"].as_object().unwrap();
+	assert!(features.is_empty(), "Expected empty offer features, got: {:?}", features);
+
+	// Variable-amount offer should have no amount
+	assert!(decoded.get("amount").is_none() || decoded["amount"].is_null());
+
+	// Test a fixed-amount offer
+	let output_fixed = run_cli(&server_a, &["bolt12-receive", "fixed amount", "50000sat"]);
+	let decoded_fixed =
+		run_cli(&server_a, &["decode-offer", output_fixed["offer"].as_str().unwrap()]);
+	assert_eq!(decoded_fixed["amount"]["amount"]["bitcoin_amount_msats"], 50_000_000);
+}
+
 #[tokio::test]
 async fn test_cli_onchain_send() {
 	let bitcoind = TestBitcoind::new();

ldk-server-cli/src/main.rs

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

ldk-server-client/src/client.rs

@@ -19,29 +19,29 @@ use ldk_server_protos::api::{
 	Bolt11ReceiveViaJitChannelResponse, Bolt11SendRequest, Bolt11SendResponse,
 	Bolt12ReceiveRequest, Bolt12ReceiveResponse, Bolt12SendRequest, Bolt12SendResponse,
 	CloseChannelRequest, CloseChannelResponse, ConnectPeerRequest, ConnectPeerResponse,
-	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,
+	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, 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, 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,
+	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_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,
@@ -374,6 +374,15 @@ impl LdkServerClient {
 		self.post_request(&request, &url).await
 	}
 
+	/// Decode a BOLT12 offer and return its parsed fields.
+	/// For API contract/usage, refer to docs for [`DecodeOfferRequest`] and [`DecodeOfferResponse`].
+	pub async fn decode_offer(
+		&self, request: DecodeOfferRequest,
+	) -> Result<DecodeOfferResponse, LdkServerError> {
+		let url = format!("https://{}/{DECODE_OFFER_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

@@ -1131,3 +1131,58 @@ pub struct DecodeInvoiceResponse {
 	#[prost(bool, tag = "15")]
 	pub is_expired: bool,
 }
+/// Decode a BOLT12 offer and return its parsed fields.
+/// This does not require a running node — it only parses the offer 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 DecodeOfferRequest {
+	/// The BOLT12 offer string to decode.
+	#[prost(string, tag = "1")]
+	pub offer: ::prost::alloc::string::String,
+}
+/// The response `content` for the `DecodeOffer` 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 DecodeOfferResponse {
+	/// The hex-encoded offer ID.
+	#[prost(string, tag = "1")]
+	pub offer_id: ::prost::alloc::string::String,
+	/// The description of the offer, if any.
+	#[prost(string, optional, tag = "2")]
+	pub description: ::core::option::Option<::prost::alloc::string::String>,
+	/// The issuer of the offer, if any.
+	#[prost(string, optional, tag = "3")]
+	pub issuer: ::core::option::Option<::prost::alloc::string::String>,
+	/// The amount, if specified.
+	#[prost(message, optional, tag = "4")]
+	pub amount: ::core::option::Option<super::types::OfferAmount>,
+	/// The hex-encoded public key used by the issuer to sign invoices, if any.
+	#[prost(string, optional, tag = "5")]
+	pub issuer_signing_pubkey: ::core::option::Option<::prost::alloc::string::String>,
+	/// The absolute expiry time in seconds since the UNIX epoch, if any.
+	#[prost(uint64, optional, tag = "6")]
+	pub absolute_expiry: ::core::option::Option<u64>,
+	/// The supported quantity of items.
+	#[prost(message, optional, tag = "7")]
+	pub quantity: ::core::option::Option<super::types::OfferQuantity>,
+	/// Blinded paths to the offer recipient.
+	#[prost(message, repeated, tag = "8")]
+	pub paths: ::prost::alloc::vec::Vec<super::types::BlindedPath>,
+	/// Feature bits advertised in the offer, keyed by bit number.
+	#[prost(map = "uint32, message", tag = "9")]
+	pub features: ::std::collections::HashMap<u32, super::types::Bolt11Feature>,
+	/// Supported blockchain networks (e.g., "bitcoin", "testnet", "signet", "regtest").
+	#[prost(string, repeated, tag = "10")]
+	pub chains: ::prost::alloc::vec::Vec<::prost::alloc::string::String>,
+	/// The metadata, hex-encoded, if any.
+	#[prost(string, optional, tag = "11")]
+	pub metadata: ::core::option::Option<::prost::alloc::string::String>,
+	/// Whether the offer has expired.
+	#[prost(bool, tag = "12")]
+	pub is_expired: bool,
+}

ldk-server-protos/src/endpoints.rs

@@ -44,3 +44,4 @@ 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";
+pub const DECODE_OFFER_PATH: &str = "DecodeOffer";

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

@@ -878,3 +878,50 @@ message DecodeInvoiceResponse {
   // Whether the invoice has expired.
   bool is_expired = 15;
 }
+
+// Decode a BOLT12 offer and return its parsed fields.
+// This does not require a running node — it only parses the offer string.
+message DecodeOfferRequest {
+  // The BOLT12 offer string to decode.
+  string offer = 1;
+}
+
+// The response `content` for the `DecodeOffer` API, when HttpStatusCode is OK (200).
+// When HttpStatusCode is not OK (non-200), the response `content` contains a serialized `ErrorResponse`.
+message DecodeOfferResponse {
+  // The hex-encoded offer ID.
+  string offer_id = 1;
+
+  // The description of the offer, if any.
+  optional string description = 2;
+
+  // The issuer of the offer, if any.
+  optional string issuer = 3;
+
+  // The amount, if specified.
+  types.OfferAmount amount = 4;
+
+  // The hex-encoded public key used by the issuer to sign invoices, if any.
+  optional string issuer_signing_pubkey = 5;
+
+  // The absolute expiry time in seconds since the UNIX epoch, if any.
+  optional uint64 absolute_expiry = 6;
+
+  // The supported quantity of items.
+  types.OfferQuantity quantity = 7;
+
+  // Blinded paths to the offer recipient.
+  repeated types.BlindedPath paths = 8;
+
+  // Feature bits advertised in the offer, keyed by bit number.
+  map<uint32, types.Bolt11Feature> features = 9;
+
+  // Supported blockchain networks (e.g., "bitcoin", "testnet", "signet", "regtest").
+  repeated string chains = 10;
+
+  // The metadata, hex-encoded, if any.
+  optional string metadata = 11;
+
+  // Whether the offer has expired.
+  bool is_expired = 12;
+}

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

@@ -843,6 +843,57 @@ message Bolt11HopHint {
   uint32 cltv_expiry_delta = 5;
 }
 
+// The amount specified in a BOLT12 offer.
+message OfferAmount {
+  oneof amount {
+    // Amount in millisatoshis for Bitcoin payments.
+    uint64 bitcoin_amount_msats = 1;
+
+    // Amount in a non-Bitcoin currency.
+    CurrencyAmount currency_amount = 2;
+  }
+}
+
+// A non-Bitcoin currency amount.
+message CurrencyAmount {
+  // ISO 4217 currency code (e.g., "USD", "EUR").
+  string iso4217_code = 1;
+
+  // The amount in the specified currency's minor unit.
+  uint64 amount = 2;
+}
+
+// The quantity of items supported by a BOLT12 offer.
+message OfferQuantity {
+  oneof quantity {
+    // Only one item may be requested.
+    bool one = 1;
+
+    // Up to this many items may be requested.
+    uint64 bounded = 2;
+
+    // Any number of items may be requested.
+    bool unbounded = 3;
+  }
+}
+
+// A blinded path to the offer recipient.
+message BlindedPath {
+  // The hex-encoded public key of the introduction node, if available.
+  // If the introduction node is a directed short channel ID, this will be empty
+  // and `introduction_scid` will be set instead.
+  optional string introduction_node_id = 1;
+
+  // The hex-encoded blinding point.
+  string blinding_point = 2;
+
+  // The number of blinded hops in the path.
+  uint32 num_hops = 3;
+
+  // If the introduction node is a directed short channel ID rather than a node ID.
+  optional uint64 introduction_scid = 4;
+}
+
 // A feature bit advertised in a BOLT11 invoice.
 message Bolt11Feature {
   // Human-readable feature name.