You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
238 lines
9.1 KiB
238 lines
9.1 KiB
syntax = "proto3"; |
|
|
|
import "rpc.proto"; |
|
|
|
package lnrpc; |
|
|
|
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; |
|
} |
|
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 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; |
|
}
|
|
|