org.bitcoinj.wallet

Interface KeyChain

All Known Subinterfaces:

EncryptableKeyChain

All Known Implementing Classes:

BasicKeyChain, DeterministicKeyChain, MarriedKeyChain

public interface KeyChain

A KeyChain is a class that stores a collection of keys for a Wallet. Key chains are expected to be able to look up keys given a hash (i.e. address) or pubkey bytes, and provide keys on request for a given purpose. They can inform event listeners about new keys being added.

However it is important to understand what this interface does not provide. It cannot encrypt or decrypt keys, for instance you need an implementor of EncryptableKeyChain. It cannot have keys imported into it, that you to use a method of a specific key chain instance, such as BasicKeyChain. The reason for these restrictions is to support key chains that may be handled by external hardware or software, or which are derived deterministically from a seed (and thus the notion of importing a key is meaningless).

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	KeyChain.KeyPurpose

Method Summary

Modifier and Type	Method and Description
void	addEventListener(KeyChainEventListener listener) Adds a listener for events that are run when keys are added, on the user thread.
void	addEventListener(KeyChainEventListener listener, Executor executor) Adds a listener for events that are run when keys are added, on the given executor.
long	getEarliestKeyCreationTime() Returns the earliest creation time of keys in this chain, in seconds since the epoch.
BloomFilter	getFilter(int size, double falsePositiveRate, long tweak) Gets a bloom filter that contains all of the public keys from this chain, and which will provide the given false-positive rate if it has size elements.
ECKey	getKey(KeyChain.KeyPurpose purpose) Obtains a key intended for the given purpose.
List<? extends ECKey>	getKeys(KeyChain.KeyPurpose purpose, int numberOfKeys) Obtains a number of key/s intended for the given purpose.
boolean	hasKey(ECKey key) Returns true if the given key is in the chain.
int	numBloomFilterEntries() Returns the number of elements this chain wishes to insert into the Bloom filter.
int	numKeys() Returns the number of keys this key chain manages.
boolean	removeEventListener(KeyChainEventListener listener) Removes a listener for events that are run when keys are added.
List<Protos.Key>	serializeToProtobuf() Returns a list of keys serialized to the bitcoinj protobuf format.

Method Detail

hasKey

boolean hasKey(ECKey key)

Returns true if the given key is in the chain.

getKeys

List<? extends ECKey> getKeys(KeyChain.KeyPurpose purpose,
                              int numberOfKeys)

Obtains a number of key/s intended for the given purpose. The chain may create new key/s, derive, or re-use an old one.

getKey

ECKey getKey(KeyChain.KeyPurpose purpose)

Obtains a key intended for the given purpose. The chain may create a new key, derive one, or re-use an old one.

serializeToProtobuf

List<Protos.Key> serializeToProtobuf()

Returns a list of keys serialized to the bitcoinj protobuf format.

addEventListener

void addEventListener(KeyChainEventListener listener)

Adds a listener for events that are run when keys are added, on the user thread.

addEventListener

void addEventListener(KeyChainEventListener listener,
                      Executor executor)

Adds a listener for events that are run when keys are added, on the given executor.

removeEventListener

boolean removeEventListener(KeyChainEventListener listener)

Removes a listener for events that are run when keys are added.

numKeys

int numKeys()

Returns the number of keys this key chain manages.

numBloomFilterEntries

int numBloomFilterEntries()

Returns the number of elements this chain wishes to insert into the Bloom filter. The size passed to getFilter(int, double, long) should be at least this large.

getEarliestKeyCreationTime

long getEarliestKeyCreationTime()

Returns the earliest creation time of keys in this chain, in seconds since the epoch. This can return zero if at least one key does not have that data (was created before key timestamping was implemented). If there are no keys in the wallet, Long.MAX_VALUE is returned.

getFilter

BloomFilter getFilter(int size,
                      double falsePositiveRate,
                      long tweak)

Gets a bloom filter that contains all of the public keys from this chain, and which will provide the given false-positive rate if it has size elements. Keep in mind that you will get 2 elements in the bloom filter for each key in the key chain, for the public key and the hash of the public key (address form). For this reason size should be at least 2x the result of numKeys().

This is used to generate a BloomFilter which can be BloomFilter.merge(BloomFilter)d with another. It could also be used if you have a specific target for the filter's size.

See the docs for BloomFilter.BloomFilter(int, double, long) for a brief explanation of anonymity when using bloom filters, and for the meaning of these parameters.