LND

docs(docker): update README for improved clarity and accuracy

Merge pull request #9637 from Roasbeef/chan-type-required

feature: start to set the require bit for channel_type

peer: add test for createHtlcValidator

lnwallet: add aux test utils

We add this constructor for an AuxHtlcDescriptor that allows setting
some of the internal fields. This is useful for testing purposes for
code external to this package that may need to extensively test the
AuxHtlcView.

peer: set and use aux htlc validator

When instantiating the lightning channel we now pass in the created HTLC
validator. This validator simply performs a bandwidth check and errors
out if that is insufficient.

lnwallet: add and use AuxHtlcValidator to lightning channel

Previously we'd perform aux bandwidth checks during path finding. This
could lead to issues where multiple HTLCs where querying the same
bandwidth but were not accounting for each other before being added to
the commitment log. We now add a new validator function that will serve
as the last point of checks before adding the HTLC to the commitment.

During path finding HTLCs could query channel bandwidth asynchronously.
At this new call site all HTLCs that are about to be added to the
channel have been organised in sequence, so it's safe to query bandwdith
again at this point as we're getting the actual up-to-date values.

We remove the aux bandwidth check from the helper canSendHtlc, which was
called from CheckHTLCTransit and CheckHTLCForward (both are methods of
the htlcswitch).

For forwards we now fail at the link level, following the introduction
of the AuxHtlcValidator.

For payments, we now may fail either at the pathfinding level, or at the
link level. The htlcswitch may no longer fail for aux bandwidth checks.

Finally, when fetching the latest htlc view (for bandwidth checks during
pathfinding) we'd silently set the nextHeight of the view to the default
zero value. We now make sure to set it to the correct nextHeight value.

docs: add release-notes

invoices: use longer timeout for HTLC resolution in AMP test

Under parallel Postgres test load, the event loop must complete
sequential DB writes after SetTime fires. Using testTimeout (5s)
is too tight; switch the three blocking hodlChan selects in
testFailPartialAMPPayment to testTimeoutLong (1 minute) to
match the pattern already used elsewhere for slow backends.

sqldb: drop redundant and unused invoice indexes

Remove four indexes from the invoices table that either duplicate existing
UNIQUE constraint indexes or are never used in WHERE clauses:

- invoices_hash_idx: redundant, UNIQUE constraint on hash already creates
an implicit index
- invoices_payment_addr_idx: redundant, UNIQUE constraint on payment_addr
already creates an implicit index
- invoices_preimage_idx: unused, preimage is NULL on all new invoices and
is never used as a query filter
- invoices_settled_at_idx: unused, settled_at is NULL on all pending
invoices and is never used as a query filter (settle_index is used
instead)

Dropping these reduces B-tree working set size, which improves page cache
utilization as the invoice table grows.

scripts: fix backwards compatibility test timing issues

The backwards compatibility test was failing intermittently due to two
related timing issues in the test setup.

The issue was that Dave's `wait_graph_sync dave 3` was hanging
for up to 60 minutes. Dave's initial gossip sync with Charlie could
complete before Charlie had forwarded the alice-bob channel
announcement, leaving Dave stuck at 2 channels until lnd's historical
syncer fired at its default interval of 1 hour. After this 1-hour idle,
some routing state had become stale, causing the subsequent payment from
alice to dave to fail with FAILURE_REASON_NO_ROUTE.

This issues is now addressed by setting `--historicalsyncinterval=10s` on
all nodes. This causes nodes to periodically re-sync the full gossip
state from their peers every 10 seconds instead of every hour. Dave
therefore picks up any missed channel announcements and routing policies
within seconds, and alice's routing graph stays up-to-date throughout
the test.

Additionally, lnd debug logs from all containers are now collected
before teardown on failure and uploaded as a CI artifact, making future
failures easier to diagnose.

invoices: add TODO to change the return type of the query

sqldb: remove unused GetInvoice query

invoices/sql: replace catch-all GetInvoice with indexed lookups

The GetInvoice query used an OR IS NULL pattern for each filter
parameter:

WHERE (i.hash = $1 OR $1 IS NULL)
AND (i.payment_addr = $2 OR $2 IS NULL)

SQLite's query planner decides on an execution plan at prepare time,
before seeing any parameter values. Because either condition can be
trivially true when its parameter is NULL, the planner conservatively
falls back to a full table scan rather than using the unique indexes on
hash and payment_addr. This caused every invoice lookup and update on
the hot path (HTLC settlement) to scan the entire invoices table.

Replace the single catch-all query with three dedicated queries, each
using a direct equality on a uniquely constrained column:

- GetInvoiceByHash: WHERE hash = $1
- GetInvoiceByAddr: WHERE payment_addr = $1 (new, covers AMP path)
- GetInvoiceBySetID: existing, unchanged

Update getInvoiceByRef to route to the appropriate query based on which
fields are present in the InvoiceRef. When both hash and payment address
are provided, we look up by hash and then verify the returned invoice's
payment address matches.

GetInvoice is now unused and removed from the SQLInvoiceQueries
interface.

sqldb: add benchmark for sqlite connection number

The results suggests that the default of 2 is a good conservative
approach. The higher the connection number and the higher the
workload the performance decreases in WAL mode since readers still
need coordination (WAL index shm for example).

go: update lightning-onion

Update lightning-onion to commit that includes onion-messaging support.

multi: actor-based onion message forwarding

Add onion message forwarding capability using the OnionPeerActor for
communication. Messages are routed through a receptionist pattern where
each peer has a dedicated OnionPeerActor for handling message sends.

The OnionEndpoint uses the sphinx router for decoding and decrypting the
onion message packet and the encrypted recipient data in the payload of
the onion messages.

multi: add sphinx router without replay protection

Initialize a sphinx router without persistent replay protection logging
for onion message processing. Onion messages don't require replay
protection since they don't involve payment routing.

onionmessage: add LRU cache to SCID resolver

Add an LRU cache to GraphNodeResolver to avoid repeated database lookups
when resolving SCIDs to node public keys. The cache stores up to 1000
compressed pubkey entries, which is sufficient for typical onion message
forwarding scenarios.

This change also introduces a NewGraphNodeResolver constructor to
properly initialize the cache, replacing direct struct literal usage.

multi: OnionPeerActor for per-peer message support

Introduce a fat OnionPeerActor that handles the full onion message
processing pipeline for each peer connection. The actor decodes incoming
onion messages, determines the routing action (forward or deliver),
executes the action via PeerMessageSender, and dispatches updates to
subscribers via OnionMessageUpdateDispatcher.

Key components:
- OnionRouter interface abstracting sphinx router operations
- PeerMessageSender interface for forwarding to other peers
- OnionMessageUpdateDispatcher interface for subscriber notifications
- OnionActorFactory for spawning per-peer actors with shared deps
- Full test suite calling Receive() directly with NoOpReplayLog

record: add func for non-final om route data

Adds the NewNonFinalBlindedRouteDataOnionMessage function to create
blinded route data specifically for onion messages.

multi: add --protocol.no-onion-messages flag

This commit adds a configuration flag to disable onion messaging support.
When set, lnd will:
- Not advertise the onion messages feature bit (39) in init and node
announcements
- Skip creating the OnionEndpoint at server startup
- Not register an onion message handler with peers, so incoming onion
messages are not processed

lnwire: add OnionMessagePayload

The new wire message defines the OnionMessagePayload, FinalHopPayload,
ReplyPath, and related TLV encoding/decoding logic.

docs: release notes for v0.21.0

docs: add release notes for KV-to-SQL payment migration

payments/migration1: freeze lnwire and record dependency

Also freeze the lnwire and record packages used by the migration.

Copy the minimal subset of lnwire files (16) into
payments/db/migration1/lnwire/ and all record files (6) into
payments/db/migration1/record/. Three lnwire files are trimmed to avoid
pulling in the full message-type dispatch tree — all changes are purely
subtractive and can be verified with:

diff lnwire/message.go payments/db/migration1/lnwire/message.go
diff lnwire/writer.go payments/db/migration1/lnwire/writer.go
diff lnwire/lnwire.go payments/db/migration1/lnwire/lnwire.go

All migration1 files now import only the frozen packages, removing the
live dependency on lnwire and record so future changes to those packages
cannot affect migration correctness.