Support passing preimage for spontaneous payments #549

aagbotemi · 2025-05-31T12:00:12Z

This PR adds support for specifying custom preimages when sending spontaneous (keysend) payments.

Solution

Added send_with_preimage() method
Added send_with_preimage_and_custom_tlvs() method for advanced use cases
Modified internal send_inner() to accept optional preimage parameter and generate random preimage only when custom preimage is not provided.

An integration test is added to verify logic, and the new methods are added to the bindings.

Fixes #535

ldk-reviews-bot · 2025-05-31T12:00:15Z

👋 I see @TheBlueMatt was un-assigned.
If you'd like another reviewer assignemnt, please click here.

chuksys

Just shared a few thoughts regarding the overall design of this API and its extensibility.

chuksys · 2025-06-01T08:43:14Z

src/payment/spontaneous.rs

+	/// Send a spontaneous with custom preimage
+	pub fn send_with_preimage(
+		&self, amount_msat: u64, node_id: PublicKey, sending_parameters: Option<SendingParameters>,
+		preimage: PaymentPreimage,


I'm wondering if we should expand the purpose of SendingParameters a bit to allow passing of any custom parameters required for sending payments (not just routing and pathfinding parameters).

This approach would allow us to include preimage as an Option within SendingParameters, providing a single, coherent place for all payment-sending customizations.

A significant benefit of this change would be the ability to deprecate or drop specialized functions like send_with_preimage and send_with_custom_tlvs (in another PR), reducing overall boilerplate for users.

What do you think about this?

I initially hesitated about mixing routing parameters with payment content. Your point about expanding SendingParameters to handle all payment customization makes sense for the long-term API design, and the benefit outweigh the conceptual mixing.

I'll refactor to move preimage into SendingParameters as an Option. I can drop the send_with_preimage and send_with_preimage_and_custom_tlvs, then send_with_custom_tlvs can be dropped in another PR.

Thank you.

I'm wondering if we should expand the purpose of SendingParameters a bit to allow passing of any custom parameters required for sending payments (not just routing and pathfinding parameters).

Ah, no, I don't think we should do that. Note that after LDK 0.2 release (cf. #462) we'll replace SendingParameters with LDK's RouteParametersConfig everywhere, so really shouldn't make any changes prior to it. Also, while we might be fine to expose the preimage for keysend payments, I don't think we'd like to allow users to override it for BOLT11/BOLT12 generally.

I'll refactor to move preimage into SendingParameters as an Option.

Please revert this. I think we can either have separate send APIs as you previously suggested, or add the preimage as an optional field to the existing ones. Will take a look after the revert, but your previous approach might be fine.

Ah, no, I don't think we should do that. Note that after LDK 0.2 release (cf. #462) we'll replace SendingParameters with LDK's RouteParametersConfig everywhere, so really shouldn't make any changes prior to it. Also, while we might be fine to expose the preimage for keysend payments, I don't think we'd like to allow users to override it for BOLT11/BOLT12 generally.

Thanks for the clarification!

chuksys · 2025-06-01T15:39:47Z

src/payment/spontaneous.rs

+		self.send_inner(amount_msat, node_id, sending_parameters, Some(custom_tlvs), None)
+	}
+
+	/// Send a spontaneous with custom preimage


I think you missed the word "payment" here (after spontaneous) - that's if we'd still be adding this method.

Yeah, I missed that. Thank you. I am removing the method.

chuksys

If we are going to use sending_parameters to pass in the custom preimage, I think we should allow the user to set it in config or pass it directly.

chuksys · 2025-06-02T07:09:13Z

src/payment/spontaneous.rs

@@ -77,7 +77,10 @@ impl SpontaneousPayment {
 			return Err(Error::NotRunning);
 		}

-		let payment_preimage = PaymentPreimage(self.keys_manager.get_secure_random_bytes());
+		let payment_preimage = sending_parameters


If we are doing this, I think we'll need to use override_params instead as that allows send_inner to select sending_parameters set in the config (if not passed into the send method directly).

No, I don't think we should do this, see above.

tnull

As mentioned above I don't think adding this field to SendingParameters is the way to go here (note it would also allowing setting global default preimage if users would override the field in Config, which is actually dangerous as preimages can never be reused). Please revert to you previous draft, will review then.

tnull · 2025-06-02T11:15:53Z

src/payment/spontaneous.rs

@@ -77,7 +77,10 @@ impl SpontaneousPayment {
 			return Err(Error::NotRunning);
 		}

-		let payment_preimage = PaymentPreimage(self.keys_manager.get_secure_random_bytes());
+		let payment_preimage = sending_parameters


No, I don't think we should do this, see above.

aagbotemi · 2025-06-02T12:21:07Z

Please revert to you previous draft, will review then.

Alright. Will do that. Thank you.

aagbotemi · 2025-06-02T13:30:41Z

Please revert to you previous draft, will review then.

Hello @tnull, I have reverted to the previous draft. This is ready.

Camillarhi · 2025-06-02T18:43:48Z

Nice work on this PR! The custom preimage functionality is implemented cleanly, and the test coverage looks good.

One small enhancement suggestion: we could add verification that node_b received the payment to complete end-to-end verification of the payment flow.

aagbotemi · 2025-06-03T09:09:53Z

One small enhancement suggestion: we could add verification that node_b received the payment to complete end-to-end verification of the payment flow.

Thanks for the suggestion! I've added the end-to-end verification as requested. It also ensure the custom preimage flows correctly through the entire payment process from sender to receiver.

tnull

Basically LGTM, but now that we actually take a PaymentPreimage from user input we should probably avoid the UniffiCustomTypeConverter for it, and rather expose a 'proper' newtype wrapper for the bindings. See #542 for inspiration on this, for example.

tnull · 2025-06-03T10:19:56Z

bindings/ldk_node.udl

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


nit: Let's move these new entries to the correct location w.r.t. API, i.e. below send_with_custom_tlvs.

tnull · 2025-06-03T10:21:10Z

src/payment/spontaneous.rs

+	/// Send a spontaneous payment with custom preimage
+	pub fn send_with_preimage(
+		&self, amount_msat: u64, node_id: PublicKey, sending_parameters: Option<SendingParameters>,
+		preimage: PaymentPreimage,


If we add this as a new required parameter, let's move it before the optional parameters, i.e., Option<SendingParameters> (here and below).

Alright, will fix it. Thank you.

aagbotemi · 2025-06-04T09:02:13Z

Basically LGTM, but now that we actually take a PaymentPreimage from user input we should probably avoid the UniffiCustomTypeConverter for it, and rather expose a 'proper' newtype wrapper for the bindings. See #542 for inspiration on this, for example.

Thank you for the feedback, I will fix it

aagbotemi added 3 commits May 31, 2025 12:42

support for passing preimage for spontaneous payment

412cff4

integration test for passing preimage for spontaneous payment

781fea7

bindings for passing preimage for spontaneous payment

15fc6b2

ldk-reviews-bot requested a review from TheBlueMatt May 31, 2025 12:10

chuksys reviewed Jun 1, 2025

View reviewed changes

refactor: move preimage from method parameter to SendingParameters

8cbb6d5

chuksys reviewed Jun 2, 2025

View reviewed changes

tnull removed the request for review from TheBlueMatt June 2, 2025 11:15

tnull reviewed Jun 2, 2025

View reviewed changes

revert to parameter-based approach

143ec7c

verify node_b recieved payment for end-to-end verification

12318c0

tnull reviewed Jun 3, 2025

View reviewed changes

Support passing preimage for spontaneous payments #549

Are you sure you want to change the base?

Support passing preimage for spontaneous payments #549

Uh oh!

Conversation

aagbotemi commented May 31, 2025

Solution

Uh oh!

ldk-reviews-bot commented May 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chuksys left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aagbotemi Jun 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chuksys left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tnull left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aagbotemi commented Jun 2, 2025

Uh oh!

aagbotemi commented Jun 2, 2025

Uh oh!

Camillarhi commented Jun 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

aagbotemi commented Jun 3, 2025

Uh oh!

tnull left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aagbotemi commented Jun 4, 2025

Uh oh!

Uh oh!

ldk-reviews-bot commented May 31, 2025 •

edited

Loading

aagbotemi Jun 1, 2025 •

edited

Loading

Camillarhi commented Jun 2, 2025 •

edited

Loading