lnd/lnrpc/walletunlocker.proto

syntax = "proto3";

import "lightning.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;
}