LND

docs: add onion message rate limiting explainer

Introduce docs/onion_message_rate_limiting.md, a prose explainer for
operators and contributors that covers the two-layer defense on the
onion message ingress path: the channel-presence gate that turns peer
identity into a capital cost, and the byte-denominated per-peer and
global token-bucket rate limiters that run behind it. The doc walks
through the adversary first so that each layer has a concrete thing
to defend against, then covers the knobs, the startup-time validation
rules, the default sizing, and the protocol.onion-msg-relay-all
escape hatch with its explicit tradeoff against Sybil resistance. A
short operator recipes section collects the common "I want to ..."
configurations so readers do not have to reconstruct them from the
principles.

No code change; documentation only.

onionmessage: add token-bucket rate limiter primitives

The existing per-peer actor mailbox (capacity 50, RED from depth 40) only
bounds in-flight queue depth. It does not cap throughput: a peer that
drains its actor quickly can saturate our Sphinx unwrap CPU, replay-DB
writes, and outbound forwarding bandwidth without ever tripping RED. At
spec-max onion message sizes (~32 KiB per sphinx packet) a single
well-behaved-draining peer is enough to push multiple Mbps of unpaid
forwarded traffic through us, and aggregate fan-in from many peers
multiplies that into tens of Mbps — an amount of bandwidth that is very
much out of proportion for a side channel on a payment routing node.

This commit adds the building blocks for two token-bucket limiters that
will be wired into the onion message ingress path in a follow-up commit:
a process-wide global limiter and a per-peer registry. Both drop (rather
than wait) on over-limit so that a hostile peer cannot grow our
goroutine or memory footprint simply by sustaining above-threshold
traffic. The per-peer registry keys buckets on the peer's compressed
pubkey, creates them lazily, and retains them for the lifetime of the
process so a peer cannot reset its burst by cycling the connection;
cardinality is bounded by the live channel-peer count (the ingress call
site gates on having a channel before allocating per-peer state), so no
time-based GC is needed.

A minimal RateLimiter interface is introduced so that callers and tests
can substitute noop or alternate implementations without reaching into
x/time/rate directly, and a small countingLimiter wrapper keeps an
atomic drop counter plus a one-shot first-drop flag for observability.
A rate of zero (or a non-positive burst) yields a noop limiter,
providing a clean "disabled" mode without branching at the call site.

On top of those, a single IngressLimiter interface composes the
per-peer and global buckets behind one surface so that callers —
notably the peer readHandler — only thread one object through Config
and call one method per incoming onion message. Drop reasons are
surfaced as sentinel errors (ErrPeerRateLimit, ErrGlobalRateLimit)
wrapped in fn.Result[fn.Unit] so callers match on them with errors.Is
rather than comparing free-form strings. The stock implementation
encodes the load-bearing ordering — per-peer first, then global —
inside AllowN so that a hostile peer whose own bucket is already empty
cannot burn global tokens on every rejected attempt and starve
legitimate peers.

Default constants targeting roughly ~5 Mbps worst-case ingress at
spec-max message sizes are added alongside the existing mailbox
defaults.

itest: fix flake in testIntroductionNodeError

`testRelayingBlindedError` already uses `flakePaymentStreamReturnEarly`
after draining Carol's outgoing liquidity for the same reason:
`drainCarolLiquidity` causes the draining node to originate a payment,
which produces SEND-type HTLC notifier events. Because `SendPaymentV2`
returns SUCCEEDED before the commitment dance (revoke-and-ack exchange)
completes, those events can still be in-flight when the test subscribes
to HTLC events. The htlc notifier's subscribe server races a pending
SendUpdate against the Subscribe call in a single handler goroutine; if
registration wins the random select, the stale SEND events land on the
new subscriber and corrupt the subsequent FORWARD-type assertion.

`testIntroductionNodeError` has the same pattern — Bob drains Carol's
incoming liquidity by originating a payment — but was missing the sleep.
Add `flakePaymentStreamReturnEarly()` to match the existing workaround.

Fixes: https://github.com/lightningnetwork/lnd/actions/runs/24278289474/job/70895848920

funding/test: add test for inline channel_ready processing

In this commit, we add TestChannelReadyUnknownChannelID which verifies
that channel_ready messages with unrecognized ChannelIDs are processed
inline in the reservation coordinator without spawning goroutines. The
test sends 100 channel_ready messages with random ChannelIDs, waits for
all of them to be consumed (verified via a FindChannel call counter),
then asserts that the goroutine count hasn't grown proportionally. It
also confirms the coordinator remains responsive by successfully opening
a new channel after the batch completes.

funding: process channel_ready messages inline in the coordinator

In this commit, we refactor how the funding manager handles incoming
channel_ready messages. Previously, every channel_ready message would
unconditionally spawn a new goroutine via `go f.handleChannelReady(...)`,
making it the only message type in the coordinator switch that wasn't
processed inline. We now handle channel_ready the same way as all the
other funding messages: synchronously within the reservation coordinator
loop.

The goroutine was originally needed because handleChannelReady may need
to block on a `localDiscoverySignal` while the channel's funding
confirmation flow completes locally. In this commit, we split the
function into two parts: `handleChannelReady` (the lightweight entry
point that runs inline) and `processChannelReady` (the extracted body
that does the actual DB lookup and channel finalization). The inline
entry point checks whether a `localDiscoverySignal` exists for the given
channel ID, and only in that case do we dispatch a goroutine to wait for
the signal before calling `processChannelReady`. For channels that have
already confirmed (or after a restart), no goroutine is spawned at all.

This short-circuits the common path: the `FindChannel` DB lookup and the
rest of the processing now happen inline in the coordinator for the
majority of channel_ready messages, reducing goroutine churn and keeping
the coordinator's message processing consistent across all message types.

multi: add SCB restore support for production taproot channels

Add the missing SimpleTaprootFinalVersion case to
chanrestore.openChannelShell() so that SCB backups created for
production taproot channels can be properly restored. Without this,
the channel type bits were not reconstructed during restore, causing
DLP to fail.

Also add integration tests for both confirmed and zero-conf variants
of production taproot channel backup restoration.

itest: extend watchtower breach test to cover production taproot channels

Add SIMPLE_TAPROOT_FINAL to the watchtower revoked close retribution
test matrix. This exercises the new FlagTaprootFinalChannel blob type
and ensures the watchtower correctly constructs justice transactions
using production taproot scripts with OP_CHECKSIGVERIFY.

docs/release-notes: add release note for production taproot channels

lnwallet: emit actual MuSig2 partial sigs and nonces in test vectors

In this commit, we fix the taproot test vector generator to capture and
emit the real MuSig2 partial signatures and public nonces rather than
the dummy `CommitSig` value which is zeroed out for taproot channels.

Previously, the generator was reading from `CommitSig.ToSignatureBytes()`
which yielded a minimal DER encoding of `(0, 0)` (the 8-byte string
`3006020100020100`). For taproot channels the actual signature lives in
the `PartialSig` field of the `CommitSigs` struct, which carries both
the 32-byte partial sig scalar and the 66-byte compressed public nonce
needed by the verifier to reconstruct the combined signature.

We now unwrap the `PartialSig` from both the local and remote commitment
signatures, extract the nonce and sig bytes, and include `local_nonce`
and `remote_nonce` fields alongside `remote_partial_sig` in the emitted
JSON. This gives other implementations (eclair, CLN, etc.) all the
material they need to independently verify commitment transaction
signatures using their own MuSig2 libraries.

lnwallet: regenerate taproot channel test vectors

Regenerate `test_vectors_taproot.json` to reflect the corrected test
vector generator. Changes include actual 32-byte MuSig2 partial
signatures (replacing the dummy 8-byte DER stubs), 66-byte public
nonces for both local and remote parties, corrected HTLC sig-to-
transaction mapping sorted by BIP 69 output index, proper HTLC-success
witness layout with preimage in the correct witness slot, and the
updated trimming test case which now trims 3 of the 5 test HTLCs below
the 2500 sat dust limit (down from 5 HTLC outputs to 2).

lnwallet: add secret nonce stashing to MusigSession for test vectors

In this commit, we add the ability for MusigSession to capture and
expose the raw 97-byte MuSig2 secret nonce generated during JIT signing
nonce creation. This is gated behind the customNonceRand option, so it
only activates in test vector generation mode.

The stashed secret nonce is consumed on read (cleared after access) to
prevent accidental nonce reuse. This enables interop test vectors to
include the raw secret nonces, allowing other implementations to replay
the MuSig2 signing process without needing to match the exact nonce
derivation algorithm used by btcd's musig2 library.

lnwallet: regenerate taproot test vectors with secret nonces

Regenerate the test vectors JSON to include local_sec_nonce and
remote_sec_nonce fields alongside the existing public nonces. The local
nonce fields now correctly correspond to local's verification nonce for
their own commitment transaction, matching the commitment tx stored in
the test vector.

multi: fix lint and itest failures for production taproot channels

Fix line length lint violations in utxonursery.go by adding nolint:ll
directives to long case statements for production taproot witness types.

Fix itest funding negotiation test to handle SIMPLE_TAPROOT_FINAL in
the taproot negotiation failure check. Previously the test only expected
failure when Carol wanted SIMPLE_TAPROOT and Dave lacked taproot
support, but did not handle the symmetric case where Carol wants
SIMPLE_TAPROOT_FINAL.

chanbackup: add SimpleTaprootFinalVersion for production taproot backups

Add a dedicated backup version (7) for production taproot channels that
use final scripts with OP_CHECKSIGVERIFY. This distinguishes them from
staging taproot channels in the SCB format, ensuring backup
compatibility is explicit about the channel type.

lnwallet: return error from AggregateNonces in MusigSession

Fix swallowed error in MusigSession.Refresh where AggregateNonces
failure returned nil instead of the actual error.

multi: use feature bits to pick which taproot nonce field to use

Before this commit, we'd _always_ set both nonces fields, for both the
staging and the final taproot channels type.

With this commit, we've switched to only setting the new nonce map field
for the final taproot feature bit type.

watchtower: add production taproot channel support to justice kit

Wire channel type through BreachRetribution and the watchtower blob
system to support production taproot channels with final scripts.

The key changes are:

1. Add ChanType field to BreachRetribution so downstream consumers
(including the watchtower) can determine the script variant.

2. Add FlagTaprootFinalChannel blob type flag and
TypeAltruistTaprootFinalCommit blob type to distinguish production
from staging taproot channels in watchtower backups.

3. Add TaprootFinalCommitment to the watchtower's CommitmentType enum
with appropriate witness type and size mappings.

4. Update taprootJusticeKit to use WithProdScripts() when constructing
script trees for production taproot channels. The isFinal flag is
set during construction from BreachRetribution.ChanType and during
deserialization from the blob's commitment type.

Without this change, the watchtower would construct justice transactions
using staging scripts for production taproot channels, resulting in
invalid witnesses that fail to sweep breached outputs.

lnwallet: add MuSig2 secret nonces and partial sig replay to test vectors

In this commit, we extend the taproot test vector generator and verifier
to include MuSig2 secret nonces and a full partial signature replay
test.

For the generator, we now capture the correct nonces for each
commitment transaction: local's verification nonce (from LocalSession)
for local's own commitment, and remote's JIT signing nonce (from
RemoteSession) for the same commitment. Previously, the local nonce was
incorrectly captured from the RemoteSession, which corresponds to a
different commitment transaction.

The new musig2_partial_sig_replay test sub-suite verifies three
properties for each test case:

1. The remote partial sig can be independently reproduced from the
secret nonce and private key using musig2.Sign().

2. The local partial sig can be independently produced and verified
using the local secret nonce.

3. Both partial sigs combine (via the Session API) into the exact
Schnorr signature present in the commitment transaction witness.

This enables interop implementations to validate their MuSig2 signing
logic against the test vectors without needing to match nonce derivation
algorithms across different secp256k1 libraries.

lnwallet: use BIP-340 nonce derivation for HTLC sigs in test vectors

btcd's schnorr.Sign defaults to RFC6979 nonce derivation, while
libsecp256k1 (used by eclair, CLN, etc) uses BIP-340's standard
nonce derivation with zero auxrand. Both are deterministic but produce
different signatures for the same key and message, causing HTLC
signature mismatches in interop test vectors.

This commit introduces a bip340Signer wrapper that overrides
SignOutputRaw for taproot script path spends to use
schnorr.CustomNonce([32]byte{}) — matching BIP-340 deterministic
signing behavior. The wrapper is only used in the test vector
generator; production signing paths are unchanged.

Note that MuSig2 commitment signatures were already using BIP-340
nonces internally (via the musig2.Sign path), so only the HTLC
second-level transaction signatures were affected.

lnwallet: fix HTLC sig-to-transaction mapping in test vector generator

In this commit, we fix two interrelated bugs in the way HTLC signatures
are associated with their corresponding second-level transactions in the
taproot test vector generator.

The first issue was that HtlcSigs are sorted by BIP 69 output index
(matching the commitment transaction's output ordering), but the old
code was assigning signatures using the iteration order of incoming
HTLCs followed by outgoing HTLCs. This meant timeout transaction
signatures were getting paired with success transactions and vice versa
whenever the output ordering didn't happen to match the incoming-first
iteration order. This is the root cause of the invalid HTLC-timeout
signatures that eclair reported when cross-validating.

We now collect all HTLC entries (both incoming and outgoing) into a
single slice, sort them by their commitment output index, then zip them
against the HtlcSigs array so each signature lines up with the correct
second-level transaction.

The second issue was in the HTLC-success preimage extraction path. The
old code read the witness script from index [4] (the control block) and
used a hardcoded byte offset of 69 to locate the payment hash, then
wrote the preimage into index [3] (overwriting the script). The correct
taproot witness layout is [remoteSig, localSig, preimage, script,
controlBlock], so the script lives at [3] and the preimage slot is [2].
We now use `txscript.ScriptTokenizer` to walk the script opcodes and
find OP_HASH160 followed by the 20-byte push data, which is far more
robust than relying on fragile byte offsets that break if the script
template ever changes.

cmd/commands: add taproot-final to lncli open command

multi: add custom nonce rand support to MuSig2 sessions

In this commit, we add the ability to inject a custom random source
for generating JIT (Just-In-Time) signing nonces in MuSig2 sessions.
By default, MuSig2 signing nonces are generated using crypto/rand,
which makes signatures non-deterministic across runs. For test vector
generation, we need fully reproducible signatures from a fixed seed.

A new `customNonceRand` field is threaded through `MusigSession`,
`MusigSessionCfg`, `MusigPairSession`, and exposed via the
`WithCustomSigningRand` channel option. When set, the custom reader
is passed to `musig2.WithCustomRand()` during JIT nonce generation
in `SignCommit`. All existing callers pass `fn.None[io.Reader]()` to
preserve the current behavior of using the system CSPRNG.

lnwallet: add taproot channel test vector generator

In this commit, we add a test vector generator and verifier for
taproot channel constructions. All vectors are derived
deterministically from a single 32-byte seed using SHA256(seed ||
label) for key derivation, ensuring any implementation can reproduce
them independently.

The generator covers two areas:

Script vectors decompose the full tapscript trees for every output
type: funding (MuSig2 aggregated key), to_local (delay + revocation
leaves), to_remote (1-block CSV leaf), anchors (OP_16 OP_CSV),
offered/accepted HTLCs on both local and remote commits, and
second-level HTLC transactions. Each entry captures the raw leaf
scripts, leaf hashes, tapscript root, internal key, output key, and
pkScript.

Transaction vectors produce full serialized commitment transactions
and HTLC resolution transactions for three scenarios: a simple
commitment with no HTLCs, a commitment with five untrimmed HTLCs,
and the same HTLCs at a higher fee rate causing some to be trimmed.

To generate: go test -run TestTaprootVectors ./lnwallet/ -args -generate-taproot-vectors
To verify: go test -run TestTaprootVectors ./lnwallet/

lnwallet: fix HTLC trimming test case to use dust_limit for zero-fee HTLCs

In this commit, we fix the "commitment tx with some HTLCs trimmed" test
case to actually exercise trimming for taproot's zero-fee HTLC
transactions.

With zero-fee second-level HTLCs, the HTLC output value on the
commitment transaction equals the HTLC amount directly (no fee is
deducted). This means trimming is determined solely by whether the HTLC
amount falls below the dust limit, not by the fee rate. The previous
parameters (fee_per_kw=100000, dust_limit=546) didn't actually trim any
of the test HTLCs because even the smallest test HTLC (1000 sats) was
above the 546 sat dust limit.

We now use fee_per_kw=644 (a reasonable rate) and dust_limit=2500 to
ensure that the three smallest test HTLCs (1000, 2000, 2000 sats) are
properly trimmed, leaving only the 3000 and 4000 sat HTLCs on the
commitment transaction.

lnwallet: add 3rd-party signature verification for taproot test vectors

In this commit, we add a `signature_verification` sub-test to the
taproot test vector verifier that performs full script execution against
both the commitment transaction and all HTLC resolution transactions.

This uses `txscript.NewEngine` to execute the taproot witness programs
exactly as a Bitcoin node would, providing an independent check that all
signatures in the test vectors are cryptographically valid. For the
commitment transaction, we verify its witness against the funding output
pkScript. For each HTLC resolution transaction, we verify its witness
against the corresponding commitment output it spends.

This catches issues that the structural comparison tests (hex matching)
cannot: for instance, a transaction can have the correct structure but
carry an invalid signature if the sighash was computed over the wrong
prevout or if the wrong key was used for signing. Running the full
script engine also validates the control block, the tap leaf hash, and
the overall taproot spend path.