bchwallet: github.com/gcash/bchwallet/waddrmgr Index | Files

package waddrmgr

import "github.com/gcash/bchwallet/waddrmgr"

Package waddrmgr provides a secure hierarchical deterministic wallet address manager.

Overview

One of the fundamental jobs of a wallet is to manage addresses, private keys, and script data associated with them. At a high level, this package provides the facilities to perform this task with a focus on security and also allows recovery through the use of hierarchical deterministic keys (BIP0032) generated from a caller provided seed. The specific structure used is as described in BIP0044. This setup means as long as the user writes the seed down (even better is to use a mnemonic for the seed), all their addresses and private keys can be regenerated from the seed.

There are two master keys which are protected by two independent passphrases. One is intended for public facing data, while the other is intended for private data. The public password can be hardcoded for callers who don't want the additional public data protection or the same password can be used if a single password is desired. These choices provide a usability versus security tradeoff. However, keep in mind that extended hd keys, as called out in BIP0032 need to be handled more carefully than normal EC public keys because they can be used to generate all future addresses. While this is part of what makes them attractive, it also means an attacker getting access to your extended public key for an account will allow them to know all derived addresses you will use and hence reduces privacy. For this reason, it is highly recommended that you do not hard code a password which allows any attacker who gets a copy of your address manager database to access your effectively plain text extended public keys.

Each master key in turn protects the three real encryption keys (called crypto keys) for public, private, and script data. Some examples include payment addresses, extended hd keys, and scripts associated with pay-to-script-hash addresses. This scheme makes changing passphrases more efficient since only the crypto keys need to be re-encrypted versus every single piece of information (which is what is needed for *rekeying*). This results in a fully encrypted database where access to it does not compromise address, key, or script privacy. This differs from the handling by other wallets at the time of this writing in that they divulge your addresses, and worse, some even expose the chain code which can be used by the attacker to know all future addresses that will be used.

The address manager is also hardened against memory scrapers. This is accomplished by typically having the address manager locked meaning no private keys or scripts are in memory. Unlocking the address manager causes the crypto private and script keys to be decrypted and loaded in memory which in turn are used to decrypt private keys and scripts on demand. Relocking the address manager actively zeros all private material from memory. In addition, temp private key material used internally is zeroed as soon as it's used.

Locking and Unlocking

As previously mentioned, this package provide facilities for locking and unlocking the address manager to protect access to private material and remove it from memory when locked. The Lock, Unlock, and IsLocked functions are used for this purpose.

Creating a New Address Manager

A new address manager is created via the Create function. This function accepts a wallet database namespace, passphrases, network, and perhaps most importantly, a cryptographically random seed which is used to generate the master node of the hierarchical deterministic keychain which allows all addresses and private keys to be recovered with only the seed. The GenerateSeed function in the hdkeychain package can be used as a convenient way to create a random seed for use with this function. The address manager is locked immediately upon being created.

Opening an Existing Address Manager

An existing address manager is opened via the Open function. This function accepts an existing wallet database namespace, the public passphrase, and network. The address manager is opened locked as expected since the open function does not take the private passphrase to unlock it.

Closing the Address Manager

The Close method should be called on the address manager when the caller is done with it. While it is not required, it is recommended because it sanely shuts down the database and ensures all private and public key material is purged from memory.

Managed Addresses

Each address returned by the address manager satisifies the ManagedAddress interface as well as either the ManagedPubKeyAddress or ManagedScriptAddress interfaces. These interfaces provide the means to obtain relevant information about the addresses such as their private keys and scripts.

Chained Addresses

Most callers will make use of the chained addresses for normal operations. Internal addresses are intended for internal wallet uses such as change outputs, while external addresses are intended for uses such payment addresses that are shared. The NextInternalAddresses and NextExternalAddresses functions provide the means to acquire one or more of the next addresses that have not already been provided. In addition, the LastInternalAddress and LastExternalAddress functions can be used to get the most recently provided internal and external address, respectively.

Requesting Existing Addresses

In addition to generating new addresses, access to old addresses is often required. Most notably, to sign transactions in order to redeem them. The Address function provides this capability and returns a ManagedAddress.

Importing Addresses

While the recommended approach is to use the chained addresses discussed above because they can be deterministically regenerated to avoid losing funds as long as the user has the master seed, there are many addresses that already exist, and as a result, this package provides the ability to import existing private keys in Wallet Import Format (WIF) and hence the associated public key and address.

Importing Scripts

In order to support pay-to-script-hash transactions, the script must be securely stored as it is needed to redeem the transaction. This can be useful for a variety of scenarios, however the most common use is currently multi-signature transactions.

Syncing

The address manager also supports storing and retrieving a block hash and height which the manager is known to have all addresses synced through. The manager itself does not have any notion of which addresses are synced or not. It only provides the storage as a convenience for the caller.

Network

The address manager must be associated with a given network in order to provide appropriate addresses and reject imported addresses and scripts which don't apply to the associated network.

Errors

All errors returned from this package are of type ManagerError. This allows the caller to programmatically ascertain the specific reasons for failure by examining the ErrorCode field of the type asserted ManagerError. For certain error codes, as documented by the specific error codes, the underlying error will be contained in the Err field.

Bitcoin Improvement Proposals

This package includes concepts outlined by the following BIPs:

BIP0032 (https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki)
BIP0043 (https://github.com/bitcoin/bips/blob/master/bip-0043.mediawiki)
BIP0044 (https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki)

Index

Package Files

address.go db.go doc.go error.go log.go manager.go migrations.go scoped_manager.go sync.go

Constants

const (
    // MaxAccountNum is the maximum allowed account number.  This value was
    // chosen because accounts are hardened children and therefore must not
    // exceed the hardened child range of extended keys and it provides a
    // reserved account at the top of the range for supporting imported
    // addresses.
    MaxAccountNum = hdkeychain.HardenedKeyStart - 2 // 2^31 - 2

    // MaxAddressesPerAccount is the maximum allowed number of addresses
    // per account number.  This value is based on the limitation of the
    // underlying hierarchical deterministic key derivation.
    MaxAddressesPerAccount = hdkeychain.HardenedKeyStart - 1

    // ImportedAddrAccount is the account number to use for all imported
    // addresses.  This is useful since normal accounts are derived from
    // the root hierarchical deterministic key and imported addresses do
    // not fit into that model.
    ImportedAddrAccount = MaxAccountNum + 1 // 2^31 - 1

    // ImportedAddrAccountName is the name of the imported account.
    ImportedAddrAccountName = "imported"

    // DefaultAccountNum is the number of the default account.
    DefaultAccountNum = 0

    // ExternalBranch is the child number to use when performing BIP0044
    // style hierarchical deterministic key derivation for the external
    // branch.
    ExternalBranch uint32 = 0

    // InternalBranch is the child number to use when performing BIP0044
    // style hierarchical deterministic key derivation for the internal
    // branch.
    InternalBranch uint32 = 1

    // NumInitialAddrs is the number of internal and external addresses to
    // pre-generate when the wallet is created.
    NumInitialAddrs = 10
)
const (
    // MaxReorgDepth represents the maximum number of block hashes we'll
    // keep within the wallet at any given point in order to recover from
    // long reorgs.
    MaxReorgDepth = 10000
)

Variables

var (
    // KeyScopeBIP0044 is the key scope for BIP0044 derivation. Legacy
    // wallets will only be able to use this key scope, and no keys beyond
    // it.
    KeyScopeBIP0044 = KeyScope{
        Purpose: 44,
        Coin:    0,
    }

    // DefaultKeyScopes is the set of default key scopes that will be
    // created by the root manager upon initial creation.
    DefaultKeyScopes = []KeyScope{
        KeyScopeBIP0044,
    }

    // ScopeAddrMap is a map from the default key scopes to the scope
    // address schema for each scope type. This will be consulted during
    // the initial creation of the root key manager.
    ScopeAddrMap = map[KeyScope]ScopeAddrSchema{
        KeyScopeBIP0044: {
            InternalAddrType: PubKeyHash,
            ExternalAddrType: PubKeyHash,
        },
    }
)
var Break = managerError(ErrCallBackBreak, "callback break", nil)

Break is a global err used to signal a break from the callback function by returning an error with the code ErrCallBackBreak

var DefaultScryptOptions = ScryptOptions{
    N:  262144,
    R:  8,
    P:  1,
}

DefaultScryptOptions is the default options used with scrypt.

var (
    // LatestMgrVersion is the most recent manager version.
    LatestMgrVersion = getLatestVersion()
)

func Create Uses

func Create(ns walletdb.ReadWriteBucket, seed, pubPassphrase, privPassphrase []byte,
    chainParams *chaincfg.Params, config *ScryptOptions,
    birthday time.Time) error

Create creates a new address manager in the given namespace. The seed must conform to the standards described in hdkeychain.NewMaster and will be used to create the master root node from which all hierarchical deterministic addresses are derived. This allows all chained addresses in the address manager to be recovered by using the same seed.

All private and public keys and information are protected by secret keys derived from the provided private and public passphrases. The public passphrase is required on subsequent opens of the address manager, and the private passphrase is required to unlock the address manager in order to gain access to any private keys and information.

If a config structure is passed to the function, that configuration will override the defaults.

A ManagerError with an error code of ErrAlreadyExists will be returned the address manager already exists in the specified namespace.

func DeleteBirthdayBlock Uses

func DeleteBirthdayBlock(ns walletdb.ReadWriteBucket) error

DeleteBirthdayBlock removes the birthday block from the database.

NOTE: This does not alter the birthday block verification state.

func DisableLog Uses

func DisableLog()

DisableLog disables all library log output. Logging output is disabled by default until either UseLogger or SetLogWriter are called.

func IsError Uses

func IsError(err error, code ErrorCode) bool

IsError returns whether the error is a ManagerError with a matching error code.

func PutBirthdayBlock Uses

func PutBirthdayBlock(ns walletdb.ReadWriteBucket, block BlockStamp) error

PutBirthdayBlock stores the provided birthday block to the database.

The block is serialized as follows:

[0:4]   block height
[4:36]  block hash
[36:44] block timestamp

NOTE: This does not alter the birthday block verification state.

func PutSyncedTo Uses

func PutSyncedTo(ns walletdb.ReadWriteBucket, bs *BlockStamp) error

PutSyncedTo stores the provided synced to blockstamp to the database.

func UseLogger Uses

func UseLogger(logger bchlog.Logger)

UseLogger uses a specified Logger to output package logging info. This should be used in preference to SetLogWriter if the caller is also using btclog.

func ValidateAccountName Uses

func ValidateAccountName(name string) error

ValidateAccountName validates the given account name and returns an error, if any.

type AccountProperties Uses

type AccountProperties struct {
    AccountNumber    uint32
    AccountName      string
    ExternalKeyCount uint32
    InternalKeyCount uint32
    ImportedKeyCount uint32
}

AccountProperties contains properties associated with each account, such as the account name, number, and the nubmer of derived and imported keys.

type AddressType Uses

type AddressType uint8

AddressType represents the various address types waddrmgr is currently able to generate, and maintain.

NOTE: These MUST be stable as they're used for scope address schema recognition within the database.

const (
    // PubKeyHash is a regular p2pkh address.
    PubKeyHash AddressType = iota

    // Script reprints a raw script address.
    Script

    // RawPubKey is just raw public key to be used within scripts, This
    // type indicates that a scoped manager with this address type
    // shouldn't be consulted during historical rescans.
    RawPubKey
)

type BlockStamp Uses

type BlockStamp struct {
    Height    int32
    Hash      chainhash.Hash
    Timestamp time.Time
}

BlockStamp defines a block (by height and a unique hash) and is used to mark a point in the blockchain that an address manager element is synced to.

func FetchBirthdayBlock Uses

func FetchBirthdayBlock(ns walletdb.ReadBucket) (BlockStamp, error)

FetchBirthdayBlock retrieves the birthday block from the database.

The block is serialized as follows:

[0:4]   block height
[4:36]  block hash
[36:44] block timestamp

func FetchStartBlock Uses

func FetchStartBlock(ns walletdb.ReadBucket) (*BlockStamp, error)

FetchStartBlock loads the start block stamp for the manager from the database.

type CryptoKeyType Uses

type CryptoKeyType byte

CryptoKeyType is used to differentiate between different kinds of crypto keys.

const (
    // CKTPrivate specifies the key that is used for encryption of private
    // key material such as derived extended private keys and imported
    // private keys.
    CKTPrivate CryptoKeyType = iota

    // CKTScript specifies the key that is used for encryption of scripts.
    CKTScript

    // CKTPublic specifies the key that is used for encryption of public
    // key material such as dervied extended public keys and imported public
    // keys.
    CKTPublic
)

Crypto key types.

type DerivationPath Uses

type DerivationPath struct {
    // Account is the account, or the first immediate child from the scoped
    // manager's hardened coin type key.
    Account uint32

    // Branch is the branch to be derived from the account index above. For
    // BIP0044-like derivation, this is either 0 (external) or 1
    // (internal). However, we allow this value to vary arbitrarily within
    // its size range.
    Branch uint32

    // Index is the final child in the derivation path. This denotes the
    // key index within as a child of the account and branch.
    Index uint32
}

DerivationPath represents a derivation path from a particular key manager's scope. Each ScopedKeyManager starts key derivation from the end of their cointype hardened key: m/purpose'/cointype'. The fields in this struct allow further derivation to the next three child levels after the coin type key. This restriction is in the spriti of BIP0044 type derivation. We maintain a degree of coherency with the standard, but allow arbitrary derivations beyond the cointype key. The key derived using this path will be exactly: m/purpose'/cointype'/account/branch/index, where purpose' and cointype' are bound by the scope of a particular manager.

type EncryptorDecryptor Uses

type EncryptorDecryptor interface {
    Encrypt(in []byte) ([]byte, error)
    Decrypt(in []byte) ([]byte, error)
    Bytes() []byte
    CopyBytes([]byte)
    Zero()
}

EncryptorDecryptor provides an abstraction on top of snacl.CryptoKey so that our tests can use dependency injection to force the behaviour they need.

type ErrorCode Uses

type ErrorCode int

ErrorCode identifies a kind of error.

const (
    // ErrDatabase indicates an error with the underlying database.  When
    // this error code is set, the Err field of the ManagerError will be
    // set to the underlying error returned from the database.
    ErrDatabase ErrorCode = iota

    // ErrUpgrade indicates the manager needs to be upgraded.  This should
    // not happen in practice unless the version number has been increased
    // and there is not yet any code written to upgrade.
    ErrUpgrade

    // ErrKeyChain indicates an error with the key chain typically either
    // due to the inability to create an extended key or deriving a child
    // extended key.  When this error code is set, the Err field of the
    // ManagerError will be set to the underlying error.
    ErrKeyChain

    // ErrCrypto indicates an error with the cryptography related operations
    // such as decrypting or encrypting data, parsing an EC public key,
    // or deriving a secret key from a password.  When this error code is
    // set, the Err field of the ManagerError will be set to the underlying
    // error.
    ErrCrypto

    // ErrInvalidKeyType indicates an error where an invalid crypto
    // key type has been selected.
    ErrInvalidKeyType

    // ErrNoExist indicates that the specified database does not exist.
    ErrNoExist

    // ErrAlreadyExists indicates that the specified database already exists.
    ErrAlreadyExists

    // ErrCoinTypeTooHigh indicates that the coin type specified in the provided
    // network parameters is higher than the max allowed value as defined
    // by the maxCoinType constant.
    ErrCoinTypeTooHigh

    // ErrAccountNumTooHigh indicates that the specified account number is higher
    // than the max allowed value as defined by the MaxAccountNum constant.
    ErrAccountNumTooHigh

    // ErrLocked indicates that an operation, which requires the account
    // manager to be unlocked, was requested on a locked account manager.
    ErrLocked

    // ErrWatchingOnly indicates that an operation, which requires the
    // account manager to have access to private data, was requested on
    // a watching-only account manager.
    ErrWatchingOnly

    // ErrInvalidAccount indicates that the requested account is not valid.
    ErrInvalidAccount

    // ErrAddressNotFound indicates that the requested address is not known to
    // the account manager.
    ErrAddressNotFound

    // ErrAccountNotFound indicates that the requested account is not known to
    // the account manager.
    ErrAccountNotFound

    // ErrDuplicateAddress indicates an address already exists.
    ErrDuplicateAddress

    // ErrDuplicateAccount indicates an account already exists.
    ErrDuplicateAccount

    // ErrTooManyAddresses indicates that more than the maximum allowed number of
    // addresses per account have been requested.
    ErrTooManyAddresses

    // ErrWrongPassphrase indicates that the specified passphrase is incorrect.
    // This could be for either public or private master keys.
    ErrWrongPassphrase

    // ErrWrongNet indicates that the private key to be imported is not for the
    // the same network the account manager is configured for.
    ErrWrongNet

    // ErrCallBackBreak is used to break from a callback function passed
    // down to the manager.
    ErrCallBackBreak

    // ErrEmptyPassphrase indicates that the private passphrase was refused
    // due to being empty.
    ErrEmptyPassphrase

    // ErrScopeNotFound is returned when a target scope cannot be found
    // within the database.
    ErrScopeNotFound

    // ErrBirthdayBlockNotSet is returned when we attempt to retrieve the
    // wallet's birthday but it has not been set yet.
    ErrBirthdayBlockNotSet

    // ErrBlockNotFound is returned when we attempt to retrieve the hash for
    // a block that we do not know of.
    ErrBlockNotFound
)

These constants are used to identify a specific ManagerError.

func (ErrorCode) String Uses

func (e ErrorCode) String() string

String returns the ErrorCode as a human-readable name.

type KeyScope Uses

type KeyScope struct {
    // Purpose is the purpose of this key scope. This is the first child of
    // the master HD key.
    Purpose uint32

    // Coin is a value that represents the particular coin which is the
    // child of the purpose key. With this key, any accounts, or other
    // children can be derived at all.
    Coin uint32
}

KeyScope represents a restricted key scope from the primary root key within the HD chain. From the root manager (m/) we can create a nearly arbitrary number of ScopedKeyManagers of key derivation path: m/purpose'/cointype'. These scoped managers can then me managed indecently, as they house the encrypted cointype key and can derive any child keys from there on.

func (*KeyScope) String Uses

func (k *KeyScope) String() string

String returns a human readable version describing the keypath encapsulated by the target key scope.

type ManagedAddress Uses

type ManagedAddress interface {
    // Account returns the account the address is associated with.
    Account() uint32

    // Address returns a bchutil.Address for the backing address.
    Address() bchutil.Address

    // AddrHash returns the key or script hash related to the address
    AddrHash() []byte

    // Imported returns true if the backing address was imported instead
    // of being part of an address chain.
    Imported() bool

    // Internal returns true if the backing address was created for internal
    // use such as a change output of a transaction.
    Internal() bool

    // Compressed returns true if the backing address is compressed.
    Compressed() bool

    // Used returns true if the backing address has been used in a transaction.
    Used(ns walletdb.ReadBucket) bool

    // AddrType returns the address type of the managed address. This can
    // be used to quickly discern the address type without further
    // processing
    AddrType() AddressType
}

ManagedAddress is an interface that provides acces to information regarding an address managed by an address manager. Concrete implementations of this type may provide further fields to provide information specific to that type of address.

type ManagedPubKeyAddress Uses

type ManagedPubKeyAddress interface {
    ManagedAddress

    // PubKey returns the public key associated with the address.
    PubKey() *bchec.PublicKey

    // ExportPubKey returns the public key associated with the address
    // serialized as a hex encoded string.
    ExportPubKey() string

    // PrivKey returns the private key for the address.  It can fail if the
    // address manager is watching-only or locked, or the address does not
    // have any keys.
    PrivKey() (*bchec.PrivateKey, error)

    // ExportPrivKey returns the private key associated with the address
    // serialized as Wallet Import Format (WIF).
    ExportPrivKey() (*bchutil.WIF, error)

    // DerivationInfo contains the information required to derive the key
    // that backs the address via traditional methods from the HD root. For
    // imported keys, the first value will be set to false to indicate that
    // we don't know exactly how the key was derived.
    DerivationInfo() (KeyScope, DerivationPath, bool)
}

ManagedPubKeyAddress extends ManagedAddress and additionally provides the public and private keys for pubkey-based addresses.

type ManagedScriptAddress Uses

type ManagedScriptAddress interface {
    ManagedAddress

    // Script returns the script associated with the address.
    Script() ([]byte, error)
}

ManagedScriptAddress extends ManagedAddress and represents a pay-to-script-hash style of bitcoin addresses. It additionally provides information about the script.

type Manager Uses

type Manager struct {
    // contains filtered or unexported fields
}

Manager represents a concurrency safe crypto currency address manager and key store.

func Open Uses

func Open(ns walletdb.ReadBucket, pubPassphrase []byte,
    chainParams *chaincfg.Params) (*Manager, error)

Open loads an existing address manager from the given namespace. The public passphrase is required to decrypt the public keys used to protect the public information such as addresses. This is important since access to BIP0032 extended keys means it is possible to generate all future addresses.

If a config structure is passed to the function, that configuration will override the defaults.

A ManagerError with an error code of ErrNoExist will be returned if the passed manager does not exist in the specified namespace.

func (*Manager) ActiveScopedKeyManagers Uses

func (m *Manager) ActiveScopedKeyManagers() []*ScopedKeyManager

ActiveScopedKeyManagers returns a slice of all the active scoped key managers currently known by the root key manager.

func (*Manager) AddrAccount Uses

func (m *Manager) AddrAccount(ns walletdb.ReadBucket,
    address bchutil.Address) (*ScopedKeyManager, uint32, error)

AddrAccount returns the account to which the given address belongs. We also return the scoped manager that owns the addr+account combo.

func (*Manager) Address Uses

func (m *Manager) Address(ns walletdb.ReadBucket,
    address bchutil.Address) (ManagedAddress, error)

Address returns a managed address given the passed address if it is known to the address manager. A managed address differs from the passed address in that it also potentially contains extra information needed to sign transactions such as the associated private key for pay-to-pubkey and pay-to-pubkey-hash addresses and the script associated with pay-to-script-hash addresses.

func (*Manager) Birthday Uses

func (m *Manager) Birthday() time.Time

Birthday returns the birthday, or earliest time a key could have been used, for the manager.

func (*Manager) BirthdayBlock Uses

func (m *Manager) BirthdayBlock(ns walletdb.ReadBucket) (BlockStamp, bool, error)

BirthdayBlock returns the birthday block, or earliest block a key could have been used, for the manager. A boolean is also returned to indicate whether the birthday block has been verified as correct.

func (*Manager) BlockHash Uses

func (m *Manager) BlockHash(ns walletdb.ReadBucket, height int32) (
    *chainhash.Hash, error)

BlockHash returns the block hash at a particular block height. This information is useful for comparing against the chain back-end to see if a reorg is taking place and how far back it goes.

func (*Manager) ChainParams Uses

func (m *Manager) ChainParams() *chaincfg.Params

ChainParams returns the chain parameters for this address manager.

func (*Manager) ChangePassphrase Uses

func (m *Manager) ChangePassphrase(ns walletdb.ReadWriteBucket, oldPassphrase,
    newPassphrase []byte, private bool, config *ScryptOptions) error

ChangePassphrase changes either the public or private passphrase to the provided value depending on the private flag. In order to change the private password, the address manager must not be watching-only. The new passphrase keys are derived using the scrypt parameters in the options, so changing the passphrase may be used to bump the computational difficulty needed to brute force the passphrase.

func (*Manager) Close Uses

func (m *Manager) Close()

Close cleanly shuts down the manager. It makes a best try effort to remove and zero all private key and sensitive public key material associated with the address manager from memory.

func (*Manager) ConvertToWatchingOnly Uses

func (m *Manager) ConvertToWatchingOnly(ns walletdb.ReadWriteBucket) error

ConvertToWatchingOnly converts the current address manager to a locked watching-only address manager.

WARNING: This function removes private keys from the existing address manager which means they will no longer be available. Typically the caller will make a copy of the existing wallet database and modify the copy since otherwise it would mean permanent loss of any imported private keys and scripts.

Executing this function on a manager that is already watching-only will have no effect.

func (*Manager) Decrypt Uses

func (m *Manager) Decrypt(keyType CryptoKeyType, in []byte) ([]byte, error)

Decrypt in using the crypto key type specified by keyType.

func (*Manager) Encrypt Uses

func (m *Manager) Encrypt(keyType CryptoKeyType, in []byte) ([]byte, error)

Encrypt in using the crypto key type specified by keyType.

func (*Manager) FetchScopedKeyManager Uses

func (m *Manager) FetchScopedKeyManager(scope KeyScope) (*ScopedKeyManager, error)

FetchScopedKeyManager attempts to fetch an active scoped manager according to its registered scope. If the manger is found, then a nil error is returned along with the active scoped manager. Otherwise, a nil manager and a non-nil error will be returned.

func (*Manager) ForEachAccountAddress Uses

func (m *Manager) ForEachAccountAddress(ns walletdb.ReadBucket, account uint32,
    fn func(maddr ManagedAddress) error) error

ForEachAccountAddress calls the given function with each address of the given account stored in the manager, breaking early on error.

func (*Manager) ForEachActiveAccountAddress Uses

func (m *Manager) ForEachActiveAccountAddress(ns walletdb.ReadBucket,
    account uint32, fn func(maddr ManagedAddress) error) error

ForEachActiveAccountAddress calls the given function with each active address of the given account stored in the manager, across all active scopes, breaking early on error.

TODO(tuxcanfly): actually return only active addresses

func (*Manager) ForEachActiveAddress Uses

func (m *Manager) ForEachActiveAddress(ns walletdb.ReadBucket, fn func(addr bchutil.Address) error) error

ForEachActiveAddress calls the given function with each active address stored in the manager, breaking early on error.

func (*Manager) IsLocked Uses

func (m *Manager) IsLocked() bool

IsLocked returns whether or not the address managed is locked. When it is unlocked, the decryption key needed to decrypt private keys used for signing is in memory.

func (*Manager) Lock Uses

func (m *Manager) Lock() error

Lock performs a best try effort to remove and zero all secret keys associated with the address manager.

This function will return an error if invoked on a watching-only address manager.

func (*Manager) MarkUsed Uses

func (m *Manager) MarkUsed(ns walletdb.ReadWriteBucket, address bchutil.Address) error

MarkUsed updates the used flag for the provided address.

func (*Manager) MaybeExtendAddress Uses

func (m *Manager) MaybeExtendAddress(ns walletdb.ReadWriteBucket, address bchutil.Address) error

MaybeExtendAddress tells the scopedManger to extend the keychain by one if the number of used keys is below the buffer.

func (*Manager) NeuterRootKey Uses

func (m *Manager) NeuterRootKey(ns walletdb.ReadWriteBucket) error

NeuterRootKey is a special method that should be used once a caller is *certain* that no further scoped managers are to be created. This method will *delete* the encrypted master HD root private key from the database.

func (*Manager) NewScopedKeyManager Uses

func (m *Manager) NewScopedKeyManager(ns walletdb.ReadWriteBucket, scope KeyScope,
    addrSchema ScopeAddrSchema) (*ScopedKeyManager, error)

NewScopedKeyManager creates a new scoped key manager from the root manager. A scoped key manager is a sub-manager that only has the coin type key of a particular coin type and BIP0043 purpose. This is useful as it enables callers to create an arbitrary BIP0043 like schema with a stand alone manager. Note that a new scoped manager cannot be created if: the wallet is watch only, the manager hasn't been unlocked, or the root key has been. neutered from the database.

TODO(roasbeef): addrtype of raw key means it'll look in scripts to possibly mark as gucci?

func (*Manager) ScopesForExternalAddrType Uses

func (m *Manager) ScopesForExternalAddrType(addrType AddressType) []KeyScope

ScopesForExternalAddrType returns the set of key scopes that are able to produce the target address type as external addresses.

func (*Manager) ScopesForInternalAddrTypes Uses

func (m *Manager) ScopesForInternalAddrTypes(addrType AddressType) []KeyScope

ScopesForInternalAddrTypes returns the set of key scopes that are able to produce the target address type as internal addresses.

func (*Manager) SetBirthday Uses

func (m *Manager) SetBirthday(ns walletdb.ReadWriteBucket,
    birthday time.Time) error

SetBirthday sets the birthday, or earliest time a key could have been used, for the manager.

func (*Manager) SetBirthdayBlock Uses

func (m *Manager) SetBirthdayBlock(ns walletdb.ReadWriteBucket,
    block BlockStamp, verified bool) error

SetBirthdayBlock sets the birthday block, or earliest time a key could have been used, for the manager. The verified boolean can be used to specify whether this birthday block should be sanity checked to determine if there exists a better candidate to prevent less block fetching.

func (*Manager) SetSyncedTo Uses

func (m *Manager) SetSyncedTo(ns walletdb.ReadWriteBucket, bs *BlockStamp) error

SetSyncedTo marks the address manager to be in sync with the recently-seen block described by the blockstamp. When the provided blockstamp is nil, the oldest blockstamp of the block the manager was created at and of all imported addresses will be used. This effectively allows the manager to be marked as unsynced back to the oldest known point any of the addresses have appeared in the block chain.

func (*Manager) SyncedTo Uses

func (m *Manager) SyncedTo() BlockStamp

SyncedTo returns details about the block height and hash that the address manager is synced through at the very least. The intention is that callers can use this information for intelligently initiating rescans to sync back to the best chain from the last known good block.

func (*Manager) Unlock Uses

func (m *Manager) Unlock(ns walletdb.ReadBucket, passphrase []byte) error

Unlock derives the master private key from the specified passphrase. An invalid passphrase will return an error. Otherwise, the derived secret key is stored in memory until the address manager is locked. Any failures that occur during this function will result in the address manager being locked, even if it was already unlocked prior to calling this function.

This function will return an error if invoked on a watching-only address manager.

func (*Manager) WatchOnly Uses

func (m *Manager) WatchOnly() bool

WatchOnly returns true if the root manager is in watch only mode, and false otherwise.

type ManagerError Uses

type ManagerError struct {
    ErrorCode   ErrorCode // Describes the kind of error
    Description string    // Human readable description of the issue
    Err         error     // Underlying error
}

ManagerError provides a single type for errors that can happen during address manager operation. It is used to indicate several types of failures including errors with caller requests such as invalid accounts or requesting private keys against a locked address manager, errors with the database (ErrDatabase), errors with key chain derivation (ErrKeyChain), and errors related to crypto (ErrCrypto).

The caller can use type assertions to determine if an error is a ManagerError and access the ErrorCode field to ascertain the specific reason for the failure.

The ErrDatabase, ErrKeyChain, and ErrCrypto error codes will also have the Err field set with the underlying error.

func (ManagerError) Error Uses

func (e ManagerError) Error() string

Error satisfies the error interface and prints human-readable errors.

type MigrationManager Uses

type MigrationManager struct {
    // contains filtered or unexported fields
}

MigrationManager is an implementation of the migration.Manager interface that will be used to handle migrations for the address manager. It exposes the necessary parameters required to successfully perform migrations.

func NewMigrationManager Uses

func NewMigrationManager(ns walletdb.ReadWriteBucket) *MigrationManager

NewMigrationManager creates a new migration manager for the address manager. The given bucket should reflect the top-level bucket in which all of the address manager's data is contained within.

func (*MigrationManager) CurrentVersion Uses

func (m *MigrationManager) CurrentVersion(ns walletdb.ReadBucket) (uint32, error)

CurrentVersion returns the current version of the service's database.

NOTE: This method is part of the migration.Manager interface.

func (*MigrationManager) Name Uses

func (m *MigrationManager) Name() string

Name returns the name of the service we'll be attempting to upgrade.

NOTE: This method is part of the migration.Manager interface.

func (*MigrationManager) Namespace Uses

func (m *MigrationManager) Namespace() walletdb.ReadWriteBucket

Namespace returns the top-level bucket of the service.

NOTE: This method is part of the migration.Manager interface.

func (*MigrationManager) SetVersion Uses

func (m *MigrationManager) SetVersion(ns walletdb.ReadWriteBucket,
    version uint32) error

SetVersion sets the version of the service's database.

NOTE: This method is part of the migration.Manager interface.

func (*MigrationManager) Versions Uses

func (m *MigrationManager) Versions() []migration.Version

Versions returns all of the available database versions of the service.

NOTE: This method is part of the migration.Manager interface.

type ObtainUserInputFunc Uses

type ObtainUserInputFunc func() ([]byte, error)

ObtainUserInputFunc is a function that reads a user input and returns it as a byte stream. It is used to accept data required during upgrades, for e.g. wallet seed and private passphrase.

type OpenCallbacks Uses

type OpenCallbacks struct {
    // ObtainSeed is a callback function that is potentially invoked during
    // upgrades.  It is intended to be used to request the wallet seed
    // from the user (or any other mechanism the caller deems fit).
    ObtainSeed ObtainUserInputFunc

    // ObtainPrivatePass is a callback function that is potentially invoked
    // during upgrades.  It is intended to be used to request the wallet
    // private passphrase from the user (or any other mechanism the caller
    // deems fit).
    ObtainPrivatePass ObtainUserInputFunc
}

OpenCallbacks houses caller-provided callbacks that may be called when opening an existing manager. The open blocks on the execution of these functions.

type ScopeAddrSchema Uses

type ScopeAddrSchema struct {
    // ExternalAddrType is the address type for all keys within branch 0.
    ExternalAddrType AddressType

    // InternalAddrType is the address type for all keys within branch 1
    // (change addresses).
    InternalAddrType AddressType
}

ScopeAddrSchema is the address schema of a particular KeyScope. This will be persisted within the database, and will be consulted when deriving any keys for a particular scope to know how to encode the public keys as addresses.

type ScopedIndex Uses

type ScopedIndex struct {
    // Scope is the BIP44 account' used to derive the child key.
    Scope KeyScope

    // Index is the BIP44 address_index used to derive the child key.
    Index uint32
}

ScopedIndex is a tuple of KeyScope and child Index. This is used to compactly identify a particular child key, when the account and branch can be inferred from context.

type ScopedKeyManager Uses

type ScopedKeyManager struct {
    // contains filtered or unexported fields
}

ScopedKeyManager is a sub key manager under the main root key manager. The root key manager will handle the root HD key (m/), while each sub scoped key manager will handle the cointype key for a particular key scope (m/purpose'/cointype'). This abstraction allows higher-level applications built upon the root key manager to perform their own arbitrary key derivation, while still being protected under the encryption of the root key manager.

func (*ScopedKeyManager) AccountName Uses

func (s *ScopedKeyManager) AccountName(ns walletdb.ReadBucket, account uint32) (string, error)

AccountName returns the account name for the given account number stored in the manager.

func (*ScopedKeyManager) AccountProperties Uses

func (s *ScopedKeyManager) AccountProperties(ns walletdb.ReadBucket,
    account uint32) (*AccountProperties, error)

AccountProperties returns properties associated with the account, such as the account number, name, and the number of derived and imported keys.

func (*ScopedKeyManager) AddrAccount Uses

func (s *ScopedKeyManager) AddrAccount(ns walletdb.ReadBucket,
    address bchutil.Address) (uint32, error)

AddrAccount returns the account to which the given address belongs.

func (*ScopedKeyManager) AddrSchema Uses

func (s *ScopedKeyManager) AddrSchema() ScopeAddrSchema

AddrSchema returns the set address schema for the target ScopedKeyManager.

func (*ScopedKeyManager) Address Uses

func (s *ScopedKeyManager) Address(ns walletdb.ReadBucket,
    address bchutil.Address) (ManagedAddress, error)

Address returns a managed address given the passed address if it is known to the address manager. A managed address differs from the passed address in that it also potentially contains extra information needed to sign transactions such as the associated private key for pay-to-pubkey and pay-to-pubkey-hash addresses and the script associated with pay-to-script-hash addresses.

func (*ScopedKeyManager) ChainParams Uses

func (s *ScopedKeyManager) ChainParams() *chaincfg.Params

ChainParams returns the chain parameters for this address manager.

func (*ScopedKeyManager) Close Uses

func (s *ScopedKeyManager) Close()

Close cleanly shuts down the manager. It makes a best try effort to remove and zero all private key and sensitive public key material associated with the address manager from memory.

func (*ScopedKeyManager) CountUnused Uses

func (s *ScopedKeyManager) CountUnused(ns walletdb.ReadBucket,
    account uint32, internal bool) (int, error)

CountUnused returns the total number of unused addresses in the keychain.

This function will return an error if the provided account number is greater than the MaxAccountNum constant or there is no account information for the passed account. Any other errors returned are generally unexpected.

func (*ScopedKeyManager) DeriveFromKeyPath Uses

func (s *ScopedKeyManager) DeriveFromKeyPath(ns walletdb.ReadBucket,
    kp DerivationPath) (ManagedAddress, error)

DeriveFromKeyPath attempts to derive a maximal child key (under the BIP0044 scheme) from a given key path. If key derivation isn't possible, then an error will be returned.

func (*ScopedKeyManager) ExtendExternalAddresses Uses

func (s *ScopedKeyManager) ExtendExternalAddresses(ns walletdb.ReadWriteBucket,
    account uint32, lastIndex uint32) error

ExtendExternalAddresses ensures that all valid external keys through lastIndex are derived and stored in the wallet. This is used to ensure that wallet's persistent state catches up to a external child that was found during recovery.

func (*ScopedKeyManager) ExtendInternalAddresses Uses

func (s *ScopedKeyManager) ExtendInternalAddresses(ns walletdb.ReadWriteBucket,
    account uint32, lastIndex uint32) error

ExtendInternalAddresses ensures that all valid internal keys through lastIndex are derived and stored in the wallet. This is used to ensure that wallet's persistent state catches up to an internal child that was found during recovery.

func (*ScopedKeyManager) FirstUnusedAddress Uses

func (s *ScopedKeyManager) FirstUnusedAddress(ns walletdb.ReadBucket,
    account uint32, internal bool) (ManagedAddress, error)

FirstUnusedAddress returns the first unused address found in the keychain.

This function will return an error if the provided account number is greater than the MaxAccountNum constant or there is no account information for the passed account. Any other errors returned are generally unexpected.

func (*ScopedKeyManager) ForEachAccount Uses

func (s *ScopedKeyManager) ForEachAccount(ns walletdb.ReadBucket,
    fn func(account uint32) error) error

ForEachAccount calls the given function with each account stored in the manager, breaking early on error.

func (*ScopedKeyManager) ForEachAccountAddress Uses

func (s *ScopedKeyManager) ForEachAccountAddress(ns walletdb.ReadBucket,
    account uint32, fn func(maddr ManagedAddress) error) error

ForEachAccountAddress calls the given function with each address of the given account stored in the manager, breaking early on error.

func (*ScopedKeyManager) ForEachActiveAccountAddress Uses

func (s *ScopedKeyManager) ForEachActiveAccountAddress(ns walletdb.ReadBucket, account uint32,
    fn func(maddr ManagedAddress) error) error

ForEachActiveAccountAddress calls the given function with each active address of the given account stored in the manager, breaking early on error.

TODO(tuxcanfly): actually return only active addresses

func (*ScopedKeyManager) ForEachActiveAddress Uses

func (s *ScopedKeyManager) ForEachActiveAddress(ns walletdb.ReadBucket,
    fn func(addr bchutil.Address) error) error

ForEachActiveAddress calls the given function with each active address stored in the manager, breaking early on error.

func (*ScopedKeyManager) ImportPrivateKey Uses

func (s *ScopedKeyManager) ImportPrivateKey(ns walletdb.ReadWriteBucket,
    wif *bchutil.WIF, bs *BlockStamp) (ManagedPubKeyAddress, error)

ImportPrivateKey imports a WIF private key into the address manager. The imported address is created using either a compressed or uncompressed serialized public key, depending on the CompressPubKey bool of the WIF.

All imported addresses will be part of the account defined by the ImportedAddrAccount constant.

NOTE: When the address manager is watching-only, the private key itself will not be stored or available since it is private data. Instead, only the public key will be stored. This means it is paramount the private key is kept elsewhere as the watching-only address manager will NOT ever have access to it.

This function will return an error if the address manager is locked and not watching-only, or not for the same network as the key trying to be imported. It will also return an error if the address already exists. Any other errors returned are generally unexpected.

func (*ScopedKeyManager) ImportScript Uses

func (s *ScopedKeyManager) ImportScript(ns walletdb.ReadWriteBucket,
    script []byte, bs *BlockStamp) (ManagedScriptAddress, error)

ImportScript imports a user-provided script into the address manager. The imported script will act as a pay-to-script-hash address.

All imported script addresses will be part of the account defined by the ImportedAddrAccount constant.

When the address manager is watching-only, the script itself will not be stored or available since it is considered private data.

This function will return an error if the address manager is locked and not watching-only, or the address already exists. Any other errors returned are generally unexpected.

func (*ScopedKeyManager) LastAccount Uses

func (s *ScopedKeyManager) LastAccount(ns walletdb.ReadBucket) (uint32, error)

LastAccount returns the last account stored in the manager.

func (*ScopedKeyManager) LastExternalAddress Uses

func (s *ScopedKeyManager) LastExternalAddress(ns walletdb.ReadBucket,
    account uint32) (ManagedAddress, error)

LastExternalAddress returns the most recently requested chained external address from calling NextExternalAddress for the given account. The first external address for the account will be returned if none have been previously requested.

This function will return an error if the provided account number is greater than the MaxAccountNum constant or there is no account information for the passed account. Any other errors returned are generally unexpected.

func (*ScopedKeyManager) LastInternalAddress Uses

func (s *ScopedKeyManager) LastInternalAddress(ns walletdb.ReadBucket,
    account uint32) (ManagedAddress, error)

LastInternalAddress returns the most recently requested chained internal address from calling NextInternalAddress for the given account. The first internal address for the account will be returned if none have been previously requested.

This function will return an error if the provided account number is greater than the MaxAccountNum constant or there is no account information for the passed account. Any other errors returned are generally unexpected.

func (*ScopedKeyManager) LookupAccount Uses

func (s *ScopedKeyManager) LookupAccount(ns walletdb.ReadBucket, name string) (uint32, error)

LookupAccount loads account number stored in the manager for the given account name

func (*ScopedKeyManager) MarkUsed Uses

func (s *ScopedKeyManager) MarkUsed(ns walletdb.ReadWriteBucket,
    address bchutil.Address) error

MarkUsed updates the used flag for the provided address.

func (*ScopedKeyManager) NewAccount Uses

func (s *ScopedKeyManager) NewAccount(ns walletdb.ReadWriteBucket, name string) (uint32, error)

NewAccount creates and returns a new account stored in the manager based on the given account name. If an account with the same name already exists, ErrDuplicateAccount will be returned. Since creating a new account requires access to the cointype keys (from which extended account keys are derived), it requires the manager to be unlocked.

func (*ScopedKeyManager) NewRawAccount Uses

func (s *ScopedKeyManager) NewRawAccount(ns walletdb.ReadWriteBucket, number uint32) error

NewRawAccount creates a new account for the scoped manager. This method differs from the NewAccount method in that this method takes the acount number *directly*, rather than taking a string name for the account, then mapping that to the next highest account number.

func (*ScopedKeyManager) NextExternalAddresses Uses

func (s *ScopedKeyManager) NextExternalAddresses(ns walletdb.ReadWriteBucket,
    account uint32, numAddresses uint32) ([]ManagedAddress, error)

NextExternalAddresses returns the specified number of next chained addresses that are intended for external use from the address manager.

func (*ScopedKeyManager) NextInternalAddresses Uses

func (s *ScopedKeyManager) NextInternalAddresses(ns walletdb.ReadWriteBucket,
    account uint32, numAddresses uint32) ([]ManagedAddress, error)

NextInternalAddresses returns the specified number of next chained addresses that are intended for internal use such as change from the address manager.

func (*ScopedKeyManager) RenameAccount Uses

func (s *ScopedKeyManager) RenameAccount(ns walletdb.ReadWriteBucket,
    account uint32, name string) error

RenameAccount renames an account stored in the manager based on the given account number with the given name. If an account with the same name already exists, ErrDuplicateAccount will be returned.

func (*ScopedKeyManager) Scope Uses

func (s *ScopedKeyManager) Scope() KeyScope

Scope returns the exact KeyScope of this scoped key manager.

type ScryptOptions Uses

type ScryptOptions struct {
    N, R, P int
}

ScryptOptions is used to hold the scrypt parameters needed when deriving new passphrase keys.

type SecretKeyGenerator Uses

type SecretKeyGenerator func(
    passphrase *[]byte, config *ScryptOptions) (*snacl.SecretKey, error)

SecretKeyGenerator is the function signature of a method that can generate secret keys for the address manager.

func SetSecretKeyGen Uses

func SetSecretKeyGen(keyGen SecretKeyGenerator) SecretKeyGenerator

SetSecretKeyGen replaces the existing secret key generator, and returns the previous generator.

Package waddrmgr imports 20 packages (graph) and is imported by 8 packages. Updated 2019-09-04. Refresh now. Tools for package owners.