Enforce Trampoline Constraints (replacement) by carlaKC · Pull Request #4226 · lightningdevkit/rust-lightning

carlaKC · 2025-11-17T18:03:17Z

This PR replaces #3983, adding validation of trampoline onions (as compared to the outer onion). It makes some quite significant changes to the tests in the original PR to consolidate blinded and unblinded tests for success/failure scenarios into a single helper (apologies to reviewers who've already looked at the tests, but I think this DRYs it up quite nicely).

While we're here, it also moves rustfmt::skip to a per-function level on blinded_payment_tests.rs and formats the existing test helper that we're modifying in a pre-factor so that the new code can be formatted.

ldk-reviews-bot · 2025-11-17T18:03:20Z

👋 Thanks for assigning @tankyleo 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-11-17T18:03:52Z

 }),
- onion_utils::Hop::TrampolineForward { next_trampoline_hop_data, next_trampoline_hop_hmac, new_trampoline_packet_bytes, trampoline_shared_secret, .. } => {
+ onion_utils::Hop::TrampolineForward { ref outer_hop_data, next_trampoline_hop_data, next_trampoline_hop_hmac, new_trampoline_packet_bytes, trampoline_shared_secret, .. } => {
+ // TODO: return reason as forward issue, not as receiving issue when forwarding is ready.


I'm not quite clear on what this todo means, still catching up on some context - @a-mpch could you help me out?

carlaKC · 2025-11-17T18:04:57Z

Assigning reviewers who looked at the original PR - please free yourself if not appropriate!

codecov · 2025-11-17T19:31:39Z

Codecov Report

❌ Patch coverage is 92.33129% with 25 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.32%. Comparing base (6d9c676) to head (785c781).
⚠️ Report is 17 commits behind head on main.

Files with missing lines	Patch %	Lines
lightning/src/ln/onion_payment.rs	70.00%	15 Missing ⚠️
lightning/src/ln/onion_utils.rs	0.00%	6 Missing ⚠️
lightning/src/ln/blinded_payment_tests.rs	98.47%	3 Missing and 1 partial ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #4226 +/- ##
==========================================
- Coverage 89.32% 89.32% -0.01% 
==========================================
Files 180 180 Lines 138641 138916 +275 Branches 138641 138916 +275 ==========================================
+ Hits 123844 124088 +244 - Misses 12174 12205 +31 
Partials 2623 2623

Flag	Coverage Δ
fuzzing	`34.97% <0.00%> (-1.01%)`	⬇️
tests	`88.69% <92.33%> (+<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.

carlaKC · 2025-11-17T21:26:04Z

One thing to note about the tests here: we've currently only got coverage for blinded receives checking the constraints (this is what the original PR had). We could also add coverage for blinded forwards in the failure case (can't do for success because we just fail the forwards rn), which would make codecov a bit happier.

I think this is worth doing, but it would mean adding a bit more code to the mega test helper - interested on hearing thoughts on how readable others find it before adding another layer to an already quite dense test! Can also easily be a small follow. up.

valentinewallace · 2025-11-18T19:43:04Z

Needs rebase :(

I did find the new testing not ideal from a readability PoV at first glance, going to take a closer look in a bit but let me know if you see any obvious ways to improve things. It may be that the nature of what we're testing makes it hard to improve things though.

valentinewallace · 2025-11-18T23:07:50Z

+}
+
+// Creates a replacement onion that is used to produce scenarios that we don't support, specifically
+// unblinded receives and invalid payloads.


Here and a few other places, I thought we did support unblinded trampoline receives but didn't support unblinded trampoline sends. At least I can't see where we reject them + it seems like we understand how to decode the payload 👀 may be missing something though

Badly worded comment - we don't support creating payloads (sends) with unblinded receives, I'll fix!

valentinewallace · 2025-11-18T23:43:48Z

- onion_utils::Hop::TrampolineForward { next_trampoline_hop_data, next_trampoline_hop_hmac, new_trampoline_packet_bytes, trampoline_shared_secret, .. } => {
+ onion_utils::Hop::TrampolineForward { ref outer_hop_data, next_trampoline_hop_data, next_trampoline_hop_hmac, new_trampoline_packet_bytes, trampoline_shared_secret, .. } => {
+ // TODO: return reason as forward issue, not as receiving issue when forwarding is ready.
+ check_trampoline_onion_constraints(outer_hop_data, next_trampoline_hop_data.outgoing_cltv_value, next_trampoline_hop_data.amt_to_forward)?;


I'm a bit confused why we're calling this method here. It only returns IncorrectFinal* errors, which seems like it should only be used for receives and not forwards. I might be missing something from the trampoline spec here? Or do we need a new similar method for forwards that will return some of the new errors, like TrampolineFeeOrExpiryInsufficient, if the cltv/forward amount are mismatching between the inner and outer onion?

This is the todo I'm not so sure about. It seems to me like the approach in the original PR is to add this validation here (even though it's not in the spec) and then remove it when we add more forwarding logic. cc @a-mpch?
I think that we can remove check_trampoline_onion_constraints on the forwarding branches and get to them in subsequent PRs, but just want to make sure I'm not missing context from the original change.

We need to check the trampoline constraints in forwarding branches when implementing the forwarding. We can safely remove it and re-added in follow up PRs.
As at this point we don't have implemented this error: https://github.com/lightning/bolts/pull/836/files#diff-ad65f0beaac5cef88f5fd7a8b9ca36cbc5a790f4815b4b50b9ea794a55aaf012R1441
That would be returned here.

Going to go ahead with removing the forwarding check and will re-add when we get to more forwarding logic.

ldk-reviews-bot · 2025-11-19T18:05:37Z

🔔 1st Reminder

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

To allow formatting on new code, move to per-function skips.

Remove skip without fixing up any of the ugly formatting, so that the diff is a bit more readable in review.

This commit adds three new local htlc failure error reasons: `TemporaryTrampolineFailure`, `TrampolineFeeOrExpiryInsufficient`, and `UnknownNextTrampoline` for trampoline payment forwarding failures.

carlaKC · 2025-11-20T13:56:06Z

Rebased + addressed review in fixups, removing validation of trampoline forwards because we'll need a different check/error there anyway.

valentinewallace

LGTM, feel free to squash!

ldk-reviews-bot · 2025-11-22T00:00:18Z

🔔 2nd Reminder

Hey @tankyleo! 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-11-24T00:01:06Z

🔔 3rd Reminder

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

tankyleo

Just two nits, thanks for your patience, took the time to read up on blinded paths + trampoline so I can review future PRs :)

Tests are added to cover validation of blinded and unblinded trampoline payloads against their outer onion. These are consolidated with our existing coverage for successful receives. Co-authored-by: Arik Sosman <git@arik.io> Co-authored-by: Maurice Poirrier <mpch@hey.com>

carlaKC · 2025-11-25T13:29:57Z

Addressed last two nits directly on commit, diff here.

ldk-reviews-bot · 2025-11-27T03:17:58Z

🔔 1st Reminder

Hey @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-11-29T03:18:14Z

🔔 2nd Reminder

Hey @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-12-01T03:19:04Z

🔔 3rd Reminder

Hey @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.

valentinewallace

Looks good, one comment that I think should be addressed but feel free to land and save for follow-up

valentinewallace · 2025-12-01T19:25:12Z

+ ) {
+ Ok((amt, cltv)) => (amt, cltv),
+ Err(()) => {
+ return encode_relay_error("Trampoline blinded forward amt or CLTV values exceeded the outer onion's",


nit: I think this change could've been a bit better suited to a separate commit, also this error message is a bit weird since there isn't an explicit forward amount/cltv for blinded trampoline forwards

valentinewallace · 2025-12-01T19:29:51Z

 	(40, HTLCMaximum),
 	(41, PeerOffline),
-	(42, ChannelBalanceOverdrawn)
+	(42, ChannelBalanceOverdrawn),


Sorry I just noticed this, on line 1778 we have a macro that says "Error codes that represent BOLT04 error codes must be included here", which looks like it should include these new errors

carlaKC commented Nov 17, 2025
View reviewed changes

carlaKC changed the title ~~3983 trampoline constraints~~Enforce Trampoline Constraints (replacement)Nov 17, 2025

carlaKC requested review from tankyleo and valentinewallace November 17, 2025 18:04

carlaKC mentioned this pull request Nov 17, 2025
Trampoline Forwarding: Enforce trampoline constraints #3983
Closed

carlaKC added this to Weekly Goals Nov 17, 2025

carlaKC self-assigned this Nov 17, 2025

valentinewallace reviewed Nov 18, 2025
View reviewed changes

carlaKCand others added 4 commits November 20, 2025 08:47

ln/fmt: move rustfmt_skip to per-function in blinded_payment_tests
e11b30c
To allow formatting on new code, move to per-function skips.

ln/fmt: remove rustfmt::skip from do_test_trampoline_unblinded_receive
8c9e01e
Remove skip without fixing up any of the ugly formatting, so that the diff is a bit more readable in review.

ln/fmt: clean up ugly formatting of do_test_trampoline_unblinded_receive
26a2222

ln: add trampoline LocalHTLCFailureReason variants per spec
269eb6b
This commit adds three new local htlc failure error reasons: `TemporaryTrampolineFailure`, `TrampolineFeeOrExpiryInsufficient`, and `UnknownNextTrampoline` for trampoline payment forwarding failures.

carlaKC force-pushed the 3983-trampoline-constraints branch from b43670e to 531cca6Compare November 20, 2025 13:50

carlaKC requested a review from valentinewallace November 20, 2025 15:19

valentinewallace reviewed Nov 20, 2025
View reviewed changes

carlaKC force-pushed the 3983-trampoline-constraints branch from 136641d to 6b5cd30Compare November 20, 2025 16:40

tankyleo previously approved these changes Nov 25, 2025
View reviewed changes

Comment threadlightning/src/ln/blinded_payment_tests.rs Outdated
Comment threadlightning/src/ln/msgs.rs Outdated

tankyleo requested a review from valentinewallace November 25, 2025 03:17

carlaKC dismissed tankyleo’s stale review via 785c781November 25, 2025 13:29

carlaKC force-pushed the 3983-trampoline-constraints branch from 6b5cd30 to 785c781Compare November 25, 2025 13:29

carlaKC requested a review from tankyleo November 25, 2025 14:55

tankyleo approved these changes Nov 25, 2025
View reviewed changes

valentinewallace approved these changes Dec 1, 2025
View reviewed changes

carlaKC merged commit 3e186bc into lightningdevkit:mainDec 1, 2025
26 checks passed

github-project-automationBot moved this to Done in Weekly Goals Dec 1, 2025

carlaKC mentioned this pull request Dec 1, 2025
Minor followups for 4226 #4252
Merged

Uh oh!

Conversation

carlaKC commented Nov 17, 2025

Uh oh!

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

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

carlaKC commented Nov 17, 2025

Uh oh!

codecovBot commented Nov 17, 2025• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

carlaKC commented Nov 17, 2025

Uh oh!

valentinewallace commented Nov 18, 2025• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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!

ldk-reviews-bot commented Nov 19, 2025

Uh oh!

carlaKC commented Nov 20, 2025

Uh oh!

valentinewallace left a comment

Choose a reason for hiding this comment

Uh oh!

ldk-reviews-bot commented Nov 22, 2025

Uh oh!

ldk-reviews-bot commented Nov 24, 2025

Uh oh!

tankyleo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

carlaKC commented Nov 25, 2025

Uh oh!

ldk-reviews-bot commented Nov 27, 2025

Uh oh!

ldk-reviews-bot commented Nov 29, 2025

Uh oh!

ldk-reviews-bot commented Dec 1, 2025

Uh oh!

valentinewallace 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!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

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

codecovBot commented Nov 17, 2025•
edited
Loading

valentinewallace commented Nov 18, 2025•
edited
Loading