lnd/docs/release-notes/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.

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

lncli Updates

Breaking Changes

Performance Improvements

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.

Code Health

Tooling and Documentation

Contributors (Alphabetical Order)

• Boris Nagaev
• Elle Mouton
• Erick Cestari
• hieblmi
• Matt Morehouse
• Mohamed Awnallah
• Nishant Bansal
• Pins