LSPS5 implementation

[martinsaposnic]

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

[ldk-reviews-bot]

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

[martinsaposnic]

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]

Codecov Report

Attention: Patch coverage is 86.79868% with 240 lines in your changes missing coverage. Please review.

Project coverage is 89.18%. Comparing base (0e1bbc4) to head (b0b7bad).
Report is 39 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning-liquidity/src/lsps5/service.rs	78.18%	101 Missing and 5 partials ⚠️
lightning-liquidity/src/lsps5/client.rs	89.83%	60 Missing and 2 partials ⚠️
lightning-liquidity/src/lsps0/ser.rs	72.16%	9 Missing and 18 partials ⚠️
lightning-liquidity/src/lsps5/msgs.rs	88.49%	21 Missing and 5 partials ⚠️
lightning-liquidity/src/lsps5/url_utils.rs	95.97%	13 Missing and 1 partial ⚠️
lightning-liquidity/src/manager.rs	90.90%	2 Missing and 2 partials ⚠️
lightning-liquidity/src/lsps0/msgs.rs	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3662      +/-   ##
==========================================
- Coverage   89.21%   89.18%   -0.03%     
==========================================
  Files         155      159       +4     
  Lines      119314   121772    +2458     
  Branches   119314   121772    +2458     
==========================================
+ Hits       106450   108607    +2157     
- Misses      10261    10506     +245     
- Partials     2603     2659      +56     

☔ 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:

1. 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.

2. 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.

3. 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.

4. 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 lightning-liquidity: Introduce EventQueue notifier and wake BP for message processing #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]

👋 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]

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]

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]

@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]

🔔 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]

🔔 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.

[tnull]

Did another parial pass up to (and including) webhook signing.

Please feel free to squash fixups, although some of them need to be changed/dropped (such as un-stding of LSPSDateTime)

[tnull]

FYI I fixed the Rust 1.63.0 build failures by downgrading the url crate to 1.7.2 in this commit.

I'm not thrilled about using such an old version (5+ years). It works, but maybe not ideal.

A few other options:

* I could write a small URL validator that just handles what we need for the webhook validation. It can bring other bugs / issues but eliminates the dependency headache.

* Use feature flags in Cargo.toml

* Bump the MSRV for lightning-liquidity

I can implement any of these alternatives if you think it's worth it. Let me know what you think!

Yes, let's please also drop the url dependency and just write the few checks we need to run on the URLs ourselves. I'd rather avoid introducing feature flags and have LSPS5 available to all users. Bumping MSRV is really no option currently, as we're looking to expose lightning-liquidity in our language bindings, which currently relies on said 1.63 MSRV.

[martinsaposnic]

Hey @tnull, thank you so much for reviewing and answering my questions!

I just pushed some updates, addressing all your comments, including:

• All new crates added before are now deleted
• Correct notification signature
• URL validation is now handled by us (not an external crate)
• Generic time trait for user-provided implementations (with a default std implementation)
• Added tests with spec examples and test vectors (more tests are coming, so we are sure the PR is following the spec byte-for-byte)

This should be ready for the next round of review.

Thanks again!

[tnull]

Thanks for the changes so far, this is def. quickly moving in the right direction!

Added a bunch of more high-level comments, will see to get more into the details in the next round. Feel free to squash current fixups!

[martinsaposnic]

Thanks for the changes so far! This is definitely moving in the right direction quickly.

I’ve added more high-level comments and will get into the details in the next round. Feel free to squash the fixups!

Thanks for the review @tnull!

I've addressed all new comments and pushed them as fixup: commits.

Key changes:

• http_client has been removed. Instead, there's now a SendWebhookNotifications event that informs the user which URLs to call, leaving the actual POST requests to them.
• No more panics or unsafe unwraps.
• TimeProvider can now be injected via an alternative constructor.

CI is taking forever, so I may need to push a few fixes if anything breaks, but this should be ready for review again!

A couple of things I know will get comments:

1. I'm using fromRFC3339 and toRFC3339 from LSPSDateTime, but since timestamps are handled as Duration, I had to introduce a function to convert Duration into LSPSDateTime:

/// Returns the number of seconds since the Unix epoch.
pub fn new_from_duration(duration: Duration) -> Self {
    Self(DateTime::from_timestamp(duration.as_secs() as i64, duration.subsec_nanos()).unwrap())
}

It works, but it’s not the cleanest approach—open to suggestions.

2. The client receives app_name and webhook_url as plain strings, which are then wrapped in LSPS5AppName and LSPS5WebhookUrl via a new method that validates them.

When the event is triggered, the service picks it up and receives already-validated LSPS5AppName and LSPS5WebhookUrl, but it calls validate again to ensure nothing changed.

This pattern—new calls validate, and then validate runs again later—works, but feels a bit redundant. Curious to hear thoughts on whether this is a good approach.

Looking forward to your feedback!