LND

sample-conf: sync neutrino useragentversion with upstream

The neutrino bump updates the default UserAgentVersion from
"0.12.0-beta" to "0.16.2", which made the sample-conf check fail.

payments/db: remap legacy zero attempt IDs

Legacy KV payments can contain HTLC attempts with attempt ID zero. The
SQL payments schema requires payment_htlc_attempts.attempt_index to be
globally unique, so migrating multiple such attempts can fail with a
UNIQUE constraint violation.

Allocate synthetic attempt indexes for legacy zero-ID attempts from the
switch payment ID sequencer horizon. Keep nonzero attempt IDs unchanged
and advance the switch sequence once after migration validation succeeds.

This preserves the SQL uniqueness invariant and prevents future switch
IDs from colliding with migrated attempts. It also wraps HTLC insert
errors with the attempted index and payment hash so future migration
failures identify the problematic row.

lnrpc: depend on chanstate Store

Replace concrete ChannelStateDB fields in the invoices and wallet RPC
configs with chanstate.Store, and update the subserver dependency
wiring to pass the interface. The affected RPC paths only need
channel-state store methods for hop hints and waiting-close channel
queries.

server: depend on chanstate Store

Store channel-state access on server as chanstate.Store instead of
*channeldb.ChannelStateDB. Keep link-node access as a separate concrete
*channeldb.LinkNodeDB field so LinkNodeDB does not leak into the
channel-state store contract.

lnd: use chanstate Store for channel restore

Make chanDBRestorer persist restored channel shells through
chanstate.Store instead of the concrete ChannelStateDB. The restorer
still builds channeldb channel shell values, but only needs
RestoreChannelShells from the store.

contractcourt: use chanstate Store in breach arb

Replace BreachConfig's concrete ChannelStateDB dependency with
chanstate.Store. The breach arbitrator only needs closed-channel reads
and MarkChanFullyClosed from the channel-state store.

funding: depend on chanstate Store

Replace the funding manager's concrete *channeldb.ChannelStateDB
dependency with chanstate.Store. The manager only uses methods covered
by the store contract, including channel opening state and initial
forwarding policy persistence.

peer: depend on chanstate Store

Replace the peer config's concrete channel state DB dependency with
chanstate.Store. Brontide only needs channel lookups, closed-channel
lookup, and initial forwarding policy access from the channel-state
store.

channelnotifier: depend on chanstate Store

Accept chanstate.Store in ChannelNotifier instead of the concrete
ChannelStateDB. The notifier only fetches open and closed channel
records to populate channel event payloads.

chanstate: introduce Store interface

Add a new chanstate package containing the Store interface plus a
package logger. The interface mirrors the public surface of
*channeldb.ChannelStateDB so the compile-time assertion

var _ ChannelStore = (*channeldb.ChannelStateDB)(nil)

No consumer migrates in this commit.

channeldb: drop unused kvdb.RTx parameter from FetchChannelByID

All four call sites pass nil for tx today (server.go, two in
channeldb/db_test.go, funding/manager_test.go). The internal
channelScanner(nil, selector) call inside FetchChannelByID is preserved
verbatim, so runtime behavior is unchanged.

This is a prerequisite for the upcoming chanstate.ChannelStore
interface: keeping the parameter would leak kvdb into a domain
interface.

docs: release note for BOLT-02 push_msat fundee enforcement

Document the user-visible error string change introduced when the
fundee rejects incoming open_channel messages whose push_msat exceeds
1000 * funding_satoshis.

funding: enforce BOLT-02 push_msat bound on fundee

Reject incoming OpenChannel messages where push_msat exceeds
1000 * funding_satoshis, as required by BOLT-02. The existing RejectPush
flag only gates on push_msat > 0 and does not cover the spec bound.

An over-sized push is eventually caught downstream in reservation.go when
theirBalance = capacity - fee - push_msat goes negative and
ErrFunderBalanceDust is returned. Rejecting it up front produces a
clearer, spec-aligned error and avoids the chanacceptor and commitment
type negotiation round-trips for a channel we will refuse anyway.

graph/db: remove address loading from cached node iteration

ForEachNodeCached is now only used for topology-oriented traversal,
so the address-loading option forced one autopilot scoring path to
bypass the in-memory graph cache for data it did not consume. Remove
the withAddrs parameter and the associated SQL/KV address plumbing
so cached node iteration can consistently use the graph cache when
it is loaded.

Autopilot still requires peer addresses before opening channels.
That filtering remains in Agent.openChans via ForEachNode, where the
selected candidates' addresses are collected for ConnectToPeer. The
trade-off is that ForEachNodesChannels no longer excludes
addressless nodes from graph-wide scoring inputs such as median
channel size or centrality, which also feed lncli getnetworkinfo
statistics like graph diameter. In practice the only addressless
nodes our local view tends to know about are nodes with no public
channels (e.g. our own node or peers we share only private channels
with), so the impact on the reported stats should be negligible.
Active channel candidates remain address-filtered before dialing.

kvdb/sqlbase: fix non-constant format strings

When updating the Go version in kvdb to >= 1.24, schema.go no
longer compiles due to non-constant format strings. This is
invisible until:
- a new version of kvdb is tagged and imported in consumers
- kvdb is redirected to the local copy

This commit fixes the bug.

docs: release note for closed-channel tombstones on KV-SQL backends

Document the tombstone close path that #10780 wires onto sqlite/postgres,
the operator-visible iteration-cost growth that comes from leaving closed
chanBuckets on disk, and the NumForwardingPackages divergence that the
preserved forwarding-package bucket produces in PendingChannels.

multi: enable closed-channel tombstones on KV-SQL backends

Wire OptionTombstoneClosedChannels for sqlite and postgres backends in
config_builder.go. bbolt keeps the synchronous one-shot close path
unchanged.

Add UsesClosedChanTombstones() to the integration test harness so
backend-symmetric tests can skip post-close assertions about deleted
forwarding-package or revocation-log state — that state is intentionally
preserved on tombstone backends until the upcoming native-SQL
channel-state migration reclaims it. Update testWipeForwardingPackages
to honor the new predicate while still exercising the close flow on
both backend families.

channeldb: tombstone closed channels without bulk delete

Wire the tombstone close path on backends that opted in via
OptionTombstoneClosedChannels:

- ChannelStateDB.CloseChannel branches on tombstoneClosedChannels.
The default path remains closeChannelSync; closeChannelTombstone
runs on tombstone-enabled backends.
- closeChannelTombstone leaves every byte of the channel's nested
state in place — chanBucket, revocation log, per-channel
forwarding-package bucket, commitment heads — and relies on the
outpointBucket flip from outpointOpen to outpointClosed (already
performed by the shared updateClosedOutpointIndex helper) as the
authoritative closed-channel marker. The historical-channel and
close-summary archival use the same archiveClosedChannel helper as
the synchronous path so closed-channel and historical readers see
uniform records regardless of backend.
- locateOpenChannel rejects already-closed chanKeys (outpointClosed
in the index) with ErrChannelNotFound so a redundant CloseChannel
is a no-op rather than a re-archive.

Open-channel-bucket readers still surface tombstoned channels — that
audit lands in the next commit. The tests added here only assert the
writer's on-disk artefacts and the redundant-close guard.

Tests:
- TestCloseChannelTombstoneWritePath: outpoint flipped, historical
record, close summary, revlog/fwd-pkgs preserved.
- TestCloseChannelTombstoneRedundantClose: second CloseChannel
returns ErrChannelNotFound.
- TestCloseChannelSync: regression test for the synchronous path —
chanBucket and fwd-pkgs gone, outpoint flipped.

channeldb: hide tombstoned channels from open views

Wire every reader of openChannelBucket to consult isOutpointClosed
before treating a chanKey as open. Without this commit the previous one
flips the outpoint index but FetchAllChannels and friends still surface
the channel as if it were open — that intermediate state is fine for
tests because OptionTombstoneClosedChannels stays off until the multi:
commit flips it on for sqlite/postgres, but the readers must be wired
before that lands.

Audit covers all six call sites that descend into chanBucket:

- fetchChanBucket / fetchChanBucketRw — direct lookup paths used by
Refresh, MarkBorked, and the rest of OpenChannel's read/write
methods. Single-call sites; the tx.ReadBucket(outpointBucket)
lookup is inlined into the isOutpointClosed call.
- fetchNodeChannels — per-node ForEach iteration; tx threaded
through and the outpoint-bucket lookup is hoisted above the loop
so the closed-channel check is a per-iteration map probe rather
than a tx-level bucket resolve.
- FetchPermAndTempPeers — cross-node ForEach; same hoisting pattern.
The closed peer's protected status is still established by the
historical-channel second pass that runs after the open-channel
pass.
- channelScanner — single-channel-selector iteration site reached by
FetchChannel and FetchChannelByID; outpoint-bucket lookup hoisted
inside chanScan so a single visit pays the bucket-resolve cost
once.

The redundant-close guard added in the previous commit lives in
locateOpenChannel and is unchanged here.

Tests:
- TestCloseChannelTombstoneRemovesFromOpenScans: end-to-end —
FetchAllChannels, FetchOpenChannels, and FetchPermAndTempPeers all
behave as if the closed channel is gone, while the historical pass
still marks the peer as having a closed channel.
- TestClosedChannelHiddenFromFetchChannel: channelScanner path.
- TestClosedChannelHiddenFromDirectMethods: fetchChanBucket /
fetchChanBucketRw via Refresh and MarkBorked.

channeldb: add tombstone option and isOutpointClosed helper

Add the option, field, and reader helper that the tombstone close path
will consume in the next commit. Nothing is wired yet:

- OptionTombstoneClosedChannels — option modifier that sets the new
Options.tombstoneClosedChannels field. Defaults to off.
- ChannelStateDB.tombstoneClosedChannels — the decision-bit, set at
construction from the option.
- isOutpointClosed(opBucket, chanKey) — decodes the indexStatus TLV
stored under outpointBucket and reports true for entries flipped to
outpointClosed by updateClosedOutpointIndex (called from both close
paths). The helper accepts the bucket directly so loop-style
callers can hoist the tx.ReadBucket(outpointBucket) lookup out of
the inner loop and pay it once per iteration set.

Reusing outpointBucket as the "logically closed" signal avoids a
dedicated tombstone bucket. The flip from outpointOpen to outpointClosed
is already performed by the existing close path, so the signal exists on
both backends — readers just need to consult it.

Behavior is unchanged. The option and helper have no callers yet; the
close-path branch and reader audit land in the next two commits.

channeldb: extract close-channel helpers

Move the body of OpenChannel.CloseChannel into ChannelStateDB.CloseChannel
(which dispatches to a new closeChannelSync method), and split the close
logic into three free helpers:

- locateOpenChannel: descends the open-channel bucket tree and returns the
chain bucket, channel bucket, and serialized chanKey for an OpenChannel.
- updateClosedOutpointIndex: flips the outpoint index entry for a chanKey
from open to closed.
- archiveClosedChannel: writes the historical-channel record and the close
summary that survive the close.

Behavior is preserved: closeChannelSync runs the same sequence of mutations
(packager wipe, chanBucket delete, log-bucket delete, outpoint flip,
historical archive, close summary) that the inline body did, just composed
out of the new helpers. No callers, options, or readers change.

This is preparation for adding a tombstone close strategy on KV-SQL
backends; the helpers will be shared between the synchronous and tombstone
paths so historical and closed-channel records remain identical across
backends.

onionmessage: add BFS pathfinding for onion messages

In this commit we add FindPath, a BFS-based shsortest-path
algorithm that finds routes through the channel graph for
onion messages. The search filters nodes by the
OnionMessage feature bits (38/39).

We also add a unit tests covering: direct neighbor routing,
multi-hop paths, feature-bit filtering, missing destination
nodes, destination without onion support, max hop limits,
cycle handling, and shortest-path selection.
choice of BFS is because there isn't any weight involve.

docs: add release not for pathfinding

docs: fix Contributors TOC anchor in v0.21.0 release notes

The TOC link for the Contributors section pointed to `#contributors`,
but GitHub generates the anchor for `# Contributors (Alphabetical
Order)` as `#contributors-alphabetical-order`, leaving the link
broken when the rendered file is viewed on GitHub. Update the TOC
to use the working anchor (matching the form already used in
release-notes-0.18.0.md).

docs: add empty release notes for v0.22.0

Scaffold release-notes-0.22.0.md with the same section structure as
the 0.21.0 file so contributors have a place to land entries during
the v0.22 cycle.