waddrmgr

package
v0.0.0-...-f4bb749 Latest Latest
Warning

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

Go to latest
Published: Nov 7, 2016 License: ISC Imports: 18 Imported by: 0

README

waddrmgr

[Build Status] (https://travis-ci.org/btcsuite/btcwallet)

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/btcsuite/btcwallet/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/btcsuite/btcwallet/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/btcsuite/btcwallet/waddrmgr

Installation

$ go get github.com/btcsuite/btcwallet/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

	// InsecurePubPassphrase is the default outer encryption passphrase used
	// for public data (everything but private keys).  Using a non-default
	// public passphrase can prevent an attacker without the public
	// passphrase from discovering all past and future wallet addresses if
	// they gain access to the wallet database.
	//
	// NOTE: at time of writing, public encryption only applies to public
	// data in the waddrmgr namespace.  Transactions are not yet encrypted.
	InsecurePubPassphrase = "public"

	// InsecurePrivPassphrase is used if no private passphrase is given.
	// For use with option 'nopass'.
	InsecurePrivPassphrase = "priv"
)
View Source
const (
	// LatestMgrVersion is the most recent manager version.
	LatestMgrVersion = 4
)

Variables

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.

Functions

func Create

func Create(namespace walletdb.Namespace, seed, pubPassphrase, privPassphrase []byte, chainParams *chaincfg.Params, config *ScryptOptions) 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 IsError

func IsError(err error, code ErrorCode) bool

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

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 BlockIterator

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

BlockIterator allows for the forwards and backwards iteration of recently seen blocks.

func (*BlockIterator) BlockStamp

func (it *BlockIterator) BlockStamp() BlockStamp

BlockStamp returns the block stamp associated with the recently seen block the iterator is currently pointing to.

func (*BlockIterator) Next

func (it *BlockIterator) Next() bool

Next returns the next recently seen block or false if there is not one.

func (*BlockIterator) Prev

func (it *BlockIterator) Prev() bool

Prev returns the previous recently seen block or false if there is not one.

type BlockStamp

type BlockStamp struct {
	Height int32
	Hash   chainhash.Hash
}

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.

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

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 ManagedAddress

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

	// Address returns a btcutil.Address for the backing address.
	Address() btcutil.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() (bool, error)
}

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() *btcec.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() (*btcec.PrivateKey, error)

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

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(namespace walletdb.Namespace, pubPassphrase []byte, chainParams *chaincfg.Params, cbs *OpenCallbacks) (*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) AccountName

func (m *Manager) AccountName(account uint32) (string, error)

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

func (*Manager) AccountProperties

func (m *Manager) AccountProperties(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.

TODO: Instead of opening a second read transaction after making a change, and then fetching the account properties with a new read tx, this can be made more performant by simply returning the new account properties during the change.

func (*Manager) AddrAccount

func (m *Manager) AddrAccount(address btcutil.Address) (uint32, error)

AddrAccount returns the account to which the given address belongs.

func (*Manager) Address

func (m *Manager) Address(address btcutil.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) ChainParams

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

ChainParams returns the chain parameters for this address manager.

func (*Manager) ChangePassphrase

func (m *Manager) ChangePassphrase(oldPass, newPass []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() error

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() 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) ForEachAccount

func (m *Manager) ForEachAccount(fn func(account uint32) error) error

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

func (*Manager) ForEachAccountAddress

func (m *Manager) ForEachAccountAddress(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(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 (*Manager) ForEachActiveAddress

func (m *Manager) ForEachActiveAddress(fn func(addr btcutil.Address) error) error

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

func (*Manager) ImportPrivateKey

func (m *Manager) ImportPrivateKey(wif *btcutil.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 (*Manager) ImportScript

func (m *Manager) ImportScript(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 (*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) LastAccount

func (m *Manager) LastAccount() (uint32, error)

LastAccount returns the last account stored in the manager.

func (*Manager) LastExternalAddress

func (m *Manager) LastExternalAddress(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 (*Manager) LastInternalAddress

func (m *Manager) LastInternalAddress(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 (*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) LookupAccount

func (m *Manager) LookupAccount(name string) (uint32, error)

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

func (*Manager) MarkUsed

func (m *Manager) MarkUsed(address btcutil.Address) error

MarkUsed updates the used flag for the provided address.

func (*Manager) NewAccount

func (m *Manager) NewAccount(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 (*Manager) NewIterateRecentBlocks

func (m *Manager) NewIterateRecentBlocks() *BlockIterator

NewIterateRecentBlocks returns an iterator for recently-seen blocks. The iterator starts at the most recently-added block, and Prev should be used to access earlier blocks.

NOTE: Ideally this should not really be a part of the address manager as it is intended for syncing purposes. It is being exposed here for now to go with the other syncing code. Ultimately, all syncing code should probably go into its own package and share the data store.

func (*Manager) NextExternalAddresses

func (m *Manager) NextExternalAddresses(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 (*Manager) NextInternalAddresses

func (m *Manager) NextInternalAddresses(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 (*Manager) RenameAccount

func (m *Manager) RenameAccount(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 (*Manager) SetSyncedTo

func (m *Manager) SetSyncedTo(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(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.

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 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 ScryptOptions

type ScryptOptions struct {
	N, R, P int
}

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL