Lnd: v0.4.2-beta

This release marks the second patch release to the recently released v0.4-beta! No new major features have been added in this release. Instead, this release packages a series of bug fixes, modifications to ensure better cross-implementation compatibility, the ability to perform on-chain seed rescans w/ full look ahead, and a series of important fixes related to the switch and state machine. No database level breaking changes have been made in this release, as a result users should be able to perform a clean update.

Notable Changes


The max payment size and channel size for Litecoin has been increased by ~60x. This is a stop gap measure before a feature bit is added to the protocol to enable arbitrarily sized payments and channel sizes.


Full on-chain seed recovery with configurable look aheads is now fully implemented!. As a result, users will now be able to use their aezeed with lncli create or lncli unlock to trigger a full rescan to recover any on-chain funds. The implementation is generic, so it works with: btcd, bitcoind, and neutrino. The look ahead value is configurable in order to give users more control over the thoroughness of the on-chain key search.

We’ll now ensure that that any transaction broadcast have fee rates above the min relay fee of the node lnd is connected to.

Bitcoind and btcd Chain Backends

A bug in the bitcoindchain backend has been fixed that would cause lnd to stall on start up at times due to an internal bug when attempting to rescan to see if an output has been spent or not. As a result, startup using the bitcoindbackend should be generally much snappier. Future versions of lnd will continue to increase the performance of the bitcoind backend. Particularly, once the BIP 158 implementation is merged and exposed over RPC, we’ll be able to use those filters for rescans internally as we do for btcd.

The txindex is now no longer required for either btcd or bitcoind!. However, users will find that lnd is generally more performant if the index is enabled, as it saves us from performing manual rescans. v0.5-beta will contain an overhaul to the way we perform historical notifications dispatches which will eliminate manual rescanning all together.

It’s now possible to shutdown lnd with the lncli stop command while lnd is still syncing with the chain backend.

Configuration and Documentation

Users can now configure log rotation to optional. By default lnd will maintain 3 compressed log files on disk, rotating them over each time we fill up a new log file. When running with the trace or debug logging levels, the logging can be quite verbose, which warrants disabling log rotation all together or tweaking parms concerning the max log size and also the total number of log files to maintain.

lnd will now properly recognize the BIP 173 hrp prefix for regtest.

The Javascript docs for lnd’s gRPC interface have been updated to show proper usage of macaroons and TLS cipher suites.


A number of bugs have been fixed in the contract court ensuring that we don’t play duplicate commitments, properly lay the remote party’s full set of commitments, and also ensure that all related goroutines exit properly on shutdown (https://github.com/lightningnetwork/lnd/commit/c5169a79f597526486755af19e6220ae162a3b77).

The ChannelArbitrator sub-system has been modified to only act on confirmed commitments. This fixes a number of bugs encountered and ensures that we’ll only attempt resolve contracts which are properly buried in the chain. As a result, new state has been added to the pendingchannels RPC: commitment broadcast. Channels will be in this state once we broadcast a commitment, but before a transaction spending the funding output has been confirmed. We do this as although we broadcasted a commitment, it’s possible that another distinct transaction is confirmed instead. In either case, we’ll play which ever spending transaction is confirmed, and proceed to resolve any active contracts.

The ChainWatcher has been modified to ensure it always plays all possible active commitments.

For cooperative channel closes, we’ll now ensure that we play the transaction which ultimately enters the chain, rather than assuming the final signed closing transaction would be the one that wins over.

Channel Funding

A bug has been fixed that would at times cause a state desynchronization if both sides were lnd nodes and had selected custom values for the CSV delay.


The BreachArbiter (the sub-system tasked with enforcing justice against cheating channel peers) has been significantly simplified. Along the way, hand off between the breach arb and the contractcourt has been improved to ensure the hand off is atomic, even in the phase of a breach at the point of a daemon shutdown.


The docker image for lnd is now around 10% the size of the prior image! Additionally, it’ll now pull in local changes rather than fetch the source from git. As a result, developers can now use the docker-compose set up for local simnet cluster management when doing development, or testing new pending PRs.

A “production” docker image has also now been added. With this, we’ll start to post images for new lnd release on Docker Hub.

lncli and lnrpc

Several errors that result from incorrect usage of the rpc interface, or invalid arguments have now been made clearer.

The macaroon package now contains a set of unit tests, as well as integration tests on the lnd level. This paves the way to the more flexible “Macaroon Bakery”, which will allow callers to generate a set of custom macaroons.

The GetInfo command now contains the version that lnd is running, and if compiled properly, will also display the commit hash that lnd was built off of.

A cosmetic bug wherein the payment hash for all active HTLCs on a channel was duplicated on the RPC level.

It’s now possible to turn off logging all together for all or a set of targeted sub-systems.

lncli unlock will now display a more helpful error message when a user attempts to unlock an already unlocked wallet.

Commands in lncli will now be grouped by category:

   lncli - control plane for your Lightning Network Daemon (lnd)

   lncli [global options] command [command options] [arguments...]
   0.4.1 commit=80852601dbd2b84c257a1b52a7f13518ed8a6091
     getinfo     Returns basic information related to the active daemon.
     debuglevel  Set the debug level.
     stop        Stop and shutdown the daemon.
     help, h     Shows a list of commands or help for one command

     openchannel       Open a channel to a node or an existing peer.
     closechannel      Close an existing channel.
     closeallchannels  Close all existing channels.
     channelbalance    Returns the sum of the total available channel balance across all open channels.
     pendingchannels   Display information pertaining to pending channels.
     listchannels      List all open channels.
     getchaninfo       Get the state of a channel.
     getnetworkinfo    Get statistical information about the current state of the network.
     feereport         Display the current fee policies of all active channels.
     updatechanpolicy  Update the channel policy for all channels, or a single channel.

     sendmany       Send bitcoin on-chain to multiple addresses.
     sendcoins      Send bitcoin on-chain to an address.
     listchaintxns  List transactions from the wallet.

     sendpayment    Send a payment over lightning.
     payinvoice     Pay an invoice over lightning.
     addinvoice     Add a new invoice.
     lookupinvoice  Lookup an existing invoice by its payment hash.
     listinvoices   List all invoices currently stored.
     listpayments   List all outgoing payments.
     queryroutes    Query a route to a destination.
     decodepayreq   Decode a payment request.
     fwdinghistory  Query the history of all forwarded HTLCs.

     connect        Connect to a remote lnd peer.
     disconnect     Disconnect a remote lnd peer identified by public key.
     listpeers      List all active, currently connected peers.
     describegraph  Describe the network graph.
     getnodeinfo    Get information on a specific node.

     create  Initialize a wallet when starting lnd for the first time.
     unlock  Unlock an encrypted wallet at startup.

     newaddress     Generates a new address.
     walletbalance  Compute and display the wallet's current balance.
     signmessage    Sign a message with the node's private key.
     verifymessage  Verify a message signed with the signature.

   --rpcserver value        host:port of ln daemon (default: "localhost:10009")
   --lnddir value           path to lnd's base directory (default: "/home/guggero/.lnd")
   --tlscertpath value      path to TLS certificate (default: "/home/guggero/.lnd/tls.cert")
   --no-macaroons           disable macaroon authentication
   --macaroonpath value     path to macaroon file (default: "/home/guggero/.lnd/admin.macaroon")
   --macaroontimeout value  anti-replay macaroon validity time in seconds (default: 60)
   --macaroonip value       if set, lock macaroon to specific IP address
   --help, -h               show help
   --version, -v            print the version

Channel State Machine

A bug has been fixed wherein we’d attempt to sweep breached dust outputs. Additionally, we now ensure that we can sweep breaches that contain both incoming and outgoing HTLCs.

A bug that prevented fees from being negotiated down has been fixed.

A bug has been fixed that would previously cause lnd to initiate a new state transition without any committed updates. This was a spec violation and would cause a compliant implementation to abandon the channel.

A bug has been fixed that would result in lnd restoring the incorrect log state after a restart with a pending commitment dangling. This bug would cause lnd to crash on start up with a nil pointer panic.

HTLC Routing

A number of improvements have been made within the ChannelRouter w.r.t how we respond to received onion htlc errors. As a result, users should generally find the routing hiccups that existed in prior versions of lnd have been resolved. Version 0.5-beta for lnd will contain a large overhaul in the MissionControl sub-system to address several drawbacks in the current naive implementation.

We’ve modified the way we handle FeeInsufficientErrors to more aggressively route around nodes that repeatedly return the same error to us. This will ensure we skip older nodes on the network which are running a buggier older version of lnd.

We’ll now no longer prune vertexes in response to receiving an UnknownNextPeer error. Instead, we’ll now prune the edges as otherwise faulty or malicious nodes could cause us to backlist a target node, rather than routing around the failure.

We’ll now skip local channels unable to satisfies a potential payment flow during path finding. This should reduce payment latency a bit, and also result in less internal routing failures.

Private Channel Invoicing

When a user creates a invoice w/ active private channels, we’ll now encode routing hints for each of these channels. These routing hints enable non-advertised channels to still receive incoming payments, and will be an important component of the network as it continues to grow. Additionally, our path finding logic has been updated to utilize any routing hints if populated.

HTLC Switch

When disconnecting peer due to an invalid commitment, we’ll now ensure that the error to the remote peer is sent before we kill the socket. This ensures that our new log message with useful debugging information reaches the peer before we shut down the link.

A very old bug in the forwarding logic of the switch has been fixed. When accepting an HTLC we are meant to validate the fee against the constraints of the outgoing link. This is due to the fact that we’re offering a payment transit service on our outgoing link. Before this commit, we would use the policies of the incoming link. This would at times lead to odd routing errors as we would go to route, get an error update and then route again, repeating the process.

We’ll now properly use the incoming link for timelock related constraints, and the outgoing link for fee related constraints. We do this by introducing a new HtlcSatisfiesPolicy method in the link. This method should return a non-nil error if the link can carry the HTLC as it satisfies its current forwarding policy. We’ll use this method now at forwarding time to ensure that we only forward to links that actually accept the policy. This fixes a number of bugs that existed before that could result in a link accepting an HTLC that actually violated its policy. In the case that the policy is violated for all links, we take care to return the error returned by the target link so the caller can update their sending accordingly.

The DecayedLog implementation to protect against Sphinx replays has been moved to the htlcswitch package.

A number of bugs surrounding forwarding to channels which haven’t yet been confirmed, as well as premature HTLC trimming have been fixed.

A deadlock/panic bug in the switch has been fixed that would be triggered when we were trying to add metrics for a non-settle event.

We’ll now automatically force close channels that have de-sync’d due to an invalid commitment or settle.

A bug has been fixed that would cause a state machine that accepted a duplicate fail or settle to crash upon restarts. We now ensure that we’ll reject any duplicate fails or settles.

A bug has been fixed that would cause us to forward a fail/settle too early internally, leading to inconsistencies within the switch, and the mailbox of each of the links.

A bug has been fixed that would cause us to add an HTLC to the log, but not fully evaluate it. We’ll now ensure that we properly set the add/remove heights of internal PaymentDescriptors properly when restoring the update logs after a restart.

Peer to Peer and Server

An optimization has been made within the peer struct to no longer allocate a new buffer each time we to to write a message. Instead, we’ll use a static write buf sized for the largest possible protocol message within each peer instance. As a result, our memory usage is much less bursty, and generally much lower.

We’ll now on a best effort basis attempt to locate the advertised port of peers that have connected to us via inbound connections. Before this addition, lnd would at times be unable to automatically connect a certain class of peers which we first discovered via an inbound connection.


A bug has been fixed in the AuthenticatedGossiper that could at times cause a deadlock when a user attempted to update the set of channel policies.

A bug has been fixed that would cause partial goroutine leaks when the AuthenticatedGossiper is shutting down. The changes ensure faster and cleaner shutdowns of the ChannelRouter as well.


The ChainNotifier has been modified to primarily only dispatch spend notifications once the spending transaction has been confirmed within a block. Switching to this behavior fixes a bug wherein if both sides attempted to force close simultaneously, or a closing transaction we weren’t expecting hits the chain, then we would fail to realize the contract has been resolved on chain.


A set of test vectors has been added , and also the README now has additional details concerning the underlying cipher seed scheme.




The full list of changes since 0.4.1-beta can be found here: * https://github.com/lightningnetwork/lnd/compare/v0.4.1-beta...v0.4.2-beta