Static invoice server #621

joostjager · 2025-08-19T14:12:48Z

Wires up async payments functionality in ldk-node. This PR only covers the static invoice creation part. In a follow up, the full mechanism will be put in place to hold an htlc sender-side until the receiver comes online again.

ldk-reviews-bot · 2025-08-19T14:12:51Z

👋 Thanks for assigning @tnull as a reviewer!
I'll wait for their review and will help manage the review process.
Once they submit their review, I'll check if a second reviewer would be helpful.

tnull

I realize this is in draft for good reason, just leaving some early comments here.

src/config.rs

src/builder.rs

src/lib.rs

joostjager · 2025-08-28T11:33:11Z

src/rate_limiter.rs

+	min_interval: Duration,
+}
+
+impl RateLimiter {


Keeping it simple here

joostjager · 2025-08-28T11:34:07Z

src/static_invoice_store.rs

+
+pub(crate) struct StaticInvoiceStore {
+	kv_store: Arc<DynStore>,
+	rate_limiter: Mutex<RateLimiter>,


Needed to add Mutex here even though I don't think it is used concurrently. Otherwise handle_event needed to be made mutable, the Arc higher up no longer working, etc.

joostjager · 2025-08-28T11:45:07Z

src/static_invoice_store.rs

+		}
+	}
+
+	pub(crate) async fn handle_static_invoice_requested(


Async, prepare for async kv store.

joostjager · 2025-09-05T10:15:02Z

Added bindings

src/error.rs

joostjager · 2025-09-05T12:37:23Z

Made rate limiter a bit less simplistic by adding a leaky bucket. Otherwise the second call of two consecutive calls immediately fails.

ldk-reviews-bot · 2025-09-06T12:02:16Z

🔔 1st Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

tnull

Took a first look, have yet to review the rate limiter logic and tests closer.

src/error.rs

src/lib.rs

tnull · 2025-09-08T08:21:22Z

src/lib.rs

+	/// [`StaticInvoice`]: lightning::offers::static_invoice::StaticInvoice
+	pub fn blinded_paths_for_async_recipient(
+		&self, recipient_id: Vec<u8>,
+	) -> Result<Vec<u8>, Error> {


In the Rust API, we def. still want to return the actual BlindedMessagePaths, just for the uniffi interface it's okay to fallback to a bytes for now.

Why would it be required to know the details of the blinded paths for the Rust API and not for the other APIs? Not sure which use that unlocks.

Why would it be required to know the details of the blinded paths for the Rust API and not for the other APIs? Not sure which use that unlocks.

Users might want to expect what they're paying to. It's fine to take a shortcut here for bindings, but please use the full Rust type in the Rust API.

This is not about what they are paying to. It's the path that the receiver can use to contact the static invoice server. Because it is blinded, they still don't know where that server is potentially?

We try to use the proper Rust types where possible, and I really don't see why we shouldn't in this case. In case of set_paths_to_static_invoice_server users could theoretically handcraft a blinded path somehow if their service implementation doesn't exactly meet our serialization and try to use it. Here we'd just match that API type.

I think consistency between languages is more important. Especially if the handcrafted blinded path is speculative. But no blocker, I've updated the code with distinct method signatures.

bindings/ldk_node.udl

src/static_invoice_store.rs

joostjager · 2025-09-08T14:02:12Z

Unit tests added for static invoice store and rate limiter.

joostjager · 2025-09-08T14:14:52Z

Added async services config flag

tnull

Mostly looks good, some comments/questions.

src/event.rs

tnull · 2025-09-11T07:50:40Z

src/event.rs

+					{
+						Ok(_) => {},
+						Err(e) => {
+							log_error!(self.logger, "Failed to persist static invoice: {}", e);


I think we need to return Err(ReplayEvent()) here and below in case of persistence failure to be able to retry?

Good point. Also static_invoice_persisted shouldn't be called in that case. Fixed here and below.

tnull · 2025-09-11T07:51:35Z

src/io/mod.rs

+
+// Static invoices will be persisted at "static_invoices/<sha256(recipient_id)>/<invoice_slot>".
+//
+// Example: static_invoices/039058c6f2c0cb492c533b0a4d14ef77cc0f78abccced5287d84a1a2011cfb81/001f


This is out-of-date now that we don't serialize invoice_slot as hex?

Also, let's move this example to the static invoice store, as this is just the primary namespace const. We should however cross-link to the the respective LDK docs here so that readers know what 'static invoices' are in the first place.

Decimal invoice slot, example moved, LDK link added.

tnull · 2025-09-11T07:51:59Z

src/io/mod.rs

+// Static invoices will be persisted at "static_invoices/<sha256(recipient_id)>/<invoice_slot>".
+//
+// Example: static_invoices/039058c6f2c0cb492c533b0a4d14ef77cc0f78abccced5287d84a1a2011cfb81/001f
+pub(crate) const STATIC_INVOICES_PRIMARY_NAMESPACE: &str = "static_invoices";


Suggested change

pub(crate) const STATIC_INVOICES_PRIMARY_NAMESPACE: &str = "static_invoices";

pub(crate) const STATIC_INVOICE_STORE_PRIMARY_NAMESPACE: &str = "static_invoices";

Not sure if I like this better. It's not the store that is stored, but the invoices. I don't really mind either. Changed.

tnull · 2025-09-11T07:54:25Z

src/payment/asynchronous/mod.rs

This and the other new files need a module description and a copyright header.

src/payment/asynchronous/static_invoice_store.rs

tnull · 2025-09-11T08:16:21Z

src/payment/asynchronous/static_invoice_store.rs

+mod tests {
+	use std::{sync::Arc, time::Duration};
+
+	use bitcoin::{


nit: As mentioned elsewhere previously, module-level grouping of imports would be preferred.

I'm starting to wonder if we should go 'bleeding edge' here and introduce a nightly rustfmt CI job, which would indeed support dealing with the import groups for us:

group_imports = "StdExternalCrate" reorder_imports = true imports_granularity = "Module"

That would be great. FIxing import groups isn't something that humans should be required to do, especially because some people don't even care for them.

tnull · 2025-09-11T08:30:04Z

src/payment/bolt12.rs

 	pub(crate) fn new(
 		channel_manager: Arc<ChannelManager>, payment_store: Arc<PaymentStore>,
-		is_running: Arc<RwLock<bool>>, logger: Arc<Logger>,
+		async_payment_services_enabled: bool, is_running: Arc<RwLock<bool>>, logger: Arc<Logger>,


Hmm, let's just forward the full Config as we might need it for other things in the future, too?

I didn't want to add a dependency to the full object if a bool suffices. Also makes it more clear what part of config matters. Maybe we don't need things in the future. But no strong objection, so changed.

tnull · 2025-09-11T08:31:14Z

src/payment/bolt12.rs

+	/// Will only return an offer if [`Bolt12Payment::set_paths_to_static_invoice_server`] was called and we succeeded
+	/// in interactively building a [`StaticInvoice`] with the static invoice server.
+	///
+	/// Useful for posting offers to receive payments later, such as posting an offer on a website.


Mind adding an 'experimental feature' note here and on the other main APIs?

I can do that, but in what regard is it experimental? Added

tnull · 2025-09-11T08:34:41Z

src/payment/asynchronous/static_invoice_store.rs

+			)
+	}
+
+	pub(crate) async fn handle_persist_static_invoice(


Do we need to check whether we actually know/have a channel open with the recipient? Or is all that fully handled on the LDK side already?

Discussed offline. At this point, I think it is part of the integration of ldk-node into the wider system to ensure that blinded_paths_for_async_recipient isn't called without restrictions.

joostjager · 2025-09-11T10:07:04Z

Squashed previous fixups and added new fix up that addresses review comments.

ldk-reviews-bot · 2025-09-13T10:08:22Z

🔔 1st Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

ldk-reviews-bot · 2025-09-15T10:09:02Z

🔔 2nd Reminder

Hey @tnull! This PR has been waiting for your review.
Please take a look when you have a chance. If you're unable to review, please let us know so we can find another reviewer.

tnull

Looks good to me, feel free to squash!

tnull · 2025-09-16T05:24:54Z

src/event.rs

+								log_error!(self.logger, "Failed to send static invoice: {:?}", e);
+							}
+						},
+						Ok(None) => {},


Should we log here, or do we think this would be very spammy? Also, does this point to a gap in the protocol that we don't seem to have a way to communicate to the client that a lookup failed?

I think there's already more per-onion message trace logging, so spamming the logs is possible already. I've added a trace statement. At this stage it may be helpful in debugging production issues.

You could consider the lack of a failure onion message a gap in the protocol. Onion messages are problematic anyway because they may be dropped without notice.

A similar gap exists for the held_htlc_available message. The sender won't get an ack indicating whether that message was processed. If that one gets dropped, the sender lsp will hold the htlc waiting for a release that will never come.

tnull

LGTM, mind adding a bit more verbose commit message/title, then happy to land this!

This commit adds support for using ldk-node as a static invoice server. When configured as such, the node persists and retrieves invoices from the configured kv store. Access is guarded by a rate limiter to prevent overload and mitigate potential DoS attacks. In this mode, ldk-node also exposes blinded paths that can be shared with async recipients, allowing them to contact the static invoice server. When ldk-node functions as a recipient, it can communicate with the static invoice server to set up async payments.

joostjager · 2025-09-16T06:56:27Z

Commit msg/title added

tnull reviewed Aug 20, 2025

View reviewed changes

src/config.rs Outdated Show resolved Hide resolved

src/builder.rs Outdated Show resolved Hide resolved

src/lib.rs Outdated Show resolved Hide resolved

joostjager self-assigned this Aug 21, 2025

joostjager added this to Weekly Goals Aug 21, 2025

joostjager force-pushed the static-invoice-server branch 2 times, most recently from 4bcdc95 to e2f293b Compare August 27, 2025 14:50

joostjager commented Aug 28, 2025

View reviewed changes

src/rate_limiter.rs Outdated

min_interval: Duration,

}

impl RateLimiter {

Copy link

Contributor Author

joostjager Aug 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Keeping it simple here

joostjager commented Aug 28, 2025

View reviewed changes

joostjager force-pushed the static-invoice-server branch 6 times, most recently from 0c92e33 to 5c43a3b Compare September 3, 2025 12:54

joostjager requested a review from tnull September 4, 2025 12:01

joostjager marked this pull request as ready for review September 4, 2025 12:04

joostjager force-pushed the static-invoice-server branch from 5c43a3b to 472cf60 Compare September 5, 2025 10:14

joostjager commented Sep 5, 2025

View reviewed changes

src/error.rs Outdated Show resolved Hide resolved

joostjager force-pushed the static-invoice-server branch from 472cf60 to 16ad843 Compare September 5, 2025 12:36

tnull reviewed Sep 8, 2025

View reviewed changes

joostjager force-pushed the static-invoice-server branch 2 times, most recently from 04a3c30 to 514676c Compare September 8, 2025 13:37

joostjager force-pushed the static-invoice-server branch from b1ca4e2 to 5b489c2 Compare September 9, 2025 09:09

joostjager requested a review from tnull September 9, 2025 09:54

joostjager force-pushed the static-invoice-server branch 5 times, most recently from 278669e to 4225a5f Compare September 10, 2025 09:00

joostjager changed the base branch from main to develop September 10, 2025 09:00

joostjager mentioned this pull request Sep 10, 2025

Add onion mailbox for async recipients #632

Merged

tnull reviewed Sep 11, 2025

View reviewed changes

joostjager force-pushed the static-invoice-server branch from 4225a5f to e76d6d7 Compare September 11, 2025 10:05

joostjager requested a review from tnull September 11, 2025 10:07

joostjager force-pushed the static-invoice-server branch from e76d6d7 to 8ad197f Compare September 11, 2025 10:59

valentinewallace mentioned this pull request Sep 12, 2025

Async Payments lightningdevkit/rust-lightning#2298

Closed

45 tasks

tnull reviewed Sep 16, 2025

View reviewed changes

joostjager force-pushed the static-invoice-server branch from 8ad197f to f471f11 Compare September 16, 2025 06:43

joostjager requested a review from tnull September 16, 2025 06:46

tnull reviewed Sep 16, 2025

View reviewed changes

joostjager force-pushed the static-invoice-server branch from f471f11 to 66f5c28 Compare September 16, 2025 06:56

joostjager requested a review from tnull September 16, 2025 06:59

tnull approved these changes Sep 16, 2025

View reviewed changes

tnull merged commit 8f0e4fd into lightningdevkit:develop Sep 16, 2025
11 of 15 checks passed

github-project-automation bot moved this to Done in Weekly Goals Sep 16, 2025

	pub(crate) const STATIC_INVOICES_PRIMARY_NAMESPACE: &str = "static_invoices";
	pub(crate) const STATIC_INVOICE_STORE_PRIMARY_NAMESPACE: &str = "static_invoices";

Static invoice server #621

Static invoice server #621

Uh oh!

Conversation

joostjager commented Aug 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

tnull left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

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!

joostjager commented Sep 5, 2025

Uh oh!

Uh oh!

joostjager commented Sep 5, 2025

Uh oh!

ldk-reviews-bot commented Sep 6, 2025

Uh oh!

tnull left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

joostjager commented Sep 8, 2025

Uh oh!

joostjager commented Sep 8, 2025

Uh oh!

tnull left a comment

Choose a reason for hiding this comment

Uh oh!

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!

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!

Uh oh!

joostjager commented Aug 19, 2025 •

edited

Loading

ldk-reviews-bot commented Aug 19, 2025 •

edited

Loading

joostjager Sep 11, 2025 •

edited

Loading

joostjager Sep 11, 2025 •

edited

Loading

joostjager Sep 16, 2025 •

edited

Loading