waddrmgr

package
v0.11.0-rc1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 21, 2024 License: ISC Imports: 20 Imported by: 9

README

waddrmgr

Build Status

Package waddrmgr provides a secure hierarchical deterministic wallet address manager.

A suite of tests is provided to ensure proper functionality. See test_coverage.txt for the gocov coverage report. Alternatively, if you are running a POSIX OS, you can run the cov_report.sh script for a real-time report. Package waddrmgr is licensed under the liberal ISC license.

Feature Overview

  • BIP0032 hierarchical deterministic keys
  • BIP0043/BIP0044 multi-account hierarchy
  • Strong focus on security:
    • Fully encrypted database including public information such as addresses as well as private information such as private keys and scripts needed to redeem pay-to-script-hash transactions
    • Hardened against memory scraping through the use of actively clearing private material from memory when locked
    • Different crypto keys used for public, private, and script data
    • Ability for different passphrases for public and private data
    • Scrypt-based key derivation
    • NaCl-based secretbox cryptography (XSalsa20 and Poly1305)
  • Scalable design:
    • Multi-tier key design to allow instant password changes regardless of the number of addresses stored
    • Import WIF keys
    • Import pay-to-script-hash scripts for things such as multi-signature transactions
    • Ability to export a watching-only version which does not contain any private key material
    • Programmatically detectable errors, including encapsulation of errors from packages it relies on
    • Address synchronization capabilities
  • Comprehensive test coverage

Documentation

[GoDoc] (http://godoc.org/github.com/gcash/bchwallet/waddrmgr)

Full go doc style documentation for the project can be viewed online without installing this package by using the GoDoc site here: http://godoc.org/github.com/gcash/bchwallet/waddrmgr

You can also view the documentation locally once the package is installed with the godoc tool by running godoc -http=":6060" and pointing your browser to http://localhost:6060/pkg/github.com/gcash/bchwallet/waddrmgr

Installation

$ go get github.com/gcash/bchwallet/waddrmgr

Package waddrmgr is licensed under the copyfree ISC License.

Documentation

Overview

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

Constants

View Source 
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
)
View Source 
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

View Source 
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,
		},
	}
)
View Source 
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

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

DefaultScryptOptions is the default options used with scrypt.

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

Functions

func Create 

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 added in v0.8.2 

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 

func DisableLog()

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

func IsError 

func IsError(err error, code ErrorCode) bool

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

func PutBirthdayBlock added in v0.8.2 

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 

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

PutSyncedTo stores the provided synced to blockstamp to the database.

func UseLogger 

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 

func ValidateAccountName(name string) error

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

Types

type AccountProperties 

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 

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 

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 

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 

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

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

type CryptoKeyType 

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 

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 

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 

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 

func (e ErrorCode) String() string

String returns the ErrorCode as a human-readable name.

type KeyScope 

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 

func (k *KeyScope) String() string

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

type ManagedAddress 

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 

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 

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 

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

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

func Open 

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 

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 

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 

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 

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 

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 

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 

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

ChainParams returns the chain parameters for this address manager.

func (*Manager) ChangePassphrase 

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 

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 

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 

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

Decrypt in using the crypto key type specified by keyType.

func (*Manager) Encrypt 

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

Encrypt in using the crypto key type specified by keyType.

func (*Manager) FetchScopedKeyManager 

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 

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 

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 

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 

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 

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 

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

MarkUsed updates the used flag for the provided address.

func (*Manager) MaybeExtendAddress 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

func (m *Manager) WatchOnly() bool

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

type ManagerError 

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 

func (e ManagerError) Error() string

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

type MigrationManager 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

func (s *ScopedKeyManager) AddrSchema() ScopeAddrSchema

AddrSchema returns the set address schema for the target ScopedKeyManager.

func (*ScopedKeyManager) Address 

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 

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

ChainParams returns the chain parameters for this address manager.

func (*ScopedKeyManager) Close 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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

LastAccount returns the last account stored in the manager.

func (*ScopedKeyManager) LastExternalAddress 

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 

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 

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 

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

MarkUsed updates the used flag for the provided address.

func (*ScopedKeyManager) NewAccount 

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 

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 

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 

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 

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 

func (s *ScopedKeyManager) Scope() KeyScope

Scope returns the exact KeyScope of this scoped key manager.

type ScryptOptions 

type ScryptOptions struct {
	N, R, P int
}

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.