`lightning-liquidity`: Pre-/Refactors to prepare for persistence by tnull · Pull Request #4008 · lightningdevkit/rust-lightning

tnull · 2025-08-13T09:04:35Z

Before we can introduce persistence to the lightning-liquidity crate, we make a number of pre-/refactors to make our lives easier. We split this out here to keep PR sizes manageable and to introducing too many conflicts with concurrent work.

In this PR, we move some LSPS2/LSPS5 state data to dedicated types, which will allow use to use our serialization macros in the next step. We also simplify the last_notification_sent tracking in LSPS5 (now only tracking a single timestamp for all notification methods), which was requested on a previous PR. We furthermore now reset the notification cooldown on peer disconnection (useful in case we somehow notified last while the peer was connected), and move to prune the LSPS5 service state only on peer_{dis}connected, which should be more than enough.

(cc @martinsaposnic)

.. which streamlines the `PaymentQueue` API a bit, but most importantly can more easily get persisted using macros in the next step.

ldk-reviews-bot · 2025-08-13T09:04:38Z

👋 Thanks for assigning @martinsaposnic 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.

codecov · 2025-08-13T09:14:52Z

Codecov Report

❌ Patch coverage is 97.57576% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.86%. Comparing base (3b16c77) to head (f95ba69).
⚠️ Report is 21 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning-liquidity/src/lsps5/service.rs	97.52%	3 Missing ⚠️
lightning-liquidity/src/manager.rs	66.66%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #4008 +/- ##
=======================================
Coverage 88.85% 88.86% =======================================
Files 175 175 Lines 127682 127758 +76 Branches 127682 127758 +76 =======================================
+ Hits 113449 113527 +78 + Misses 11675 11669 -6 - Partials 2558 2562 +4

Flag	Coverage Δ
fuzzing	`21.75% <0.00%> (-0.11%)`	⬇️
tests	`88.69% <97.57%> (+<0.01%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

martinsaposnic · 2025-08-13T14:41:29Z

+	}
+
+	// Returns whether the entire state is empty and can be pruned.
+	fn prune_stale_webhooks(&mut self, now: LSPSDateTime) -> bool {


this function name is kind of confusing, it sounds like an action but it's not

this function name is kind of confusing, it sounds like an action but it's not
It is an action though, as it drops stale webhooks?

martinsaposnic · 2025-08-13T15:01:16Z

+ if let Some(webhook) = peer_state_lock.webhook_mut(&params.app_name.clone()) {
+ no_change = webhook.url == params.webhook;
+ if !no_change {
+ webhook.last_used = now


in here you need to set the webhook.url to params.webhook. if not, the update webhook functionality will be broken.
unfortunately, right now the tests are not testing the webhook update feature. they only test that the notification is sent with the updated url, but they don't test that the url is actually updated and persisted :(
here is a regression test that passes on main but fails on this branch
#[test]fnwebhook_update_affects_future_notifications(){let mock_time_provider = Arc::new(MockTimeProvider::new(1000));let time_provider = Arc::<MockTimeProvider>::clone(&mock_time_provider);let chanmon_cfgs = create_chanmon_cfgs(2);let node_cfgs = create_node_cfgs(2,&chanmon_cfgs);let node_chanmgrs = create_node_chanmgrs(2,&node_cfgs,&[None,None]);let nodes = create_network(2,&node_cfgs,&node_chanmgrs);let(lsps_nodes, _) = lsps5_test_setup(nodes, time_provider);letLSPSNodes{ service_node, client_node } = lsps_nodes;let service_node_id = service_node.inner.node.get_our_node_id();let client_node_id = client_node.inner.node.get_our_node_id();let client_handler = client_node.liquidity_manager.lsps5_client_handler().unwrap();let service_handler = service_node.liquidity_manager.lsps5_service_handler().unwrap();let app = "UpdateTestApp";let url_v1 = "https://example.org/v1";let url_v2 = "https://example.org/v2";// register v1 client_handler.set_webhook(service_node_id, app.into(), url_v1.into()).unwrap();let req = get_lsps_message!(client_node, service_node_id); service_node.liquidity_manager.handle_custom_message(req, client_node_id).unwrap();let _ = service_node.liquidity_manager.next_event().unwrap();// initial webhook_registeredlet resp = get_lsps_message!(service_node, client_node_id); client_node.liquidity_manager.handle_custom_message(resp, service_node_id).unwrap();let _ = client_node.liquidity_manager.next_event().unwrap();// update to v2 client_handler.set_webhook(service_node_id, app.into(), url_v2.into()).unwrap();let upd_req = get_lsps_message!(client_node, service_node_id); service_node.liquidity_manager.handle_custom_message(upd_req, client_node_id).unwrap();let update_event = service_node.liquidity_manager.next_event().unwrap();match update_event {LiquidityEvent::LSPS5Service(LSPS5ServiceEvent::SendWebhookNotification{ url, .. }) => {assert_eq!(url.as_str(), url_v2);}, _ => panic!("Expected webhook_registered for update"),}let upd_resp = get_lsps_message!(service_node, client_node_id); client_node.liquidity_manager.handle_custom_message(upd_resp, service_node_id).unwrap();let _ = client_node.liquidity_manager.next_event().unwrap();// Advance past cooldown and send a notification again mock_time_provider.advance_time(NOTIFICATION_COOLDOWN_TIME.as_secs() + 1); service_handler.notify_payment_incoming(client_node_id).unwrap();let ev = service_node.liquidity_manager.next_event().unwrap();match ev {LiquidityEvent::LSPS5Service(LSPS5ServiceEvent::SendWebhookNotification{ url, notification, .. }) => {assert_eq!(notification.method,WebhookNotificationMethod::LSPS5PaymentIncoming);assert_eq!(url.as_str(), url_v2,"Should target updated URL");}, _ => panic!("Expected SendWebhookNotification after update"),}}

you also need to set last_notification_sent to None so you don't carry the old cooldown to the new url

so you don't carry the old cooldown to the new url
we can add a test that asserts that a notification can be sent immediately after updating a webhook

in here you need to set the webhook.url to params.webhook. if not, the update webhook functionality will be broken.
unfortunately, right now the tests are not testing the webhook update feature. they only test that the notification is sent with the updated url, but they don't test that the url is actually updated and persisted :(
here is a regression test that passes on main but fails on this branch
Ah, good catch, that's indeed a behavior change. I added a fix and included the test, thanks for that.

martinsaposnic · 2025-08-13T15:03:31Z

@tnull left a few small comments but otherwise looks good!

tnull · 2025-08-14T07:55:20Z

Addressed pending comments.

TheBlueMatt

This all LGTM, feel free to squash.

martinsaposnic · 2025-08-17T22:44:04Z

Sorry for the delay here. Fixups look good. No further comments 👍

While bLIP-55 describes that the service should wait at least some cooldown between sending notifications per individual `method`, there is nothing that keeps us from simplifying our approach to apply the cooldown to *any* notifications sent, especially since we just reduced the cooldown period to 1 minute elsewhere. Here, we therefore simplify the `last_notification_sent` field to just be a `Option<LSPSDateTime>`.

If we happened to send a notification while the client is connected to us, we would previously only reset the cooldown once the client connects again. While theoretically it would be preferable to never set the `last_notification_sent` field to begin with if the client is connected to us, allowing the service handler to query the peer connection state would be unnecessarily complex. Here, we therefore simply opt to also reset the `last_notification_sent` state once the peer disconnects from us.

Going forward, we'll add serialization logic for LSPS5 types. To contain the persisted state a bit better (and to align the model with LSPS1/2), we refactor the `LSPS5ServiceHandler` to hold a `PeerState` object.

Previously, we'd constantly check whether or not we can prune stale webhooks. While not wrong, it lead to a bunch of ~unnecessary operations, especially given that we only prune once a day currently. Here we move pruning to `peer_connected`/`peer_disconnected`, which is similar to what we do for LSPS2, and should still be more than enough.

We add the license header to all files in `lightning-liquidity` where it was absent.

tnull · 2025-08-18T07:04:56Z

This all LGTM, feel free to squash.

Squashed without further changes.

tnull · 2025-08-13T09:04:35Z

Before we can introduce persistence to the lightning-liquidity crate, we make a number of pre-/refactors to make our lives easier. We split this out here to keep PR sizes manageable and to introducing too many conflicts with concurrent work.

In this PR, we move some LSPS2/LSPS5 state data to dedicated types, which will allow use to use our serialization macros in the next step. We also simplify the last_notification_sent tracking in LSPS5 (now only tracking a single timestamp for all notification methods), which was requested on a previous PR. We furthermore now reset the notification cooldown on peer disconnection (useful in case we somehow notified last while the peer was connected), and move to prune the LSPS5 service state only on peer_{dis}connected, which should be more than enough.

(cc @martinsaposnic)

.. which streamlines the `PaymentQueue` API a bit, but most importantly can more easily get persisted using macros in the next step.

ldk-reviews-bot · 2025-08-13T09:04:38Z

👋 Thanks for assigning @martinsaposnic 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.

codecov · 2025-08-13T09:14:52Z

Codecov Report

❌ Patch coverage is 97.57576% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.86%. Comparing base (3b16c77) to head (f95ba69).
⚠️ Report is 21 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning-liquidity/src/lsps5/service.rs	97.52%	3 Missing ⚠️
lightning-liquidity/src/manager.rs	66.66%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #4008 +/- ##
=======================================
Coverage 88.85% 88.86% =======================================
Files 175 175 Lines 127682 127758 +76 Branches 127682 127758 +76 =======================================
+ Hits 113449 113527 +78 + Misses 11675 11669 -6 - Partials 2558 2562 +4

Flag	Coverage Δ
fuzzing	`21.75% <0.00%> (-0.11%)`	⬇️
tests	`88.69% <97.57%> (+<0.01%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

martinsaposnic · 2025-08-13T14:41:29Z

+	}
+
+	// Returns whether the entire state is empty and can be pruned.
+	fn prune_stale_webhooks(&mut self, now: LSPSDateTime) -> bool {


this function name is kind of confusing, it sounds like an action but it's not

this function name is kind of confusing, it sounds like an action but it's not
It is an action though, as it drops stale webhooks?

martinsaposnic · 2025-08-13T15:01:16Z

+ if let Some(webhook) = peer_state_lock.webhook_mut(&params.app_name.clone()) {
+ no_change = webhook.url == params.webhook;
+ if !no_change {
+ webhook.last_used = now


in here you need to set the webhook.url to params.webhook. if not, the update webhook functionality will be broken.
unfortunately, right now the tests are not testing the webhook update feature. they only test that the notification is sent with the updated url, but they don't test that the url is actually updated and persisted :(
here is a regression test that passes on main but fails on this branch
#[test]fnwebhook_update_affects_future_notifications(){let mock_time_provider = Arc::new(MockTimeProvider::new(1000));let time_provider = Arc::<MockTimeProvider>::clone(&mock_time_provider);let chanmon_cfgs = create_chanmon_cfgs(2);let node_cfgs = create_node_cfgs(2,&chanmon_cfgs);let node_chanmgrs = create_node_chanmgrs(2,&node_cfgs,&[None,None]);let nodes = create_network(2,&node_cfgs,&node_chanmgrs);let(lsps_nodes, _) = lsps5_test_setup(nodes, time_provider);letLSPSNodes{ service_node, client_node } = lsps_nodes;let service_node_id = service_node.inner.node.get_our_node_id();let client_node_id = client_node.inner.node.get_our_node_id();let client_handler = client_node.liquidity_manager.lsps5_client_handler().unwrap();let service_handler = service_node.liquidity_manager.lsps5_service_handler().unwrap();let app = "UpdateTestApp";let url_v1 = "https://example.org/v1";let url_v2 = "https://example.org/v2";// register v1 client_handler.set_webhook(service_node_id, app.into(), url_v1.into()).unwrap();let req = get_lsps_message!(client_node, service_node_id); service_node.liquidity_manager.handle_custom_message(req, client_node_id).unwrap();let _ = service_node.liquidity_manager.next_event().unwrap();// initial webhook_registeredlet resp = get_lsps_message!(service_node, client_node_id); client_node.liquidity_manager.handle_custom_message(resp, service_node_id).unwrap();let _ = client_node.liquidity_manager.next_event().unwrap();// update to v2 client_handler.set_webhook(service_node_id, app.into(), url_v2.into()).unwrap();let upd_req = get_lsps_message!(client_node, service_node_id); service_node.liquidity_manager.handle_custom_message(upd_req, client_node_id).unwrap();let update_event = service_node.liquidity_manager.next_event().unwrap();match update_event {LiquidityEvent::LSPS5Service(LSPS5ServiceEvent::SendWebhookNotification{ url, .. }) => {assert_eq!(url.as_str(), url_v2);}, _ => panic!("Expected webhook_registered for update"),}let upd_resp = get_lsps_message!(service_node, client_node_id); client_node.liquidity_manager.handle_custom_message(upd_resp, service_node_id).unwrap();let _ = client_node.liquidity_manager.next_event().unwrap();// Advance past cooldown and send a notification again mock_time_provider.advance_time(NOTIFICATION_COOLDOWN_TIME.as_secs() + 1); service_handler.notify_payment_incoming(client_node_id).unwrap();let ev = service_node.liquidity_manager.next_event().unwrap();match ev {LiquidityEvent::LSPS5Service(LSPS5ServiceEvent::SendWebhookNotification{ url, notification, .. }) => {assert_eq!(notification.method,WebhookNotificationMethod::LSPS5PaymentIncoming);assert_eq!(url.as_str(), url_v2,"Should target updated URL");}, _ => panic!("Expected SendWebhookNotification after update"),}}

you also need to set last_notification_sent to None so you don't carry the old cooldown to the new url

so you don't carry the old cooldown to the new url
we can add a test that asserts that a notification can be sent immediately after updating a webhook

in here you need to set the webhook.url to params.webhook. if not, the update webhook functionality will be broken.
unfortunately, right now the tests are not testing the webhook update feature. they only test that the notification is sent with the updated url, but they don't test that the url is actually updated and persisted :(
here is a regression test that passes on main but fails on this branch
Ah, good catch, that's indeed a behavior change. I added a fix and included the test, thanks for that.

martinsaposnic · 2025-08-13T15:03:31Z

@tnull left a few small comments but otherwise looks good!

tnull · 2025-08-14T07:55:20Z

Addressed pending comments.

TheBlueMatt

This all LGTM, feel free to squash.

martinsaposnic · 2025-08-17T22:44:04Z

Sorry for the delay here. Fixups look good. No further comments 👍

While bLIP-55 describes that the service should wait at least some cooldown between sending notifications per individual `method`, there is nothing that keeps us from simplifying our approach to apply the cooldown to *any* notifications sent, especially since we just reduced the cooldown period to 1 minute elsewhere. Here, we therefore simplify the `last_notification_sent` field to just be a `Option<LSPSDateTime>`.

If we happened to send a notification while the client is connected to us, we would previously only reset the cooldown once the client connects again. While theoretically it would be preferable to never set the `last_notification_sent` field to begin with if the client is connected to us, allowing the service handler to query the peer connection state would be unnecessarily complex. Here, we therefore simply opt to also reset the `last_notification_sent` state once the peer disconnects from us.

Going forward, we'll add serialization logic for LSPS5 types. To contain the persisted state a bit better (and to align the model with LSPS1/2), we refactor the `LSPS5ServiceHandler` to hold a `PeerState` object.

Previously, we'd constantly check whether or not we can prune stale webhooks. While not wrong, it lead to a bunch of ~unnecessary operations, especially given that we only prune once a day currently. Here we move pruning to `peer_connected`/`peer_disconnected`, which is similar to what we do for LSPS2, and should still be more than enough.

We add the license header to all files in `lightning-liquidity` where it was absent.

tnull · 2025-08-18T07:04:56Z

This all LGTM, feel free to squash.

Squashed without further changes.

tnull · 2025-08-13T09:04:35Z

Before we can introduce persistence to the lightning-liquidity crate, we make a number of pre-/refactors to make our lives easier. We split this out here to keep PR sizes manageable and to introducing too many conflicts with concurrent work.

In this PR, we move some LSPS2/LSPS5 state data to dedicated types, which will allow use to use our serialization macros in the next step. We also simplify the last_notification_sent tracking in LSPS5 (now only tracking a single timestamp for all notification methods), which was requested on a previous PR. We furthermore now reset the notification cooldown on peer disconnection (useful in case we somehow notified last while the peer was connected), and move to prune the LSPS5 service state only on peer_{dis}connected, which should be more than enough.

(cc @martinsaposnic)

.. which streamlines the `PaymentQueue` API a bit, but most importantly can more easily get persisted using macros in the next step.

ldk-reviews-bot · 2025-08-13T09:04:38Z

👋 Thanks for assigning @martinsaposnic 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.

codecov · 2025-08-13T09:14:52Z

Codecov Report

❌ Patch coverage is 97.57576% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.86%. Comparing base (3b16c77) to head (f95ba69).
⚠️ Report is 21 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning-liquidity/src/lsps5/service.rs	97.52%	3 Missing ⚠️
lightning-liquidity/src/manager.rs	66.66%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #4008 +/- ##
=======================================
Coverage 88.85% 88.86% =======================================
Files 175 175 Lines 127682 127758 +76 Branches 127682 127758 +76 =======================================
+ Hits 113449 113527 +78 + Misses 11675 11669 -6 - Partials 2558 2562 +4

Flag	Coverage Δ
fuzzing	`21.75% <0.00%> (-0.11%)`	⬇️
tests	`88.69% <97.57%> (+<0.01%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

martinsaposnic · 2025-08-13T14:41:29Z

+	}
+
+	// Returns whether the entire state is empty and can be pruned.
+	fn prune_stale_webhooks(&mut self, now: LSPSDateTime) -> bool {


this function name is kind of confusing, it sounds like an action but it's not

this function name is kind of confusing, it sounds like an action but it's not
It is an action though, as it drops stale webhooks?

martinsaposnic · 2025-08-13T15:01:16Z

+ if let Some(webhook) = peer_state_lock.webhook_mut(&params.app_name.clone()) {
+ no_change = webhook.url == params.webhook;
+ if !no_change {
+ webhook.last_used = now


in here you need to set the webhook.url to params.webhook. if not, the update webhook functionality will be broken.
unfortunately, right now the tests are not testing the webhook update feature. they only test that the notification is sent with the updated url, but they don't test that the url is actually updated and persisted :(
here is a regression test that passes on main but fails on this branch
#[test]fnwebhook_update_affects_future_notifications(){let mock_time_provider = Arc::new(MockTimeProvider::new(1000));let time_provider = Arc::<MockTimeProvider>::clone(&mock_time_provider);let chanmon_cfgs = create_chanmon_cfgs(2);let node_cfgs = create_node_cfgs(2,&chanmon_cfgs);let node_chanmgrs = create_node_chanmgrs(2,&node_cfgs,&[None,None]);let nodes = create_network(2,&node_cfgs,&node_chanmgrs);let(lsps_nodes, _) = lsps5_test_setup(nodes, time_provider);letLSPSNodes{ service_node, client_node } = lsps_nodes;let service_node_id = service_node.inner.node.get_our_node_id();let client_node_id = client_node.inner.node.get_our_node_id();let client_handler = client_node.liquidity_manager.lsps5_client_handler().unwrap();let service_handler = service_node.liquidity_manager.lsps5_service_handler().unwrap();let app = "UpdateTestApp";let url_v1 = "https://example.org/v1";let url_v2 = "https://example.org/v2";// register v1 client_handler.set_webhook(service_node_id, app.into(), url_v1.into()).unwrap();let req = get_lsps_message!(client_node, service_node_id); service_node.liquidity_manager.handle_custom_message(req, client_node_id).unwrap();let _ = service_node.liquidity_manager.next_event().unwrap();// initial webhook_registeredlet resp = get_lsps_message!(service_node, client_node_id); client_node.liquidity_manager.handle_custom_message(resp, service_node_id).unwrap();let _ = client_node.liquidity_manager.next_event().unwrap();// update to v2 client_handler.set_webhook(service_node_id, app.into(), url_v2.into()).unwrap();let upd_req = get_lsps_message!(client_node, service_node_id); service_node.liquidity_manager.handle_custom_message(upd_req, client_node_id).unwrap();let update_event = service_node.liquidity_manager.next_event().unwrap();match update_event {LiquidityEvent::LSPS5Service(LSPS5ServiceEvent::SendWebhookNotification{ url, .. }) => {assert_eq!(url.as_str(), url_v2);}, _ => panic!("Expected webhook_registered for update"),}let upd_resp = get_lsps_message!(service_node, client_node_id); client_node.liquidity_manager.handle_custom_message(upd_resp, service_node_id).unwrap();let _ = client_node.liquidity_manager.next_event().unwrap();// Advance past cooldown and send a notification again mock_time_provider.advance_time(NOTIFICATION_COOLDOWN_TIME.as_secs() + 1); service_handler.notify_payment_incoming(client_node_id).unwrap();let ev = service_node.liquidity_manager.next_event().unwrap();match ev {LiquidityEvent::LSPS5Service(LSPS5ServiceEvent::SendWebhookNotification{ url, notification, .. }) => {assert_eq!(notification.method,WebhookNotificationMethod::LSPS5PaymentIncoming);assert_eq!(url.as_str(), url_v2,"Should target updated URL");}, _ => panic!("Expected SendWebhookNotification after update"),}}

you also need to set last_notification_sent to None so you don't carry the old cooldown to the new url

so you don't carry the old cooldown to the new url
we can add a test that asserts that a notification can be sent immediately after updating a webhook

in here you need to set the webhook.url to params.webhook. if not, the update webhook functionality will be broken.
unfortunately, right now the tests are not testing the webhook update feature. they only test that the notification is sent with the updated url, but they don't test that the url is actually updated and persisted :(
here is a regression test that passes on main but fails on this branch
Ah, good catch, that's indeed a behavior change. I added a fix and included the test, thanks for that.

martinsaposnic · 2025-08-13T15:03:31Z

@tnull left a few small comments but otherwise looks good!

tnull · 2025-08-14T07:55:20Z

Addressed pending comments.

TheBlueMatt

This all LGTM, feel free to squash.

martinsaposnic · 2025-08-17T22:44:04Z

Sorry for the delay here. Fixups look good. No further comments 👍

While bLIP-55 describes that the service should wait at least some cooldown between sending notifications per individual `method`, there is nothing that keeps us from simplifying our approach to apply the cooldown to *any* notifications sent, especially since we just reduced the cooldown period to 1 minute elsewhere. Here, we therefore simplify the `last_notification_sent` field to just be a `Option<LSPSDateTime>`.

If we happened to send a notification while the client is connected to us, we would previously only reset the cooldown once the client connects again. While theoretically it would be preferable to never set the `last_notification_sent` field to begin with if the client is connected to us, allowing the service handler to query the peer connection state would be unnecessarily complex. Here, we therefore simply opt to also reset the `last_notification_sent` state once the peer disconnects from us.

Going forward, we'll add serialization logic for LSPS5 types. To contain the persisted state a bit better (and to align the model with LSPS1/2), we refactor the `LSPS5ServiceHandler` to hold a `PeerState` object.

Previously, we'd constantly check whether or not we can prune stale webhooks. While not wrong, it lead to a bunch of ~unnecessary operations, especially given that we only prune once a day currently. Here we move pruning to `peer_connected`/`peer_disconnected`, which is similar to what we do for LSPS2, and should still be more than enough.

We add the license header to all files in `lightning-liquidity` where it was absent.

tnull · 2025-08-18T07:04:56Z

This all LGTM, feel free to squash.

Squashed without further changes.

tnull · 2025-08-13T09:04:35Z

Before we can introduce persistence to the lightning-liquidity crate, we make a number of pre-/refactors to make our lives easier. We split this out here to keep PR sizes manageable and to introducing too many conflicts with concurrent work.

In this PR, we move some LSPS2/LSPS5 state data to dedicated types, which will allow use to use our serialization macros in the next step. We also simplify the last_notification_sent tracking in LSPS5 (now only tracking a single timestamp for all notification methods), which was requested on a previous PR. We furthermore now reset the notification cooldown on peer disconnection (useful in case we somehow notified last while the peer was connected), and move to prune the LSPS5 service state only on peer_{dis}connected, which should be more than enough.

(cc @martinsaposnic)

.. which streamlines the `PaymentQueue` API a bit, but most importantly can more easily get persisted using macros in the next step.

ldk-reviews-bot · 2025-08-13T09:04:38Z

👋 Thanks for assigning @martinsaposnic 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.

codecov · 2025-08-13T09:14:52Z

Codecov Report

❌ Patch coverage is 97.57576% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.86%. Comparing base (3b16c77) to head (f95ba69).
⚠️ Report is 21 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning-liquidity/src/lsps5/service.rs	97.52%	3 Missing ⚠️
lightning-liquidity/src/manager.rs	66.66%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #4008 +/- ##
=======================================
Coverage 88.85% 88.86% =======================================
Files 175 175 Lines 127682 127758 +76 Branches 127682 127758 +76 =======================================
+ Hits 113449 113527 +78 + Misses 11675 11669 -6 - Partials 2558 2562 +4

Flag	Coverage Δ
fuzzing	`21.75% <0.00%> (-0.11%)`	⬇️
tests	`88.69% <97.57%> (+<0.01%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

martinsaposnic · 2025-08-13T14:41:29Z

+	}
+
+	// Returns whether the entire state is empty and can be pruned.
+	fn prune_stale_webhooks(&mut self, now: LSPSDateTime) -> bool {


this function name is kind of confusing, it sounds like an action but it's not

this function name is kind of confusing, it sounds like an action but it's not
It is an action though, as it drops stale webhooks?

martinsaposnic · 2025-08-13T15:01:16Z

+ if let Some(webhook) = peer_state_lock.webhook_mut(&params.app_name.clone()) {
+ no_change = webhook.url == params.webhook;
+ if !no_change {
+ webhook.last_used = now


in here you need to set the webhook.url to params.webhook. if not, the update webhook functionality will be broken.
unfortunately, right now the tests are not testing the webhook update feature. they only test that the notification is sent with the updated url, but they don't test that the url is actually updated and persisted :(
here is a regression test that passes on main but fails on this branch
#[test]fnwebhook_update_affects_future_notifications(){let mock_time_provider = Arc::new(MockTimeProvider::new(1000));let time_provider = Arc::<MockTimeProvider>::clone(&mock_time_provider);let chanmon_cfgs = create_chanmon_cfgs(2);let node_cfgs = create_node_cfgs(2,&chanmon_cfgs);let node_chanmgrs = create_node_chanmgrs(2,&node_cfgs,&[None,None]);let nodes = create_network(2,&node_cfgs,&node_chanmgrs);let(lsps_nodes, _) = lsps5_test_setup(nodes, time_provider);letLSPSNodes{ service_node, client_node } = lsps_nodes;let service_node_id = service_node.inner.node.get_our_node_id();let client_node_id = client_node.inner.node.get_our_node_id();let client_handler = client_node.liquidity_manager.lsps5_client_handler().unwrap();let service_handler = service_node.liquidity_manager.lsps5_service_handler().unwrap();let app = "UpdateTestApp";let url_v1 = "https://example.org/v1";let url_v2 = "https://example.org/v2";// register v1 client_handler.set_webhook(service_node_id, app.into(), url_v1.into()).unwrap();let req = get_lsps_message!(client_node, service_node_id); service_node.liquidity_manager.handle_custom_message(req, client_node_id).unwrap();let _ = service_node.liquidity_manager.next_event().unwrap();// initial webhook_registeredlet resp = get_lsps_message!(service_node, client_node_id); client_node.liquidity_manager.handle_custom_message(resp, service_node_id).unwrap();let _ = client_node.liquidity_manager.next_event().unwrap();// update to v2 client_handler.set_webhook(service_node_id, app.into(), url_v2.into()).unwrap();let upd_req = get_lsps_message!(client_node, service_node_id); service_node.liquidity_manager.handle_custom_message(upd_req, client_node_id).unwrap();let update_event = service_node.liquidity_manager.next_event().unwrap();match update_event {LiquidityEvent::LSPS5Service(LSPS5ServiceEvent::SendWebhookNotification{ url, .. }) => {assert_eq!(url.as_str(), url_v2);}, _ => panic!("Expected webhook_registered for update"),}let upd_resp = get_lsps_message!(service_node, client_node_id); client_node.liquidity_manager.handle_custom_message(upd_resp, service_node_id).unwrap();let _ = client_node.liquidity_manager.next_event().unwrap();// Advance past cooldown and send a notification again mock_time_provider.advance_time(NOTIFICATION_COOLDOWN_TIME.as_secs() + 1); service_handler.notify_payment_incoming(client_node_id).unwrap();let ev = service_node.liquidity_manager.next_event().unwrap();match ev {LiquidityEvent::LSPS5Service(LSPS5ServiceEvent::SendWebhookNotification{ url, notification, .. }) => {assert_eq!(notification.method,WebhookNotificationMethod::LSPS5PaymentIncoming);assert_eq!(url.as_str(), url_v2,"Should target updated URL");}, _ => panic!("Expected SendWebhookNotification after update"),}}

you also need to set last_notification_sent to None so you don't carry the old cooldown to the new url

so you don't carry the old cooldown to the new url
we can add a test that asserts that a notification can be sent immediately after updating a webhook

in here you need to set the webhook.url to params.webhook. if not, the update webhook functionality will be broken.
unfortunately, right now the tests are not testing the webhook update feature. they only test that the notification is sent with the updated url, but they don't test that the url is actually updated and persisted :(
here is a regression test that passes on main but fails on this branch
Ah, good catch, that's indeed a behavior change. I added a fix and included the test, thanks for that.

martinsaposnic · 2025-08-13T15:03:31Z

@tnull left a few small comments but otherwise looks good!

tnull · 2025-08-14T07:55:20Z

Addressed pending comments.

TheBlueMatt

This all LGTM, feel free to squash.

martinsaposnic · 2025-08-17T22:44:04Z

Sorry for the delay here. Fixups look good. No further comments 👍

While bLIP-55 describes that the service should wait at least some cooldown between sending notifications per individual `method`, there is nothing that keeps us from simplifying our approach to apply the cooldown to *any* notifications sent, especially since we just reduced the cooldown period to 1 minute elsewhere. Here, we therefore simplify the `last_notification_sent` field to just be a `Option<LSPSDateTime>`.

If we happened to send a notification while the client is connected to us, we would previously only reset the cooldown once the client connects again. While theoretically it would be preferable to never set the `last_notification_sent` field to begin with if the client is connected to us, allowing the service handler to query the peer connection state would be unnecessarily complex. Here, we therefore simply opt to also reset the `last_notification_sent` state once the peer disconnects from us.

Going forward, we'll add serialization logic for LSPS5 types. To contain the persisted state a bit better (and to align the model with LSPS1/2), we refactor the `LSPS5ServiceHandler` to hold a `PeerState` object.

Previously, we'd constantly check whether or not we can prune stale webhooks. While not wrong, it lead to a bunch of ~unnecessary operations, especially given that we only prune once a day currently. Here we move pruning to `peer_connected`/`peer_disconnected`, which is similar to what we do for LSPS2, and should still be more than enough.

We add the license header to all files in `lightning-liquidity` where it was absent.

tnull · 2025-08-18T07:04:56Z

This all LGTM, feel free to squash.

Squashed without further changes.

tnull · 2025-08-13T09:04:35Z

Before we can introduce persistence to the lightning-liquidity crate, we make a number of pre-/refactors to make our lives easier. We split this out here to keep PR sizes manageable and to introducing too many conflicts with concurrent work.

In this PR, we move some LSPS2/LSPS5 state data to dedicated types, which will allow use to use our serialization macros in the next step. We also simplify the last_notification_sent tracking in LSPS5 (now only tracking a single timestamp for all notification methods), which was requested on a previous PR. We furthermore now reset the notification cooldown on peer disconnection (useful in case we somehow notified last while the peer was connected), and move to prune the LSPS5 service state only on peer_{dis}connected, which should be more than enough.

(cc @martinsaposnic)

.. which streamlines the `PaymentQueue` API a bit, but most importantly can more easily get persisted using macros in the next step.

ldk-reviews-bot · 2025-08-13T09:04:38Z

👋 Thanks for assigning @martinsaposnic 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.

codecov · 2025-08-13T09:14:52Z

Codecov Report

❌ Patch coverage is 97.57576% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.86%. Comparing base (3b16c77) to head (f95ba69).
⚠️ Report is 21 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning-liquidity/src/lsps5/service.rs	97.52%	3 Missing ⚠️
lightning-liquidity/src/manager.rs	66.66%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #4008 +/- ##
=======================================
Coverage 88.85% 88.86% =======================================
Files 175 175 Lines 127682 127758 +76 Branches 127682 127758 +76 =======================================
+ Hits 113449 113527 +78 + Misses 11675 11669 -6 - Partials 2558 2562 +4

Flag	Coverage Δ
fuzzing	`21.75% <0.00%> (-0.11%)`	⬇️
tests	`88.69% <97.57%> (+<0.01%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

martinsaposnic · 2025-08-13T14:41:29Z

+	}
+
+	// Returns whether the entire state is empty and can be pruned.
+	fn prune_stale_webhooks(&mut self, now: LSPSDateTime) -> bool {


this function name is kind of confusing, it sounds like an action but it's not

this function name is kind of confusing, it sounds like an action but it's not
It is an action though, as it drops stale webhooks?

martinsaposnic · 2025-08-13T15:01:16Z

+ if let Some(webhook) = peer_state_lock.webhook_mut(&params.app_name.clone()) {
+ no_change = webhook.url == params.webhook;
+ if !no_change {
+ webhook.last_used = now


in here you need to set the webhook.url to params.webhook. if not, the update webhook functionality will be broken.
unfortunately, right now the tests are not testing the webhook update feature. they only test that the notification is sent with the updated url, but they don't test that the url is actually updated and persisted :(
here is a regression test that passes on main but fails on this branch
#[test]fnwebhook_update_affects_future_notifications(){let mock_time_provider = Arc::new(MockTimeProvider::new(1000));let time_provider = Arc::<MockTimeProvider>::clone(&mock_time_provider);let chanmon_cfgs = create_chanmon_cfgs(2);let node_cfgs = create_node_cfgs(2,&chanmon_cfgs);let node_chanmgrs = create_node_chanmgrs(2,&node_cfgs,&[None,None]);let nodes = create_network(2,&node_cfgs,&node_chanmgrs);let(lsps_nodes, _) = lsps5_test_setup(nodes, time_provider);letLSPSNodes{ service_node, client_node } = lsps_nodes;let service_node_id = service_node.inner.node.get_our_node_id();let client_node_id = client_node.inner.node.get_our_node_id();let client_handler = client_node.liquidity_manager.lsps5_client_handler().unwrap();let service_handler = service_node.liquidity_manager.lsps5_service_handler().unwrap();let app = "UpdateTestApp";let url_v1 = "https://example.org/v1";let url_v2 = "https://example.org/v2";// register v1 client_handler.set_webhook(service_node_id, app.into(), url_v1.into()).unwrap();let req = get_lsps_message!(client_node, service_node_id); service_node.liquidity_manager.handle_custom_message(req, client_node_id).unwrap();let _ = service_node.liquidity_manager.next_event().unwrap();// initial webhook_registeredlet resp = get_lsps_message!(service_node, client_node_id); client_node.liquidity_manager.handle_custom_message(resp, service_node_id).unwrap();let _ = client_node.liquidity_manager.next_event().unwrap();// update to v2 client_handler.set_webhook(service_node_id, app.into(), url_v2.into()).unwrap();let upd_req = get_lsps_message!(client_node, service_node_id); service_node.liquidity_manager.handle_custom_message(upd_req, client_node_id).unwrap();let update_event = service_node.liquidity_manager.next_event().unwrap();match update_event {LiquidityEvent::LSPS5Service(LSPS5ServiceEvent::SendWebhookNotification{ url, .. }) => {assert_eq!(url.as_str(), url_v2);}, _ => panic!("Expected webhook_registered for update"),}let upd_resp = get_lsps_message!(service_node, client_node_id); client_node.liquidity_manager.handle_custom_message(upd_resp, service_node_id).unwrap();let _ = client_node.liquidity_manager.next_event().unwrap();// Advance past cooldown and send a notification again mock_time_provider.advance_time(NOTIFICATION_COOLDOWN_TIME.as_secs() + 1); service_handler.notify_payment_incoming(client_node_id).unwrap();let ev = service_node.liquidity_manager.next_event().unwrap();match ev {LiquidityEvent::LSPS5Service(LSPS5ServiceEvent::SendWebhookNotification{ url, notification, .. }) => {assert_eq!(notification.method,WebhookNotificationMethod::LSPS5PaymentIncoming);assert_eq!(url.as_str(), url_v2,"Should target updated URL");}, _ => panic!("Expected SendWebhookNotification after update"),}}

you also need to set last_notification_sent to None so you don't carry the old cooldown to the new url

so you don't carry the old cooldown to the new url
we can add a test that asserts that a notification can be sent immediately after updating a webhook

in here you need to set the webhook.url to params.webhook. if not, the update webhook functionality will be broken.
unfortunately, right now the tests are not testing the webhook update feature. they only test that the notification is sent with the updated url, but they don't test that the url is actually updated and persisted :(
here is a regression test that passes on main but fails on this branch
Ah, good catch, that's indeed a behavior change. I added a fix and included the test, thanks for that.

martinsaposnic · 2025-08-13T15:03:31Z

@tnull left a few small comments but otherwise looks good!

tnull · 2025-08-14T07:55:20Z

Addressed pending comments.

TheBlueMatt

This all LGTM, feel free to squash.

martinsaposnic · 2025-08-17T22:44:04Z

Sorry for the delay here. Fixups look good. No further comments 👍

While bLIP-55 describes that the service should wait at least some cooldown between sending notifications per individual `method`, there is nothing that keeps us from simplifying our approach to apply the cooldown to *any* notifications sent, especially since we just reduced the cooldown period to 1 minute elsewhere. Here, we therefore simplify the `last_notification_sent` field to just be a `Option<LSPSDateTime>`.

If we happened to send a notification while the client is connected to us, we would previously only reset the cooldown once the client connects again. While theoretically it would be preferable to never set the `last_notification_sent` field to begin with if the client is connected to us, allowing the service handler to query the peer connection state would be unnecessarily complex. Here, we therefore simply opt to also reset the `last_notification_sent` state once the peer disconnects from us.

Going forward, we'll add serialization logic for LSPS5 types. To contain the persisted state a bit better (and to align the model with LSPS1/2), we refactor the `LSPS5ServiceHandler` to hold a `PeerState` object.

Previously, we'd constantly check whether or not we can prune stale webhooks. While not wrong, it lead to a bunch of ~unnecessary operations, especially given that we only prune once a day currently. Here we move pruning to `peer_connected`/`peer_disconnected`, which is similar to what we do for LSPS2, and should still be more than enough.

We add the license header to all files in `lightning-liquidity` where it was absent.

tnull · 2025-08-18T07:04:56Z

This all LGTM, feel free to squash.

Squashed without further changes.

tnull · 2025-08-13T09:04:35Z

Before we can introduce persistence to the lightning-liquidity crate, we make a number of pre-/refactors to make our lives easier. We split this out here to keep PR sizes manageable and to introducing too many conflicts with concurrent work.

In this PR, we move some LSPS2/LSPS5 state data to dedicated types, which will allow use to use our serialization macros in the next step. We also simplify the last_notification_sent tracking in LSPS5 (now only tracking a single timestamp for all notification methods), which was requested on a previous PR. We furthermore now reset the notification cooldown on peer disconnection (useful in case we somehow notified last while the peer was connected), and move to prune the LSPS5 service state only on peer_{dis}connected, which should be more than enough.

(cc @martinsaposnic)

.. which streamlines the `PaymentQueue` API a bit, but most importantly can more easily get persisted using macros in the next step.

ldk-reviews-bot · 2025-08-13T09:04:38Z

👋 Thanks for assigning @martinsaposnic 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.

codecov · 2025-08-13T09:14:52Z

Codecov Report

❌ Patch coverage is 97.57576% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.86%. Comparing base (3b16c77) to head (f95ba69).
⚠️ Report is 21 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning-liquidity/src/lsps5/service.rs	97.52%	3 Missing ⚠️
lightning-liquidity/src/manager.rs	66.66%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #4008 +/- ##
=======================================
Coverage 88.85% 88.86% =======================================
Files 175 175 Lines 127682 127758 +76 Branches 127682 127758 +76 =======================================
+ Hits 113449 113527 +78 + Misses 11675 11669 -6 - Partials 2558 2562 +4

Flag	Coverage Δ
fuzzing	`21.75% <0.00%> (-0.11%)`	⬇️
tests	`88.69% <97.57%> (+<0.01%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

martinsaposnic · 2025-08-13T14:41:29Z

+	}
+
+	// Returns whether the entire state is empty and can be pruned.
+	fn prune_stale_webhooks(&mut self, now: LSPSDateTime) -> bool {


this function name is kind of confusing, it sounds like an action but it's not

this function name is kind of confusing, it sounds like an action but it's not
It is an action though, as it drops stale webhooks?

martinsaposnic · 2025-08-13T15:01:16Z

+ if let Some(webhook) = peer_state_lock.webhook_mut(&params.app_name.clone()) {
+ no_change = webhook.url == params.webhook;
+ if !no_change {
+ webhook.last_used = now


in here you need to set the webhook.url to params.webhook. if not, the update webhook functionality will be broken.
unfortunately, right now the tests are not testing the webhook update feature. they only test that the notification is sent with the updated url, but they don't test that the url is actually updated and persisted :(
here is a regression test that passes on main but fails on this branch
#[test]fnwebhook_update_affects_future_notifications(){let mock_time_provider = Arc::new(MockTimeProvider::new(1000));let time_provider = Arc::<MockTimeProvider>::clone(&mock_time_provider);let chanmon_cfgs = create_chanmon_cfgs(2);let node_cfgs = create_node_cfgs(2,&chanmon_cfgs);let node_chanmgrs = create_node_chanmgrs(2,&node_cfgs,&[None,None]);let nodes = create_network(2,&node_cfgs,&node_chanmgrs);let(lsps_nodes, _) = lsps5_test_setup(nodes, time_provider);letLSPSNodes{ service_node, client_node } = lsps_nodes;let service_node_id = service_node.inner.node.get_our_node_id();let client_node_id = client_node.inner.node.get_our_node_id();let client_handler = client_node.liquidity_manager.lsps5_client_handler().unwrap();let service_handler = service_node.liquidity_manager.lsps5_service_handler().unwrap();let app = "UpdateTestApp";let url_v1 = "https://example.org/v1";let url_v2 = "https://example.org/v2";// register v1 client_handler.set_webhook(service_node_id, app.into(), url_v1.into()).unwrap();let req = get_lsps_message!(client_node, service_node_id); service_node.liquidity_manager.handle_custom_message(req, client_node_id).unwrap();let _ = service_node.liquidity_manager.next_event().unwrap();// initial webhook_registeredlet resp = get_lsps_message!(service_node, client_node_id); client_node.liquidity_manager.handle_custom_message(resp, service_node_id).unwrap();let _ = client_node.liquidity_manager.next_event().unwrap();// update to v2 client_handler.set_webhook(service_node_id, app.into(), url_v2.into()).unwrap();let upd_req = get_lsps_message!(client_node, service_node_id); service_node.liquidity_manager.handle_custom_message(upd_req, client_node_id).unwrap();let update_event = service_node.liquidity_manager.next_event().unwrap();match update_event {LiquidityEvent::LSPS5Service(LSPS5ServiceEvent::SendWebhookNotification{ url, .. }) => {assert_eq!(url.as_str(), url_v2);}, _ => panic!("Expected webhook_registered for update"),}let upd_resp = get_lsps_message!(service_node, client_node_id); client_node.liquidity_manager.handle_custom_message(upd_resp, service_node_id).unwrap();let _ = client_node.liquidity_manager.next_event().unwrap();// Advance past cooldown and send a notification again mock_time_provider.advance_time(NOTIFICATION_COOLDOWN_TIME.as_secs() + 1); service_handler.notify_payment_incoming(client_node_id).unwrap();let ev = service_node.liquidity_manager.next_event().unwrap();match ev {LiquidityEvent::LSPS5Service(LSPS5ServiceEvent::SendWebhookNotification{ url, notification, .. }) => {assert_eq!(notification.method,WebhookNotificationMethod::LSPS5PaymentIncoming);assert_eq!(url.as_str(), url_v2,"Should target updated URL");}, _ => panic!("Expected SendWebhookNotification after update"),}}

you also need to set last_notification_sent to None so you don't carry the old cooldown to the new url

so you don't carry the old cooldown to the new url
we can add a test that asserts that a notification can be sent immediately after updating a webhook

in here you need to set the webhook.url to params.webhook. if not, the update webhook functionality will be broken.
unfortunately, right now the tests are not testing the webhook update feature. they only test that the notification is sent with the updated url, but they don't test that the url is actually updated and persisted :(
here is a regression test that passes on main but fails on this branch
Ah, good catch, that's indeed a behavior change. I added a fix and included the test, thanks for that.

martinsaposnic · 2025-08-13T15:03:31Z

@tnull left a few small comments but otherwise looks good!

tnull · 2025-08-14T07:55:20Z

Addressed pending comments.

TheBlueMatt

This all LGTM, feel free to squash.

martinsaposnic · 2025-08-17T22:44:04Z

Sorry for the delay here. Fixups look good. No further comments 👍

While bLIP-55 describes that the service should wait at least some cooldown between sending notifications per individual `method`, there is nothing that keeps us from simplifying our approach to apply the cooldown to *any* notifications sent, especially since we just reduced the cooldown period to 1 minute elsewhere. Here, we therefore simplify the `last_notification_sent` field to just be a `Option<LSPSDateTime>`.

If we happened to send a notification while the client is connected to us, we would previously only reset the cooldown once the client connects again. While theoretically it would be preferable to never set the `last_notification_sent` field to begin with if the client is connected to us, allowing the service handler to query the peer connection state would be unnecessarily complex. Here, we therefore simply opt to also reset the `last_notification_sent` state once the peer disconnects from us.

Going forward, we'll add serialization logic for LSPS5 types. To contain the persisted state a bit better (and to align the model with LSPS1/2), we refactor the `LSPS5ServiceHandler` to hold a `PeerState` object.

Previously, we'd constantly check whether or not we can prune stale webhooks. While not wrong, it lead to a bunch of ~unnecessary operations, especially given that we only prune once a day currently. Here we move pruning to `peer_connected`/`peer_disconnected`, which is similar to what we do for LSPS2, and should still be more than enough.

We add the license header to all files in `lightning-liquidity` where it was absent.

tnull · 2025-08-18T07:04:56Z

This all LGTM, feel free to squash.

Squashed without further changes.

tnull · 2025-08-13T09:04:35Z

Before we can introduce persistence to the lightning-liquidity crate, we make a number of pre-/refactors to make our lives easier. We split this out here to keep PR sizes manageable and to introducing too many conflicts with concurrent work.

In this PR, we move some LSPS2/LSPS5 state data to dedicated types, which will allow use to use our serialization macros in the next step. We also simplify the last_notification_sent tracking in LSPS5 (now only tracking a single timestamp for all notification methods), which was requested on a previous PR. We furthermore now reset the notification cooldown on peer disconnection (useful in case we somehow notified last while the peer was connected), and move to prune the LSPS5 service state only on peer_{dis}connected, which should be more than enough.

(cc @martinsaposnic)

.. which streamlines the `PaymentQueue` API a bit, but most importantly can more easily get persisted using macros in the next step.

ldk-reviews-bot · 2025-08-13T09:04:38Z

👋 Thanks for assigning @martinsaposnic 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.

codecov · 2025-08-13T09:14:52Z

Codecov Report

❌ Patch coverage is 97.57576% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.86%. Comparing base (3b16c77) to head (f95ba69).
⚠️ Report is 21 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning-liquidity/src/lsps5/service.rs	97.52%	3 Missing ⚠️
lightning-liquidity/src/manager.rs	66.66%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #4008 +/- ##
=======================================
Coverage 88.85% 88.86% =======================================
Files 175 175 Lines 127682 127758 +76 Branches 127682 127758 +76 =======================================
+ Hits 113449 113527 +78 + Misses 11675 11669 -6 - Partials 2558 2562 +4

Flag	Coverage Δ
fuzzing	`21.75% <0.00%> (-0.11%)`	⬇️
tests	`88.69% <97.57%> (+<0.01%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

martinsaposnic · 2025-08-13T14:41:29Z

+	}
+
+	// Returns whether the entire state is empty and can be pruned.
+	fn prune_stale_webhooks(&mut self, now: LSPSDateTime) -> bool {


this function name is kind of confusing, it sounds like an action but it's not

this function name is kind of confusing, it sounds like an action but it's not
It is an action though, as it drops stale webhooks?

martinsaposnic · 2025-08-13T15:01:16Z

+ if let Some(webhook) = peer_state_lock.webhook_mut(&params.app_name.clone()) {
+ no_change = webhook.url == params.webhook;
+ if !no_change {
+ webhook.last_used = now


in here you need to set the webhook.url to params.webhook. if not, the update webhook functionality will be broken.
unfortunately, right now the tests are not testing the webhook update feature. they only test that the notification is sent with the updated url, but they don't test that the url is actually updated and persisted :(
here is a regression test that passes on main but fails on this branch
#[test]fnwebhook_update_affects_future_notifications(){let mock_time_provider = Arc::new(MockTimeProvider::new(1000));let time_provider = Arc::<MockTimeProvider>::clone(&mock_time_provider);let chanmon_cfgs = create_chanmon_cfgs(2);let node_cfgs = create_node_cfgs(2,&chanmon_cfgs);let node_chanmgrs = create_node_chanmgrs(2,&node_cfgs,&[None,None]);let nodes = create_network(2,&node_cfgs,&node_chanmgrs);let(lsps_nodes, _) = lsps5_test_setup(nodes, time_provider);letLSPSNodes{ service_node, client_node } = lsps_nodes;let service_node_id = service_node.inner.node.get_our_node_id();let client_node_id = client_node.inner.node.get_our_node_id();let client_handler = client_node.liquidity_manager.lsps5_client_handler().unwrap();let service_handler = service_node.liquidity_manager.lsps5_service_handler().unwrap();let app = "UpdateTestApp";let url_v1 = "https://example.org/v1";let url_v2 = "https://example.org/v2";// register v1 client_handler.set_webhook(service_node_id, app.into(), url_v1.into()).unwrap();let req = get_lsps_message!(client_node, service_node_id); service_node.liquidity_manager.handle_custom_message(req, client_node_id).unwrap();let _ = service_node.liquidity_manager.next_event().unwrap();// initial webhook_registeredlet resp = get_lsps_message!(service_node, client_node_id); client_node.liquidity_manager.handle_custom_message(resp, service_node_id).unwrap();let _ = client_node.liquidity_manager.next_event().unwrap();// update to v2 client_handler.set_webhook(service_node_id, app.into(), url_v2.into()).unwrap();let upd_req = get_lsps_message!(client_node, service_node_id); service_node.liquidity_manager.handle_custom_message(upd_req, client_node_id).unwrap();let update_event = service_node.liquidity_manager.next_event().unwrap();match update_event {LiquidityEvent::LSPS5Service(LSPS5ServiceEvent::SendWebhookNotification{ url, .. }) => {assert_eq!(url.as_str(), url_v2);}, _ => panic!("Expected webhook_registered for update"),}let upd_resp = get_lsps_message!(service_node, client_node_id); client_node.liquidity_manager.handle_custom_message(upd_resp, service_node_id).unwrap();let _ = client_node.liquidity_manager.next_event().unwrap();// Advance past cooldown and send a notification again mock_time_provider.advance_time(NOTIFICATION_COOLDOWN_TIME.as_secs() + 1); service_handler.notify_payment_incoming(client_node_id).unwrap();let ev = service_node.liquidity_manager.next_event().unwrap();match ev {LiquidityEvent::LSPS5Service(LSPS5ServiceEvent::SendWebhookNotification{ url, notification, .. }) => {assert_eq!(notification.method,WebhookNotificationMethod::LSPS5PaymentIncoming);assert_eq!(url.as_str(), url_v2,"Should target updated URL");}, _ => panic!("Expected SendWebhookNotification after update"),}}

you also need to set last_notification_sent to None so you don't carry the old cooldown to the new url

so you don't carry the old cooldown to the new url
we can add a test that asserts that a notification can be sent immediately after updating a webhook

in here you need to set the webhook.url to params.webhook. if not, the update webhook functionality will be broken.
unfortunately, right now the tests are not testing the webhook update feature. they only test that the notification is sent with the updated url, but they don't test that the url is actually updated and persisted :(
here is a regression test that passes on main but fails on this branch
Ah, good catch, that's indeed a behavior change. I added a fix and included the test, thanks for that.

martinsaposnic · 2025-08-13T15:03:31Z

@tnull left a few small comments but otherwise looks good!

tnull · 2025-08-14T07:55:20Z

Addressed pending comments.

TheBlueMatt

This all LGTM, feel free to squash.

martinsaposnic · 2025-08-17T22:44:04Z

Sorry for the delay here. Fixups look good. No further comments 👍

While bLIP-55 describes that the service should wait at least some cooldown between sending notifications per individual `method`, there is nothing that keeps us from simplifying our approach to apply the cooldown to *any* notifications sent, especially since we just reduced the cooldown period to 1 minute elsewhere. Here, we therefore simplify the `last_notification_sent` field to just be a `Option<LSPSDateTime>`.

If we happened to send a notification while the client is connected to us, we would previously only reset the cooldown once the client connects again. While theoretically it would be preferable to never set the `last_notification_sent` field to begin with if the client is connected to us, allowing the service handler to query the peer connection state would be unnecessarily complex. Here, we therefore simply opt to also reset the `last_notification_sent` state once the peer disconnects from us.

Going forward, we'll add serialization logic for LSPS5 types. To contain the persisted state a bit better (and to align the model with LSPS1/2), we refactor the `LSPS5ServiceHandler` to hold a `PeerState` object.

Previously, we'd constantly check whether or not we can prune stale webhooks. While not wrong, it lead to a bunch of ~unnecessary operations, especially given that we only prune once a day currently. Here we move pruning to `peer_connected`/`peer_disconnected`, which is similar to what we do for LSPS2, and should still be more than enough.

We add the license header to all files in `lightning-liquidity` where it was absent.

tnull · 2025-08-18T07:04:56Z

This all LGTM, feel free to squash.

Squashed without further changes.

tnull · 2025-08-13T09:04:35Z

Before we can introduce persistence to the lightning-liquidity crate, we make a number of pre-/refactors to make our lives easier. We split this out here to keep PR sizes manageable and to introducing too many conflicts with concurrent work.

In this PR, we move some LSPS2/LSPS5 state data to dedicated types, which will allow use to use our serialization macros in the next step. We also simplify the last_notification_sent tracking in LSPS5 (now only tracking a single timestamp for all notification methods), which was requested on a previous PR. We furthermore now reset the notification cooldown on peer disconnection (useful in case we somehow notified last while the peer was connected), and move to prune the LSPS5 service state only on peer_{dis}connected, which should be more than enough.

(cc @martinsaposnic)

.. which streamlines the `PaymentQueue` API a bit, but most importantly can more easily get persisted using macros in the next step.

ldk-reviews-bot · 2025-08-13T09:04:38Z

👋 Thanks for assigning @martinsaposnic 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.

codecov · 2025-08-13T09:14:52Z

Codecov Report

❌ Patch coverage is 97.57576% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.86%. Comparing base (3b16c77) to head (f95ba69).
⚠️ Report is 21 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning-liquidity/src/lsps5/service.rs	97.52%	3 Missing ⚠️
lightning-liquidity/src/manager.rs	66.66%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #4008 +/- ##
=======================================
Coverage 88.85% 88.86% =======================================
Files 175 175 Lines 127682 127758 +76 Branches 127682 127758 +76 =======================================
+ Hits 113449 113527 +78 + Misses 11675 11669 -6 - Partials 2558 2562 +4

Flag	Coverage Δ
fuzzing	`21.75% <0.00%> (-0.11%)`	⬇️
tests	`88.69% <97.57%> (+<0.01%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

martinsaposnic · 2025-08-13T14:41:29Z

+	}
+
+	// Returns whether the entire state is empty and can be pruned.
+	fn prune_stale_webhooks(&mut self, now: LSPSDateTime) -> bool {


this function name is kind of confusing, it sounds like an action but it's not

this function name is kind of confusing, it sounds like an action but it's not
It is an action though, as it drops stale webhooks?

martinsaposnic · 2025-08-13T15:01:16Z

+ if let Some(webhook) = peer_state_lock.webhook_mut(&params.app_name.clone()) {
+ no_change = webhook.url == params.webhook;
+ if !no_change {
+ webhook.last_used = now


in here you need to set the webhook.url to params.webhook. if not, the update webhook functionality will be broken.
unfortunately, right now the tests are not testing the webhook update feature. they only test that the notification is sent with the updated url, but they don't test that the url is actually updated and persisted :(
here is a regression test that passes on main but fails on this branch
#[test]fnwebhook_update_affects_future_notifications(){let mock_time_provider = Arc::new(MockTimeProvider::new(1000));let time_provider = Arc::<MockTimeProvider>::clone(&mock_time_provider);let chanmon_cfgs = create_chanmon_cfgs(2);let node_cfgs = create_node_cfgs(2,&chanmon_cfgs);let node_chanmgrs = create_node_chanmgrs(2,&node_cfgs,&[None,None]);let nodes = create_network(2,&node_cfgs,&node_chanmgrs);let(lsps_nodes, _) = lsps5_test_setup(nodes, time_provider);letLSPSNodes{ service_node, client_node } = lsps_nodes;let service_node_id = service_node.inner.node.get_our_node_id();let client_node_id = client_node.inner.node.get_our_node_id();let client_handler = client_node.liquidity_manager.lsps5_client_handler().unwrap();let service_handler = service_node.liquidity_manager.lsps5_service_handler().unwrap();let app = "UpdateTestApp";let url_v1 = "https://example.org/v1";let url_v2 = "https://example.org/v2";// register v1 client_handler.set_webhook(service_node_id, app.into(), url_v1.into()).unwrap();let req = get_lsps_message!(client_node, service_node_id); service_node.liquidity_manager.handle_custom_message(req, client_node_id).unwrap();let _ = service_node.liquidity_manager.next_event().unwrap();// initial webhook_registeredlet resp = get_lsps_message!(service_node, client_node_id); client_node.liquidity_manager.handle_custom_message(resp, service_node_id).unwrap();let _ = client_node.liquidity_manager.next_event().unwrap();// update to v2 client_handler.set_webhook(service_node_id, app.into(), url_v2.into()).unwrap();let upd_req = get_lsps_message!(client_node, service_node_id); service_node.liquidity_manager.handle_custom_message(upd_req, client_node_id).unwrap();let update_event = service_node.liquidity_manager.next_event().unwrap();match update_event {LiquidityEvent::LSPS5Service(LSPS5ServiceEvent::SendWebhookNotification{ url, .. }) => {assert_eq!(url.as_str(), url_v2);}, _ => panic!("Expected webhook_registered for update"),}let upd_resp = get_lsps_message!(service_node, client_node_id); client_node.liquidity_manager.handle_custom_message(upd_resp, service_node_id).unwrap();let _ = client_node.liquidity_manager.next_event().unwrap();// Advance past cooldown and send a notification again mock_time_provider.advance_time(NOTIFICATION_COOLDOWN_TIME.as_secs() + 1); service_handler.notify_payment_incoming(client_node_id).unwrap();let ev = service_node.liquidity_manager.next_event().unwrap();match ev {LiquidityEvent::LSPS5Service(LSPS5ServiceEvent::SendWebhookNotification{ url, notification, .. }) => {assert_eq!(notification.method,WebhookNotificationMethod::LSPS5PaymentIncoming);assert_eq!(url.as_str(), url_v2,"Should target updated URL");}, _ => panic!("Expected SendWebhookNotification after update"),}}

you also need to set last_notification_sent to None so you don't carry the old cooldown to the new url

so you don't carry the old cooldown to the new url
we can add a test that asserts that a notification can be sent immediately after updating a webhook

in here you need to set the webhook.url to params.webhook. if not, the update webhook functionality will be broken.
unfortunately, right now the tests are not testing the webhook update feature. they only test that the notification is sent with the updated url, but they don't test that the url is actually updated and persisted :(
here is a regression test that passes on main but fails on this branch
Ah, good catch, that's indeed a behavior change. I added a fix and included the test, thanks for that.

martinsaposnic · 2025-08-13T15:03:31Z

@tnull left a few small comments but otherwise looks good!

tnull · 2025-08-14T07:55:20Z

Addressed pending comments.

TheBlueMatt

This all LGTM, feel free to squash.

martinsaposnic · 2025-08-17T22:44:04Z

Sorry for the delay here. Fixups look good. No further comments 👍

While bLIP-55 describes that the service should wait at least some cooldown between sending notifications per individual `method`, there is nothing that keeps us from simplifying our approach to apply the cooldown to *any* notifications sent, especially since we just reduced the cooldown period to 1 minute elsewhere. Here, we therefore simplify the `last_notification_sent` field to just be a `Option<LSPSDateTime>`.

If we happened to send a notification while the client is connected to us, we would previously only reset the cooldown once the client connects again. While theoretically it would be preferable to never set the `last_notification_sent` field to begin with if the client is connected to us, allowing the service handler to query the peer connection state would be unnecessarily complex. Here, we therefore simply opt to also reset the `last_notification_sent` state once the peer disconnects from us.

Going forward, we'll add serialization logic for LSPS5 types. To contain the persisted state a bit better (and to align the model with LSPS1/2), we refactor the `LSPS5ServiceHandler` to hold a `PeerState` object.

Previously, we'd constantly check whether or not we can prune stale webhooks. While not wrong, it lead to a bunch of ~unnecessary operations, especially given that we only prune once a day currently. Here we move pruning to `peer_connected`/`peer_disconnected`, which is similar to what we do for LSPS2, and should still be more than enough.

We add the license header to all files in `lightning-liquidity` where it was absent.

tnull · 2025-08-18T07:04:56Z

This all LGTM, feel free to squash.

Squashed without further changes.

tnull added 2 commits August 13, 2025 10:32

Prefactor: Introduce PaymentQueueEntry
dc67685
.. which streamlines the `PaymentQueue` API a bit, but most importantly can more easily get persisted using macros in the next step.

Prefactor: Rename StoredWebhook to Webhook
e6ca208

tnull requested a review from TheBlueMatt August 13, 2025 09:04

tnull self-assigned this Aug 13, 2025

tnull added this to Weekly Goals Aug 13, 2025

tnull added lightning-liquidity weekly goal Someone wants to land this this week labels Aug 13, 2025

tnull moved this to Goal: Merge in Weekly Goals Aug 13, 2025

graphite-appBot reviewed Aug 13, 2025
View reviewed changes

Comment threadlightning-liquidity/src/lsps5/service.rs Outdated

tnull force-pushed the 2025-08-liquidity-persistence-prefactors branch from 7447f32 to 1d490f2Compare August 13, 2025 12:23

martinsaposnic reviewed Aug 13, 2025
View reviewed changes

Comment threadlightning-liquidity/src/lsps5/service.rs Outdated

martinsaposnic reviewed Aug 13, 2025
View reviewed changes

Comment threadlightning-liquidity/src/lsps5/service.rs Outdated

martinsaposnic reviewed Aug 13, 2025
View reviewed changes

Comment threadlightning-liquidity/src/lsps5/service.rs Outdated

martinsaposnic reviewed Aug 13, 2025
View reviewed changes

TheBlueMatt reviewed Aug 13, 2025
View reviewed changes

Comment threadlightning-liquidity/src/lsps5/service.rs

tnull force-pushed the 2025-08-liquidity-persistence-prefactors branch from 1d490f2 to e952cbdCompare August 14, 2025 07:47

tnull requested review from TheBlueMatt and martinsaposnic August 15, 2025 09:54

TheBlueMatt reviewed Aug 17, 2025
View reviewed changes

martinsaposnic approved these changes Aug 17, 2025
View reviewed changes

tnull added 4 commits August 18, 2025 09:02

Refactor LSPS5ServiceHandler to hold a PeerState
ce89e6b
Going forward, we'll add serialization logic for LSPS5 types. To contain the persisted state a bit better (and to align the model with LSPS1/2), we refactor the `LSPS5ServiceHandler` to hold a `PeerState` object.

Add missing license headers
f95ba69
We add the license header to all files in `lightning-liquidity` where it was absent.

tnull force-pushed the 2025-08-liquidity-persistence-prefactors branch from e952cbd to f95ba69Compare August 18, 2025 07:03

TheBlueMatt approved these changes Aug 18, 2025
View reviewed changes

TheBlueMatt merged commit e1a31e1 into lightningdevkit:mainAug 18, 2025
24 checks passed

github-project-automationBot moved this from Goal: Merge to Done in Weekly Goals Aug 18, 2025

This was referenced Sep 4, 2025
LSPS5 Follow ups #3944
Closed
lightning-liquidity Persistence Tracking Issue #4058
Closed

This was referenced Sep 16, 2025
LSPS2: Isolate PeerState types via a sealed sub-module #4073
Open
lightning-liquidity: Introduce better error types #4074
Open