Package org.bitcoinj.crypto

Class DeterministicHierarchy

java.lang.Object
org.bitcoinj.crypto.DeterministicHierarchy
public class DeterministicHierarchy extends Object

A DeterministicHierarchy calculates and keeps a whole tree (hierarchy) of keys originating from a single root key. This implements part of the BIP 32 specification. A deterministic key tree is useful because Bitcoin's privacy system require new keys to be created for each transaction, but managing all these keys quickly becomes unwieldy. In particular it becomes hard to back up and distribute them. By having a way to derive random-looking but deterministic keys we can make wallet backup simpler and gain the ability to hand out DeterministicKeys to other people who can then create new addresses on the fly, without having to contact us.

The hierarchy is started from a single root key, and a location in the tree is given by a path which is a list of ChildNumbers.

  • Field Details

    • BIP32_STANDARDISATION_TIME

      public static final Instant BIP32_STANDARDISATION_TIME

    • BIP32_STANDARDISATION_TIME_SECS

      @Deprecated public static final int BIP32_STANDARDISATION_TIME_SECS
      Deprecated.
      Use BIP32_STANDARDISATION_TIME

  • Constructor Details

    • DeterministicHierarchy

      public DeterministicHierarchy(DeterministicKey rootKey)
      Constructs a new hierarchy rooted at the given key. Note that this does not have to be the top of the tree. You can construct a DeterministicHierarchy for a subtree of a larger tree that you may not own.

  • Method Details

    • putKey

      public final void putKey(DeterministicKey key)
      Inserts a key into the hierarchy. Used during deserialization: you normally don't need this. Keys must be inserted in order.

    • putKeys

      public final void putKeys(List<DeterministicKey> keys)
      Inserts a list of keys into the hierarchy
      Parameters:
      keys - A list of keys to put in the hierarchy

    • get

      public DeterministicKey get(List<ChildNumber> path, boolean relativePath, boolean create)
      Returns a key for the given path, optionally creating it.
      Parameters:
      path - the path to the key
      relativePath - whether the path is relative to the root path
      create - whether the key corresponding to path should be created (with any necessary ancestors) if it doesn't exist already
      Returns:
      next newly created key using the child derivation function
      Throws:
      IllegalArgumentException - if create is false and the path was not found.

    • deriveNextChild

      public DeterministicKey deriveNextChild(List<ChildNumber> parentPath, boolean relative, boolean createParent, boolean privateDerivation)
      Extends the tree by calculating the next key that hangs off the given parent path. For example, if you pass a path of 1/2 here and there are already keys 1/2/1 and 1/2/2 then it will derive 1/2/3.
      Parameters:
      parentPath - the path to the parent
      relative - whether the path is relative to the root path
      createParent - whether the parent corresponding to path should be created (with any necessary ancestors) if it doesn't exist already
      privateDerivation - whether to use private or public derivation
      Returns:
      next newly created key using the child derivation function
      Throws:
      IllegalArgumentException - if the parent doesn't exist and createParent is false.

    • getNumChildren

      public int getNumChildren(HDPath path)

    • deriveChild

      public DeterministicKey deriveChild(List<ChildNumber> parentPath, boolean relative, boolean createParent, ChildNumber createChildNumber)
      Extends the tree by calculating the requested child for the given path. For example, to get the key at position 1/2/3 you would pass 1/2 as the parent path and 3 as the child number.
      Parameters:
      parentPath - the path to the parent
      relative - whether the path is relative to the root path
      createParent - whether the parent corresponding to path should be created (with any necessary ancestors) if it doesn't exist already
      Returns:
      the requested key.
      Throws:
      IllegalArgumentException - if the parent doesn't exist and createParent is false.

    • getRootKey

      public DeterministicKey getRootKey()
      Returns the root key that the DeterministicHierarchy was created with.