Package org.bitcoinj.wallet

Class DeterministicKeyChain

java.lang.Object
org.bitcoinj.wallet.DeterministicKeyChain
All Implemented Interfaces:
EncryptableKeyChain, KeyChain
Direct Known Subclasses:
MarriedKeyChain
public class DeterministicKeyChain extends 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(NetworkParameters). The resulting "xpub..." string encodes sufficient information about the account key to create a watching chain via DeterministicKey.deserializeB58(DeterministicKey, String, NetworkParameters) (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 Details

    • lock

      protected final ReentrantLock lock

    • DEFAULT_PASSPHRASE_FOR_MNEMONIC

      public static final String DEFAULT_PASSPHRASE_FOR_MNEMONIC
      See Also:

    • 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

    • sigsRequiredToSpend

      protected int sigsRequiredToSpend

  • Constructor Details

    • DeterministicKeyChain

      public DeterministicKeyChain(DeterministicKey key, boolean isFollowing, boolean isWatching, Script.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.

    • DeterministicKeyChain

      protected DeterministicKeyChain(DeterministicSeed seed, @Nullable KeyCrypter crypter, Script.ScriptType outputScriptType, List<ChildNumber> accountPath)

      Creates a deterministic key chain with an encrypted deterministic seed using the provided account path. Using KeyCrypter to decrypt.

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

    • DeterministicKeyChain

      protected DeterministicKeyChain(KeyCrypter crypter, org.bouncycastle.crypto.params.KeyParameter aesKey, DeterministicKeyChain chain)
      For use in encryption when toEncrypted(KeyCrypter, KeyParameter) is called, so that subclasses can override that method and create an instance of the right class. See also makeKeyChainFromSeed(DeterministicSeed, List, Script.ScriptType)

  • Method Details

    • builder

      public static DeterministicKeyChain.Builder<?> builder()

    • getAccountPath

      public HDPath getAccountPath()

    • getOutputScriptType

      public Script.ScriptType getOutputScriptType()

    • getKey

      public DeterministicKey getKey(KeyChain.KeyPurpose purpose)
      Returns a freshly derived key that has not been returned by this method before.
      Specified by:
      getKey in interface KeyChain

    • getKeys

      public List<DeterministicKey> getKeys(KeyChain.KeyPurpose purpose, int numberOfKeys)
      Returns freshly derived key/s that have not been returned by this method before.
      Specified by:
      getKeys in interface KeyChain

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

    • markPubHashAsUsed

      @Nullable public DeterministicKey markPubHashAsUsed(byte[] pubkeyHash)
      Mark the DeterministicKeys as used, if they match the pubkeyHash See markKeyAsUsed(DeterministicKey) for more info on this.

    • markPubKeyAsUsed

      @Nullable public DeterministicKey markPubKeyAsUsed(byte[] pubkey)
      Mark the DeterministicKeys as used, if they match the pubkey See markKeyAsUsed(DeterministicKey) for more info on this.

    • 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(List<ChildNumber> path)
      Returns the deterministic key for the given absolute path in the hierarchy.

    • getKeyByPath

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

    • getRootKey

      @Nullable public DeterministicKey getRootKey()

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

    • getEarliestKeyCreationTime

      public long getEarliestKeyCreationTime()
      Description copied from interface: KeyChain

      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.

      Specified by:
      getEarliestKeyCreationTime in interface KeyChain

    • 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, 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

    • removeEventListener

      public boolean removeEventListener(KeyChainEventListener listener)
      Description copied from interface: KeyChain
      Removes a listener for events that are run when keys are added.
      Specified by:
      removeEventListener in interface KeyChain

    • getMnemonicCode

      @Nullable public List<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 List<Protos.Key> serializeToProtobuf()
      Description copied from interface: KeyChain
      Returns a list of keys serialized to the bitcoinj protobuf format.
      Specified by:
      serializeToProtobuf in interface KeyChain

    • serializeMyselfToProtobuf

      protected List<Protos.Key> serializeMyselfToProtobuf()

    • fromProtobuf

      public static List<DeterministicKeyChain> fromProtobuf(List<Protos.Key> keys, @Nullable KeyCrypter crypter, KeyChainFactory factory) throws UnreadableWalletException
      Returns all the key chains found in the given list of keys. Typically there will only be one, but in the case of key rotation it can happen that there are multiple chains found.
      Throws:
      UnreadableWalletException

    • toEncrypted

      public DeterministicKeyChain toEncrypted(CharSequence password)
      Description copied from interface: EncryptableKeyChain
      Takes the given password, which should be strong, derives a key from it and then invokes EncryptableKeyChain.toEncrypted(KeyCrypter, KeyParameter) with KeyCrypterScrypt as the crypter.
      Specified by:
      toEncrypted in interface EncryptableKeyChain
      Returns:
      The derived key, in case you wish to cache it for future use.

    • toEncrypted

      public DeterministicKeyChain toEncrypted(KeyCrypter keyCrypter, org.bouncycastle.crypto.params.KeyParameter aesKey)
      Description copied from interface: EncryptableKeyChain
      Returns a new keychain holding identical/cloned keys to this chain, but encrypted under the given key. Old keys and keychains remain valid and so you should ensure you don't accidentally hold references to them.
      Specified by:
      toEncrypted in interface EncryptableKeyChain

    • toDecrypted

      public DeterministicKeyChain toDecrypted(CharSequence password)
      Description copied from interface: EncryptableKeyChain
      Decrypts the key chain with the given password. See EncryptableKeyChain.toDecrypted(KeyParameter) for details.
      Specified by:
      toDecrypted in interface EncryptableKeyChain

    • toDecrypted

      public DeterministicKeyChain toDecrypted(org.bouncycastle.crypto.params.KeyParameter 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, List<ChildNumber> accountPath, Script.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.

    • checkPassword

      public boolean checkPassword(CharSequence password)
      Specified by:
      checkPassword in interface EncryptableKeyChain

    • checkAESKey

      public boolean checkAESKey(org.bouncycastle.crypto.params.KeyParameter aesKey)
      Specified by:
      checkAESKey in interface EncryptableKeyChain

    • getKeyCrypter

      @Nullable public KeyCrypter getKeyCrypter()
      Description copied from interface: EncryptableKeyChain
      Returns the key crypter used by this key chain, or null if it's not encrypted.
      Specified by:
      getKeyCrypter in interface EncryptableKeyChain

    • numBloomFilterEntries

      public int numBloomFilterEntries()
      Description copied from interface: KeyChain
      Returns the number of elements this chain wishes to insert into the Bloom filter. The size passed to KeyChain.getFilter(int, double, long) should be at least this large.
      Specified by:
      numBloomFilterEntries in interface KeyChain

    • getFilter

      public BloomFilter getFilter(int size, double falsePositiveRate, long 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, long) 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 List<DeterministicKey> getIssuedReceiveKeys()
      Returns only the external keys that have been issued by this chain, lookahead not included.

    • getLeafKeys

      public List<DeterministicKey> getLeafKeys()
      Returns leaf keys issued by this chain (including lookahead zone)

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

    • isMarried

      public boolean isMarried()
      Whether the keychain is married. A keychain is married when it vends P2SH addresses from multiple keychains in a multisig relationship.
      See Also:

    • 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 String toString()
      Overrides:
      toString in class Object

    • toString

      public String toString(boolean includeLookahead, boolean includePrivateKeys, @Nullable org.bouncycastle.crypto.params.KeyParameter aesKey, NetworkParameters params)

    • formatAddresses

      protected void formatAddresses(boolean includeLookahead, boolean includePrivateKeys, @Nullable org.bouncycastle.crypto.params.KeyParameter aesKey, NetworkParameters params, 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.