# Wallet Management The wallet in the context of `lnd` is a database file (located in the data directory, for example `~/.lnd/data/chain/bitcoin/mainnet/wallet.db` on Linux) that contains all addresses and private keys for the on-chain **and** off-chain (LN) funds. The wallet is independent of the chain backend that is used (`bitcoind`, `btcd` or `neutrino`) and must therefore be created as the first step after starting up a fresh `lnd` node. To protect the sensitive content of the wallet, the database is encrypted with a password chosen by the user when creating the wallet (simply called "wallet password"). `lnd` will not store that password anywhere by itself (as that would defeat the purpose of the password) so every time `lnd` is restarted, its wallet needs to be unlocked with that password. This can either be done [manually through the command line](#unlocking-a-wallet) or (starting with `lnd` version `v0.13.0-beta`) [automatically from a file](#auto-unlocking-a-wallet). ## Creating a wallet If `lnd` is being run for the first time, create a new wallet with: ```shell $ lncli create ``` This will prompt for a wallet password, and optionally a cipher seed passphrase. `lnd` will then print a 24 word cipher seed mnemonic, which can be used to recover the wallet in case of data loss. The user should write this down and keep in a safe place. In case a node needs to be recovered from an existing seed, this can also be done through the `create` command. Please refer to the [recovery guide](https://github.com/lightninglabs/docs.lightning.engineering/blob/master/docs/lnd/recovery.md) for more information about recovering a node. ## Unlocking a wallet Every time `lnd` starts up fresh (e.g. after a system restart or a version upgrade) the user-chosen wallet password needs to be entered to unlock (decrypt) the wallet database. This will be indicated in `lnd`'s log with a message like this: ``` 2021-05-06 11:36:11.445 [INF] LTND: Waiting for wallet encryption password. Use `lncli create` to create a wallet, `lncli unlock` to unlock an existing wallet, or `lncli changepassword` to change the password of an existing wallet and unlock it. ``` Unlocking the password manually is as simple as running the command ```shell $ lncli unlock ``` and then typing the wallet password. ## Auto-unlocking a wallet In some situations (for example automated, cluster based setups) it can be impractical to manually unlock the wallet every time `lnd` is restarted. In `lnd` version `v0.13.0-beta` and later there is a configuration option to tell the wallet to auto-unlock itself by reading the password from a file. This can only be activated *after* the wallet was created manually. ### Very basic example (not very secure) This example only tries to give a basic, minimal example on how to use the auto-unlock feature. Storing a password in a file on the same disk as the wallet database is not in itself more secure than leaving the database unencrypted in the first place. This example might be useful in a containerized environment though where the secrets are mounted to a file anyway. * Start `lnd` without the flag: ```shell $ lnd --bitcoin.active --bitcoin.xxxx ..... ``` * Create the wallet and write down the seed in a safe place: ```shell $ lncli create ``` * Stop `lnd` again: ```shell $ lncli stop ``` * Write the password to a file: ```shell $ echo 'my-$up3r-Secret-Passw0rd' > /some/safe/location/password.txt ``` * Make sure the password file can only be read by our user: ```shell $ chmod 0400 /some/safe/location/password.txt ``` * Start `lnd` with the auto-unlock flag: ```shell $ lnd --bitcoin.active --bitcoin.xxxx ..... \ --wallet-unlock-password-file=/some/safe/location/password.txt ``` As with every command line flag, the `wallet-unlock-password-file` option can also be added to `lnd`'s configuration file, for example: ``` [Application Options] debuglevel=debug wallet-unlock-password-file=/some/safe/location/password.txt [Bitcoin] bitcoin.active=1 ... ``` ### More secure example with password manager and using a named pipe This example is a bit more involved and requires the use of a password manager of some sort. It will also only work on Unix like file systems that support named pipes. We will use the password manager [`pass`](https://www.passwordstore.org/) as an example here, but it should work similarly with other password managers. * Start `lnd` without the flag: ```shell $ lnd --bitcoin.active --bitcoin.xxxx ..... ``` * Create the wallet and write down the seed in a safe place: ```shell $ lncli create ``` * Stop `lnd` again: ```shell $ lncli stop ``` * Store the password in `pass`: ```shell $ pass insert lnd/my-wallet-password ``` * Create a startup script for starting `lnd`, for example `run-lnd.sh`: ```shell #!/bin/bash # Create a named pipe. As the name suggests, this is a FIFO (first in first # out) pipe. Everything sent in can be read out again without the content # actually being written to a disk. mkfifo /tmp/wallet-password-pipe # Read the password from the manager and attempt to write it to the pipe. Any # write to a pipe will only be accepted once there is a process that reads # from the pipe at the same time. That's why we need to run this process in # the background (the ampersand & at the end) because it would block our # script from continuing otherwise. pass lnd/my-wallet-password > /tmp/wallet-password-pipe & # Now we can start lnd. lnd --bitcoin.active --bitcoin.xxxx ..... \ --wallet-unlock-password-file=/tmp/wallet-password-pipe ``` * Run the startup script instead of running `lnd` directly. ```shell $ ./run-lnd.sh ``` ## Changing the password Changing the wallet password is possible but only while the wallet is locked. So after restarting `lnd`, instead of using the `unlock` command, the `changepassword` command can be used: ```shell $ lncli changepassword ``` This will ask for the old/existing password and a new one. If successful, the database is re-encrypted with the new password and then the wallet is also unlocked in the process. ## DO NOT USE --noseedbackup on mainnet There is a way to get rid of the need to unlock the wallet password: The `--noseedbackup` flag. Using that flag with **real funds (mainnet) is extremely risky for two reasons**: 1. On first startup a wallet is created automatically. The seed phrase (the 24 words needed to restore a wallet) is never shown to the user. Therefore, if the worst thing happens and the hard disk crashes or the wallet file is deleted by accident, **THERE IS NO WAY OF GETTING THE FUNDS BACK**. 2. In addition to the seed not being known to the user, the wallet database is also not protected. A well-known default password is chosen for the encryption. Any user (or malware) with access to the wallet database can steal the funds if they copy the file. The `--noseedbackup` flag should only ever be used in a test setup, for example on Bitcoin testnet, regtest or simnet. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.lightning.engineering/lightning-network-tools/lnd/wallet.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.