LSPS5 implementation #3662

martinsaposnic · 2025-03-11T20:12:16Z

A complete implementation for LSPS5 (spec defined here lightning/blips#55)

Reviewing commit by commit is recommended (~40% of the added lines are tests)

Notes:

Persistence of the state will come on a future PR
~~- Will rebase from lightning-liquidity: Introduce EventQueue notifier and wake BP for message processing #3509 once that PR is merged~~ DONE

ldk-reviews-bot · 2025-03-11T20:12:19Z

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

martinsaposnic · 2025-03-11T20:16:28Z

This is a huge PR, but it wasn’t obvious to me how to split it in a way that would still make sense (I did split it into small commits to make it easier to review.). I’m open to suggestions if you have ideas on how this could be structured differently.

codecov · 2025-03-11T20:21:35Z

Codecov Report

Attention: Patch coverage is 86.38596% with 194 lines in your changes missing coverage. Please review.

Project coverage is 88.92%. Comparing base (65d518b) to head (18fe164).
Report is 13 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning-liquidity/src/lsps5/msgs.rs	76.84%	81 Missing and 16 partials ⚠️
lightning-liquidity/src/lsps5/client.rs	90.59%	30 Missing and 3 partials ⚠️
lightning-liquidity/src/lsps5/service.rs	91.16%	20 Missing and 5 partials ⚠️
lightning-liquidity/src/lsps0/ser.rs	79.16%	3 Missing and 17 partials ⚠️
lightning-liquidity/src/lsps5/url_utils.rs	94.87%	1 Missing and 5 partials ⚠️
lightning-liquidity/src/manager.rs	93.84%	2 Missing and 2 partials ⚠️
lightning-liquidity/src/lsps5/validator.rs	95.83%	0 Missing and 3 partials ⚠️
lightning/src/util/test_utils.rs	50.00%	3 Missing ⚠️
lightning/src/ln/blinded_payment_tests.rs	0.00%	2 Missing ⚠️
lightning-liquidity/src/lsps0/msgs.rs	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3662      +/-   ##
==========================================
- Coverage   88.95%   88.92%   -0.04%     
==========================================
  Files         168      173       +5     
  Lines      121974   123393    +1419     
  Branches   121974   123393    +1419     
==========================================
+ Hits       108502   109723    +1221     
- Misses      11072    11216     +144     
- Partials     2400     2454      +54

Flag	Coverage Δ
fuzzing	`22.31% <2.12%> (-0.38%)`	⬇️
tests	`88.74% <86.38%> (-0.04%)`	⬇️

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.

tnull

Wow, thank you for looking into this! I did a first pass, and it looks pretty amazing already!

Before going too much into further details, here are a few general comments upfront:

I'm generally no fan of introducing additional dependencies here, an in particular not reqwest and tokio. I think following the pattern so far BroadcastNotifications could be a request that the user handles with any HTTP client they want and then could call back into LSPS5ServiceHandler. Alternatively, we could also use a trait similar to the current HTTPClient, but I don't think we want to keep the default implementation. Note that the blocking reqwest variant wraps a tokio runtime internally, and therefore should never (1, 2, ...) be used together. I guess technically we could consider a default async version of the trait that uses async reqwest, but I would prefer to simply have well-documented trait on our end that the user can implement however they choose to. Also note that stacking tokio runtimes is heavily discouraged in general, so assuming our users would themselves use a tokio runtime, we shouldn't wrap one in LSPS5ServiceHandler.
Note that lightning-liquidity is optionally no-std compliant, so please don't rely on std wherever possible, often it's just a matter of using core instead and importing the respective types from crate::prelude. If you really find yourselves needing to use std, make sure it's feature gated behind feature = "std" and we provide an alternative for users that don't support it.
Minor: Regarding formatting we're using tabs, not spaces. Feel free to run ./contrib/run-rustfmt.sh after each commit to run our formatting scripts.
This PR in its current scope is great, just want to note that eventually we need to add persistence for the state. As we haven't fully fleshed out the persistence strategy for lightning-liquidity in general yet, it's actually preferred to defer this to a follow-up, but just wanted to mention it. Also note that some changes to MessageQueue/EventQueue will happen in #3509, but will ping you to rebase once that has been merged. (just sidenotes here).

I hope these initial points make sense, let me know if you have any questions, or once you made corresponding changes and think this is ready for the next round of review!

ldk-reviews-bot · 2025-03-13T12:45:04Z

👋 The first review has been submitted!

Do you think this PR is ready for a second reviewer? If so, click here to assign a second reviewer.

tnull · 2025-03-13T12:48:30Z

This is a huge PR, but it wasn’t obvious to me how to split it in a way that would still make sense (I did split it into small commits to make it easier to review.). I’m open to suggestions if you have ideas on how this could be structured differently.

Thanks for asking! I'm totally fine to keep this (with its current scope) in a single PR, as long as we keep the commit history pretty clean to allow continuing review to happen commit-by-commit. To this end, please make sure add any fixup commits clearly marked (e.g. via a f or fixup prefix in the commit message header) directly under the commit they belong to, so they can cleanly be squashed into the respective feature commits in-between review rounds.

tnull · 2025-03-13T12:54:53Z

Btw, I'm not sure if you're familiar with the previous attempt of implementing LSPS5: #3499

Given this is a clean slate, not sure how much there is to learn, but still might be worth a look. Also not sure if @johncantrell97 would be interested in reviewing this PR, too, as he's familiar with the codebase and LSPS5.

martinsaposnic · 2025-03-14T17:11:07Z

@tnull, ready for the next review round!

Removed reqwest and tokio.
HttpClient is now a generic trait, allowing users to pass any implementation.
Removed std.
Small refactor on client and service to be able to delete some silly / unnecessary code.
Ran formatting on every commit.
All new changes are in commits prefixed with fixup:.

CI is failing because of the usage of the url crate (which I guess does not support rust 1.63?), which I need for validating the webhook URL. A new commit will come addressing that shortly

ldk-reviews-bot · 2025-03-17T00:00:52Z

🔔 1st Reminder

Hey @tnull @valentinewallace! 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-03-17T00:00:54Z

🔔 1st Reminder

Hey @tnull @valentinewallace! 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.

martinsaposnic · 2025-07-22T13:42:43Z

@TheBlueMatt just pushed a few commits addressing your comments. let me know what you think

tnull

One last improvement suggestion on the fixups (add a link), otherwise fixups are fine by me and would be good for squashing.

tnull · 2025-07-22T14:36:08Z

lightning/src/sign/mod.rs

+	/// Sign an arbitrary message with the node's secret key.
+	///
+	/// Creates a digital signature of a message given the node's secret. The message is prefixed
+	/// with "Lightning Signed Message:" before signing.


FWIW, we could link to Rusty's spec-in-a-tweet here: https://web.archive.org/web/20191010011846/https://twitter.com/rusty_twit/status/1182102005914800128

looks good 2cb5743

TheBlueMatt

I think I'm happy with this as it is, needs squash, though (I think the need for rebase will go away after squash, but maybe not).

This will be used to allow disabling time-dependent functionality. 'time' is included in the features default.

Introduce new_from_duration_since_epoch constructor from Duration. Also add abs_diff function to use on client / service. Also do feature='time' instead of feature='std' on time related functionality

…5/service when signing notifications

Allows validating webhook URLs without depending on the external url crate.

Define LSPSMessage request, response and error types. Also introduce LSPS5AppName, LSPS5WebhookUrl, WebhookNotification types

Introduce SendWebhookNotification event for LSPS5/service, and also WebhookRegistered, WebhookRegistrationFailed, WebhooksListed, WebhookRemoved and WebhookRemovalFailed events for LSPS5/client.

Implements the LSPS5 webhook registration service that allows LSPs to notify clients of important events via webhooks. This service handles webhook registration, listing, removal, and notification delivery according to the LSPS5 specification.

Implements the client-side functionality for LSPS5 webhook registration, allowing clients to register, list, and remove webhooks with LSPs.

…ions from an LSP. As context, this utility started as part of the client, but was extracted in favor of having it separated, so it's clear that this functions should not be used by the client, but by the proxy server that has to forward the notifications

Fully integrates the LSPS5 webhook components into the lightning-liquidity framework, enabling usage through the LiquidityManager.

martinsaposnic · 2025-07-23T21:29:36Z

conflicts fixed and fixups squashed!

tnull

Alright, since Matt said he's happy I'm gonna land this to reduce the risk of the branch getting stale yet again. We have quite a few follow-ups planned anyways, so can always still iterate on it if we found we missed something.

TheBlueMatt

Did another brief skim through and found a few more things its probably worth following up on.

TheBlueMatt · 2025-07-24T13:41:13Z

lightning-liquidity/src/lsps5/client.rs

+						"Received unexpected request message from {}",
+						counterparty_node_id
+					),
+					action: ErrorAction::IgnoreAndLog(Level::Info),


Oops, we shouldn't log at INFO a peer (any peer, might not be "our LSP") sending us garbage.

TheBlueMatt · 2025-07-24T13:41:32Z

lightning-liquidity/src/lsps5/client.rs

+		};
+		let mut result: Result<(), LightningError> = Err(LightningError {
+			err: format!("Received LSPS5 response from unknown peer: {}", counterparty_node_id),
+			action: ErrorAction::IgnoreAndLog(Level::Error),


Same here, we shouldn't be logging at ERROR a peer sending us garbage.

TheBlueMatt · 2025-07-24T13:42:41Z

lightning-liquidity/src/lsps5/client.rs

+			} else {
+				result = Err(LightningError {
+					err: format!("Received response for unknown request ID: {}", request_id.0),
+					action: ErrorAction::IgnoreAndLog(Level::Info),


TheBlueMatt · 2025-07-24T14:03:55Z

lightning-liquidity/src/lsps5/service.rs

+pub struct LSPS5ServiceConfig {
+	/// Maximum number of webhooks allowed per client.
+	pub max_webhooks_per_client: u32,
+	/// Minimum time between sending the same notification type in hours (default: 24)


Shouldn't this be, like, 30 seconds, not a full day? If a user receives two payments over the course of an hour we definitely want to send two notifications, not eat the second.

TheBlueMatt · 2025-07-24T14:09:37Z

lightning-liquidity/src/manager.rs

+						lsps5_client_handler.handle_message(msg, sender_node_id)?;
+					},
+					None => {
+						return Err(LightningError { err: format!("Received LSPS5 response message without LSPS5 client handler configured. From node = {:?}", sender_node_id), action: ErrorAction::IgnoreAndLog(Level::Info)});


Here and in the logs above we also shouldn't be logging this at INFO level.

martinsaposnic mentioned this pull request Mar 11, 2025

Add bLIP 55: Webhook Registration (LSPS5) lightning/blips#55

Merged

ldk-reviews-bot requested a review from arik-so March 11, 2025 20:22

tnull self-requested a review March 11, 2025 20:37

wpaulino removed the request for review from arik-so March 11, 2025 20:39

tnull reviewed Mar 13, 2025

View reviewed changes

martinsaposnic force-pushed the lsps5 branch from 3aca4fc to 4dbe74d Compare March 14, 2025 14:48

martinsaposnic marked this pull request as draft March 14, 2025 14:49

martinsaposnic force-pushed the lsps5 branch 2 times, most recently from 1d4b47c to edf5346 Compare March 14, 2025 16:31

martinsaposnic marked this pull request as ready for review March 14, 2025 16:31

ldk-reviews-bot requested a review from valentinewallace March 14, 2025 16:32

martinsaposnic requested a review from tnull March 14, 2025 17:12

martinsaposnic force-pushed the lsps5 branch 7 times, most recently from 9809682 to af5929e Compare March 16, 2025 14:24

tnull removed the request for review from valentinewallace March 17, 2025 08:33

martinsaposnic force-pushed the lsps5 branch from af5929e to e018300 Compare March 17, 2025 16:10

tnull reviewed Jul 22, 2025

View reviewed changes

martinsaposnic force-pushed the lsps5 branch from 2d87764 to 3b5aba6 Compare July 22, 2025 14:47

TheBlueMatt reviewed Jul 23, 2025

View reviewed changes

martinsaposnic added 12 commits July 23, 2025 18:11

Introduce 'time' feature in lightning-liquidity.

f7c9d04

This will be used to allow disabling time-dependent functionality. 'time' is included in the features default.

Prefactor - Improvements on LSPSDateTime

b105bc5

Introduce new_from_duration_since_epoch constructor from Duration. Also add abs_diff function to use on client / service. Also do feature='time' instead of feature='std' on time related functionality

Prefactor -> Introduce sign_message on NodeSigner, to be used by LSPS…

8ac732c

…5/service when signing notifications

Add custom URL parser for LSPS5.

c0b8834

Allows validating webhook URLs without depending on the external url crate.

Add LSPS5 message formats for webhook registration

82ae710

Define LSPSMessage request, response and error types. Also introduce LSPS5AppName, LSPS5WebhookUrl, WebhookNotification types

Add LSPS5 service and client events

229dfb0

Introduce SendWebhookNotification event for LSPS5/service, and also WebhookRegistered, WebhookRegistrationFailed, WebhooksListed, WebhookRemoved and WebhookRemovalFailed events for LSPS5/client.

Add LSPS5 webhook service implementation

bc2f990

Implements the LSPS5 webhook registration service that allows LSPs to notify clients of important events via webhooks. This service handles webhook registration, listing, removal, and notification delivery according to the LSPS5 specification.

Add LSPS5 webhook client implementation

867f12b

Implements the client-side functionality for LSPS5 webhook registration, allowing clients to register, list, and remove webhooks with LSPs.

Add LSPS5 module structure

f135fee

Integrate LSPS5 with liquidity manager

2c870fb

Fully integrates the LSPS5 webhook components into the lightning-liquidity framework, enabling usage through the LiquidityManager.

Add tests for LSPS5 client and service.

18fe164

martinsaposnic force-pushed the lsps5 branch from 3b5aba6 to 18fe164 Compare July 23, 2025 21:13

martinsaposnic requested review from tnull and TheBlueMatt July 24, 2025 00:11

tnull approved these changes Jul 24, 2025

View reviewed changes

tnull merged commit ff279d6 into lightningdevkit:main Jul 24, 2025
27 of 28 checks passed

tnull mentioned this pull request Jul 24, 2025

Support client_trusts_lsp on LSPS2 #3838

Draft

TheBlueMatt reviewed Jul 24, 2025

View reviewed changes

LSPS5 implementation #3662

LSPS5 implementation #3662

Uh oh!

Conversation

martinsaposnic commented Mar 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

martinsaposnic commented Mar 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Mar 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

tnull left a comment • 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!

ldk-reviews-bot commented Mar 13, 2025

Uh oh!

tnull commented Mar 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tnull commented Mar 13, 2025

Uh oh!

martinsaposnic commented Mar 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ldk-reviews-bot commented Mar 17, 2025

Uh oh!

ldk-reviews-bot commented Mar 17, 2025

Uh oh!

martinsaposnic commented Jul 22, 2025

Uh oh!

tnull left a comment

Choose a reason for hiding this comment

Uh oh!

tnull Jul 22, 2025

Choose a reason for hiding this comment

Uh oh!

martinsaposnic Jul 22, 2025

Choose a reason for hiding this comment

Uh oh!

TheBlueMatt left a comment

Choose a reason for hiding this comment

Uh oh!

martinsaposnic commented Jul 23, 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!

TheBlueMatt left a comment

Choose a reason for hiding this comment

Uh oh!

TheBlueMatt Jul 24, 2025

Choose a reason for hiding this comment

Uh oh!

TheBlueMatt Jul 24, 2025

Choose a reason for hiding this comment

Uh oh!

TheBlueMatt Jul 24, 2025

Choose a reason for hiding this comment

Uh oh!

TheBlueMatt Jul 24, 2025

Choose a reason for hiding this comment

Uh oh!

TheBlueMatt Jul 24, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

martinsaposnic commented Mar 11, 2025 •

edited

Loading

ldk-reviews-bot commented Mar 11, 2025 •

edited

Loading

martinsaposnic commented Mar 11, 2025 •

edited

Loading

codecov bot commented Mar 11, 2025 •

edited

Loading

tnull left a comment •

edited

Loading

tnull commented Mar 13, 2025 •

edited

Loading

martinsaposnic commented Mar 14, 2025 •

edited

Loading

martinsaposnic commented Jul 23, 2025 •

edited

Loading