lnd. We encourage every person that is planning on putting mainnet funds into a Lightning Network channel using
lndto read this guide carefully. As of this writing,
lndis still in beta and it is considered
#recklessto put any life altering amounts of BTC into the network. That said, we constantly put in a lot of effort to make
lndsafer to use and more secure. We will update this documentation with each safety mechanism that we implement.
lndand 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
lndnodes during the last 18 months and counting.
aezeedis 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
aezeedis not compatible with BIP39. The 24 words of
aezeedencode 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
aezeedscheme is being written and should be published soon.
lndnodes with the same seed! Even if
lndnode to a new device,
lnd. It is completely independent from the
aezeedcipher seed passphrase (which is optional). The wallet password is used to encrypt the sensitive parts of
lnd's databases, currently some parts of
macaroons.db. Loss of this password does not necessarily mean loss of funds, as long as the
aezeedpassphrase is still available. But the node will need to be restored using the SCB restore procedure.
lndoffers (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,
lndwill never even see the certificate that is supplied to
lnclionly uses that certificate to verify it is talking to the correct gRPC server. If the key/certificate pair (
tls.keyin the main
lnddata directory) is missing on startup, a new self-signed key/certificate pair is generated. Clients connecting to
lndthen 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
lndthis 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).
lnddoes 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.
*.macaroonfiles in the
lndto recreate the default macaroons. But this does
macaroons.dbhas to be
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.
lndwill 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.dbfile. 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.
lndnode. 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.backupfile which holds the Static Channel Backups (SCBs). This file is only updated every time
lndstarts, a channel is opened or a channel is closed.
<lnddir>/data/graph/mainnet/channel.dbis what is very risky and should never be done! This requires some explanation: The way LN channels are currently set up (until
eltoois 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.
lndcan 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.
lndstores and updates a backup of all channels whenever the node is restarted, a new channel is opened or a channel is closed:
lnd, 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>/.lnddirectory in Linux (or
$HOME/Library/Application Support/lndin MacOS,
%LOCALAPPDATA%\lndin Windows) can be moved to the new device and
lndstarted there. It is important to shut down
lndon the old device before moving the directory! Not supported/untested is moving the data directory between different operating systems (for example
Linux) or different system architectures (for example
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
lndwill 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 pendingchannelsto see if any channels are still in the process of being force closed. 1. After all channels are fully closed (and
lncli pendingchannelslists zero channels),
lndcan be shut down on the old device. 1. Start
lndon 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 (
"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.certfiles in the data directory and
lndto recreate them.
--tlsextraipsetting also means regenerating the certificate pair. See
10009for gRPC) was forwarded on the router, these
lndon the old address.
lndnode 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
lndnode 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.
lndnode can be prevented by avoiding data corruption in the channel database (
lnd's main data directory being written on an SD card or USB thumb drive
lnd's main data directory being written to a network drive without
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.
lnclicommand if it is manipulating the channel database, which is true for the following commands:
lndconnected to a
bitcoindnode that is running in prune mode is not supported!
lndneeds to verify the funding transaction of every channel in the network and be able to retrieve that information from
bitcoindwhich it cannot deliver when that information is pruned away.
-txindexflag for performance reasons, though this is not strictly required.
lndnodes can run off of a single
bitcoindinstance. There will be connection/thread/performance limits at some number of
lndnodes but in practice running 2 or 3
bitcoindnode didn't show any problems.