feat: add ability to set payment preimage for spontaneous payments

Author: aagbotemi

bindings/ldk_node.udl

@@ -213,6 +213,10 @@ interface SpontaneousPayment {
 	[Throws=NodeError]
 	PaymentId send_with_custom_tlvs(u64 amount_msat, PublicKey node_id, SendingParameters? sending_parameters, sequence<CustomTlvRecord> custom_tlvs);
 	[Throws=NodeError]
+	PaymentId send_with_preimage(u64 amount_msat, PublicKey node_id, PaymentPreimage preimage, SendingParameters? sending_parameters);
+	[Throws=NodeError]
+	PaymentId send_with_preimage_and_custom_tlvs(u64 amount_msat, PublicKey node_id, sequence<CustomTlvRecord> custom_tlvs, PaymentPreimage preimage, SendingParameters? sending_parameters);
+	[Throws=NodeError]
 	void send_probes(u64 amount_msat, PublicKey node_id);
 };
 

src/payment/bolt11.rs

@@ -539,6 +539,7 @@ impl Bolt11Payment {
 		} else {
 			None
 		};
+
 		let kind = PaymentKind::Bolt11 {
 			hash: payment_hash,
 			preimage,

src/payment/spontaneous.rs

@@ -57,27 +57,45 @@ impl SpontaneousPayment {
 	pub fn send(
 		&self, amount_msat: u64, node_id: PublicKey, sending_parameters: Option<SendingParameters>,
 	) -> Result<PaymentId, Error> {
-		self.send_inner(amount_msat, node_id, sending_parameters, None)
+		self.send_inner(amount_msat, node_id, sending_parameters, None, None)
 	}
 
 	/// Send a spontaneous payment including a list of custom TLVs.
 	pub fn send_with_custom_tlvs(
 		&self, amount_msat: u64, node_id: PublicKey, sending_parameters: Option<SendingParameters>,
 		custom_tlvs: Vec<CustomTlvRecord>,
 	) -> Result<PaymentId, Error> {
-		self.send_inner(amount_msat, node_id, sending_parameters, Some(custom_tlvs))
+		self.send_inner(amount_msat, node_id, sending_parameters, Some(custom_tlvs), None)
+	}
+
+	/// Send a spontaneous payment with custom preimage
+	pub fn send_with_preimage(
+		&self, amount_msat: u64, node_id: PublicKey, preimage: PaymentPreimage,
+		sending_parameters: Option<SendingParameters>,
+	) -> Result<PaymentId, Error> {
+		self.send_inner(amount_msat, node_id, sending_parameters, None, Some(preimage))
+	}
+
+	/// Send a spontaneous payment with custom preimage including a list of custom TLVs.
+	pub fn send_with_preimage_and_custom_tlvs(
+		&self, amount_msat: u64, node_id: PublicKey, custom_tlvs: Vec<CustomTlvRecord>,
+		preimage: PaymentPreimage, sending_parameters: Option<SendingParameters>,
+	) -> Result<PaymentId, Error> {
+		self.send_inner(amount_msat, node_id, sending_parameters, Some(custom_tlvs), Some(preimage))
 	}
 
 	fn send_inner(
 		&self, amount_msat: u64, node_id: PublicKey, sending_parameters: Option<SendingParameters>,
-		custom_tlvs: Option<Vec<CustomTlvRecord>>,
+		custom_tlvs: Option<Vec<CustomTlvRecord>>, preimage: Option<PaymentPreimage>,
 	) -> Result<PaymentId, Error> {
 		let rt_lock = self.runtime.read().unwrap();
 		if rt_lock.is_none() {
 			return Err(Error::NotRunning);
 		}
 
-		let payment_preimage = PaymentPreimage(self.keys_manager.get_secure_random_bytes());
+		let payment_preimage = preimage
+			.unwrap_or_else(|| PaymentPreimage(self.keys_manager.get_secure_random_bytes()));
+
 		let payment_hash = PaymentHash::from(payment_preimage);
 		let payment_id = PaymentId(payment_hash.0);
 

src/payment/store.rs

@@ -221,40 +221,40 @@ impl StorableObject for PaymentDetails {
 				},
 			}
 		}
-		if let Some(preimage_opt) = update.preimage {
+		if let Some(preimage_opt) = &update.preimage {
 			match self.kind {
 				PaymentKind::Bolt11 { ref mut preimage, .. } => {
-					update_if_necessary!(*preimage, preimage_opt)
+					update_if_necessary!(*preimage, preimage_opt.clone())
 				},
 				PaymentKind::Bolt11Jit { ref mut preimage, .. } => {
-					update_if_necessary!(*preimage, preimage_opt)
+					update_if_necessary!(*preimage, preimage_opt.clone())
 				},
 				PaymentKind::Bolt12Offer { ref mut preimage, .. } => {
-					update_if_necessary!(*preimage, preimage_opt)
+					update_if_necessary!(*preimage, preimage_opt.clone())
 				},
 				PaymentKind::Bolt12Refund { ref mut preimage, .. } => {
-					update_if_necessary!(*preimage, preimage_opt)
+					update_if_necessary!(*preimage, preimage_opt.clone())
 				},
 				PaymentKind::Spontaneous { ref mut preimage, .. } => {
-					update_if_necessary!(*preimage, preimage_opt)
+					update_if_necessary!(*preimage, preimage_opt.clone())
 				},
 				_ => {},
 			}
 		}
 
-		if let Some(secret_opt) = update.secret {
+		if let Some(secret_opt) = &update.secret {
 			match self.kind {
 				PaymentKind::Bolt11 { ref mut secret, .. } => {
-					update_if_necessary!(*secret, secret_opt)
+					update_if_necessary!(*secret, *secret_opt)
 				},
 				PaymentKind::Bolt11Jit { ref mut secret, .. } => {
-					update_if_necessary!(*secret, secret_opt)
+					update_if_necessary!(*secret, *secret_opt)
 				},
 				PaymentKind::Bolt12Offer { ref mut secret, .. } => {
-					update_if_necessary!(*secret, secret_opt)
+					update_if_necessary!(*secret, *secret_opt)
 				},
 				PaymentKind::Bolt12Refund { ref mut secret, .. } => {
-					update_if_necessary!(*secret, secret_opt)
+					update_if_necessary!(*secret, *secret_opt)
 				},
 				_ => {},
 			}
@@ -563,13 +563,17 @@ impl PaymentDetailsUpdate {
 
 impl From<&PaymentDetails> for PaymentDetailsUpdate {
 	fn from(value: &PaymentDetails) -> Self {
-		let (hash, preimage, secret) = match value.kind {
+		let (hash, preimage, secret) = match &value.kind {
 			PaymentKind::Bolt11 { hash, preimage, secret, .. } => (Some(hash), preimage, secret),
 			PaymentKind::Bolt11Jit { hash, preimage, secret, .. } => (Some(hash), preimage, secret),
-			PaymentKind::Bolt12Offer { hash, preimage, secret, .. } => (hash, preimage, secret),
-			PaymentKind::Bolt12Refund { hash, preimage, secret, .. } => (hash, preimage, secret),
-			PaymentKind::Spontaneous { hash, preimage, .. } => (Some(hash), preimage, None),
-			_ => (None, None, None),
+			PaymentKind::Bolt12Offer { hash, preimage, secret, .. } => {
+				(hash.as_ref(), preimage, secret)
+			},
+			PaymentKind::Bolt12Refund { hash, preimage, secret, .. } => {
+				(hash.as_ref(), preimage, secret)
+			},
+			PaymentKind::Spontaneous { hash, preimage, .. } => (Some(hash), preimage, &None),
+			_ => (None, &None, &None),
 		};
 
 		let confirmation_status = match value.kind {
@@ -586,9 +590,9 @@ impl From<&PaymentDetails> for PaymentDetailsUpdate {
 
 		Self {
 			id: value.id,
-			hash: Some(hash),
-			preimage: Some(preimage),
-			secret: Some(secret),
+			hash: Some(hash.copied()),
+			preimage: Some(preimage.clone()),
+			secret: Some(*secret),
 			amount_msat: Some(value.amount_msat),
 			fee_paid_msat: Some(value.fee_paid_msat),
 			counterparty_skimmed_fee_msat,

tests/common/mod.rs

@@ -802,7 +802,7 @@ pub(crate) fn do_channel_full_cycle<E: ElectrumApi>(
 	);
 	node_b
 		.bolt11_payment()
-		.claim_for_hash(manual_payment_hash, claimable_amount_msat, manual_preimage)
+		.claim_for_hash(manual_payment_hash, claimable_amount_msat, manual_preimage.into())
 		.unwrap();
 	expect_payment_received_event!(node_b, claimable_amount_msat);
 	expect_payment_successful_event!(node_a, Some(manual_payment_id), None);

tests/integration_tests_rust.rs

@@ -19,8 +19,8 @@ use common::{
 use ldk_node::config::EsploraSyncConfig;
 use ldk_node::liquidity::LSPS2ServiceConfig;
 use ldk_node::payment::{
-	ConfirmationStatus, PaymentDirection, PaymentKind, PaymentStatus, QrPaymentResult,
-	SendingParameters,
+	ConfirmationStatus, PaymentDetails, PaymentDirection, PaymentKind, PaymentStatus,
+	QrPaymentResult, SendingParameters,
 };
 use ldk_node::{Builder, Event, NodeError};
 
@@ -29,8 +29,10 @@ use lightning::routing::gossip::{NodeAlias, NodeId};
 use lightning::util::persist::KVStore;
 
 use lightning_invoice::{Bolt11InvoiceDescription, Description};
+use lightning_types::payment::PaymentPreimage;
 
 use bitcoin::address::NetworkUnchecked;
+use bitcoin::hashes::sha256::Hash as Sha256Hash;
 use bitcoin::hashes::Hash;
 use bitcoin::Address;
 use bitcoin::Amount;
@@ -817,7 +819,7 @@ fn simple_bolt12_send_receive() {
 	let node_a_payments =
 		node_a.list_payments_with_filter(|p| matches!(p.kind, PaymentKind::Bolt12Offer { .. }));
 	assert_eq!(node_a_payments.len(), 1);
-	match node_a_payments.first().unwrap().kind {
+	match &node_a_payments.first().unwrap().kind {
 		PaymentKind::Bolt12Offer {
 			hash,
 			preimage,
@@ -828,7 +830,7 @@ fn simple_bolt12_send_receive() {
 		} => {
 			assert!(hash.is_some());
 			assert!(preimage.is_some());
-			assert_eq!(offer_id, offer.id());
+			assert_eq!(offer_id, &offer.id());
 			assert_eq!(&expected_quantity, qty);
 			assert_eq!(expected_payer_note.unwrap(), note.clone().unwrap().0);
 			//TODO: We should eventually set and assert the secret sender-side, too, but the BOLT12
@@ -844,12 +846,12 @@ fn simple_bolt12_send_receive() {
 	let node_b_payments =
 		node_b.list_payments_with_filter(|p| matches!(p.kind, PaymentKind::Bolt12Offer { .. }));
 	assert_eq!(node_b_payments.len(), 1);
-	match node_b_payments.first().unwrap().kind {
+	match &node_b_payments.first().unwrap().kind {
 		PaymentKind::Bolt12Offer { hash, preimage, secret, offer_id, .. } => {
 			assert!(hash.is_some());
 			assert!(preimage.is_some());
 			assert!(secret.is_some());
-			assert_eq!(offer_id, offer.id());
+			assert_eq!(offer_id, &offer.id());
 		},
 		_ => {
 			panic!("Unexpected payment kind");
@@ -883,7 +885,7 @@ fn simple_bolt12_send_receive() {
 		matches!(p.kind, PaymentKind::Bolt12Offer { .. }) && p.id == payment_id
 	});
 	assert_eq!(node_a_payments.len(), 1);
-	let payment_hash = match node_a_payments.first().unwrap().kind {
+	let payment_hash = match &node_a_payments.first().unwrap().kind {
 		PaymentKind::Bolt12Offer {
 			hash,
 			preimage,
@@ -894,7 +896,7 @@ fn simple_bolt12_send_receive() {
 		} => {
 			assert!(hash.is_some());
 			assert!(preimage.is_some());
-			assert_eq!(offer_id, offer.id());
+			assert_eq!(offer_id, &offer.id());
 			assert_eq!(&expected_quantity, qty);
 			assert_eq!(expected_payer_note.unwrap(), note.clone().unwrap().0);
 			//TODO: We should eventually set and assert the secret sender-side, too, but the BOLT12
@@ -913,12 +915,12 @@ fn simple_bolt12_send_receive() {
 		matches!(p.kind, PaymentKind::Bolt12Offer { .. }) && p.id == node_b_payment_id
 	});
 	assert_eq!(node_b_payments.len(), 1);
-	match node_b_payments.first().unwrap().kind {
+	match &node_b_payments.first().unwrap().kind {
 		PaymentKind::Bolt12Offer { hash, preimage, secret, offer_id, .. } => {
 			assert!(hash.is_some());
 			assert!(preimage.is_some());
 			assert!(secret.is_some());
-			assert_eq!(offer_id, offer.id());
+			assert_eq!(offer_id, &offer.id());
 		},
 		_ => {
 			panic!("Unexpected payment kind");
@@ -951,7 +953,7 @@ fn simple_bolt12_send_receive() {
 		matches!(p.kind, PaymentKind::Bolt12Refund { .. }) && p.id == node_b_payment_id
 	});
 	assert_eq!(node_b_payments.len(), 1);
-	match node_b_payments.first().unwrap().kind {
+	match &node_b_payments.first().unwrap().kind {
 		PaymentKind::Bolt12Refund {
 			hash,
 			preimage,
@@ -977,7 +979,7 @@ fn simple_bolt12_send_receive() {
 		matches!(p.kind, PaymentKind::Bolt12Refund { .. }) && p.id == node_a_payment_id
 	});
 	assert_eq!(node_a_payments.len(), 1);
-	match node_a_payments.first().unwrap().kind {
+	match &node_a_payments.first().unwrap().kind {
 		PaymentKind::Bolt12Refund { hash, preimage, secret, .. } => {
 			assert!(hash.is_some());
 			assert!(preimage.is_some());
@@ -1389,3 +1391,69 @@ fn facade_logging() {
 		validate_log_entry(entry);
 	}
 }
+
+#[test]
+fn spontaneous_send_with_custom_preimage() {
+	let (bitcoind, electrsd) = setup_bitcoind_and_electrsd();
+	let chain_source = TestChainSource::Esplora(&electrsd);
+	let (node_a, node_b) = setup_two_nodes(&chain_source, false, true, false);
+
+	let address_a = node_a.onchain_payment().new_address().unwrap();
+	let premine_sat = 1_000_000;
+	premine_and_distribute_funds(
+		&bitcoind.client,
+		&electrsd.client,
+		vec![address_a],
+		Amount::from_sat(premine_sat),
+	);
+	node_a.sync_wallets().unwrap();
+	node_b.sync_wallets().unwrap();
+	open_channel(&node_a, &node_b, 500_000, true, &electrsd);
+	generate_blocks_and_wait(&bitcoind.client, &electrsd.client, 6);
+	node_a.sync_wallets().unwrap();
+	node_b.sync_wallets().unwrap();
+	expect_channel_ready_event!(node_a, node_b.node_id());
+	expect_channel_ready_event!(node_b, node_a.node_id());
+
+	let seed = b"test_payment_preimage";
+	let bytes: Sha256Hash = Sha256Hash::hash(seed);
+	let custom_bytes = bytes.to_byte_array();
+	let custom_preimage = PaymentPreimage(custom_bytes);
+
+	let amount_msat = 100_000;
+	let payment_id = node_a
+		.spontaneous_payment()
+		.send_with_preimage(amount_msat, node_b.node_id(), custom_preimage.clone().into(), None)
+		.unwrap();
+
+	// check payment status and verify stored preimage
+	expect_payment_successful_event!(node_a, Some(payment_id), None);
+	let details: PaymentDetails =
+		node_a.list_payments_with_filter(|p| p.id == payment_id).first().unwrap().clone();
+	assert_eq!(details.status, PaymentStatus::Succeeded);
+	if let PaymentKind::Spontaneous { preimage: Some(pi), .. } = details.kind {
+		assert_eq!(pi, custom_preimage.into());
+	} else {
+		panic!("Expected a spontaneous PaymentKind with a preimage");
+	}
+
+	// Verify receiver side (node_b)
+	expect_payment_received_event!(node_b, amount_msat);
+	let receiver_payments: Vec<PaymentDetails> = node_b.list_payments_with_filter(|p| {
+		p.direction == PaymentDirection::Inbound
+			&& matches!(p.kind, PaymentKind::Spontaneous { .. })
+	});
+
+	assert_eq!(receiver_payments.len(), 1);
+	let receiver_details = &receiver_payments[0];
+	assert_eq!(receiver_details.status, PaymentStatus::Succeeded);
+	assert_eq!(receiver_details.amount_msat, Some(amount_msat));
+	assert_eq!(receiver_details.direction, PaymentDirection::Inbound);
+
+	// Verify receiver also has the same preimage
+	if let PaymentKind::Spontaneous { preimage: Some(pi), .. } = &receiver_details.kind {
+		assert_eq!(pi, &custom_preimage.into());
+	} else {
+		panic!("Expected receiver to have spontaneous PaymentKind with preimage");
+	}
+}