Interface KeyChain

  • All Known Subinterfaces:
    EncryptableKeyChain
    All Known Implementing Classes:
    BasicKeyChain, DeterministicKeyChain

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

    • Method Detail

      • hasKey

        boolean hasKey​(ECKey key)
        Returns true if the given key is in the chain.
      • getKeys

        java.util.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

        java.util.List<org.bitcoinj.protobuf.wallet.Protos.Key> serializeToProtobuf()
        Return a list of keys serialized to the bitcoinj protobuf format.
        Returns:
        list of keys (treat as unmodifiable list)
      • 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,
                              java.util.concurrent.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, int) should be at least this large.
      • earliestKeyCreationTime

        java.time.Instant earliestKeyCreationTime()
        Returns the earliest creation time of keys in this chain.
        Returns:
        earliest creation times of keys in this chain, Instant.EPOCH if at least one time is unknown, Instant.MAX if no keys in this chain
      • getEarliestKeyCreationTime

        @Deprecated
        default long getEarliestKeyCreationTime()
        Deprecated.
      • getFilter

        BloomFilter getFilter​(int size,
                              double falsePositiveRate,
                              int 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(int, double, int) for a brief explanation of anonymity when using bloom filters, and for the meaning of these parameters.