LND

Merge pull request #11024 from ziggie1984/invoices-update-validation

invoices: refine update handling

invoices: refine update handling

docs: update 0.21.2 release notes

docs: move gossip bounds note to v0.21.2

discovery: bound channel range reply buffering

In this commit, we cap each QueryChannelRange response at 100,000 SCIDs
across all streamed replies. The existing reply-count limit did not track
the aggregate decoded working set, so memory use varied with the encoding
and composition of the reply stream.

We count raw SCIDs before timestamp filtering, charge replies using the
received encoding type, and release all accumulated range state on any
error. This bounds both memory and CPU work while still leaving headroom
above the current graph.

docs: update release notes

witness beacon: report node-ID next hop to the on-chain HTLC interceptor

Extend the on-chain interceptor path in the witness beacon to expose a
node-ID next hop, mirroring the off-chain path. A node-ID next hop has no
outgoing channel of its own, so the beacon reports hop.Exit as the outgoing
channel (via ForwardingInfo.NextHopChannel().UnwrapOr) and the requested
next node's public key. The RPC boundary maps that to the NodeIDForwardSCID
sentinel so the forward is not misread as a final receive.

This is the requested next hop, not the channel eventually selected by
non-strict forwarding, so the beacon deliberately does not resolve it
against the circuit map.

itest: cover blinded route next_node_id forwarding

Add integration tests for an lnd introduction node forwarding a blinded
payment whose non-final hops identify the next hop by node ID (next_node_id)
rather than a short channel ID, as produced by other implementations:

- testBlindedRouteNextNodeID: the outgoing channel is public.
- testBlindedRouteNextNodeIDPrivateChannel: the outgoing channel is
private, so the node ID resolves to an SCID alias.
- testBlindedRouteNextNodeIDRestart: the introduction node is restarted
while the HTLC is in flight, exercising forwarding-package replay and
re-decode of the node-ID blinded hop.

htlcswitch: forward node-ID blinded hops via non-strict forwarding

Fixes lightningnetwork/lnd#10937: forward a blinded-route payment when the
recipient identifies the next hop by node ID rather than a short channel
ID. The htlcPacket carries the decoded next hop to the switch, whose
handlePacketAdd resolves the pubkey to the peer's links via getLinks() and
lets the existing non-strict forwarding logic load-balance across the
peer's channels.

outgoingChanID stays a ShortChannelID. It is the persisted CircuitKey and
is set to the selected channel after non-strict selection. The circular
route check filters candidate channels before selection.

htlcswitch: classify a node-ID forward as a forward event

Now that the switch forwards blinded hops identified by node ID, a new
problem surfaces in the HTLC event stream. A node-ID next hop has no
outgoing short channel ID until non-strict forwarding selects one, so a
forward that fails before selection still carries outgoingChanID ==
hop.Exit. getEventType keys the exit hop off that sentinel, so it
misclassifies such a failed node-ID forward as a receive, mislabeling the
event streamed via SubscribeHtlcEvents (a forwarding failure reported as
a receive failure).

Two paths reach getEventType before an SCID is selected: the fail packet
built by failAddPacket and the resolution packet built by resolve, both
of which dropped the decoded next hop. Carry outgoingHop into both, and
classify a Right (node-ID) outgoingHop as a forward before the hop.Exit
check. A node-ID next hop is always a forward, never the exit hop.

htlcswitch+lnrpc: report node-ID next hop to the off-chain HTLC interceptor

When the switch forwards a blinded hop identified by node ID, it has not
yet resolved a concrete outgoing channel at interception time. Expose the
next hop to the interceptor: InterceptedForward.Packet() reports the
packet's outgoing channel as-is (hop.Exit, since none is selected yet) and
carries the requested pubkey in OutgoingNodeID.

At the RPC boundary, forwardInterceptor.onIntercept maps a node-ID hop to
the reserved NodeIDForwardSCID sentinel in outgoing_requested_chan_id and
the pubkey in outgoing_requested_node_id, so a client switching on a zero
channel ID to detect the exit hop does not misread the forward as a final
receive. The sentinel is a wire-only concern, applied where the request is
built rather than in the switch's internal InterceptedPacket, which stays
truthful (OutgoingNodeID.IsSome() is the node-ID discriminator).

htlcswitch/hop: decode next_node_id blinded hops

Some implementations (e.g. Core Lightning) identify the next hop in a
blinded route by the next node's ID (next_node_id) instead of a short
channel ID. Decode such a hop into a node-ID next hop, the Right of
ForwardingInfo.NextHop, holding the next node's public key. The switch
resolves that key to one of our channels with the peer in a later commit.

BOLT 4 requires a non-final blinded hop to carry exactly one of
short_channel_id or next_node_id, so a hop that sets both is rejected.

lnwire: cap decoded short channel IDs

In this commit, we cap each decompressed short channel ID set at 100,000
entries, matching the aggregate range reply budget. The old zlib reader
bounded compressed input rather than decoded output, so the two working-set
limits could drift apart.

We retain compatibility with protocol-valid compressed replies, reject
truncated or corrupt zlib streams, and close the reader on every exit.
Boundary, compatibility, corruption, and property tests cover the
decoder.

lnrpc/routerrpc: add outgoing_node_id to HTLC intercept request

A blinded route may identify the next hop by node ID (next_node_id) rather
than by channel, in which case there is no sender-specified outgoing channel
to report to an HTLC interceptor. Add an outgoing_node_id field to
ForwardHtlcInterceptRequest to carry the next hop's public key for these
forwards, and document that outgoing_requested_chan_id then holds a reserved
sentinel value so that clients switching on a zero channel ID to detect the
exit hop do not misclassify the forward as a final receive.

This commit only adds the schema and regenerated stubs; the fields are
populated by later commits.

multi: represent the blinded forwarding next hop as an fn.Either

The forwarding next hop is currently always a short channel ID. To allow a
blinded route to identify the next hop by node ID instead, change
ForwardingInfo.NextHop to fn.Either[lnwire.ShortChannelID, [33]byte], where
the Left is the outgoing channel ID and the Right (wired up in a follow-up
commit) is the next node's public key.

This commit is a pure representational change with no behavioural effect:
every next hop is still a channel ID. The Either is encapsulated behind
ForwardingInfo methods so callers never destructure it directly: IsExit()
is the single source of truth for exit-hop detection (used by the link and
the contract court) and NextHopChannel() yields the outgoing SCID.

htlcswitch: key the aux traffic shaper on the evaluated channel

During non-strict forwarding, handlePacketAdd evaluates every candidate
channel to the next peer and calls CheckHtlcForward with the sender-requested
outgoing SCID (originalOutgoingChanID) for each candidate. That SCID flowed
through canSendHtlc into AuxTrafficShaper.ShouldHandleTraffic, so a
channel-keyed shaper was asked about the requested channel rather than the
candidate actually being evaluated. With parallel channels to a peer this
inspects the wrong channel.

Key the shaper on l.ShortChanID() (the channel under evaluation) instead.
originalScid is retained solely for createFailureWithUpdate / FailAliasUpdate,
so the alias-aware channel_update returned to the sender is unchanged and the
real SCID handed to the shaper never leaks onto the wire.

github: bump gateway code-review to v0.6.0

Bumps both pins together: the gateway-action SHA and the runtime_ref it
resolves. runtime_ref is pinned explicitly rather than left to the
action's default, so bumping only the action would leave the job on the
v0.5.0 runtime.

v0.6.0 adds no trigger and no input, so the rest of the shim is
unchanged.

channeldb: recover missing db version

Use strict metadata reads during migration selection so a metadata bucket with a
missing metadata/dbp key is not interpreted as the latest DB version.

Recover this state from mandatory DB version 33, the last mandatory version
before the v0.20.x releases that could initialize a DB without writing the DB
version key. This runs migration 35 without replaying migrations 0 through 33
against a DB that was already created by a modern schema/code path.

After the selected migrations complete, syncVersions writes the latest DB
version as usual.

channeldb: preserve db version during init

Keep the top-level bucket creation introduced by PR #9653, since initialized
DBs can still be missing newer buckets such as the historical channel bucket.

Do not let the metadata bucket created during init make a fresh DB look
initialized. Use strict metadata reads so a missing metadata/dbp key is distinct
from a present DB version, then write metadata/dbp for genuinely fresh DBs.

Existing DBs with a metadata bucket but missing metadata/dbp are left for the
migration recovery path instead of being treated as latest.

channeldb: make waiting proof migration repeatable

Allow migration 35 to skip records that are already keyed using the typed
waiting proof format. This lets the missing-version recovery path safely run
migration 35 on DBs that were created directly by v0.21 and may already contain
typed waiting proofs.

Legacy 9-byte records are still migrated and unexpected key shapes still fail.

bolt12: add InvoiceError onion message replies

InvoiceError is the negative-reply counterpart to an invoice, sent over
onion messages at namespace type 68 when the receiver rejects an invoice
request or the sender rejects a returned invoice. All three fields are
odd (informational): erroneous_field (TLV 1, the offending TLV type),
suggested_value (TLV 3, a valid replacement), and error (TLV 5, a UTF-8
explanation). Unlike Offer/InvoiceRequest/Invoice this type has no
bech32 form and no Merkle signature — it travels only inside onion
message payloads.

docs: update release notes

docs: add payment migration release note

Document the handling of historical total-only blinded route data and the
new SendToRouteV2 validation that prevents creating such records.

paymentsdb: normalize orphaned blinded total

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.

routerrpc: require encrypted blinded hop data

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.