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.backuplnd 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:openchannelclosechannel and closeallchannelsabandonchannelupdatechanpolicyrestorechanbackuplndmon 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