Use LocalHTLCFailureReason in Onion Processing #3744

carlaKC · 2025-04-17T20:48:36Z

This PR contains some of the follow ups that didn't make it into #3601:

Implement Display for LocalHTLCFailureReason
Use LocalHTLCFailureReason in onion error processing, removing the last few places where we were using raw u16 values
Adds a very simple macro to de-dup use of u16 failure codes in failure_code and from<u16> to dedup codes

ldk-reviews-bot · 2025-04-17T20:48:38Z

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

carlaKC · 2025-04-21T13:47:47Z

@joostjager anything else that you'd like to add here?

In some places where we have LocalHTLCFailureReason, the string we're passing around is redundant. This isn't the case in all uses of LocalHTLCFailureReason, for example InboundHTLCError provides additional information about payload and blinding related errors that isn't captured in LocalHTLCFailureReason. In these cases we keep the error string, tolerating some duplication.

These error codes were removed from the specification seven years ago to prevent probing, so we don't need to handle these cases anymore.

joostjager

The only comment that I think may not be in this PR is #3601 (comment)

If that one still applies now of course.

joostjager · 2025-04-21T16:37:43Z

lightning/src/ln/onion_payment.rs

@@ -601,19 +601,18 @@ where

 pub(super) fn check_incoming_htlc_cltv(
 	cur_height: u32, outgoing_cltv_value: u32, cltv_expiry: u32
-) -> Result<(), (&'static str, LocalHTLCFailureReason)> {
+) -> Result<(), LocalHTLCFailureReason> {


In decode_incoming_update_add_htlc_onion, encode_malformed_error could have its message param dropped perhaps.

We lose some information from the encode_relay_error calls eg: "Underflow calculating outbound amount or cltv value for blinded forward" just turns into InvalidOnionBlinding.

Tension between internal/api struct shows up there.

Doesn't that indicate that another enum value is needed, that is mapped to InvalidOnionBlinding on the wire?

We could add that, but IMO it's not interesting to surface that on the API, and they all map to the same bolt04 code.

So we'd be adding a new enum variant just for the sake of getting rid of a string - not worth the change IMO.

It isn't completely clear to me why something like Underflow calculating outbound amount or cltv value for blinded forward isn't interesting to surface on the API, while other internal reasons that are also not uniquely mapped to a bolt code are.

This particular string also occurs in the code base multiple times.

But fine to leave as is.

To me, blinding errors are totally useless to a forwarding node because somebody else made a mistake.

Other non-bolt04 errors like liquidity errors (actionable) and private channel aliases (interesting, somebody is probing you) just seem much more obvious candidates to be surfaced.

That said, there's also things like ZeroAmount that we've surfaced which arguably aren't interesting either (buggy sender), but they happened to be co-located with other interesting errors - so acknowledge that there isn't one pure logical reason for this, some of it is just what was easy/reasonable to do.

Noted in #3753.

lightning/src/ln/channel.rs

lightning/src/util/errors.rs

carlaKC · 2025-04-23T13:41:43Z

The only comment that I think may not be in this PR is #3601 (comment)

Addressed in 2cc8799

lightning/src/ln/channel.rs

joostjager · 2025-04-25T18:04:53Z

lightning/src/ln/onion_payment.rs

@@ -601,19 +601,18 @@ where

 pub(super) fn check_incoming_htlc_cltv(
 	cur_height: u32, outgoing_cltv_value: u32, cltv_expiry: u32
-) -> Result<(), (&'static str, LocalHTLCFailureReason)> {
+) -> Result<(), LocalHTLCFailureReason> {


Doesn't that indicate that another enum value is needed, that is mapped to InvalidOnionBlinding on the wire?

lightning/src/ln/onion_utils.rs

ldk-reviews-bot · 2025-04-25T21:48:56Z

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

ldk-reviews-bot · 2025-04-28T13:03:33Z

✅ Added second reviewer: @wpaulino

De-duplicate use of u16 failure codes by using a macro that will match against each variant's failure_code instead.

carlaKC · 2025-04-28T20:28:23Z

@joostjager your approval came in before I could address last comment last comment - diff here 🙏

valentinewallace · 2025-04-29T21:48:38Z

lightning/src/ln/onion_utils.rs

@@ -1651,14 +1652,42 @@ impl LocalHTLCFailureReason {
 		}
 	}

+	fn get_onion_debug_field(&self) -> (&'static str, usize) {


nit: document return values

valentinewallace · 2025-04-29T22:09:47Z

lightning/src/ln/onion_utils.rs

+		self.failure_code() == LocalHTLCFailureReason::IncorrectPaymentDetails.failure_code()
+			|| *self == LocalHTLCFailureReason::FinalIncorrectCLTVExpiry
+			|| *self == LocalHTLCFailureReason::FinalIncorrectHTLCAmount
+			|| *self == LocalHTLCFailureReason::MPPTimeout


I think this is intended to only apply to errors that directly map from onion codes, but we could also include InvalidKeysendPreimage and PaymentSecretRequired here if we expect this method to be used elsewhere in the future.

valentinewallace · 2025-04-29T22:24:01Z

lightning/src/ln/onion_utils.rs

 				error_code,
+				error_code.failure_code(),
 				debug_field,
 				log_bytes!(&err_packet.failuremsg[4..4 + debug_field_size]),
-				description
+				error_code


nit: no need to log error_code twice, similar below

valentinewallace · 2025-04-29T22:38:51Z

lightning/src/ln/onion_utils.rs

@@ -1713,6 +1713,86 @@ impl From<u16> for LocalHTLCFailureReason {
 	}
 }

+impl fmt::Display for LocalHTLCFailureReason {


I'm a bit hesitant on adding this, mainly because I'm not sure it adds much since the enum variant names are already nicely descriptive and can be easily cross-referenced to the LDK docs if more detail is desired. I also think one of the reasons we had strings to begin with was due to the lack of a nice enum, which we now have. We'll also need to remember to update these strings if any docs on the enum change, potentially. Don't feel tooo strongly about it though.

ln: implement Display for LocalHTLCFailureReason

29f0ccb

carlaKC force-pushed the 3541-followups branch from 3a56ca6 to 503d13b Compare April 21, 2025 13:47

carlaKC added 2 commits April 21, 2025 11:26

ln/fix: remove legacy payment related error codes

54f18b8

These error codes were removed from the specification seven years ago to prevent probing, so we don't need to handle these cases anymore.

carlaKC force-pushed the 3541-followups branch from 503d13b to 7c78b01 Compare April 21, 2025 15:28

joostjager reviewed Apr 21, 2025

View reviewed changes

carlaKC marked this pull request as ready for review April 23, 2025 13:43

carlaKC requested a review from joostjager April 23, 2025 13:43

joostjager reviewed Apr 25, 2025

View reviewed changes

joostjager previously approved these changes Apr 26, 2025

View reviewed changes

ldk-reviews-bot requested a review from wpaulino April 28, 2025 13:03

wpaulino requested review from valentinewallace and removed request for wpaulino April 28, 2025 16:25

carlaKC added 2 commits April 28, 2025 16:03

ln/refactor: use LocalHTLCFailureCodes in onion error processing

f89ba52

ln/refactor: macro to impl From<u16> for LocalHTLCFailureReason

d105761

De-duplicate use of u16 failure codes by using a macro that will match against each variant's failure_code instead.

carlaKC dismissed joostjager’s stale review via d105761 April 28, 2025 20:27

carlaKC force-pushed the 3541-followups branch from 7c78b01 to d105761 Compare April 28, 2025 20:27

carlaKC requested a review from joostjager April 28, 2025 20:28

carlaKC mentioned this pull request Apr 28, 2025

Enhancements for LocalHTLCFailureReason #3753

Open

joostjager approved these changes Apr 28, 2025

View reviewed changes

valentinewallace reviewed Apr 29, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Use LocalHTLCFailureReason in Onion Processing #3744

Use LocalHTLCFailureReason in Onion Processing #3744

carlaKC commented Apr 17, 2025

ldk-reviews-bot commented Apr 17, 2025 •

edited

Loading

carlaKC commented Apr 21, 2025

joostjager left a comment

joostjager Apr 21, 2025

carlaKC Apr 23, 2025

joostjager Apr 25, 2025

carlaKC Apr 26, 2025

joostjager Apr 26, 2025 •

edited

Loading

carlaKC Apr 28, 2025

carlaKC Apr 28, 2025

carlaKC commented Apr 23, 2025

joostjager Apr 25, 2025

ldk-reviews-bot commented Apr 25, 2025

ldk-reviews-bot commented Apr 28, 2025

carlaKC commented Apr 28, 2025

valentinewallace Apr 29, 2025

valentinewallace Apr 29, 2025

valentinewallace Apr 29, 2025

valentinewallace Apr 29, 2025

Use LocalHTLCFailureReason in Onion Processing #3744

Are you sure you want to change the base?

Use LocalHTLCFailureReason in Onion Processing #3744

Conversation

carlaKC commented Apr 17, 2025

ldk-reviews-bot commented Apr 17, 2025 • edited Loading

carlaKC commented Apr 21, 2025

joostjager left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joostjager Apr 26, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

carlaKC commented Apr 23, 2025

Choose a reason for hiding this comment

ldk-reviews-bot commented Apr 25, 2025

ldk-reviews-bot commented Apr 28, 2025

carlaKC commented Apr 28, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ldk-reviews-bot commented Apr 17, 2025 •

edited

Loading

joostjager Apr 26, 2025 •

edited

Loading