Package 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	Description
static java.time.Instant	BIP32_STANDARDISATION_TIME
static int	BIP32_STANDARDISATION_TIME_SECS	Deprecated. Use BIP32_STANDARDISATION_TIME

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method	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(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.
DeterministicKey	get(java.util.List<ChildNumber> path, boolean relativePath, boolean create)	Returns a key for the given path, optionally creating it.
int	getNumChildren(HDPath path)
DeterministicKey	getRootKey()	Returns the root key that the DeterministicHierarchy was created with.
void	putKey(DeterministicKey key)	Inserts a key into the hierarchy.
void	putKeys(java.util.List<DeterministicKey> keys)	Inserts a list of keys 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

public static final java.time.Instant BIP32_STANDARDISATION_TIME

BIP32_STANDARDISATION_TIME_SECS

@Deprecated
public static final int BIP32_STANDARDISATION_TIME_SECS

Deprecated.

Use BIP32_STANDARDISATION_TIME

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.

getRootKey

public DeterministicKey getRootKey()

Returns the root key that the DeterministicHierarchy was created with.