lnd
. We encourage every person that is planning on putting mainnet funds into a Lightning Network channel using lnd
to read this guide carefully.
As of this writing, lnd
is still in beta and it is considered #reckless
to put any life altering amounts of BTC into the network.
That said, we constantly put in a lot of effort to make lnd
safer to use and more secure. We will update this documentation with each safety mechanism that we implement.lnd
and how they work on a high level.
The second part is a list of best practices that has crystallized from bug reports, developer recommendations and experiences from a lot of individuals running mainnet lnd
nodes during the last 18 months and counting.aezeed
is similar to BIP39 as it uses the same word list to encode the seed as a mnemonic phrase. But this is where the similarities end, because aezeed
is not compatible with BIP39. The 24 words of aezeed
encode a 128 bit entropy (the seed itself), a wallet birthday (days since BTC genesis block) and a version.
This data is encrypted with a password using the AEZ cipher suite (hence the name). Encrypting the content instead of using the password to derive the HD extended root key has the advantage that the password can actually be checked for correctness and can also be changed without affecting any of the derived keys.
A BIP for the aezeed
scheme is being written and should be published soon.lnd
nodes with the same seed! Even iflnd
node to a new device,lnd
. It is completely independent from the aezeed
cipher seed passphrase (which is optional). The wallet password is used to encrypt the sensitive parts of lnd
's databases, currently some parts of wallet.db
and macaroons.db
. Loss of this password does not necessarily mean loss of funds, as long as the aezeed
passphrase is still available. But the node will need to be restored using the SCB restore procedure.lnd
offers (gRPC on port 10009 and REST on port 8080) use TLS with a self-signed certificate for transport level security. Specifying the certificate on the client side (for example lncli
) is only a protection against man-in-the-middle attacks and does not provide any authentication. In fact, lnd
will never even see the certificate that is supplied to lncli
with the --tlscertpath
argument. lncli
only uses that certificate to verify it is talking to the correct gRPC server.
If the key/certificate pair (tls.cert
and tls.key
in the main lnd
data directory) is missing on startup, a new self-signed key/certificate pair is generated. Clients connecting to lnd
then have to use the new certificate to verify they are talking to the correct server.lnd
. A macaroon is a cryptographically verifiable token, comparable to a JWT or other form of API access token. In lnd
this token consists of a list of permissions (what operations does the user of the token have access to) and a set of restrictions (e.g. token expiration timestamp, IP address restriction). lnd
does not keep track of the individual macaroons issued, only the key that was used to create (and later verify) them. That means, individual tokens cannot currently be invalidated, only all of them at once.
See the high-level macaroons documentation or the technical README for more information.*.macaroon
files in the <lnd-dir>/data/chain/bitcoin/mainnet/
lnd
to recreate the default macaroons. But this doesmacaroons.db
has to be*.macaroon
.v0.8.0-beta
, lnd
supports the option_static_remote_key
(also known as "safu commitments"). All new channels will be opened with this option enabled by default, if the other node also supports it.
In essence, this change makes it possible for a node to sweep their channel funds if the remote node force-closes, without any further communication between the nodes. Previous to this change, your node needed to get a random channel secret (called the per_commit_point
) from the remote node even if they force-closed the channel, which could make recovery very difficult.lnd
will print out 24 words to write down, which is the wallet's seed (in the aezeed format). That seed is optionally encrypted with a passphrase, also called the cipher seed passphrase.
It is absolutely important to write both the seed and, if set, the password down and store it in a safe place as there is no way of exporting the seed from an lnd wallet. When creating the wallet, after printing the seed to the command line, it is hashed and only the hash (or to be more exact, the BIP32 extended root key) is stored in the wallet.db
file.
There is a tool being worked on that can extract the BIP32 extended root key but currently you cannot restore lnd with only this root key.lnd
node. Making a mistake here is also still the single biggest risk of losing off-chain funds, even though we do everything to mitigate those risks.<lnddir>/data/chain/bitcoin/mainnet/channel.backup
file which holds the Static Channel Backups (SCBs). This file is only updated every time lnd
starts, a channel is opened or a channel is closed.<lnddir>/data/graph/mainnet/channel.db
is what is very risky and should never be done!
This requires some explanation:
The way LN channels are currently set up (until eltoo
is implemented) is that both parties agree on a current balance. To make sure none of the two peers in a channel ever try to publish an old state of that balance, they both hand over their keys to the other peer that gives them the means to take all funds (not just their agreed upon part) from a channel, if an old state is ever published. Therefore, having an old state of a channel basically means forfeiting the balance to the other party.lnd
can be made multiple times a second, it's very hard to make a backup of the channel database every time it is updated. And even if it can be technically done, the confidence that a particular state is certainly the most up-to-date can never be very high. That's why the focus should be on making sure the channel database is not corrupted, closing out the zombie channels and keeping your SCBs safe.lnd
stores and updates a backup of all channels whenever the node is restarted, a new channel is opened or a channel is closed: <lnddir>/data/chain/bitcoin/mainnet/channel.backup
lnd
updatedlnd
, new security features are added. Users are always encouraged to update their nodes as soon as possible. This also helps the network in general as new safety features that require compatibility among nodes can be used sooner./home/<user>/.lnd
directory in Linux (or $HOME/Library/Application Support/lnd
in MacOS, %LOCALAPPDATA%\lnd
in Windows) can be moved to the new device and lnd
started there. It is important to shut down lnd
on the old device before moving the directory!
Not supported/untested is moving the data directory between different operating systems (for example MacOS
-> Linux
) or different system architectures (for example 32bit
-> 64bit
or ARM
-> amd64
). Data corruption or unexpected behavior can be the result. Users switching between operating systems or architectures should always use Option 2!lncli closeallchannels
). The command can take up to several minutes depending on the number of channels. Do not interrupt the command! 1. Wait for all channels to be fully closed. If some nodes don't respond to the close request it can be that lnd
will go ahead and force close those channels. This means that the local balance will be time locked for up to two weeks (depending on the channel size). Check lncli pendingchannels
to see if any channels are still in the process of being force closed. 1. After all channels are fully closed (and lncli pendingchannels
lists zero channels), lnd
can be shut down on the old device. 1. Start lnd
on the new device and create a new wallet with the existing seed that was used on the old device (answer "yes" when asked if an existing seed should be used). 1. Wait for the wallet to rescan the blockchain. This can take up to several hours depending on the age of the seed and the speed of the chain backend. 1. After the chain is fully synced (lncli getinfo
shows "synced_to_chain": true
) the on-chain funds from the previous device should now be visible on the new device as well and new channels can be opened.tls.key
and tls.cert
files in the data directory andlnd
to recreate them.--externalip
or --tlsextraip
) these--tlsextraip
setting also means regenerating the certificate pair. See9735
(or 10009
for gRPC) was forwarded on the router, theselnd
on the old address.lnd
node has already been connected to the internet with an IPv4 or IPv6 (clearnet) address and has any non-private channels, this connection between channels and IP address is known to the network and cannot be deleted.
Starting the same node with the same identity and channels using Tor is trivial to link back to any previously used clearnet IP address and does therefore not provide any privacy benefits.
The following steps are recommended to cut all links between the old clearnet node and the new Tor node: 1. Close all channels on the old node and wait for them to fully close. 1. Send all on-chain funds of the old node through a Coin Join service (like Wasabi or Samurai/Whirlpool) until a sufficiently high anonymity set is reached. 1. Create a new lnd
node with a new seed that is only connected to Tor and generate an on-chain address on the new node. 1. Send the mixed/coinjoined coins to the address of the new node. 1. Start opening channels. 1. Check an online network explorer that no IPv4 or IPv6 address is associated with the new node's identity.lnd
node can be prevented by avoiding data corruption in the channel database (<lnddir>/data/graph/mainnet/channel.db
).lnd
's main data directory being written on an SD card or USB thumb drivelnd
's main data directory being written to a network drive withoutfsync
support.lnd
.lnd
's main data directory between different operating systems/lnd
's main data directory on an Solid State Drive (SSD) of a reliable manufacturer. An alternative or extension to that is to use a replicated disk setup. Making sure a power failure does not interrupt the node by running a UPS ( uninterruptible power supply) might also make sense depending on the reliability of the local power grid and the amount of funds at stake.lncli
commandslncli
command if it is manipulating the channel database, which is true for the following commands:openchannel
closechannel
and closeallchannels
abandonchannel
updatechanpolicy
restorechanbackup
lndmon
can assist with these tasks.lnd
connected to a bitcoind
node that is running in prune mode is not supported! lnd
needs to verify the funding transaction of every channel in the network and be able to retrieve that information from bitcoind
which it cannot deliver when that information is pruned away.bitcoind
with the -txindex
flag for performance reasons, though this is not strictly required.lnd
nodes can run off of a single bitcoind
instance. There will be connection/thread/performance limits at some number of lnd
nodes but in practice running 2 or 3 lnd
instances per bitcoind
node didn't show any problems.--noseedbackup
flag