UnlockWallet

UnlockWallet is used at startup of lnd to provide a password to unlock the wallet database.

Source: walletunlocker.proto

gRPC

rpc UnlockWallet (UnlockWalletRequest) returns (UnlockWalletResponse);

REST

HTTP Method	Path
POST	/v1/unlockwallet

Code Samples

gRPC

Javascript

const fs = require('fs');
const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');

const GRPC_HOST = 'localhost:10009'
const TLS_PATH = 'LND_DIR/tls.cert'

const loaderOptions = {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true,
};
const packageDefinition = protoLoader.loadSync(['lightning.proto', 'walletunlocker.proto'], loaderOptions);
const lnrpc = grpc.loadPackageDefinition(packageDefinition).lnrpc;
process.env.GRPC_SSL_CIPHER_SUITES = 'HIGH+ECDSA';
const tlsCert = fs.readFileSync(TLS_PATH);
const sslCreds = grpc.credentials.createSsl(tlsCert);
let client = new lnrpc.WalletUnlocker(GRPC_HOST, sslCreds);
let request = {
  wallet_password: <bytes>,
  recovery_window: <int32>,
  channel_backups: <ChanBackupSnapshot>,
  stateless_init: <bool>,
};
client.unlockWallet(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//  }

Python

import codecs, grpc, os
# Generate the following 2 modules by compiling the walletunlocker.proto with the grpcio-tools.
# See https://github.com/lightningnetwork/lnd/blob/master/docs/grpc/python.md for instructions.
import walletunlocker_pb2 as lnrpc, walletunlocker_pb2_grpc as walletunlockerstub

GRPC_HOST = 'localhost:10009'
TLS_PATH = 'LND_DIR/tls.cert'

# create SSL credentials
os.environ['GRPC_SSL_CIPHER_SUITES'] = 'HIGH+ECDSA'
cert = open(TLS_PATH, 'rb').read()
ssl_creds = grpc.ssl_channel_credentials(cert)
# make the request
channel = grpc.secure_channel(GRPC_HOST, ssl_creds)
stub = walletunlockerstub.WalletUnlockerStub(channel)
request = lnrpc.UnlockWalletRequest(
  wallet_password=<bytes>,
  recovery_window=<int32>,
  channel_backups=<ChanBackupSnapshot>,
  stateless_init=<bool>,
)
response = stub.UnlockWallet(request)
print(response)
# {
# }

REST

Javascript

const fs = require('fs');
const request = require('request');

const REST_HOST = 'localhost:8080'

let requestBody = {
  wallet_password: <string>, // <bytes> (base64 encoded)
  recovery_window: <integer>, // <int32> 
  channel_backups: <object>, // <ChanBackupSnapshot> 
  stateless_init: <boolean>, // <bool> 
};
let options = {
  url: `https://${REST_HOST}/v1/unlockwallet`,
  // Work-around for self-signed certificates.
  rejectUnauthorized: false,
  json: true,
  form: JSON.stringify(requestBody),
}
request.post(options, function(error, response, body) {
  console.log(body);
});
// Console output:
//  {
//  }

Python

import base64, codecs, json, requests

REST_HOST = 'localhost:8080'
TLS_PATH = 'LND_DIR/tls.cert'

url = f'https://{REST_HOST}/v1/unlockwallet'
data = {
  'wallet_password': base64.b64encode(<bytes>),
  'recovery_window': <int32>,
  'channel_backups': <ChanBackupSnapshot>,
  'stateless_init': <bool>,
}
r = requests.post(url, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
# }

Shell

$ lncli unlock --help

NAME:
   lncli unlock - Unlock an encrypted wallet at startup.

USAGE:
   lncli unlock [command options] [arguments...]

CATEGORY:
   Startup

DESCRIPTION:
   
  The unlock command is used to decrypt lnd's wallet state in order to
  start up. This command MUST be run after booting up lnd before it's
  able to carry out its duties. An exception is if a user is running with
  --noseedbackup, then a default passphrase will be used.

  If the --stateless_init flag is set, no macaroon files are created by
  the daemon. This should be set for every unlock if the daemon was
  initially initialized stateless. Otherwise the daemon will create
  unencrypted macaroon files which could leak information to the system
  that the daemon runs on.
  

OPTIONS:
   --recovery_window value  address lookahead to resume recovery rescan, value should be non-zero --  To recover all funds, this should be greater than the maximum number of consecutive, unused addresses ever generated by the wallet. (default: 0)
   --stdin                  read password from standard input instead of prompting for it. THIS IS CONSIDERED TO BE DANGEROUS if the password is located in a file that can be read by another user. This flag should only be used in combination with some sort of password manager or secrets vault.
   --stateless_init         do not create any macaroon files in the file system of the daemon
   

Messages

lnrpc.UnlockWalletRequest

Source: walletunlocker.proto

Field	gRPC Type	REST Type	REST Placement
wallet_password wallet_password should be the current valid passphrase for the daemon. This will be required to decrypt on-disk material that the daemon requires to function properly. When using REST, this field must be encoded as base64.	bytes	string	body
recovery_window recovery_window is an optional argument specifying the address lookahead when restoring a wallet seed. The recovery window applies to each individual branch of the BIP44 derivation paths. Supplying a recovery window of zero indicates that no addresses should be recovered, such after the first initialization of the wallet.	int32	integer	body
channel_backups channel_backups is an optional argument that allows clients to recover the settled funds within a set of channels. This should be populated if the user was unable to close out all channels and sweep funds before partial or total data loss occurred. If specified, then after on-chain recovery of funds, lnd begin to carry out the data loss recovery protocol in order to recover the funds in each channel from a remote force closed transaction.	ChanBackupSnapshot	object	body
stateless_init stateless_init is an optional argument instructing the daemon NOT to create any *.macaroon files in its file system.	bool	boolean	body

lnrpc.UnlockWalletResponse

Source: walletunlocker.proto

note

This response has no parameters.

Nested Messages

lnrpc.ChanBackupSnapshot

Field	gRPC Type	REST Type
single_chan_backups The set of new channels that have been added since the last channel backup snapshot was requested.	ChannelBackups	object
multi_chan_backup A multi-channel backup that covers all open channels currently known to lnd.	MultiChanBackup	object

lnrpc.ChannelBackups

Field	gRPC Type	REST Type
chan_backups A set of single-chan static channel backups.	ChannelBackup[]	array

lnrpc.ChannelBackup

Field	gRPC Type	REST Type
chan_point Identifies the channel that this backup belongs to.	ChannelPoint	object
chan_backup Is an encrypted single-chan backup. this can be passed to RestoreChannelBackups, or the WalletUnlocker Init and Unlock methods in order to trigger the recovery protocol. When using REST, this field must be encoded as base64.	bytes	string

lnrpc.ChannelPoint

Field	gRPC Type	REST Type
funding_txid_bytes Txid of the funding transaction. When using REST, this field must be encoded as base64.	bytes	string
funding_txid_str Hex-encoded string representing the byte-reversed hash of the funding transaction.	string	string
output_index The index of the output of the funding transaction	uint32	integer

lnrpc.MultiChanBackup

Field	gRPC Type	REST Type
chan_points Is the set of all channels that are included in this multi-channel backup.	ChannelPoint[]	array
multi_chan_backup A single encrypted blob containing all the static channel backups of the channel listed above. This can be stored as a single file or blob, and safely be replaced with any prior/future versions. When using REST, this field must be encoded as base64.	bytes	string