unlock flow
This commit is contained in:
boufni95
parent
52a27a8ff9
commit
2648f55df0
13 changed files with 1815 additions and 7 deletions
338
proto/others/walletunlocker.proto
Normal file
338
proto/others/walletunlocker.proto
Normal file
|
|
@ -0,0 +1,338 @@
|
|||
syntax = "proto3";
|
||||
|
||||
package lnrpc;
|
||||
|
||||
import "lightning.proto";
|
||||
|
||||
option go_package = "github.com/lightningnetwork/lnd/lnrpc";
|
||||
|
||||
/*
|
||||
* Comments in this file will be directly parsed into the API
|
||||
* Documentation as descriptions of the associated method, message, or field.
|
||||
* These descriptions should go right above the definition of the object, and
|
||||
* can be in either block or // comment format.
|
||||
*
|
||||
* An RPC method can be matched to an lncli command by placing a line in the
|
||||
* beginning of the description in exactly the following format:
|
||||
* lncli: `methodname`
|
||||
*
|
||||
* Failure to specify the exact name of the command will cause documentation
|
||||
* generation to fail.
|
||||
*
|
||||
* More information on how exactly the gRPC documentation is generated from
|
||||
* this proto file can be found here:
|
||||
* https://github.com/lightninglabs/lightning-api
|
||||
*/
|
||||
|
||||
// WalletUnlocker is a service that is used to set up a wallet password for
|
||||
// lnd at first startup, and unlock a previously set up wallet.
|
||||
service WalletUnlocker {
|
||||
/*
|
||||
GenSeed is the first method that should be used to instantiate a new lnd
|
||||
instance. This method allows a caller to generate a new aezeed cipher seed
|
||||
given an optional passphrase. If provided, the passphrase will be necessary
|
||||
to decrypt the cipherseed to expose the internal wallet seed.
|
||||
|
||||
Once the cipherseed is obtained and verified by the user, the InitWallet
|
||||
method should be used to commit the newly generated seed, and create the
|
||||
wallet.
|
||||
*/
|
||||
rpc GenSeed (GenSeedRequest) returns (GenSeedResponse);
|
||||
|
||||
/*
|
||||
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.
|
||||
*/
|
||||
rpc InitWallet (InitWalletRequest) returns (InitWalletResponse);
|
||||
|
||||
/* lncli: `unlock`
|
||||
UnlockWallet is used at startup of lnd to provide a password to unlock
|
||||
the wallet database.
|
||||
*/
|
||||
rpc UnlockWallet (UnlockWalletRequest) returns (UnlockWalletResponse);
|
||||
|
||||
/* lncli: `changepassword`
|
||||
ChangePassword changes the password of the encrypted wallet. This will
|
||||
automatically unlock the wallet database if successful.
|
||||
*/
|
||||
rpc ChangePassword (ChangePasswordRequest) returns (ChangePasswordResponse);
|
||||
}
|
||||
|
||||
message GenSeedRequest {
|
||||
/*
|
||||
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 aezeed_passphrase = 1;
|
||||
|
||||
/*
|
||||
seed_entropy is an optional 16-bytes generated via CSPRNG. If not
|
||||
specified, then a fresh set of randomness will be used to create the seed.
|
||||
When using REST, this field must be encoded as base64.
|
||||
*/
|
||||
bytes seed_entropy = 2;
|
||||
}
|
||||
message GenSeedResponse {
|
||||
/*
|
||||
cipher_seed_mnemonic is a 24-word mnemonic that encodes a prior aezeed
|
||||
cipher seed obtained by the user. This field is optional, as if not
|
||||
provided, then the daemon will generate a new cipher seed for the user.
|
||||
Otherwise, then the daemon will attempt to recover the wallet state linked
|
||||
to this cipher seed.
|
||||
*/
|
||||
repeated string cipher_seed_mnemonic = 1;
|
||||
|
||||
/*
|
||||
enciphered_seed are the raw aezeed cipher seed bytes. This is the raw
|
||||
cipher text before run through our mnemonic encoding scheme.
|
||||
*/
|
||||
bytes enciphered_seed = 2;
|
||||
}
|
||||
|
||||
message InitWalletRequest {
|
||||
/*
|
||||
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 wallet_password = 1;
|
||||
|
||||
/*
|
||||
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.
|
||||
*/
|
||||
repeated string cipher_seed_mnemonic = 2;
|
||||
|
||||
/*
|
||||
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 aezeed_passphrase = 3;
|
||||
|
||||
/*
|
||||
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 recovery_window = 4;
|
||||
|
||||
/*
|
||||
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 channel_backups = 5;
|
||||
|
||||
/*
|
||||
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 stateless_init = 6;
|
||||
|
||||
/*
|
||||
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 extended_master_key = 7;
|
||||
|
||||
/*
|
||||
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 extended_master_key_birthday_timestamp = 8;
|
||||
|
||||
/*
|
||||
watch_only 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 watch_only = 9;
|
||||
|
||||
/*
|
||||
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 macaroon_root_key = 10;
|
||||
}
|
||||
message InitWalletResponse {
|
||||
/*
|
||||
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 admin_macaroon = 1;
|
||||
}
|
||||
|
||||
message WatchOnly {
|
||||
/*
|
||||
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 master_key_birthday_timestamp = 1;
|
||||
|
||||
/*
|
||||
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 master_key_fingerprint = 2;
|
||||
|
||||
/*
|
||||
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).
|
||||
*/
|
||||
repeated WatchOnlyAccount accounts = 3;
|
||||
}
|
||||
|
||||
message WatchOnlyAccount {
|
||||
/*
|
||||
Purpose is the first number in the derivation path, must be either 49, 84
|
||||
or 1017.
|
||||
*/
|
||||
uint32 purpose = 1;
|
||||
|
||||
/*
|
||||
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 coin_type = 2;
|
||||
|
||||
/*
|
||||
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 account = 3;
|
||||
|
||||
/*
|
||||
The extended public key at depth 3 for the given account.
|
||||
*/
|
||||
string xpub = 4;
|
||||
}
|
||||
|
||||
message UnlockWalletRequest {
|
||||
/*
|
||||
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 wallet_password = 1;
|
||||
|
||||
/*
|
||||
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 recovery_window = 2;
|
||||
|
||||
/*
|
||||
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 channel_backups = 3;
|
||||
|
||||
/*
|
||||
stateless_init is an optional argument instructing the daemon NOT to create
|
||||
any *.macaroon files in its file system.
|
||||
*/
|
||||
bool stateless_init = 4;
|
||||
}
|
||||
message UnlockWalletResponse {
|
||||
}
|
||||
|
||||
message ChangePasswordRequest {
|
||||
/*
|
||||
current_password should be the current valid passphrase used to unlock the
|
||||
daemon. When using REST, this field must be encoded as base64.
|
||||
*/
|
||||
bytes current_password = 1;
|
||||
|
||||
/*
|
||||
new_password should be the new passphrase that will be needed to unlock the
|
||||
daemon. When using REST, this field must be encoded as base64.
|
||||
*/
|
||||
bytes new_password = 2;
|
||||
|
||||
/*
|
||||
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 stateless_init = 3;
|
||||
|
||||
/*
|
||||
new_macaroon_root_key is an optional argument instructing the daemon to
|
||||
rotate the macaroon root key when set to true. This will invalidate all
|
||||
previously generated macaroons.
|
||||
*/
|
||||
bool new_macaroon_root_key = 4;
|
||||
}
|
||||
message ChangePasswordResponse {
|
||||
/*
|
||||
The binary serialized admin macaroon that can be used to access the daemon
|
||||
after rotating the macaroon root key. If both the stateless_init and
|
||||
new_macaroon_root_key parameter were set to true, this is the ONLY copy of
|
||||
the macaroon that was created from the new root key 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 admin_macaroon = 1;
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue