com.google.bitcoin.crypto

Class DeterministicHierarchy

java.lang.Object

com.google.bitcoin.crypto.DeterministicHierarchy

All Implemented Interfaces:

Serializable

public class DeterministicHierarchy
extends Object
implements Serializable

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.

See Also:

Serialized Form

Constructor Summary

Constructors

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

Method Summary

Methods

Modifier and Type	Method and Description
DeterministicKey	deriveChild(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(List<ChildNumber> path, boolean relativePath, boolean create) Returns a key for the given path, optionally creating it.
DeterministicKey	getRootKey() Returns the root key that the DeterministicHierarchy was created with.

Methods inherited from class java.lang.Object

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

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

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(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:

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

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.