Skip to content

itest: reproduce overstated blinded path HTLC maximum - #11531

Open
hieblmi wants to merge 2 commits into
lightningnetwork:masterfrom
hieblmi:hai/blinded-path-amount-limit-itest
Open

hieblmi wants to merge 2 commits into
lightningnetwork:masterfrom
hieblmi:hai/blinded-path-amount-limit-itest

Conversation

@hieblmi

@hieblmi hieblmi commented Nov 6, 2026 •

Copy link
Copy Markdown
Collaborator

Change Description

This is a test-only reproduction to review a reproducible blinded-path HTLC maximum problem. It intentionally fails on current master; no production fix is included. Please confirm the expected amount-limit semantics and diagnosis before we implement a fix.

Introduction-channel bottleneck

The first integration test creates a funded route:

Alice -> Bob (introduction) -> Carol -> Dave (recipient)
             |                    |
             | max HTLC:          | forwarding fee:
             | 1,000,000 msat     | 1,000 msat, zero ppm

Every channel has 100,000 sats of capacity. Policy buffering is explicitly disabled so the test exercises the exact limit. Dave generates a real bLIP 39 invoice with Bob as introduction node. Alice decodes it, queries a route using its blinded path, and submits one HTLC with SendToRouteV2; retries and MPP cannot hide an overstated per-HTLC maximum.

Observed on master at 0c538e1f2:

Recipient amount Advertised maximum Result
999,000 msat 1,000,000 msat Settled
1,000,000 msat 1,000,000 msat Failed at introduction node

Bob's log identifies the cause:

outgoing htlc(...) is too large: max_htlc=1000000 mSAT, htlc_value=1001000 mSAT

The payer receives INVALID_ONION_BLINDING with failure source index 1.

Hidden middle-channel bottleneck

The second case adds a forwarding node inside the blinded path:

Alice -> Bob (introduction) -> Carol -> Dave -> Eve (recipient)

Bob   -> Carol: max HTLC 1,000 sats, fee 0
Carol -> Dave:  max HTLC   500 sats, fee 0  <-- hidden bottleneck
Dave  -> Eve:  max HTLC 1,000 sats, fee 1 sat

Bob remains the introduction node; Carol's outgoing channel limits the path. Dave's downstream fee must fit inside that channel's 500-sat limit. The correct advertised recipient maximum is therefore 500 - 1 = 499 sats (499,000 msat).

For a 499-sat payment, Bob and Carol each forward 500 sats, then Dave deducts his 1-sat fee and delivers 499 sats to Eve. For the currently advertised 500-sat payment, Bob can forward 501 sats within his 1,000-sat limit, but Carol cannot forward 501 sats within her 500-sat limit.

Observed locally against unchanged master production code:

Recipient amount Advertised maximum Result
499,000 msat 500,000 msat Settled
500,000 msat 500,000 msat Rejected at Carol's outgoing channel

Carol's log confirms the hidden bottleneck:

outgoing htlc(...) is too large: max_htlc=500000 mSAT, htlc_value=501000 mSAT

The payer still sees INVALID_ONION_BLINDING with source index 1 (Bob); that public error does not identify the hidden failing node.

Why the limit is overstated

The suspected cause is collectRelayInfo taking the smallest channel maximum, without accounting for the downstream fees also carried by each channel. The fee quote itself is correct in both reproductions. Every channel must fit the recipient amount plus fees paid downstream of that channel. The whole-path maximum must be the most restrictive of those fee-adjusted limits, wherever the bottleneck sits. These examples require maxima of 999,000 and 499,000 msat respectively.

Each test first proves its fee-adjusted boundary is payable, then takes the advertised maximum from the first invoice and attempts that amount in a second invoice. It asserts settlement, exposing the current failure rather than treating it as expected behavior. Default policy buffering can mask this boundary; this test uses supported multipliers of one.

The separate aggregate-fee overflow issue is already fixed on master and is outside this PR.

Steps to Test

make build-itest
make itest-only 'icase=blinded_path_htlc_maximum

Run the cases separately because each deliberately fails its settlement assertion on current master: the control payment settles, then the advertised-maximum payment fails. Both failures have been reproduced locally. This PR is for diagnosis review, not merge.

Pull Request Checklist

Testing

  • All CI checks pass — both integration cases deliberately expose the failure.
  • Both introduction-channel and hidden middle-channel cases include a successful control and a failing boundary payment.
  • A production fix is included — intentionally deferred pending review.

Code Style and Documentation

  • Only the integration test and its registration are changed.
  • Test comments explain the topology, fee calculation, and single-attempt requirement.
  • Commits follow the repository's package-prefix convention.
  • Release note — test-only reproduction; no shipped behavior change.
    timeout=10m
    make itest-only icase=blinded_path_htlc_maximum_middle timeout=10m

Expected current result: the control payment settles, then the advertised-maximum payment fails the settlement assertion. This draft is for diagnosis review, not merge.

## Pull Request Checklist

### Testing

- [ ] All CI checks pass — the new integration test deliberately exposes the failure.
- [x] A successful control payment and the failing boundary payment are included.
- [ ] A production fix is included — intentionally deferred pending review.

### Code Style and Documentation

- [x] Only the integration test and its registration are changed.
- [x] Test comments explain the topology, fee calculation, and single-attempt requirement.
- [x] The commit follows the repository's package-prefix convention.
- [ ] Release note — test-only draft; no shipped behavior change.

A blinded invoice can advertise a recipient amount that exceeds an
intermediate channel limit once downstream fees are included. Add a
four-node test with a successful control payment, then attempt the
maximum advertised by the invoice without retries or MPP.

The settlement assertion intentionally fails on current master. Keep
this test-only reproduction separate from a fix so reviewers can
confirm the expected behavior and diagnosis first.
@github-actions github-actions Bot added ci-hold CI is held; remove this label to run CI severity-low Best-effort review labels Nov 6, 2026
@github-actions

github-actions Bot commented Nov 6, 2026

Copy link
Copy Markdown

🟢 PR Severity: LOW

itest | 2 files | 143 lines changed

🟢 Low (2 files)
  • itest/list_on_test.go - test registration list, test-only change
  • itest/lnd_blinded_path_limits_test.go - new integration test file, test-only change

Analysis

This PR only adds a new integration test (itest/lnd_blinded_path_limits_test.go) and registers it in the test list (itest/list_on_test.go). No production code paths are touched, so this qualifies for best-effort review.


To override, add a severity-override-{critical,high,medium,low} label.

@hieblmi
hieblmi marked this pull request as ready for review November 6, 2026 12:30
@hieblmi
hieblmi requested a review from bitromortac November 6, 2026 12:40
An introduction node need not own the channel that limits a blinded
path. Add a five-node case with a 500-sat hidden channel and a 1-sat
downstream fee, while the introduction channel allows 1,000 sats.

Share the invoice and payment checks with the introduction-channel
case. Both assert that the advertised maximum settles, exposing the
current overstatement after a successful fee-adjusted control payment.
No production fix is included.
@litbot-9000

Copy link
Copy Markdown
Collaborator

@bitromortac: review reminder

1 similar comment
@litbot-9000

Copy link
Copy Markdown
Collaborator

@bitromortac: review reminder

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci-hold CI is held; remove this label to run CI severity-low Best-effort review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants