LND v0.21.0-beta Release Candidate

[saubyk]

Hey Everyone,

The first release candidate for the upcoming LND v0.21.0 has been published. This release ships basic onion messaging support, finalizes production simple taproot channels, and continues our journey of migrating LND's data stores to native SQL — this time with the payments store moving over. We do expect a few rounds of RCs to iron out potential issues found during testing. Please test this release on your testing nodes.

The release can be found here:

https://github.com/lightningnetwork/lnd/releases/tag/v0.21.0-beta.rc1

The detailed release notes are available at:

https://github.com/lightningnetwork/lnd/blob/master/docs/release-notes/release-notes-0.21.0.md

Below are some of the release highlights:

Onion Messaging Support

This version adds basic support for onion message forwarding, introducing a new OnionMessage peer-to-peer message type comprising a path key and an onion blob, along with the serialization and deserialization logic required for peer-to-peer communication.

Incoming onion messages are protected by two byte-denominated token-bucket rate limiters at ingress — one per peer, one global — so that small messages consume proportionally less of the budget than spec-max ones. Defaults are 0.5 Mbps per peer (256 KiB burst) and 5 Mbps globally (1600 KiB burst), all tunable via protocol.onion-msg-peer-kbps, protocol.onion-msg-peer-burst-bytes, protocol.onion-msg-global-kbps, and protocol.onion-msg-global-burst-bytes.

As a Sybil-resistance layer, incoming onion messages from peers with no fully open channel are dropped at ingress; operators who want to accept onion messages from all peers regardless of channel state can set protocol.onion-msg-relay-all=true (the rate limiters still apply). LND also now drops onion messages whose resolved next hop would cycle back to the sending peer, closing a trivial traffic-amplification vector. See onion_message_rate_limiting.md in the repo for the adversary model, defaults, and operator recipes.

Production Simple Taproot Channels

LND now supports production (final) simple taproot channels using the finalized taproot channel scripts with feature bits 80/81. Production taproot channels use optimized scripts (OP_CHECKSIGVERIFY in place of OP_CHECKSIG + OP_DROP) and a map-based nonce encoding in channel_reestablish and revoke_and_ack keyed by funding TXID, laying the groundwork for splice support. The nonce type is now auto-detected from the negotiated channel type rather than peer feature bits, ensuring correct behavior across all recovery and resynchronization paths.

Taproot channels also now support the RBF cooperative close protocol (--protocol.rbf-coop-close), including MuSig2 partial signature handling with the JIT nonce pattern and protection against nonce reuse across RBF iterations.

Payment Store Migration to SQL

Continuing the journey started in v0.20 with the graph store, this release moves the payments database to the native SQL backend. The effort introduces a payment store interface, implements the SQL schema with query and insert methods, threads context through the payment DB layer, and adds the KV-to-SQL payments migration.

Importantly, the SQL payments migration has been promoted from behind the test_native_sql build tag to mainline production code in this release. Users on postgres or sqlite backends with --db.use-native-sql set will have their payments migrated automatically on startup. As with the graph store migration in v0.20, nodes still on bbolt can use the [lndinit](https://github.com/lightninglabs/lndinit/blob/main/docs/data-migration.md) tool to migrate to sqlite or postgres first.

Other notable improvements

• Functional improvements

  • Channel closes now require between 3 and 6 confirmations (scaled linearly with channel capacity up to the non-wumbo max; wumbo channels always require 6) instead of being finalized immediately on spend detection. This adds reorg protection on the close path.
  • A new upfront-shutdown-address configuration option in lnd.conf lets users specify a default address for cooperative channel closures, applicable to both funders and fundees, with per-channel overrides during opening or acceptance.
  • A new chain_params table persists the active Bitcoin network on first startup and refuses to start on subsequent restarts if the configured network differs. This prevents silent data corruption from accidentally reusing a database across networks, on both PostgreSQL and SQLite native-SQL backends.

• Rpc additions and updates

  • Added DeleteForwardingHistory RPC on the router sub-server, allowing operators to selectively purge old forwarding events. Deletion requires a cutoff timestamp at least 1 hour in the past to prevent accidental removal of recent data.
  • PendingChannels now includes blocks_til_close_confirmed and close_height fields on WaitingCloseChannel, giving clients direct visibility into reorg-safe close progress.
  • GetInfo has a new wallet_synced field reporting the wallet's internal sync state, independent of the composite synced_to_chain field.
  • SubscribeChannelEvents now emits channel update events so clients can subscribe to state changes.
  • EstimateFee supports explicit input selection via a new inputs field in EstimateFeeRequest.
  • Two new MuSig2 RPCs, MuSig2RegisterCombinedNonce and MuSig2GetCombinedNonce, support coordinator-based signing workflows where nonces are aggregated externally (MuSig2 v1.0.0rc2 only).

• Lncli enhancements

  • A new lncli wallet psbt sign command corresponds to walletrpc.SignPsbt and can be used to sign a PSBT.
  • lncli estimatefee supports a new --utxos flag to specify explicit inputs for fee estimation.
  • lncli getdebuginfo and lncli encryptdebugpackage gain an --include_log flag to include the daemon log file in responses and encrypted debug packages.

• Performance improvements

  • The channel graph cache is now populated asynchronously on startup. Queries are served from the database until the cache is ready, allowing LND to become query-ready sooner after restart. Opt out via --db.sync-graph-cache-load if the old behavior is preferred.
  • Invoice pagination is now cursor-based (WHERE id >= cursor) instead of LIMIT+OFFSET, so every page is an efficient primary-key range scan regardless of depth.
  • The catch-all FilterInvoices SQL query has been replaced with five focused, index-friendly queries, eliminating the full table scans the old OR $param IS NULL predicates forced.
  • The v1 node horizon query has been split into all-nodes and public-only variants with composite indexes matching the full query shapes, yielding a ~42% speedup on SQLite's hot public-only path (which previously could stall for minutes).

• Breaking changes — please review before upgrading

  • MinCLTVDelta has been raised from 18 to 24 to provide a larger safety margin above DefaultFinalCltvRejectDelta (19 blocks). Users creating invoices with custom cltv_expiry_delta values between 18–23 will now need at least 24; the default of 80 blocks is unchanged and existing invoices continue to work.
  • GetDebugInfo no longer returns log file content by default. Clients relying on the log field must now set include_log=true on the request; the same applies to the --include_log flag on lncli getdebuginfo and lncli encryptdebugpackage.

• Upcoming deprecations (removal in v0.22)

  • Long-deprecated lnrpc.Hop fields (chan_capacity, amt_to_forward, fee) will be removed in v0.22. Clients should migrate to amt_to_forward_msat and fee_msat.
  • The deprecated --sat_per_byte fee rate option will be fully removed across CloseChannel, OpenChannel(Sync), SendCoins, SendMany, and walletrpc.BumpFee. Migrate to --sat_per_vbyte, which correctly represents fee rates in vbytes.

There are a lot of other bug fixes and minor updates which can be tracked via the release notes linked above. Reports of issues found during testing will be highly appreciated 🫂

Thanks