Package org.bitcoinj.wallet

Class DeterministicKeyChain

  • All Implemented Interfaces:
    EncryptableKeyChain, KeyChain
    public class DeterministicKeyChain
extends java.lang.Object
implements EncryptableKeyChain

    A deterministic key chain is a KeyChain that uses the BIP 32 standard, as implemented by DeterministicHierarchy, to derive all the keys in the keychain from a master seed. This type of wallet is extremely convenient and flexible. Although backing up full wallet files is always a good idea, to recover money only the root seed needs to be preserved and that is a number small enough that it can be written down on paper or, when represented using a BIP 39 MnemonicCode, dictated over the phone (possibly even memorized).

    Deterministic key chains have other advantages: parts of the key tree can be selectively revealed to allow for auditing, and new public keys can be generated without access to the private keys, yielding a highly secure configuration for web servers which can accept payments into a wallet but not spend from them. This does not work quite how you would expect due to a quirk of elliptic curve mathematics and the techniques used to deal with it. A watching wallet is not instantiated using the public part of the master key as you may imagine. Instead, you need to take the account key (first child of the master key) and provide the public part of that to the watching wallet instead. You can do this by calling getWatchingKey() and then serializing it with DeterministicKey.serializePubB58(Network). The resulting "xpub..." string encodes sufficient information about the account key to create a watching chain via DeterministicKey.deserializeB58(DeterministicKey, String, Network) (with null as the first parameter) and then DeterministicKeyChain.Builder.watch(DeterministicKey).

    This class builds on DeterministicHierarchy and DeterministicKey by adding support for serialization to and from protobufs, and encryption of parts of the key tree. Internally it arranges itself as per the BIP 32 spec, with the seed being used to derive a master key, which is then used to derive an account key, the account key is used to derive two child keys called the internal and external parent keys (for change and handing out addresses respectively) and finally the actual leaf keys that users use hanging off the end. The leaf keys are special in that they don't internally store the private part at all, instead choosing to rederive the private key from the parent when needed for signing. This simplifies the design for encrypted key chains.

    The key chain manages a lookahead zone. This zone is required because when scanning the chain, you don't know exactly which keys might receive payments. The user may have handed out several addresses and received payments on them, but for latency reasons the block chain is requested from remote peers in bulk, meaning you must "look ahead" when calculating keys to put in the Bloom filter. The default lookahead zone is 100 keys, meaning if the user hands out more than 100 addresses and receives payment on them before the chain is next scanned, some transactions might be missed. 100 is a reasonable choice for consumer wallets running on CPU constrained devices. For industrial wallets that are receiving keys all the time, a higher value is more appropriate. Ideally DKC and the wallet would know how to adjust this value automatically, but that's not implemented at the moment.

    In fact the real size of the lookahead zone is larger than requested, by default, it's one third larger. This is because the act of deriving new keys means recalculating the Bloom filters and this is an expensive operation. Thus, to ensure we don't have to recalculate on every single new key/address requested or seen we add more buffer space and only extend the lookahead zone when that buffer is exhausted. For example with a lookahead zone of 100 keys, you can request 33 keys before more keys will be calculated and the Bloom filter rebuilt and rebroadcast. But even when you are requesting the 33rd key, you will still be looking 100 keys ahead.

    • Field Detail

      • lock

        protected final java.util.concurrent.locks.ReentrantLock lock

      • DEFAULT_PASSPHRASE_FOR_MNEMONIC

        public static final java.lang.String DEFAULT_PASSPHRASE_FOR_MNEMONIC
        See Also:
        Constant Field Values

      • ACCOUNT_ZERO_PATH

        public static final HDPath ACCOUNT_ZERO_PATH

      • ACCOUNT_ONE_PATH

        public static final HDPath ACCOUNT_ONE_PATH

      • BIP44_ACCOUNT_ZERO_PATH

        public static final HDPath BIP44_ACCOUNT_ZERO_PATH

      • EXTERNAL_SUBPATH

        public static final HDPath EXTERNAL_SUBPATH

      • INTERNAL_SUBPATH

        public static final HDPath INTERNAL_SUBPATH

      • lookaheadSize

        protected int lookaheadSize

      • lookaheadThreshold

        protected int lookaheadThreshold

    • Constructor Detail

      • DeterministicKeyChain

        public DeterministicKeyChain​(DeterministicKey key,
                             boolean isFollowing,
                             boolean isWatching,
                             ScriptType outputScriptType)

        Creates a deterministic key chain from a watched or spendable account key. If isWatching flag is set, then creates a deterministic key chain that watches the given (public only) root key. You can use this to calculate balances and generally follow along, but spending is not possible with such a chain. If it is not set, then this creates a deterministic key chain that allows spending. If isFollowing flag is set(only allowed if isWatching is set) then this keychain follows some other keychain. In a married wallet following keychain represents "spouse's" keychain.

        This constructor is not stable across releases! If you need a stable API, use builder() to use a DeterministicKeyChain.Builder.

    • Method Detail

      • getAccountPath

        public HDPath getAccountPath()

      • getOutputScriptType

        public ScriptType getOutputScriptType()

      • markKeyAsUsed

        public DeterministicKey markKeyAsUsed​(DeterministicKey k)
        Mark the DeterministicKey as used. Also correct the issued{Internal|External}Keys counter, because all lower children seem to be requested already. If the counter was updated, we also might trigger lookahead.

      • findKeyFromPubHash

        public DeterministicKey findKeyFromPubHash​(byte[] pubkeyHash)

      • findKeyFromPubKey

        public DeterministicKey findKeyFromPubKey​(byte[] pubkey)

      • hasKey

        public boolean hasKey​(ECKey key)
        Description copied from interface: KeyChain
        Returns true if the given key is in the chain.
        Specified by:
        hasKey in interface KeyChain

      • getKeyByPath

        protected DeterministicKey getKeyByPath​(ChildNumber... path)
        Returns the deterministic key for the given absolute path in the hierarchy.

      • getKeyByPath

        protected DeterministicKey getKeyByPath​(java.util.List<ChildNumber> path)
        Returns the deterministic key for the given absolute path in the hierarchy.

      • getKeyByPath

        public DeterministicKey getKeyByPath​(java.util.List<ChildNumber> path,
                                     boolean create)
        Returns the deterministic key for the given absolute path in the hierarchy, optionally creating it

      • getWatchingKey

        public DeterministicKey getWatchingKey()

        An alias for getKeyByPath(getAccountPath()).

        Use this when you would like to create a watching key chain that follows this one, but can't spend money from it. The returned key can be serialized and then passed into DeterministicKeyChain.Builder.watch(DeterministicKey) on another system to watch the hierarchy.

        Note that the returned key is not pubkey only unless this key chain already is: the returned key can still be used for signing etc if the private key bytes are available.

      • isWatching

        public boolean isWatching()
        Returns true if this chain is watch only, meaning it has public keys but no private key.

      • numKeys

        public int numKeys()
        Description copied from interface: KeyChain
        Returns the number of keys this key chain manages.
        Specified by:
        numKeys in interface KeyChain

      • numLeafKeysIssued

        public int numLeafKeysIssued()
        Returns number of leaf keys used including both internal and external paths. This may be fewer than the number that have been deserialized or held in memory, because of the lookahead zone.

      • earliestKeyCreationTime

        public java.time.Instant earliestKeyCreationTime()
        Description copied from interface: KeyChain
        Returns the earliest creation time of keys in this chain.
        Specified by:
        earliestKeyCreationTime in interface KeyChain
        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

      • addEventListener

        public void addEventListener​(KeyChainEventListener listener)
        Description copied from interface: KeyChain
        Adds a listener for events that are run when keys are added, on the user thread.
        Specified by:
        addEventListener in interface KeyChain

      • addEventListener

        public void addEventListener​(KeyChainEventListener listener,
                             java.util.concurrent.Executor executor)
        Description copied from interface: KeyChain
        Adds a listener for events that are run when keys are added, on the given executor.
        Specified by:
        addEventListener in interface KeyChain

      • getMnemonicCode

        @Nullable
public java.util.List<java.lang.String> getMnemonicCode()
        Returns a list of words that represent the seed or null if this chain is a watching chain.

      • isFollowing

        public boolean isFollowing()
        Return true if this keychain is following another keychain

      • serializeToProtobuf

        public java.util.List<org.bitcoinj.protobuf.wallet.Protos.Key> serializeToProtobuf()
        Serialize to a list of keys
        Specified by:
        serializeToProtobuf in interface KeyChain
        Returns:
        A list of keys (treat as unmodifiable list, will change in future release)

      • serializeMyselfToProtobuf

        protected java.util.List<org.bitcoinj.protobuf.wallet.Protos.Key> serializeMyselfToProtobuf()
        Serialize to a list of keys. Does not use lock, expects caller to provide locking.
        Returns:
        A list of keys (treat as unmodifiable list, will change in future release)

      • toDecrypted

        public DeterministicKeyChain toDecrypted​(AesKey aesKey)
        Description copied from interface: EncryptableKeyChain
        Decrypt the key chain with the given AES key and whatever KeyCrypter is already set. Note that if you just want to spend money from an encrypted wallet, don't decrypt the whole thing first. Instead, set the SendRequest.aesKey field before asking the wallet to build the send.
        Specified by:
        toDecrypted in interface EncryptableKeyChain
        Parameters:
        aesKey - AES key to use (normally created using KeyCrypter#deriveKey and cached as it is time consuming to create from a password)

      • makeKeyChainFromSeed

        protected DeterministicKeyChain makeKeyChainFromSeed​(DeterministicSeed seed,
                                                     java.util.List<ChildNumber> accountPath,
                                                     ScriptType outputScriptType)
        Factory method to create a key chain from a seed. Subclasses should override this to create an instance of the subclass instead of a plain DKC. This is used in encryption/decryption.

      • getFilter

        public BloomFilter getFilter​(int size,
                             double falsePositiveRate,
                             int tweak)
        Description copied from interface: KeyChain

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

        Specified by:
        getFilter in interface KeyChain

      • getLookaheadSize

        public int getLookaheadSize()

        The number of public keys we should pre-generate on each path before they are requested by the app. This is required so that when scanning through the chain given only a seed, we can give enough keys to the remote node via the Bloom filter such that we see transactions that are "from the future", for example transactions created by a different app that's sharing the same seed, or transactions we made before but we're replaying the chain given just the seed. The default is 100.

      • setLookaheadSize

        public void setLookaheadSize​(int lookaheadSize)
        Sets a new lookahead size. See getLookaheadSize() for details on what this is. Setting a new size that's larger than the current size will return immediately and the new size will only take effect next time a fresh filter is requested (e.g. due to a new peer being connected). So you should set this before starting to sync the chain, if you want to modify it. If you haven't modified the lookahead threshold manually then it will be automatically set to be a third of the new size.

      • setLookaheadThreshold

        public void setLookaheadThreshold​(int num)
        Sets the threshold for the key pre-generation. This is used to avoid adding new keys and thus re-calculating Bloom filters every time a new key is calculated. Without a lookahead threshold, every time we received a relevant transaction we'd extend the lookahead zone and generate a new filter, which is inefficient.

      • getLookaheadThreshold

        public int getLookaheadThreshold()
        Gets the threshold for the key pre-generation. See setLookaheadThreshold(int) for details on what this is. The default is a third of the lookahead size (100 / 3 == 33). If you don't modify it explicitly then this value will always be one third of the lookahead size.

      • maybeLookAhead

        public void maybeLookAhead()
        Pre-generate enough keys to reach the lookahead size. You can call this if you need to explicitly invoke the lookahead procedure, but it's normally unnecessary as it will be done automatically when needed.

      • maybeLookAheadScripts

        public void maybeLookAheadScripts()
        Housekeeping call to call when lookahead might be needed. Normally called automatically by KeychainGroup.

      • getIssuedExternalKeys

        public int getIssuedExternalKeys()
        Returns number of keys used on external path. This may be fewer than the number that have been deserialized or held in memory, because of the lookahead zone.

      • getIssuedInternalKeys

        public int getIssuedInternalKeys()
        Returns number of keys used on internal path. This may be fewer than the number that have been deserialized or held in memory, because of the lookahead zone.

      • getSeed

        @Nullable
public DeterministicSeed getSeed()
        Returns the seed or null if this chain is a watching chain.

      • getIssuedReceiveKeys

        public java.util.List<DeterministicKey> getIssuedReceiveKeys()
        Returns only the external keys that have been issued by this chain, lookahead not included.
        Returns:
        Unmodifiable list of keys

      • getLeafKeys

        public java.util.List<DeterministicKey> getLeafKeys()
        Returns leaf keys issued by this chain (including lookahead zone)
        Returns:
        Unmodifiable list of keys

      • getKeyLookaheadEpoch

        public int getKeyLookaheadEpoch()
        Returns a counter that is incremented each time new keys are generated due to lookahead. Used by the network code to learn whether to discard the current block and await calculation of a new filter.

      • getRedeemData

        public RedeemData getRedeemData​(DeterministicKey followedKey)
        Get redeem data for a key. Only applicable to married keychains.

      • freshOutputScript

        public Script freshOutputScript​(KeyChain.KeyPurpose purpose)
        Create a new key and return the matching output script. Only applicable to married keychains.

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • toString

        public java.lang.String toString​(boolean includeLookahead,
                                 boolean includePrivateKeys,
                                 @Nullable
                                 AesKey aesKey,
                                 Network network)

      • formatAddresses

        protected void formatAddresses​(boolean includeLookahead,
                               boolean includePrivateKeys,
                               @Nullable
                               AesKey aesKey,
                               Network network,
                               java.lang.StringBuilder builder)

      • setSigsRequiredToSpend

        public void setSigsRequiredToSpend​(int sigsRequiredToSpend)
        The number of signatures required to spend coins received by this keychain.

      • getSigsRequiredToSpend

        public int getSigsRequiredToSpend()
        Returns the number of signatures required to spend transactions for this KeyChain. It's the N from N-of-M CHECKMULTISIG script for P2SH transactions and always 1 for other transaction types.

      • findRedeemDataByScriptHash

        @Nullable
public RedeemData findRedeemDataByScriptHash​(com.google.protobuf.ByteString bytes)
        Returns the redeem script by its hash or null if this keychain did not generate the script.