release-notes-0.21.0.md

Release Notes

• Bug Fixes
• New Features
  • Functional Enhancements
  • RPC Additions
  • lncli Additions
• Improvements
  • Functional Updates
  • RPC Updates
  • lncli Updates
  • Breaking Changes
  • Performance Improvements
  • Deprecations
• Technical and Architectural Updates
  • BOLT Spec Updates
  • Testing
  • Database
  • Code Health
  • Tooling and Documentation
• Contributors (Alphabetical Order)

Bug Fixes

• Fixed OpenChannel with fund_max to use the protocol-level maximum channel size instead of the user-configured maxchansize. The maxchansize config option is intended only for limiting incoming channel requests from peers, not outgoing ones.

• Chain notifier RPCs now return the gRPC Unavailable status while the sub-server is still starting. This allows clients to reliably detect the transient condition and retry without brittle string matching.

• Fixed an issue where the TLS manager would fail to start if only one of the TLS pair files (certificate or key) existed. The manager now correctly regenerates both files when either is missing, preventing "file not found" errors on startup.

• Fixed race conditions in the channel graph database. The Node.PubKey() and ChannelEdgeInfo.NodeKey1/NodeKey2() methods had check-then-act races when caching parsed public keys. Additionally, DisconnectBlockAtHeight was accessing the reject and channel caches without proper locking. The caching has been removed from the public key parsing methods, and proper mutex protection has been added to the cache access in DisconnectBlockAtHeight.

• Fixed TLV decoders to reject malformed records with incorrect lengths. TLV decoders now strictly enforce fixed-length requirements for Fee (8 bytes), Musig2Nonce (66 bytes), ShortChannelID (8 bytes), Vertex (33 bytes), and DBytes33 (33 bytes) records, preventing malformed TLV data from being accepted.

• Fixed MarkCoopBroadcasted to correctly use the local parameter. The method was ignoring the local parameter and always marking cooperative close transactions as locally initiated, even when they were initiated by the remote peer.

• Fixed a panic in the gossiper when TrickleDelay is configured with a non-positive value. The configuration validation now checks TrickleDelay at startup and defaults it to 1 millisecond if set to zero or a negative value, preventing time.NewTicker from panicking.

• Fixed a shutdown deadlock in the gossiper. Certain gossip messages could cause multiple error messages to be sent on a channel that was only expected to be used for a single message. The erring goroutine would block on the second send, leading to a deadlock at shutdown.

• Fixed lncli unlock to wait until the wallet is ready to be unlocked before sending the unlock request. The command now reports wallet state transitions during startup, avoiding lost unlocks during slow database initialization.

New Features

• Basic Support for onion messaging forwarding consisting of a new message type, OnionMessage. This includes the message's definition, comprising a path key and an onion blob, along with the necessary serialization and deserialization logic for peer-to-peer communication.

Functional Enhancements

RPC Additions

• Added support for coordinator-based MuSig2 signing patterns with two new RPCs: MuSig2RegisterCombinedNonce allows registering a pre-aggregated combined nonce for a session (useful when a coordinator aggregates all nonces externally), and MuSig2GetCombinedNonce retrieves the combined nonce after it becomes available. These methods provide an alternative to the standard MuSig2RegisterNonces workflow and are only supported in MuSig2 v1.0.0rc2.

• The EstimateFee RPC now supports explicit input selection. Users can specify a list of inputs to use as transaction inputs via the new inputs field in EstimateFeeRequest.

lncli Additions

• The estimatefee command now supports the --utxos flag to specify explicit inputs for fee estimation.

Improvements

Functional Updates

• Added support for the upfront-shutdown-address configuration in lnd.conf, allowing users to specify an address for cooperative channel closures where funds will be sent. This applies to both funders and fundees, with the ability to override the value during channel opening or acceptance.

• Rename experimental endorsement signal to accountable to match the latest proposal.

RPC Updates

• routerrpc HTLC event subscribers now receive specific failure details for invoice-level validation failures, avoiding ambiguous UNKNOWN results. #10520

• A new wallet_synced field has been added to the GetInfo RPC response. This field indicates whether the wallet is fully synced to the best chain, providing the wallet's internal sync state independently from the composite synced_to_chain field which also considers router and blockbeat dispatcher states.

• SubscribeChannelEvents now emits channel update events to be able to subscribe to state changes.

lncli Updates

Breaking Changes

Performance Improvements

• Replace the catch-all FilterInvoices SQL query with five focused, index-friendly queries (FetchPendingInvoices, FilterInvoicesBySettleIndex, FilterInvoicesByAddIndex, FilterInvoicesForward, FilterInvoicesReverse). The old query used col >= $param OR $param IS NULL predicates and a CASE-based ORDER BY that prevented SQLite's query planner from using indexes, causing full table scans. Each new query carries only the parameters it actually needs and uses a direct ORDER BY, allowing the planner to perform efficient index range scans on the invoice table.

• Fix full table scans on the HTLC settlement hot path. Replace the catch-all GetInvoice query (which used OR $1 IS NULL predicates that forced full table scans) with three dedicated queries targeting uniquely-constrained columns. Also drop four redundant indexes that duplicated UNIQUE constraints or were never used as query filters.

Deprecations

⚠️ Warning: The deprecated fee rate option --sat_per_byte will be removed in release version 0.22

The deprecated --sat_per_byte option will be fully removed. This flag was originally deprecated and hidden from the lncli commands in v0.13.0 (PR#4704). Users should migrate to the --sat_per_vbyte option, which correctly represents fee rates in terms of virtual bytes (vbytes).

Internally --sat_per_byte was treated as sat/vbyte, this meant the option name was misleading and could result in unintended fee calculations. To avoid further confusion and to align with ecosystem terminology, the option will be removed.

The following RPCs will be impacted:

RPC Method	Messages	Removed Option
lnrpc.CloseChannel	lnrpc.CloseChannelRequest	sat_per_byte
lnrpc.OpenChannelSync	lnrpc.OpenChannelRequest	sat_per_byte
lnrpc.OpenChannel	lnrpc.OpenChannelRequest	sat_per_byte
lnrpc.SendCoins	lnrpc.SendCoinsRequest	sat_per_byte
lnrpc.SendMany	lnrpc.SendManyRequest	sat_per_byte
walletrpc.BumpFee	walletrpc.BumpFeeRequest	sat_per_byte

Technical and Architectural Updates

BOLT Spec Updates

Testing

• Added unit tests for TLV length validation across multiple packages. New tests ensure that fixed-size TLV decoders reject malformed records with invalid lengths, including roundtrip tests for Fee, Musig2Nonce, ShortChannelID and Vertex records.

Database

• Freeze the graph SQL migration code to prevent the need for maintenance as the sqlc code evolves.

• Prepare the graph DB for handling gossip V2 nodes and channels 1 2 3 4, 5.

• Payment Store SQL implementation and migration project:

  • Introduce an abstract payment store interface and refacotor the payment related LND code to make it more modular.
  • Implement the SQL backend for the payments database
  • Implement query methods (QueryPayments,FetchPayment) for the payments db SQL Backend
  • Implement insert methods for the payments db SQL Backend
  • Implement third(final) Part of SQL backend payment functions
  • Finalize SQL payments implementation enabling unit and itests for SQL backend
  • Thread context through payment db functions Part 1
  • Thread context through payment db functions Part 2
  • Finalize SQL implementation for payments db
  • Add the KV-to-SQL payment migration with comprehensive tests. The migration is currently dev-only, compiled behind the test_db_postgres, test_db_sqlite, or test_native_sql build tags.

Code Health

Tooling and Documentation

• Overhauled Docker documentation and environment to modernize the developer onboarding flow. Key updates include migrating to Docker Compose V2, updating base images (btcd v0.25.0, Go 1.25.5), and transitioning the documentation to focus on a more reliable "Simnet" workflow while removing obsolete faucet references.

Contributors (Alphabetical Order)

• bitromortac
• Boris Nagaev
• Elle Mouton
• Erick Cestari
• Gijs van Dam
• hieblmi
• Matt Morehouse
• Mohamed Awnallah
• Nishant Bansal
• Pins
• Ziggie