Merge pull request #233 from f3r10/feat/custom_preimage_in_spontaneous_send

feat: allow setting custom preimage in spontaneous-send

Author: benthecarman

e2e-tests/tests/e2e.rs

@@ -33,6 +33,7 @@ use ldk_server_client::ldk_server_grpc::events::{
 use ldk_server_client::ldk_server_grpc::types::{
 	bolt11_invoice_description, Bolt11InvoiceDescription,
 };
+use ldk_server_grpc::types::payment_kind;
 
 const EVENT_TIMEOUT: Duration = Duration::from_secs(15);
 
@@ -1531,3 +1532,40 @@ async fn test_metrics_endpoint_with_auth() {
 	assert!(metrics.contains("ldk_server_total_anchor_channels_reserve_sats 0"));
 	assert!(metrics.contains("ldk_server_total_lightning_balance_sats 0"));
 }
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 1)]
+async fn test_cli_spontaneous_send_with_preimage() {
+	let bitcoind = TestBitcoind::new();
+	let server_a = LdkServerHandle::start(&bitcoind).await;
+	let server_b = LdkServerHandle::start(&bitcoind).await;
+
+	let mut events_b = server_b.client().subscribe_events().await.unwrap();
+
+	setup_funded_channel(&bitcoind, &server_a, &server_b, 100_000).await;
+
+	// Generate a known preimage and compute its payment hash
+	let preimage_bytes = [43u8; 32];
+	let preimage_hex = preimage_bytes.to_lower_hex_string();
+	let payment_hash = sha256::Hash::hash(&preimage_bytes);
+	let payment_hash_hex = payment_hash.to_byte_array().to_lower_hex_string();
+
+	let output = run_cli(
+		&server_a,
+		&["spontaneous-send", server_b.node_id(), "10000sat", "--preimage", &preimage_hex],
+	);
+
+	assert!(!output["payment_id"].as_str().unwrap().is_empty());
+
+	// The receiver must observe in PaymentReceived for checking on Spontaneous payment.
+	let event_b = wait_for_event(&mut events_b, |e| matches!(e, Event::PaymentReceived(_))).await;
+	let Some(Event::PaymentReceived(pr)) = event_b.event else {
+		panic!("expected PaymentReceived");
+	};
+
+	let payment = pr.payment.unwrap();
+
+	let Some(payment_kind::Kind::Spontaneous(spont)) = payment.kind.unwrap().kind else {
+		panic!("expected spontaneous kind");
+	};
+	assert_eq!(spont.hash, payment_hash_hex);
+}

ldk-server-cli/src/main.rs

@@ -56,6 +56,7 @@ use serde::Serialize;
 use serde_json::{json, Value};
 use types::{
 	Amount, CliListForwardedPaymentsResponse, CliListPaymentsResponse, CliPaginatedResponse,
+	Preimage,
 };
 
 mod types;
@@ -322,6 +323,11 @@ enum Commands {
 			help = "Custom TLV record to attach, format: <type_num>:<hex_value>. Repeatable. type_num must be >= 65536."
 		)]
 		custom_tlvs: Vec<(u64, Vec<u8>)>,
+		#[arg(
+			long,
+			help = "An optional hex-encoded 32-byte payment preimage. If provided, it will be used instead of generating a random one."
+		)]
+		preimage: Option<Preimage>,
 	},
 	#[command(
 		about = "Pay a BIP 21 URI, BIP 353 Human-Readable Name, BOLT11 invoice, or BOLT12 offer"
@@ -819,6 +825,7 @@ async fn main() {
 			max_path_count,
 			max_channel_saturation_power_of_half,
 			custom_tlvs,
+			preimage,
 		} => {
 			let amount_msat = amount.to_msat();
 			let max_total_routing_fee_msat = max_total_routing_fee.map(|a| a.to_msat());
@@ -843,6 +850,7 @@ async fn main() {
 						node_id,
 						route_parameters: Some(route_parameters),
 						custom_tlvs: proto_custom_tlvs,
+						preimage: preimage.map(|p| p.to_hex_string()),
 					})
 					.await,
 			);

ldk-server-cli/src/types.rs

@@ -16,6 +16,7 @@
 use std::fmt;
 use std::str::FromStr;
 
+use hex_conservative::{DisplayHex, FromHex};
 use ldk_server_client::ldk_server_grpc::types::{ForwardedPayment, PageToken, Payment};
 use serde::Serialize;
 
@@ -119,6 +120,26 @@ impl FromStr for Amount {
 	}
 }
 
+/// A validated 32-byte payment preimage, parsed from a 64-character hex string.
+#[derive(Debug, Clone)]
+pub struct Preimage(pub [u8; 32]);
+
+impl Preimage {
+	pub fn to_hex_string(&self) -> String {
+		self.0.to_lower_hex_string()
+	}
+}
+
+impl FromStr for Preimage {
+	type Err = String;
+
+	fn from_str(s: &str) -> Result<Self, Self::Err> {
+		<[u8; 32]>::from_hex(s)
+			.map(Preimage)
+			.map_err(|_| "must be a 64-character hex string (32 bytes)".to_string())
+	}
+}
+
 #[cfg(test)]
 mod tests {
 	use super::*;
@@ -185,4 +206,25 @@ mod tests {
 		let big = format!("{}sat", u64::MAX);
 		assert!(Amount::from_str(&big).is_err());
 	}
+
+	#[test]
+	fn preimage_parsing_and_roundtrip() {
+		// valid 64-char hex string
+		let hex = "2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b";
+		let preimage = Preimage::from_str(hex).unwrap();
+		assert_eq!(preimage.0, [0x2b; 32]);
+		assert_eq!(preimage.to_hex_string(), hex);
+
+		// rejects empty string
+		assert!(Preimage::from_str("").is_err());
+
+		// rejects too short (62 chars)
+		assert!(Preimage::from_str(&"ab".repeat(31)).is_err());
+
+		// rejects too long (66 chars)
+		assert!(Preimage::from_str(&"ab".repeat(33)).is_err());
+
+		// rejects non-hex characters
+		assert!(Preimage::from_str(&"zz".repeat(32)).is_err());
+	}
 }

ldk-server-grpc/src/api.rs

@@ -474,6 +474,10 @@ pub struct SpontaneousSendRequest {
 	/// Custom TLV records to attach to the outgoing payment.
 	#[prost(message, repeated, tag = "4")]
 	pub custom_tlvs: ::prost::alloc::vec::Vec<super::types::CustomTlvRecord>,
+	/// An optional hex-encoded 32-byte payment preimage. If provided, it will be used instead of
+	/// generating a random one. The payment hash will be the SHA256 of this value.
+	#[prost(string, optional, tag = "5")]
+	pub preimage: ::core::option::Option<::prost::alloc::string::String>,
 }
 /// The response for the `SpontaneousSend` RPC. On failure, a gRPC error status is returned.
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]

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

@@ -372,6 +372,10 @@ message SpontaneousSendRequest {
 
   // Custom TLV records to attach to the outgoing payment.
   repeated types.CustomTlvRecord custom_tlvs = 4;
+
+  // An optional hex-encoded 32-byte payment preimage. If provided, it will be used instead of
+  // generating a random one. The payment hash will be the SHA256 of this value.
+  optional string preimage = 5;
 }
 
 // The response for the `SpontaneousSend` RPC. On failure, a gRPC error status is returned.

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

@@ -374,7 +374,11 @@ pub fn spontaneous_send_schema() -> Value {
 				"type": "string",
 				"description": "The hex-encoded public key of the destination node"
 			},
-			"route_parameters": route_parameters_config_schema()
+			"route_parameters": route_parameters_config_schema(),
+			"preimage": {
+				"type": "string",
+				"description": "The hex-encoded 32-byte payment preimage"
+			}
 		},
 		"required": ["amount_msat", "node_id"]
 	})

ldk-server/src/api/spontaneous_send.rs

@@ -10,7 +10,10 @@
 use std::str::FromStr;
 use std::sync::Arc;
 
+use hex::FromHex;
 use ldk_node::bitcoin::secp256k1::PublicKey;
+use ldk_node::lightning_types::payment::PaymentPreimage;
+use ldk_node::CustomTlvRecord;
 use ldk_server_grpc::api::{SpontaneousSendRequest, SpontaneousSendResponse};
 
 use crate::api::error::LdkServerError;
@@ -27,19 +30,52 @@ pub(crate) async fn handle_spontaneous_send_request(
 
 	let route_parameters = build_route_parameters_config_from_proto(request.route_parameters)?;
 
-	let payment_id = if request.custom_tlvs.is_empty() {
-		context.node.spontaneous_payment().send(request.amount_msat, node_id, route_parameters)?
+	let preimage = request
+		.preimage
+		.map(|p| {
+			<[u8; 32]>::from_hex(&p).map(PaymentPreimage).map_err(|_| {
+				LdkServerError::new(
+					InvalidRequestError,
+					"Invalid preimage, must be a 32-byte hex string.".to_string(),
+				)
+			})
+		})
+		.transpose()?;
+
+	let custom_tlvs: Option<Vec<CustomTlvRecord>> = if request.custom_tlvs.is_empty() {
+		None
 	} else {
-		let custom_tlvs: Vec<_> =
-			request.custom_tlvs.iter().map(proto_to_node_custom_tlv).collect();
-		context.node.spontaneous_payment().send_with_custom_tlvs(
+		Some(request.custom_tlvs.iter().map(proto_to_node_custom_tlv).collect())
+	};
+
+	let payment_id = match (preimage, custom_tlvs) {
+		(None, None) => context.node.spontaneous_payment().send(
+			request.amount_msat,
+			node_id,
+			route_parameters,
+		)?,
+		(None, Some(custom_tlvs)) => context.node.spontaneous_payment().send_with_custom_tlvs(
 			request.amount_msat,
 			node_id,
 			route_parameters,
 			custom_tlvs,
-		)?
+		)?,
+		(Some(preimage), None) => context.node.spontaneous_payment().send_with_preimage(
+			request.amount_msat,
+			node_id,
+			preimage,
+			route_parameters,
+		)?,
+		(Some(preimage), Some(custom_tlvs)) => {
+			context.node.spontaneous_payment().send_with_preimage_and_custom_tlvs(
+				request.amount_msat,
+				node_id,
+				custom_tlvs,
+				preimage,
+				route_parameters,
+			)?
+		},
 	};
 
-	let response = SpontaneousSendResponse { payment_id: payment_id.to_string() };
-	Ok(response)
+	Ok(SpontaneousSendResponse { payment_id: payment_id.to_string() })
 }