walletunlocker

Documentation

Index

• Variables
• func ValidatePassword(password []byte) error
• type ChannelsToRecover
• type UnlockerService
  • func New(params *chaincfg.Params, macaroonFiles []string, resetWalletTransactions bool, ...) *UnlockerService
  • func (u *UnlockerService) ChangePassword(ctx context.Context, in *lnrpc.ChangePasswordRequest) (*lnrpc.ChangePasswordResponse, error)
  • func (u *UnlockerService) GenSeed(_ context.Context, in *lnrpc.GenSeedRequest) (*lnrpc.GenSeedResponse, error)
  • func (u *UnlockerService) InitWallet(ctx context.Context, in *lnrpc.InitWalletRequest) (*lnrpc.InitWalletResponse, error)
  • func (u *UnlockerService) LoadAndUnlock(password []byte, recoveryWindow uint32) (*wallet.Wallet, func() error, error)
  • func (u *UnlockerService) SetLoaderOpts(loaderOpts []btcwallet.LoaderOption)
  • func (u *UnlockerService) SetMacaroonDB(macaroonDB kvdb.Backend)
  • func (u *UnlockerService) UnlockWallet(ctx context.Context, in *lnrpc.UnlockWalletRequest) (*lnrpc.UnlockWalletResponse, error)
  • func (u *UnlockerService) WalletExists() (bool, error)
• type WalletInitMsg
• type WalletUnlockMsg
• type WalletUnlockParams

Variables

var (
	// ErrUnlockTimeout signals that we did not get the expected unlock
	// message before the timeout occurred.
	ErrUnlockTimeout = errors.New("got no unlock message before timeout")
)

Functions

func ValidatePassword

func ValidatePassword(password []byte) error

ValidatePassword assures the password meets all of our constraints.

Types

type ChannelsToRecover

type ChannelsToRecover struct {
	// PackedMultiChanBackup is an encrypted and serialized multi-channel
	// backup.
	PackedMultiChanBackup chanbackup.PackedMulti

	// PackedSingleChanBackups is a series of encrypted and serialized
	// single-channel backup for one or more channels.
	PackedSingleChanBackups chanbackup.PackedSingles
}

ChannelsToRecover wraps any set of packed (serialized+encrypted) channel back ups together. These can be passed in when unlocking the wallet, or creating a new wallet for the first time with an existing seed.

type UnlockerService

type UnlockerService struct {
	// Required by the grpc-gateway/v2 library for forward compatibility.
	lnrpc.UnimplementedWalletUnlockerServer

	// InitMsgs is a channel that carries all wallet init messages.
	InitMsgs chan *WalletInitMsg

	// UnlockMsgs is a channel where unlock parameters provided by the rpc
	// client to be used to unlock and decrypt an existing wallet will be
	// sent.
	UnlockMsgs chan *WalletUnlockMsg

	// MacResponseChan is the channel for sending back the admin macaroon to
	// the WalletUnlocker service.
	MacResponseChan chan []byte
	// contains filtered or unexported fields
}

UnlockerService implements the WalletUnlocker service used to provide broln with a password for wallet encryption at startup. Additionally, during initial setup, users can provide their own source of entropy which will be used to generate the seed that's ultimately used within the wallet.

func New

func New(params *chaincfg.Params, macaroonFiles []string,
	resetWalletTransactions bool,
	loaderOpts []btcwallet.LoaderOption) *UnlockerService

New creates and returns a new UnlockerService.

func (*UnlockerService) ChangePassword

func (u *UnlockerService) ChangePassword(ctx context.Context,
	in *lnrpc.ChangePasswordRequest) (*lnrpc.ChangePasswordResponse, error)

ChangePassword changes the password of the wallet and sends the new password across the UnlockPasswords channel to automatically unlock the wallet if successful.

func (*UnlockerService) GenSeed

func (u *UnlockerService) GenSeed(_ context.Context,
	in *lnrpc.GenSeedRequest) (*lnrpc.GenSeedResponse, error)

GenSeed is the first method that should be used to instantiate a new broln 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.

func (*UnlockerService) InitWallet

func (u *UnlockerService) InitWallet(ctx context.Context,
	in *lnrpc.InitWalletRequest) (*lnrpc.InitWalletResponse, error)

InitWallet is used when broln 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.

func (*UnlockerService) LoadAndUnlock

func (u *UnlockerService) LoadAndUnlock(password []byte,
	recoveryWindow uint32) (*wallet.Wallet, func() error, error)

LoadAndUnlock creates a loader for the wallet and tries to unlock the wallet with the given password and recovery window. If the drop wallet transactions flag is set, the history state drop is performed before unlocking the wallet yet again.

func (*UnlockerService) SetLoaderOpts

func (u *UnlockerService) SetLoaderOpts(loaderOpts []btcwallet.LoaderOption)

SetLoaderOpts can be used to inject wallet loader options after the unlocker service has been hooked to the main RPC server.

func (*UnlockerService) SetMacaroonDB

func (u *UnlockerService) SetMacaroonDB(macaroonDB kvdb.Backend)

SetMacaroonDB can be used to inject the macaroon database after the unlocker service has been hooked to the main RPC server.

func (*UnlockerService) UnlockWallet

func (u *UnlockerService) UnlockWallet(ctx context.Context,
	in *lnrpc.UnlockWalletRequest) (*lnrpc.UnlockWalletResponse, error)

UnlockWallet sends the password provided by the incoming UnlockWalletRequest over the UnlockMsgs channel in case it successfully decrypts an existing wallet found in the chain's wallet database directory.

func (*UnlockerService) WalletExists

func (u *UnlockerService) WalletExists() (bool, error)

WalletExists returns whether a wallet exists on the file path the UnlockerService is using.

type WalletInitMsg

type WalletInitMsg struct {
	// Passphrase is the passphrase that will be used to encrypt the wallet
	// itself. This MUST be at least 8 characters.
	Passphrase []byte

	// WalletSeed is the deciphered cipher seed that the wallet should use
	// to initialize itself. The seed might be nil if the wallet should be
	// created from an extended master root key instead.
	WalletSeed *aezeed.CipherSeed

	// WalletExtendedKey is the wallet's extended master root key that
	// should be used instead of the seed, if non-nil. The extended key is
	// mutually exclusive to the wallet seed, but one of both is always set.
	WalletExtendedKey *hdkeychain.ExtendedKey

	// ExtendedKeyBirthday is the birthday of a wallet that's being restored
	// through an extended key instead of an aezeed.
	ExtendedKeyBirthday time.Time

	// WatchOnlyAccounts is a map of scoped account extended public keys
	// that should be imported to create a watch-only wallet.
	WatchOnlyAccounts map[waddrmgr.ScopedIndex]*hdkeychain.ExtendedKey

	// WatchOnlyBirthday is the birthday of the master root key the above
	// watch-only account xpubs were derived from.
	WatchOnlyBirthday time.Time

	// WatchOnlyMasterFingerprint is the fingerprint of the master root key
	// the above watch-only account xpubs were derived from.
	WatchOnlyMasterFingerprint uint32

	// RecoveryWindow is the address look-ahead used when restoring a seed
	// with existing funds. A recovery window zero indicates that no
	// recovery should be attempted, such as after the wallet's initial
	// creation.
	RecoveryWindow uint32

	// ChanBackups a set of static channel backups that should be received
	// after the wallet has been initialized.
	ChanBackups ChannelsToRecover

	// StatelessInit signals that the user requested the daemon to be
	// initialized stateless, which means no unencrypted macaroons should be
	// written to disk.
	StatelessInit bool
}

WalletInitMsg is a message sent by the UnlockerService when a user wishes to set up the internal wallet for the first time. The user MUST provide a passphrase, but is also able to provide their own source of entropy. If provided, then this source of entropy will be used to generate the wallet's HD seed. Otherwise, the wallet will generate one itself.

type WalletUnlockMsg

type WalletUnlockMsg struct {
	// Passphrase is the passphrase that will be used to encrypt the wallet
	// itself. This MUST be at least 8 characters.
	Passphrase []byte

	// RecoveryWindow is the address look-ahead used when restoring a seed
	// with existing funds. A recovery window zero indicates that no
	// recovery should be attempted, such as after the wallet's initial
	// creation, but before any addresses have been created.
	RecoveryWindow uint32

	// Wallet is the loaded and unlocked Wallet. This is returned through
	// the channel to avoid it being unlocked twice (once to check if the
	// password is correct, here in the WalletUnlocker and again later when
	// broln actually uses it). Because unlocking involves scrypt which is
	// resource intensive, we want to avoid doing it twice.
	Wallet *wallet.Wallet

	// ChanBackups a set of static channel backups that should be received
	// after the wallet has been unlocked.
	ChanBackups ChannelsToRecover

	// UnloadWallet is a function for unloading the wallet, which should
	// be called on shutdown.
	UnloadWallet func() error

	// StatelessInit signals that the user requested the daemon to be
	// initialized stateless, which means no unencrypted macaroons should be
	// written to disk.
	StatelessInit bool
}

WalletUnlockMsg is a message sent by the UnlockerService when a user wishes to unlock the internal wallet after initial setup. The user can optionally specify a recovery window, which will resume an interrupted rescan for used addresses.

type WalletUnlockParams

type WalletUnlockParams struct {
	// Password is the public and private wallet passphrase.
	Password []byte

	// Birthday specifies the approximate time that this wallet was created.
	// This is used to bound any rescans on startup.
	Birthday time.Time

	// RecoveryWindow specifies the address lookahead when entering recovery
	// mode. A recovery will be attempted if this value is non-zero.
	RecoveryWindow uint32

	// Wallet is the loaded and unlocked Wallet. This is returned
	// from the unlocker service to avoid it being unlocked twice (once in
	// the unlocker service to check if the password is correct and again
	// later when broln actually uses it). Because unlocking involves scrypt
	// which is resource intensive, we want to avoid doing it twice.
	Wallet *wallet.Wallet

	// ChansToRestore a set of static channel backups that should be
	// restored before the main server instance starts up.
	ChansToRestore ChannelsToRecover

	// UnloadWallet is a function for unloading the wallet, which should
	// be called on shutdown.
	UnloadWallet func() error

	// StatelessInit signals that the user requested the daemon to be
	// initialized stateless, which means no unencrypted macaroons should be
	// written to disk.
	StatelessInit bool

	// MacResponseChan is the channel for sending back the admin macaroon to
	// the WalletUnlocker service.
	MacResponseChan chan []byte
}

WalletUnlockParams holds the variables used to parameterize the unlocking of broln's wallet after it has already been created.