keystore

Documentation

Index

• Constants
• Variables
• type BlockIterator
  • func (it *BlockIterator) BlockStamp() BlockStamp
  • func (it *BlockIterator) Next() bool
  • func (it *BlockIterator) Prev() bool
• type BlockStamp
• type FullSync
  • func (f FullSync) ImplementsSyncStatus()
• type PartialSync
  • func (p PartialSync) ImplementsSyncStatus()
• type PubKeyAddress
• type ScriptAddress
• type Store
  • func New(dir string, desc string, passphrase []byte, net *chaincfg.Params, ...) (*Store, error)
  • func OpenDir(dir string) (*Store, error)
  • func (s *Store) ActiveAddresses() map[btcutil.Address]WalletAddress
  • func (s *Store) Address(a btcutil.Address) (WalletAddress, error)
  • func (s *Store) ChangeAddress(bs *BlockStamp) (btcutil.Address, error)
  • func (s *Store) ChangePassphrase(new []byte) error
  • func (s *Store) CreateDate() int64
  • func (s *Store) ExportWatchingWallet() (*Store, error)
  • func (s *Store) ExtendActiveAddresses(n int) ([]btcutil.Address, error)
  • func (s *Store) ImportPrivateKey(wif *btcutil.WIF, bs *BlockStamp) (btcutil.Address, error)
  • func (s *Store) ImportScript(script []byte, bs *BlockStamp) (btcutil.Address, error)
  • func (s *Store) IsLocked() bool
  • func (s *Store) LastChainedAddress() btcutil.Address
  • func (s *Store) Lock() (err error)
  • func (s *Store) MarkDirty()
  • func (s *Store) Net() *chaincfg.Params
  • func (s *Store) NewIterateRecentBlocks() *BlockIterator
  • func (s *Store) NextChainedAddress(bs *BlockStamp) (btcutil.Address, error)
  • func (s *Store) ReadFrom(r io.Reader) (n int64, err error)
  • func (s *Store) SetSyncStatus(a btcutil.Address, ss SyncStatus) error
  • func (s *Store) SetSyncedWith(bs *BlockStamp)
  • func (s *Store) SortedActiveAddresses() []WalletAddress
  • func (s *Store) SyncedTo() (hash *chainhash.Hash, height int32)
  • func (s *Store) Unlock(passphrase []byte) error
  • func (s *Store) WriteIfDirty() error
  • func (s *Store) WriteTo(w io.Writer) (n int64, err error)
• type SyncStatus
• type Unsynced
  • func (u Unsynced) ImplementsSyncStatus()
• type WalletAddress

Constants

const (
	Filename = "wallet.bin"
)

Variables

var (
	ErrAddressNotFound  = errors.New("address not found")
	ErrAlreadyEncrypted = errors.New("private key is already encrypted")
	ErrChecksumMismatch = errors.New("checksum mismatch")
	ErrDuplicate        = errors.New("duplicate key or address")
	ErrMalformedEntry   = errors.New("malformed entry")
	ErrWatchingOnly     = errors.New("keystore is watching-only")
	ErrLocked           = errors.New("keystore is locked")
	ErrWrongPassphrase  = errors.New("wrong passphrase")
)

Possible errors when dealing with key stores.

var (
	// VersArmory is the latest version used by Armory.
	VersArmory = version{1, 35, 0, 0}

	// Vers20LastBlocks is the version where key store files now hold
	// the 20 most recently seen block hashes.
	Vers20LastBlocks = version{1, 36, 0, 0}

	// VersUnsetNeedsPrivkeyFlag is the bugfix version where the
	// createPrivKeyNextUnlock address flag is correctly unset
	// after creating and encrypting its private key after unlock.
	// Otherwise, re-creating private keys will occur too early
	// in the address chain and fail due to encrypting an already
	// encrypted address.  Key store versions at or before this
	// version include a special case to allow the duplicate
	// encrypt.
	VersUnsetNeedsPrivkeyFlag = version{1, 36, 1, 0}

	// VersCurrent is the current key store file version.
	VersCurrent = VersUnsetNeedsPrivkeyFlag
)

Various versions.

Types

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

func (*BlockIterator) Next

func (it *BlockIterator) Next() bool

func (*BlockIterator) Prev

func (it *BlockIterator) Prev() bool

type BlockStamp

type BlockStamp struct {
	Hash   *chainhash.Hash
	Height int32
}

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

type FullSync

type FullSync struct{}

FullSync is a type representing an address that is in sync with the recently seen blocks.

func (FullSync) ImplementsSyncStatus

func (f FullSync) ImplementsSyncStatus()

ImplementsSyncStatus is implemented to make FullSync a SyncStatus.

type PartialSync

type PartialSync int32

PartialSync is a type representing a partially synced address (for example, due to the result of a partially-completed rescan).

func (PartialSync) ImplementsSyncStatus

func (p PartialSync) ImplementsSyncStatus()

ImplementsSyncStatus is implemented to make PartialSync a SyncStatus.

type PubKeyAddress

type PubKeyAddress interface {
	WalletAddress
	// PubKey returns the public key associated with the address.
	PubKey() *btcec.PublicKey
	// ExportPubKey returns the public key associated with the address
	// serialised as a hex encoded string.
	ExportPubKey() string
	// PrivKey returns the private key for the address.
	// It can fail if the key store is watching only, the key store is locked,
	// or the address doesn't have any keys.
	PrivKey() (*btcec.PrivateKey, error)
	// ExportPrivKey exports the WIF private key.
	ExportPrivKey() (*btcutil.WIF, error)
}

PubKeyAddress implements WalletAddress and additionally provides the pubkey for a pubkey-based address.

type ScriptAddress

type ScriptAddress interface {
	WalletAddress
	// Returns the script associated with the address.
	Script() []byte
	// Returns the class of the script associated with the address.
	ScriptClass() txscript.ScriptClass
	// Returns the addresses that are required to sign transactions from the
	// script address.
	Addresses() []btcutil.Address
	// Returns the number of signatures required by the script address.
	RequiredSigs() int
}

ScriptAddress is an interface representing a Pay-to-Script-Hash style of bitcoind address.

type Store

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

Store represents an key store in memory. It implements the io.ReaderFrom and io.WriterTo interfaces to read from and write to any type of byte streams, including files.

func New

func New(dir string, desc string, passphrase []byte, net *chaincfg.Params,
	createdAt *BlockStamp) (*Store, error)

New creates and initializes a new Store. name's and desc's byte length must not exceed 32 and 256 bytes, respectively. All address private keys are encrypted with passphrase. The key store is returned locked.

func OpenDir

func OpenDir(dir string) (*Store, error)

OpenDir opens a new key store from the specified directory. If the file does not exist, the error from the os package will be returned, and can be checked with os.IsNotExist to differentiate missing file errors from others (including deserialization).

func (*Store) ActiveAddresses

func (s *Store) ActiveAddresses() map[btcutil.Address]WalletAddress

ActiveAddresses returns a map between active payment addresses and their full info. These do not include unused addresses in the key pool. If addresses must be sorted, use SortedActiveAddresses.

func (*Store) Address

func (s *Store) Address(a btcutil.Address) (WalletAddress, error)

Address returns an walletAddress structure for an address in a key store. This address may be typecast into other interfaces (like PubKeyAddress and ScriptAddress) if specific information e.g. keys is required.

func (*Store) ChangeAddress

func (s *Store) ChangeAddress(bs *BlockStamp) (btcutil.Address, error)

ChangeAddress returns the next chained address from the key store, marking the address for a change transaction output.

func (*Store) ChangePassphrase

func (s *Store) ChangePassphrase(new []byte) error

ChangePassphrase creates a new AES key from a new passphrase and re-encrypts all encrypted private keys with the new key.

func (*Store) CreateDate

func (s *Store) CreateDate() int64

CreateDate returns the Unix time of the key store creation time. This is used to compare the key store creation time against block headers and set a better minimum block height of where to being rescans.

func (*Store) ExportWatchingWallet

func (s *Store) ExportWatchingWallet() (*Store, error)

ExportWatchingWallet creates and returns a new key store with the same addresses in w, but as a watching-only key store without any private keys. New addresses created by the watching key store will match the new addresses created the original key store (thanks to public key address chaining), but will be missing the associated private keys.

func (*Store) ExtendActiveAddresses

func (s *Store) ExtendActiveAddresses(n int) ([]btcutil.Address, error)

ExtendActiveAddresses gets or creates the next n addresses from the address chain and marks each as active. This is used to recover deterministic (not imported) addresses from a key store backup, or to keep the active addresses in sync between an encrypted key store with private keys and an exported watching key store without.

A slice is returned with the btcutil.Address of each new address. The blockchain must be rescanned for these addresses.

func (*Store) ImportPrivateKey

func (s *Store) ImportPrivateKey(wif *btcutil.WIF, bs *BlockStamp) (btcutil.Address, error)

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

func (*Store) ImportScript

func (s *Store) ImportScript(script []byte, bs *BlockStamp) (btcutil.Address, error)

ImportScript creates a new scriptAddress with a user-provided script and adds it to the key store.

func (*Store) IsLocked

func (s *Store) IsLocked() bool

IsLocked returns whether a key store is unlocked (in which case the key is saved in memory), or locked.

func (*Store) LastChainedAddress

func (s *Store) LastChainedAddress() btcutil.Address

LastChainedAddress returns the most recently requested chained address from calling NextChainedAddress, or the root address if no chained addresses have been requested.

func (*Store) Lock

func (s *Store) Lock() (err error)

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

func (*Store) MarkDirty

func (s *Store) MarkDirty()

TODO: set this automatically.

func (*Store) Net

func (s *Store) Net() *chaincfg.Params

Net returns the bitcoin network parameters for this key store.

func (*Store) NewIterateRecentBlocks

func (s *Store) 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.

func (*Store) NextChainedAddress

func (s *Store) NextChainedAddress(bs *BlockStamp) (btcutil.Address, error)

NextChainedAddress attempts to get the next chained address. If the key store is unlocked, the next pubkey and private key of the address chain are derived. If the key store is locke, only the next pubkey is derived, and the private key will be generated on next unlock.

func (*Store) ReadFrom

func (s *Store) ReadFrom(r io.Reader) (n int64, err error)

ReadFrom reads data from a io.Reader and saves it to a key store, returning the number of bytes read and any errors encountered.

func (*Store) SetSyncStatus

func (s *Store) SetSyncStatus(a btcutil.Address, ss SyncStatus) error

SetSyncStatus sets the sync status for a single key store address. This may error if the address is not found in the key store.

When marking an address as unsynced, only the type Unsynced matters. The value is ignored.

func (*Store) SetSyncedWith

func (s *Store) SetSyncedWith(bs *BlockStamp)

SetSyncedWith marks already synced addresses in the key store to be in sync with the recently-seen block described by the blockstamp. Unsynced addresses are unaffected by this method and must be marked as in sync with MarkAddressSynced or MarkAllSynced to be considered in sync with bs.

If bs is nil, the entire key store is marked unsynced.

func (*Store) SortedActiveAddresses

func (s *Store) SortedActiveAddresses() []WalletAddress

SortedActiveAddresses returns all key store addresses that have been requested to be generated. These do not include unused addresses in the key pool. Use this when ordered addresses are needed. Otherwise, ActiveAddresses is preferred.

func (*Store) SyncedTo

func (s *Store) SyncedTo() (hash *chainhash.Hash, height int32)

SyncHeight returns details about the block that a wallet is marked at least synced through. The height is the height that rescans should start at when syncing a wallet back to the best chain.

NOTE: If the hash of the synced block is not known, hash will be nil, and must be obtained from elsewhere. This must be explicitly checked before dereferencing the pointer.

func (*Store) Unlock

func (s *Store) Unlock(passphrase []byte) error

Unlock derives an AES key from passphrase and key store's KDF parameters and unlocks the root key of the key store. If the unlock was successful, the key store's secret key is saved, allowing the decryption of any encrypted private key. Any addresses created while the key store was locked without private keys are created at this time.

func (*Store) WriteIfDirty

func (s *Store) WriteIfDirty() error

func (*Store) WriteTo

func (s *Store) WriteTo(w io.Writer) (n int64, err error)

WriteTo serializes a key store and writes it to a io.Writer, returning the number of bytes written and any errors encountered.

type SyncStatus

type SyncStatus interface {
	ImplementsSyncStatus()
}

SyncStatus is the interface type for all sync variants.

type Unsynced

type Unsynced int32

Unsynced is a type representing an unsynced address. When this is returned by a key store method, the value is the recorded first seen block height.

func (Unsynced) ImplementsSyncStatus

func (u Unsynced) ImplementsSyncStatus()

ImplementsSyncStatus is implemented to make Unsynced a SyncStatus.

type WalletAddress

type WalletAddress interface {
	// Address returns a btcutil.Address for the backing address.
	Address() btcutil.Address
	// AddrHash returns the key or script hash related to the address
	AddrHash() string
	// FirstBlock returns the first block an address could be in.
	FirstBlock() int32
	// Compressed returns true if the backing address was imported instead
	// of being part of an address chain.
	Imported() bool
	// Compressed returns true if the backing address was created for a
	// change output of a transaction.
	Change() bool
	// Compressed returns true if the backing address is compressed.
	Compressed() bool
	// SyncStatus returns the current synced state of an address.
	SyncStatus() SyncStatus
}

WalletAddress is an interface that provides acces to information regarding an address managed by a key store. Concrete implementations of this type may provide further fields to provide information specific to that type of address.