Builder's Guide
  • Welcome to the Builder's Guide to the LND Galaxy!
  • The Lightning Network
    • Overview
    • Payment Channels
      • Lifecycle of a Payment Channel
      • Watchtowers
      • Understanding Sweeping
      • Etymology
    • The Gossip Network
      • Identifying Good Peers on the Lightning Network
    • Pathfinding
      • Finding routes in the Lightning Network
      • Channel Fees
      • Multipath Payments (MPP)
    • Lightning Network Invoices
      • Understanding Lightning Invoices
    • Making Payments
      • The Payment Cycle
      • Timelocks
      • ⭐Hashed Timelock Contract (HTLC)
      • Payment Etymology
      • ⭐What Makes a Good Routing Node
      • Understanding Submarine Swaps
      • Instant Submarine Swaps
    • Liquidity
      • ⭐Understanding Liquidity
      • Managing Liquidity on the Lightning Network
      • Liquidity Management for Lightning Merchants
      • How to Get Inbound Capacity on the Lightning Network
      • Lightning Service Provider
    • L402: Lightning HTTP 402 Protocol
      • Macaroons
      • L402
      • 📋Protocol Specification
      • Implementations and Links
    • Taproot Assets
      • Taproot Assets Protocol
      • Taproot Assets on Lightning
      • Edge Nodes
      • Taproot Assets Trustless Swap
      • FAQ
      • Glossary
  • Lightning Network Tools
    • LND
      • 🛠️Get Started
      • lnd.conf
      • First Steps With LND
      • Wallet Management
      • Sending Payments
      • Atomic Multi-path Payments (AMP)
      • Receiving Payments
      • Unconfirmed Bitcoin Transactions
      • Channel Fees
      • Inbound Channel Fees
      • Macaroons
      • Configuring Watchtowers
      • Pathfinding
      • Blinded Paths
      • Key Import
      • Secure Your Lightning Network Node
      • Configuration of a Routing Node
      • Quick Tor Setup
      • Configuring Tor
      • Enable ‘Neutrino mode’ in Bitcoin Core
      • Send Messages With Keysend
      • Partially Signed Bitcoin Transactions
      • Bulk onchain actions with PSBTs
      • Sweeper
      • Debugging LND
      • Fuzzing LND
      • LND API documentation
      • Channel Acceptor
      • RPC Middleware Interceptor
      • HTLC Interceptor
      • NAT Traversal
      • Recovery: Planning for Failure
      • Migrating LND
      • Disaster recovery
      • Contribute to LND
    • Lightning Terminal
      • What is Lightning Terminal?
      • 🛠️Get litd
      • Run litd
      • Integrating litd
      • Demo: Litd Speed Run
      • Connect to Terminal
      • Recommended Channels
      • Rankings
      • Health Checks
      • Liquidity Report
      • Opening Lightning Network Channels
      • Managing Channel Liquidity
      • Autofees
      • AutoOpen
      • LND Accounts
      • Loop and Lightning Terminal
      • Loop Fees
      • Pool and Lightning Terminal
      • Command Line Interface
      • Troubleshooting
      • Lightning Node Connect: Under the hood
      • LNC Node Package
      • LITD API Documentation
      • Privacy and Security
      • Privacy Policy
      • Terms of Use
    • Loop
      • 🛠️Get Started
      • The Loop CLI
      • Autoloop
      • Static Loop In Addresses
      • Instant Loop Outs
      • Peer with Loop
      • Loop API Documentation
    • Pool
      • Overview
      • Quickstart
      • 🛠️Installation
      • First Steps
      • Accounts
      • Orders and Asks
      • Sidecar Channels
      • Zero-confirmation Channels
      • Channel Leases
      • Batch Execution
      • Account Recovery
      • Pool API Documentation
      • FAQs
    • Taproot Assets
      • Get Started
      • First Steps
      • Taproot Assets Channels
      • Asset Decimal Display
      • Become an Edge Node
      • RFQ
      • Collectibles
      • Universes
      • Asset Loop
      • Debugging Tapd
      • Multisignature
      • Minting Assets With an External Signer
      • Lightning Polar
      • Operational Safety Guidelines
      • Taproot Assets API Documentation
    • Aperture
      • ⚒️Get Aperture
      • LNC Backend
      • LNC Mailbox
      • Pricing
    • Faraday
      • 🛠️Get Started
      • The Faraday CLI
      • Faraday API Documentation
  • LAPPs
    • Guides
      • Use Polar to Build Your First LAPP
        • Setup: Local Cluster with Polar
        • Setup: Run the Completed App
        • Setup: Run the App Without LND
      • Add Features
        • Feature 1: Connect to LND
        • Feature 2: Display Node Alias and Balance
        • Feature 3: Sign and Verify Posts
        • Feature 4: Modify Upvote Action
      • Make Your own LNC-powered Application
    • Next Steps
  • Community Resources
    • Resource List
    • Lightning Bulb 💡
    • Glossary
    • FAQ
Powered by GitBook
On this page
  • Creating a wallet
  • Unlocking a wallet
  • Auto-unlocking a wallet
  • Very basic example (not very secure)
  • More secure example with password manager and using a named pipe
  • Changing the password
  • DO NOT USE --noseedbackup on mainnet

Was this helpful?

  1. Lightning Network Tools
  2. LND

Wallet Management

PreviousFirst Steps With LNDNextSending Payments

Last updated 23 days ago

Was this helpful?

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 or (starting with lnd versionv0.13.0-beta) .

Creating a wallet

If lnd is being run for the first time, create a new wallet with:

$   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 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

$   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:

    $   lnd --bitcoin.active --bitcoin.xxxx .....
  • Create the wallet and write down the seed in a safe place:

    $   lncli create
  • Stop lnd again:

    $   lncli stop
  • Write the password to a file:

    $   echo 'my-$up3r-Secret-Passw0rd' > /some/safe/location/password.txt
  • Make sure the password file can only be read by our user:

    $   chmod 0400 /some/safe/location/password.txt
  • Start lnd with the auto-unlock flag:

    $   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.

  • Start lnd without the flag:

    $   lnd --bitcoin.active --bitcoin.xxxx .....
  • Create the wallet and write down the seed in a safe place:

    $   lncli create
  • Stop lnd again:

    $   lncli stop
  • Store the password in pass:

    $   pass insert lnd/my-wallet-password
  • Create a startup script for starting lnd, for example run-lnd.sh:

    #!/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.

    $   ./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, thechangepassword command can be used:

$   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.

We will use the password manager as an example here, but it should work similarly with other password managers.

pass
recovery guide
manually through the command line
automatically from a file