Add LSPS5 DOS protections. #3993

martinsaposnic · 2025-08-07T14:17:11Z

When handling an incoming LSPS5 request, the manager will check
if the counterparty is 'engaged' in some way before responding.
Engaged meaning = active channel | LSPS2 active operation | LSPS1 active operation.

Logic: If not engaged then reject request;

A single test is added only checking for the active channel condition,
because it's not super easy to get LSPS1-2 on the correct state to check this (yet).
Other tangential work is happening that will make this easier and more tests will come in the near future.

~~A few decisions that could be changed:~~

~~- the DOS protections are optional (default true). maybe this should not be configurable?~~
- I made the dos_protection_enforcer generic enough so it would be possible to add more behavior in the future. also some logic could be moved here like the ignored_peers logic from the manager, which could make sense to move to the dos enforcer

thoughts @tnull ?

ldk-reviews-bot · 2025-08-07T14:17:14Z

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

codecov · 2025-08-07T14:27:05Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88.87%. Comparing base (e1a31e1) to head (b522194).
⚠️ Report is 8 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3993      +/-   ##
==========================================
+ Coverage   88.84%   88.87%   +0.03%     
==========================================
  Files         175      175              
  Lines      127760   127790      +30     
  Branches   127760   127790      +30     
==========================================
+ Hits       113510   113579      +69     
+ Misses      11679    11641      -38     
+ Partials     2571     2570       -1

Flag	Coverage Δ
fuzzing	`21.74% <0.00%> (-0.02%)`	⬇️
tests	`88.71% <100.00%> (+0.03%)`	⬆️

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.

ldk-reviews-bot · 2025-08-11T00:00:14Z

🔔 1st Reminder

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

tnull

Thanks for looking into this!

tnull · 2025-08-11T12:58:47Z

lightning-liquidity/src/dos_protection_enforcer.rs

+use lightning::sign::NodeSigner;
+
+/// A trait for implementing Denial-of-Service (DoS) protection mechanisms for LSP services.
+pub trait DosProtectionEnforcer {


IMO this is over-engineering. We can just have a single method on LSPS5ServiceHandler that checks the necessary bools. I also don't think this warrants to be in a separate module right now.

tnull · 2025-08-11T13:04:10Z

lightning-liquidity/src/lsps2/service.rs

+			peer_state
+				.outbound_channels_by_intercept_scid
+				.values()
+				.any(|c| c.is_pending_channel_open())


Hmm, we'll also want to allow LSPS5 for any activity beyond this point, no? I think rather than adding helpers for each individual state, maybe we finally should expose the list of OutboundJITChannelStates at least pub(crate) and also implement Ord for OutboundJITChannelState? This would allow us to use comparison operators on the channel states.

Also, can we somehow enforce that for a pending payment, we'd always first process it and advance the LSPS2 state before evaluating whether we can notifiy the LSPS5 client?

what I thought here (and I didn't clarify, sorry) is that it should only check for the pending_channel_open. after that state, the channel will be opened and the LSPS5 service has_active_channels check will kick in, so there is no point on checking the other LSPS2 states. does that make sense?

tnull · 2025-08-11T13:05:18Z

lightning-liquidity/src/manager.rs

+							if !self.peer_is_engaged(sender_node_id) {
+								return Err(LightningError {
+                                    err: format!(
+                                        "Rejecting LSPS5 request from {:?} without existing engagement",


"existing engagement" is pretty unclear terminology, would be good to find more intuitive wording.

tnull · 2025-08-11T13:05:42Z

lightning-liquidity/src/manager.rs

+                                        "Rejecting LSPS5 request from {:?} without existing engagement",
+                                        sender_node_id
+                                    ),
+                                    action: ErrorAction::IgnoreAndLog(Level::Info),


Please don't log on on Info here.

tnull · 2025-08-11T13:06:53Z

lightning-liquidity/src/lsps5/service.rs

@@ -64,6 +64,8 @@ struct StoredWebhook {
 pub struct LSPS5ServiceConfig {
 	/// Maximum number of webhooks allowed per client.
 	pub max_webhooks_per_client: u32,
+	/// Require an existing channel or active LSPS1/LSPS2 flow before accepting requests.
+	pub enforce_dos_protections: bool,


Let's at least start out with enabling this by default, i.e., don't make it configurable.

ldk-reviews-bot · 2025-08-11T13:08:15Z

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

martinsaposnic · 2025-08-11T18:57:00Z

@tnull thanks for the review! I think this is a much better

I pushed a fixup commit addressing all the comments ffe25e6

I still have my doubts regarding this:

can we somehow enforce that for a pending payment, we'd always first process it and advance the LSPS2 state before evaluating whether we can notifiy the LSPS5 client?

I think that maybe that's not necessary and I posted a question related to that: #3993 (comment)

thanks!

tnull

Thanks, much cleaner already! Some comments.

lightning-liquidity/src/lsps1/service.rs

tnull · 2025-08-12T06:59:24Z

lightning-liquidity/src/lsps2/service.rs

@@ -108,8 +108,8 @@ struct ForwardPaymentAction(ChannelId, FeePayment);
 struct ForwardHTLCsAction(ChannelId, Vec<InterceptedHTLC>);

 /// The different states a requested JIT channel can be in.
-#[derive(Debug)]
-enum OutboundJITChannelState {
+#[derive(Clone, Debug, PartialEq, Eq)]


Why does this need to be Clone suddenly?

#3993 (comment)

tnull · 2025-08-12T07:01:42Z

lightning-liquidity/src/lsps2/service.rs

@@ -134,6 +134,30 @@ enum OutboundJITChannelState {
 	PaymentForwarded { channel_id: ChannelId },
 }

+impl OutboundJITChannelState {


Do we need this explicit implementation? Wouldn't derive(PartialOrd) do the ~the same thing?

this would need putting also the derive(Ord) and derive(PartialOrd) on PaymentQueue and InterceptId

happy to do it but wanted to minimize changes

seems like I can't define Ord but derive PartialOrd

from the linter:

error: you are implementing `Ord` explicitly but have derived `PartialOrd` --> lightning-liquidity/src/lsps2/service.rs:164:1 | 164 | / impl Ord for OutboundJITChannelState { 165 | | fn cmp(&self, other: &Self) -> core::cmp::Ordering { 166 | | self.stage().cmp(&other.stage()) 167 | | } 168 | | } | |_^

Ah, sorry. Then I have to eat my words. I'd actually prefer the way you had vs. introducing the redundant ..Stage object. Sorry, mind reverting to explicitly implementing it?

tnull · 2025-08-12T07:02:48Z

lightning-liquidity/src/lsps2/service.rs

+		let outer_state_lock = self.per_peer_state.read().unwrap();
+		if let Some(inner_state_lock) = outer_state_lock.get(counterparty_node_id) {
+			let peer_state = inner_state_lock.lock().unwrap();
+			peer_state.outbound_channels_by_intercept_scid.values().map(|c| c.state.clone()).max()


I don't buy we need to clone here.

error[E0507]: cannot move out of `c.state` which is behind a shared reference --> lightning-liquidity/src/lsps2/service.rs:599:68 | 599 | peer_state.outbound_channels_by_intercept_scid.values().map(|c| c.state).max() | ^^^^^^^ move occurs because `c.state` has type `OutboundJITChannelState`, which does not implement the `Copy` trait | help: consider cloning the value if the performance cost is acceptable | 599 | peer_state.outbound_channels_by_intercept_scid.values().map(|c| c.state.clone()).max() | ++++++++

Let me rephrase: we definitely can't clone the entire state, with all the HTLC data, etc each time we want to check whether a client reached a certain state. I still think handling all the state by reference should be doable, but it's probably easiest to mirror the fn has_active_requests(&self, counterparty_node_id: &PublicKey) -> bool above.

(While eventually we want to give users insight into the held state, it doesn't need to happen in this PR, so for now it's probably easiest to revert to having OutboundJITChannelState private, and just check the bool returned by the helper mentioned above)

tnull · 2025-08-12T07:04:26Z

lightning-liquidity/src/lsps5/service.rs

+	) -> bool {
+		self.client_has_open_channel(client_id)
+			|| lsps1_has_activity
+			|| lsps2_max_state.map_or(false, |s| {


Hmm, why not just use >= PendingChannelOpen now that we can?

this could not be done directly because I would need to create some dummy properties for the PendingChannelOpen struct for it to be able to compare:

|s| s >= OutboundJITChannelState::PendingChannelOpen { payment_queue: PaymentQueue::new(), opening_fee_msat: 0 })

I prefer not to do this so went with something different:

dropped the OutboundJITChannelState::ord_index()

instead, I created a new enum OutboundJITStage that matches one to one with OutboundJITChannelState but has no properties. this new OutboundJITStage has Derive(ord, partialOrd) so it just grabs the declaration order for its ordering

with this, now we can do |s| s.stage() >= OutboundJITStage::PendingChannelOpen

Ah, see #3993 (comment)

I'd prefer not to introduce a redundant object here. Sorry for the noise.

martinsaposnic · 2025-08-12T18:31:45Z

I squashed the last fixup commit and created a new fixup commit addressing the latest comments

also responded to some of the comments that may need a follow up

thanks @tnull !

martinsaposnic · 2025-08-13T17:56:35Z

just pushed a fixup commit addressing the latest comments a74c585

made the OutboundJITChannelState private again
on lsps2/service, have a bool function that returns if the node_id has an opening or open channel
use that new function on the manager and on lsps5/service

let me know what you think @tnull , thanks!!

tnull · 2025-08-15T12:06:50Z

lightning-liquidity/src/lsps2/service.rs

+			peer_state.outbound_channels_by_intercept_scid.values().any(|chan| {
+				matches!(
+					chan.state,
+					OutboundJITChannelState::PendingChannelOpen { .. }


Wait, how do we imagine this to work for the initial LSPS2 receive? If we only allow clients to even register for notifications once we already have a (pending) channel open, how would a first-time user's phone get notified to wake up and accept the channel when they receive the very first payment?

I think we'd need to extend this to also accept LSPS5 requests for PendingInitialPayment?

yeah, that makes sense. I will update this

@tnull let me know what you think 8f2805a. thanks!!

tnull

Alright, this should be good for a second reviewer.

In the meantime, it's gonna need a rebase.

ldk-reviews-bot · 2025-08-19T09:55:33Z

✅ Added second reviewer: @jkczyz

When handling an incoming LSPS5 request, the manager will check if the counterparty is 'engaged' in some way before responding. `Engaged` meaning = active channel | LSPS2 active operation | LSPS1 active operation. Logic: `If not engaged then reject request;` A single test is added only checking for the active channel condition, because it's not super easy to get LSPS1-2 on the correct state to check this (yet). Other tangential work is happening that will make this easier and more tests will come in the near future

- refactor highest_state_for_peer and has_active_requests for better readabiliy - refactor ordering logic OutboundJITChannelState

…hecking if lsps2 has any pendingChannelOpen or above

…tboundJITChannelState

martinsaposnic · 2025-08-19T12:43:28Z

it's gonna need a rebase.

done ✅

TheBlueMatt · 2025-08-19T17:26:41Z

lightning-liquidity/src/lsps1/service.rs

+		let outer_state_lock = self.per_peer_state.read().unwrap();
+		outer_state_lock.get(counterparty_node_id).map_or(false, |inner| {
+			let peer_state = inner.lock().unwrap();
+			!(peer_state.pending_requests.is_empty()


Hmmm, how are we thinking about whether pending_requests counts? I mean on the one hand not counting it is gonna cause issues cause users are gonna register a webhook quickly and see it fail (tho they should retry), on the other hand, a pending request that we haven't even responded to feels like it shouldn't count - it just means they've sent us a message and we haven't responded yet.

TheBlueMatt · 2025-08-19T17:29:55Z

lightning-liquidity/src/manager.rs

+						let lsps2_has_active_requests = self
+							.lsps2_service_handler
+							.as_ref()
+							.map_or(false, |h| h.has_active_requests(sender_node_id));
+						#[cfg(lsps1_service)]
+						let lsps1_has_active_requests = self
+							.lsps1_service_handler
+							.as_ref()
+							.map_or(false, |h| h.has_active_requests(sender_node_id));
+						#[cfg(not(lsps1_service))]
+						let lsps1_has_active_requests = false;
+
+						if !lsps5_service_handler.can_accept_request(


Should we move all this logic to only running when we get a message that indicates we're allocating state, rather than ignoring all messages from a peer?

martinsaposnic mentioned this pull request Aug 7, 2025

LSPS5 Follow ups #3944

Open

18 tasks

ldk-reviews-bot requested a review from joostjager August 7, 2025 14:28

tnull requested review from tnull and removed request for joostjager August 7, 2025 17:53

tnull reviewed Aug 11, 2025

View reviewed changes

martinsaposnic force-pushed the lsps5-dos branch 2 times, most recently from 38c8436 to ffe25e6 Compare August 11, 2025 18:50

martinsaposnic requested a review from tnull August 11, 2025 18:57

martinsaposnic force-pushed the lsps5-dos branch from ffe25e6 to aab6332 Compare August 11, 2025 19:20

tnull reviewed Aug 12, 2025

View reviewed changes

martinsaposnic force-pushed the lsps5-dos branch 5 times, most recently from 8eaea29 to 9a59755 Compare August 12, 2025 16:57

martinsaposnic requested a review from tnull August 12, 2025 18:31

tnull removed their request for review August 13, 2025 07:01

martinsaposnic requested a review from tnull August 13, 2025 17:56

martinsaposnic force-pushed the lsps5-dos branch 3 times, most recently from 142842b to 109de16 Compare August 13, 2025 18:24

tnull reviewed Aug 15, 2025

View reviewed changes

martinsaposnic requested a review from tnull August 18, 2025 15:02

tnull reviewed Aug 19, 2025

View reviewed changes

ldk-reviews-bot requested a review from jkczyz August 19, 2025 09:55

tnull requested review from TheBlueMatt and removed request for jkczyz August 19, 2025 09:55

martinsaposnic added 4 commits August 19, 2025 09:40

fixup: address comments. changes:

1eb5051

- refactor highest_state_for_peer and has_active_requests for better readabiliy - refactor ordering logic OutboundJITChannelState

fixup: make OutboundJITChannelState private, and do bool helper for c…

cb66a95

…hecking if lsps2 has any pendingChannelOpen or above

fixup: accept lsps5 requests if lsps2 has an active request in any Ou…

b522194

…tboundJITChannelState

martinsaposnic force-pushed the lsps5-dos branch from 8f2805a to b522194 Compare August 19, 2025 12:43

TheBlueMatt reviewed Aug 19, 2025

View reviewed changes

Add LSPS5 DOS protections. #3993

Are you sure you want to change the base?

Add LSPS5 DOS protections. #3993

Uh oh!

Conversation

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

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Codecov Report

Uh oh!

ldk-reviews-bot commented Aug 11, 2025

Uh oh!

tnull left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ldk-reviews-bot commented Aug 11, 2025

Uh oh!

martinsaposnic commented Aug 11, 2025

Uh oh!

tnull left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

martinsaposnic commented Aug 12, 2025

Uh oh!

martinsaposnic commented Aug 13, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tnull left a comment

Choose a reason for hiding this comment

martinsaposnic commented Aug 7, 2025 •

edited

Loading

ldk-reviews-bot commented Aug 7, 2025 •

edited

Loading

codecov bot commented Aug 7, 2025 •

edited

Loading

martinsaposnic Aug 11, 2025 •

edited

Loading

tnull Aug 13, 2025 •

edited

Loading