InitWallet

InitWallet is used when lnd is starting up for the first time to fully initialize the daemon and its internal wallet. At the very least a wallet password must be provided. This will be used to encrypt sensitive material on disk.

In the case of a recovery scenario, the user can also specify their aezeed mnemonic and passphrase. If set, then the daemon will use this prior state to initialize its internal wallet.

Alternatively, this can be used along with the GenSeed RPC to obtain a seed, then present it to the user. Once it has been verified by the user, the seed can be fed into this RPC in order to commit the new wallet.

Source: walletunlocker.proto

gRPC

rpc InitWallet (InitWalletRequest) returns (InitWalletResponse);

REST

HTTP Method	Path
POST	/v1/initwallet

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>,
  cipher_seed_mnemonic: <string>,
  aezeed_passphrase: <bytes>,
  recovery_window: <int32>,
  channel_backups: <ChanBackupSnapshot>,
  stateless_init: <bool>,
  extended_master_key: <string>,
  extended_master_key_birthday_timestamp: <uint64>,
  watch_only: <WatchOnly>,
  macaroon_root_key: <bytes>,
};
client.initWallet(request, function(err, response) {
  console.log(response);
});
// Console output:
//  {
//    "admin_macaroon": <bytes>,
//  }

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.InitWalletRequest(
  wallet_password=<bytes>,
  cipher_seed_mnemonic=<string>,
  aezeed_passphrase=<bytes>,
  recovery_window=<int32>,
  channel_backups=<ChanBackupSnapshot>,
  stateless_init=<bool>,
  extended_master_key=<string>,
  extended_master_key_birthday_timestamp=<uint64>,
  watch_only=<WatchOnly>,
  macaroon_root_key=<bytes>,
)
response = stub.InitWallet(request)
print(response)
# {
#    "admin_macaroon": <bytes>,
# }

REST

Javascript

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

const REST_HOST = 'localhost:8080'

let requestBody = {
  wallet_password: <string>, // <bytes> (base64 encoded)
  cipher_seed_mnemonic: <array>, // <string> 
  aezeed_passphrase: <string>, // <bytes> (base64 encoded)
  recovery_window: <integer>, // <int32> 
  channel_backups: <object>, // <ChanBackupSnapshot> 
  stateless_init: <boolean>, // <bool> 
  extended_master_key: <string>, // <string> 
  extended_master_key_birthday_timestamp: <string>, // <uint64> 
  watch_only: <object>, // <WatchOnly> 
  macaroon_root_key: <string>, // <bytes> (base64 encoded)
};
let options = {
  url: `https://${REST_HOST}/v1/initwallet`,
  // 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:
//  {
//    "admin_macaroon": <string>, // <bytes> 
//  }

Python

import base64, codecs, json, requests

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

url = f'https://{REST_HOST}/v1/initwallet'
data = {
  'wallet_password': base64.b64encode(<bytes>),
  'cipher_seed_mnemonic': <string>,
  'aezeed_passphrase': base64.b64encode(<bytes>),
  'recovery_window': <int32>,
  'channel_backups': <ChanBackupSnapshot>,
  'stateless_init': <bool>,
  'extended_master_key': <string>,
  'extended_master_key_birthday_timestamp': <uint64>,
  'watch_only': <WatchOnly>,
  'macaroon_root_key': base64.b64encode(<bytes>),
}
r = requests.post(url, data=json.dumps(data), verify=TLS_PATH)
print(r.json())
# {
#    "admin_macaroon": <bytes>,
# }

Shell

# There is no CLI command for this RPC

Messages

lnrpc.InitWalletRequest

Source: walletunlocker.proto

Field	gRPC Type	REST Type	REST Placement
wallet_password wallet_password is the passphrase that should be used to encrypt the wallet. This MUST be at least 8 chars in length. After creation, this password is required to unlock the daemon. When using REST, this field must be encoded as base64.	bytes	string	body
cipher_seed_mnemonic cipher_seed_mnemonic is a 24-word mnemonic that encodes a prior aezeed cipher seed obtained by the user. This may have been generated by the GenSeed method, or be an existing seed.	string[]	array	body
aezeed_passphrase aezeed_passphrase is an optional user provided passphrase that will be used to encrypt the generated aezeed cipher seed. 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 filesystem. If this parameter is set, then the admin macaroon returned in the response MUST be stored by the caller of the RPC as otherwise all access to the daemon will be lost!	bool	boolean	body
extended_master_key extended_master_key is an alternative to specifying cipher_seed_mnemonic and aezeed_passphrase. Instead of deriving the master root key from the entropy of an aezeed cipher seed, the given extended master root key is used directly as the wallet's master key. This allows users to import/use a master key from another wallet. When doing so, lnd still uses its default SegWit only (BIP49/84) derivation paths and funds from custom/non-default derivation paths will not automatically appear in the on-chain wallet. Using an 'xprv' instead of an aezeed also has the disadvantage that the wallet's birthday is not known as that is an information that's only encoded in the aezeed, not the xprv. Therefore a birthday needs to be specified in extended_master_key_birthday_timestamp or a "safe" default value will be used.	string	string	body
extended_master_key_birthday_timestamp extended_master_key_birthday_timestamp is the optional unix timestamp in seconds to use as the wallet's birthday when using an extended master key to restore the wallet. lnd will only start scanning for funds in blocks that are after the birthday which can speed up the process significantly. If the birthday is not known, this should be left at its default value of 0 in which case lnd will start scanning from the first SegWit block (481824 on mainnet).	uint64	string	body
watch_only watchonly is the third option of initializing a wallet: by importing account xpubs only and therefore creating a watch-only wallet that does not contain any private keys. That means the wallet won't be able to sign for any of the keys and _needs to be run with a remote signer that has the corresponding private keys and can serve signing RPC requests.	WatchOnly	object	body
macaroon_root_key macaroon_root_key is an optional 32 byte macaroon root key that can be provided when initializing the wallet rather than letting lnd generate one on its own.	bytes	string	body

lnrpc.InitWalletResponse

Source: walletunlocker.proto

Field	gRPC Type	REST Type
admin_macaroon The binary serialized admin macaroon that can be used to access the daemon after creating the wallet. If the stateless_init parameter was set to true, this is the ONLY copy of the macaroon and MUST be stored safely by the caller. Otherwise a copy of this macaroon is also persisted on disk by the daemon, together with other macaroon files.	bytes	string

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

lnrpc.WatchOnly

Field	gRPC Type	REST Type
master_key_birthday_timestamp The unix timestamp in seconds of when the master key was created. lnd will only start scanning for funds in blocks that are after the birthday which can speed up the process significantly. If the birthday is not known, this should be left at its default value of 0 in which case lnd will start scanning from the first SegWit block (481824 on mainnet).	uint64	string
master_key_fingerprint The fingerprint of the root key (also known as the key with derivation path m/) from which the account public keys were derived from. This may be required by some hardware wallets for proper identification and signing. The bytes must be in big-endian order.	bytes	string
accounts The list of accounts to import. There must be an account for all of lnd's main key scopes: BIP49/BIP84 (m/49'/0'/0', m/84'/0'/0', note that the coin type is always 0, even for testnet/regtest) and lnd's internal key scope (m/1017'/<coin_type>'/<account>'), where account is the key family as defined in `keychain/derivation.go` (currently indices 0 to 9).	WatchOnlyAccount[]	array

lnrpc.WatchOnlyAccount

Field	gRPC Type	REST Type
purpose Purpose is the first number in the derivation path, must be either 49, 84 or 1017.	uint32	integer
coin_type Coin type is the second number in the derivation path, this is always 0 for purposes 49 and 84. It only needs to be set to 1 for purpose 1017 on testnet or regtest.	uint32	integer
account Account is the third number in the derivation path. For purposes 49 and 84 at least the default account (index 0) needs to be created but optional additional accounts are allowed. For purpose 1017 there needs to be exactly one account for each of the key families defined in `keychain/derivation.go` (currently indices 0 to 9)	uint32	integer
xpub The extended public key at depth 3 for the given account.	string	string