Skip to content

[v0.21.x-branch] Backport #10982: paymentsdb: normalize orphaned blinded total#10986

Merged
ziggie1984 merged 3 commits into
v0.21.x-branchfrom
backport-10982-to-v0.21.x-branch
Jul 22, 2026
Merged

[v0.21.x-branch] Backport #10982: paymentsdb: normalize orphaned blinded total#10986
ziggie1984 merged 3 commits into
v0.21.x-branchfrom
backport-10982-to-v0.21.x-branch

Conversation

@github-actions

Copy link
Copy Markdown

Backport of #10982


Change Description

Fix a KV-to-SQL payment migration failure for historical routes containing a
non-zero blinded total_amt_msat without encrypted recipient data.

SendToRouteV2 historically copied the blinded total amount independently of
the encrypted data. LND did not classify such a hop as blinded at runtime, but
the migration treated the total amount as proof of a blinded hop and attempted
to insert a row with a NULL encrypted_data value. This violated the existing
SQL NOT NULL constraint and prevented LND from starting.

This PR:

  • requires encrypted recipient data when SendToRouteV2 supplies either a
    blinding point or blinded total amount;
  • omits the orphaned total when migrating the historically accepted total-only
    representation;
  • rejects malformed blinding-point-only migration records with payment,
    attempt and hop context;
  • applies the same normalization during KV/SQL migration validation;
  • emits a PYDB warning identifying the affected payment, attempt, hop and
    discarded total amount;
  • keeps the strict SQL schema unchanged.

Steps to Test

make unit-debug log="stdlog trace" \
  pkg=lnrpc/routerrpc \
  case=TestUnmarshallHopBlindedFieldsRequireEncryptedData \
  timeout=10s nocache=1

go test -v -tags="dev test_db_sqlite stdlog trace" \
  ./payments/db/migration1 \
  -run '^(TestMigrateOrphanedBlindedTotalAmount|TestMigrateBlindingPointWithoutEncryptedData) \
  -count=1 -timeout=10s

make unit pkg=lnrpc/routerrpc timeout=5m nocache=1

go test -tags=test_db_sqlite ./payments/db/migration1 \
  -count=1 -timeout=5m

Pull Request Checklist

Testing

  • Your PR passes all CI checks.
  • Tests covering the positive and negative error paths are included.
  • The bug fix contains a regression test triggering the historical case.

Code Style and Documentation

  • The change follows the documentation, commenting and 80-column rules.
  • Commits follow the ideal Git commit structure.
  • New logging uses the PYDB subsystem at warning level.
  • A change description is included in the v0.21.2 release notes.

SendToRouteV2 accepts caller-provided routes. It already required
recipient-encrypted data when a blinding point was present. However, it
copied a blinded total amount independently. This allowed a total-only
hop to enter the payment database even though LND did not classify it
as blinded.

Require encrypted data when either blinded field is supplied. Cover the
rejected combination, a valid blinded total and a regular hop.

(cherry picked from commit ffc6250)
The KV route format stores blinded fields independently. Routes accepted
through SendToRouteV2 could therefore contain a blinded total amount
without encrypted recipient data. The SQL migration treated the total as
proof of a blinded hop and bound nil to the required encrypted-data
column, preventing LND from starting.

Use encrypted recipient data as the blinded-hop discriminator and
normalize only the known total-only case. Reject blinding-point-only
records with payment, attempt and hop context instead of exposing an
opaque SQL constraint error. Log normalized totals, account for them
during migration validation, and cover both cases with regression tests.

(cherry picked from commit 04da2fa)
Document the handling of historical total-only blinded route data and the
new SendToRouteV2 validation that prevents creating such records.

(cherry picked from commit 17ee638)
@github-actions github-actions Bot added this to the v0.21.2 milestone Jul 22, 2026

@ziggie1984 ziggie1984 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM (no merge conflicts)

@ziggie1984
ziggie1984 merged commit 2804a61 into v0.21.x-branch Jul 22, 2026
1 check passed
@ziggie1984
ziggie1984 deleted the backport-10982-to-v0.21.x-branch branch July 22, 2026 18:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant