LND

server+docs: construct onion message rate limiters and document config

With the limiter primitives, config options, and peer-side enforcement
in place, this commit constructs the per-peer and global onion message
rate limiters inside the server's onion messaging setup block,
composes them with NewIngressLimiter, and threads the resulting
IngressLimiter into peer.Config alongside the existing SpawnOnionActor
factory as a single OnionLimiter field. The limiters are only built
when onion messaging is actually enabled so that the disabled path
allocates nothing.

sample-lnd.conf gains commented-out entries for the four new options
with the default values and a short explanation of the ~5 Mbps
worst-case target. The user-facing release note for this feature is
added in a single consolidated commit at the end of the series rather
than split across the commits that introduce it.

peer: enforce onion message rate limits at ingress

This commit plumbs the combined IngressLimiter (per-peer + global)
through peer.Config and consults it from the readHandler's
*lnwire.OnionMessage case. The decision is factored into a small
allowOnionMessage helper so that the ingress policy is directly
unit-testable without standing up a full Brontide harness. Per-peer is
checked first inside the IngressLimiter: if we consulted the global
limiter first, a peer whose own bucket was already empty would still
get to burn a global token on each attempt, letting a single hostile
peer drain the shared budget and starve legitimate peers.

peer.Config carries a single OnionLimiter field of IngressLimiter type;
the brontide readHandler calls a single AllowN per incoming onion
message and dispatches on sentinel errors via errors.Is for the
first-drop log path. Nil limiter values are treated as "disabled"
throughout, which both preserves the pre-change behavior when onion
messaging is entirely turned off and keeps the brontide test harness
from needing to construct real limiters. Per-peer bucket state is
retained across disconnect at the IngressLimiter layer so a peer
cannot cycle the connection to reset its per-peer allowance.

OnionMessage also gains a WireSize method that computes the
on-the-wire size directly from the in-memory fields (no round-trip
through Encode) so the hot ingress path can charge the right number of
byte tokens without paying for a full serialization.

The accompanying unit tests cover the nil/disabled path, the
per-peer-rejects-first ordering invariant (asserting the global
limiter is not consulted when the per-peer bucket is empty), the
global rejection path, per-peer isolation across distinct pubkeys, and
a small concurrent stress test that asserts every attempt is accounted
for as either accepted or dropped and that the total accepted count
equals the configured burst under -race. A property-based rapid test
on WireSize guards against silent divergence from WriteMessage if the
OnionMessage wire format ever gains a TLV extension.

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: 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.

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.

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.

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

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.

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.

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: regenerate test vectors with BIP-340 HTLC signatures

Regenerate the test vector JSON with HTLC second-level transaction
signatures that use BIP-340 standard nonce derivation (zero auxrand)
instead of RFC6979. This makes the HTLC signatures reproducible across
different Schnorr implementations. The commitment transaction MuSig2
signatures are unchanged.

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: 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.

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.

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.

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: 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).

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.

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.

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.

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.

multi: fix linter issues

Fix gci (extra blank lines) and ll (line length > 80 chars) issues
across contractcourt, input, and watchtower packages.

lnwallet: return error from AggregateNonces in MusigSession

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

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.