keystore

Documentation

Index

• Constants
• Variables
• 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, er.R)
  • func OpenDir(dir string) (*Store, er.R)
  • func (s *Store) ActiveAddresses() map[btcutil.Address]WalletAddress
  • func (s *Store) Address(a btcutil.Address) (WalletAddress, er.R)
  • func (s *Store) ChangePassphrase(newPass []byte) er.R
  • func (s *Store) ExportWatchingWallet() (*Store, er.R)
  • func (s *Store) ExtendActiveAddresses(n int) ([]btcutil.Address, er.R)
  • func (s *Store) ImportPrivateKey(wif *btcutil.WIF, bs *BlockStamp) (btcutil.Address, er.R)
  • func (s *Store) ImportScript(script []byte, bs *BlockStamp) (btcutil.Address, er.R)
  • func (s *Store) IsLocked() bool
  • func (s *Store) LastChainedAddress() btcutil.Address
  • func (s *Store) Lock() (err er.R)
  • func (s *Store) Net() *chaincfg.Params
  • func (s *Store) NextChainedAddress(bs *BlockStamp) (btcutil.Address, er.R)
  • func (s *Store) ReadFrom(r io.Reader) (int64, error)
  • func (s *Store) SetSyncStatus(a btcutil.Address, ss SyncStatus) er.R
  • func (s *Store) SortedActiveAddresses() []WalletAddress
  • func (s *Store) SyncedTo() (hash *chainhash.Hash, height int32)
  • func (s *Store) Unlock(passphrase []byte) er.R
  • func (s *Store) WriteTo(w io.Writer) (n int64, errr error)
• type SyncStatus
• type Unsynced
  • func (u Unsynced) ImplementsSyncStatus()
• type WalletAddress

Constants

const (
	Filename = "wallet.bin"
)

Variables

var (
	ErrAddressNotFound = Err.CodeWithDetail("ErrAddressNotFound",
		"address not found")
	ErrAlreadyEncrypted = Err.CodeWithDetail("ErrAlreadyEncrypted",
		"private key is already encrypted")
	ErrChecksumMismatch = Err.CodeWithDetail("ErrChecksumMismatch",
		"checksum mismatch")
	ErrDuplicate = Err.CodeWithDetail("ErrDuplicate",
		"duplicate key or address")
	ErrWatchingOnly = Err.CodeWithDetail("ErrWatchingOnly",
		"keystore is watching-only")
	ErrLocked = Err.CodeWithDetail("ErrLocked",
		"keystore is locked")
	ErrWrongPassphrase = Err.CodeWithDetail("ErrWrongPassphrase",
		"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.

var Err er.ErrorType = er.NewErrorType("keystore.Err")

Types

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, er.R)
	// ExportPrivKey exports the WIF private key.
	ExportPrivKey() (*btcutil.WIF, er.R)
}

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, er.R)

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, er.R)

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, er.R)

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

func (s *Store) ChangePassphrase(newPass []byte) er.R

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

func (*Store) ExportWatchingWallet

func (s *Store) ExportWatchingWallet() (*Store, er.R)

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, er.R)

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, er.R)

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, er.R)

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 er.R)

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

func (*Store) Net

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

Net returns the bitcoin network parameters for this key store.

func (*Store) NextChainedAddress

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

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) (int64, 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) er.R

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) 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) er.R

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

func (s *Store) WriteTo(w io.Writer) (n int64, errr 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.