org.bitcoinj.crypto

Class DeterministicHierarchy

java.lang.Object

org.bitcoinj.crypto.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 Summary

Fields

Modifier and Type	Field and Description
static int	BIP32_STANDARDISATION_TIME_SECS

Constructor Summary

Constructors

Constructor and Description
DeterministicHierarchy(DeterministicKey rootKey) Constructs a new hierarchy rooted at the given key.

Method Summary

Modifier and Type	Method and Description
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.
DeterministicKey	deriveNextChild(com.google.common.collect.ImmutableList<ChildNumber> parentPath, boolean relative, boolean createParent, boolean privateDerivation) Extends the tree by calculating the next key that hangs off the given parent path.
DeterministicKey	get(java.util.List<ChildNumber> path, boolean relativePath, boolean create) Returns a key for the given path, optionally creating it.
int	getNumChildren(com.google.common.collect.ImmutableList<ChildNumber> path)
DeterministicKey	getRootKey() Returns the root key that the DeterministicHierarchy was created with.
void	putKey(DeterministicKey key) Inserts a key into the hierarchy.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

BIP32_STANDARDISATION_TIME_SECS

public static final int BIP32_STANDARDISATION_TIME_SECS

See Also:

Constant Field Values

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.

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(com.google.common.collect.ImmutableList<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 funtcion

Throws:

java.lang.IllegalArgumentException - if the parent doesn't exist and createParent is false.

getNumChildren

public int getNumChildren(com.google.common.collect.ImmutableList<ChildNumber> 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.

getRootKey

public DeterministicKey getRootKey()

Returns the root key that the DeterministicHierarchy was created with.