Class DeterministicHierarchy


  • public class DeterministicHierarchy
    extends java.lang.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 Detail

      • BIP32_STANDARDISATION_TIME

        public static final java.time.Instant BIP32_STANDARDISATION_TIME
      • BIP32_STANDARDISATION_TIME_SECS

        @Deprecated
        public static final int BIP32_STANDARDISATION_TIME_SECS
    • Constructor Detail

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

      • 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​(java.util.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​(java.util.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:
        java.lang.IllegalArgumentException - if create is false and the path was not found.
      • deriveNextChild

        public DeterministicKey deriveNextChild​(java.util.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:
        java.lang.IllegalArgumentException - if the parent doesn't exist and createParent is false.
      • getNumChildren

        public int getNumChildren​(HDPath path)
      • deriveChild

        public DeterministicKey deriveChild​(java.util.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:
        java.lang.IllegalArgumentException - if the parent doesn't exist and createParent is false.