lnd/docs/wallet.md

# 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](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:

```text
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:

```text
[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.