HDKeys

Create and derive extended public and private keys according to the BIP32 standard for Hierarchical Deterministic (HD) keys.

Hierarchically Derived Keys

Bitcore provides full support for BIP32, allowing for many key management schemas that benefit from this property. Please be sure to read and understand the basic concepts and the warnings on that BIP before using these classes.

HDPrivateKey

An instance of a PrivateKey that also contains information required to derive child keys.

Sample usage:

var bitcore = require('bitcore');
var HDPrivateKey = bitcore.HDPrivateKey;

var hdPrivateKey = new HDPrivateKey();
var retrieved = new HDPrivateKey('xpriv...');
var derived = hdPrivateKey.derive("m/0'");
var derivedByNumber = hdPrivateKey.derive(1).derive(2, true);
var derivedByArgument = hdPrivateKey.derive("m/1/2'");
assert(derivedByNumber.xprivkey === derivedByArgument.xprivkey);

var address = derived.privateKey.toAddress();

// obtain HDPublicKey
var hdPublicKey = hdPrivateKey.hdPublicKey;

HDPublicKey

An instance of a PublicKey that can be derived to build extended public keys. Note that hardened paths are not available when deriving an HDPublicKey.

var hdPrivateKey = new HDPrivateKey();
var hdPublicKey = hdPrivateKey.hdPublicKey;
try {
  new HDPublicKey();
} catch(e) {
  console.log("Can't generate a public key without a private key");
}

var address = new Address(hdPublicKey.publicKey, Networks.livenet);
var derivedAddress = new Address(hdPublicKey.derive(100).publicKey, Networks.testnet);

HDPrivateKey

Kind: global class

new HDPrivateKey(arg)

Represents an instance of an hierarchically derived private key.

More info on https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki

Param Type
arg string | Buffer | Object

hdPrivateKey.toObject ⇒ Object

Returns a plain object with a representation of this private key.

Fields include:

  • network: either 'livenet' or 'testnet'

  • depth: a number ranging from 0 to 255

  • fingerPrint: a number ranging from 0 to 2^32-1, taken from the hash of the

  • associated public key

  • parentFingerPrint: a number ranging from 0 to 2^32-1, taken from the hash

  • of this parent's associated public key or zero.

  • childIndex: the index from which this child was derived (or zero)

  • chainCode: an hexa string representing a number used in the derivation

  • privateKey: the private key associated, in hexa representation

  • xprivkey: the representation of this extended private key in checksum

  • base58 format

  • checksum: the base58 checksum of xprivkey

Kind: instance property of HDPrivateKey

hdPrivateKey.derive(arg, hardened)

Get a derived child based on a string or number.

If the first argument is a string, it's parsed as the full path of derivation. Valid values for this argument include "m" (which returns the same private key), "m/0/1/40/2'/1000", where the ' quote means a hardened derivation.

If the first argument is a number, the child with that index will be derived. If the second argument is truthy, the hardened version will be derived. See the example usage for clarification.

Kind: instance method of HDPrivateKey

Param Type
arg string | number
hardened boolean

Example

var parent = new HDPrivateKey('xprv...');
var child_0_1_2h = parent.derive(0).derive(1).derive(2, true);
var copy_of_child_0_1_2h = parent.derive("m/0/1/2'");
assert(child_0_1_2h.xprivkey === copy_of_child_0_1_2h);

hdPrivateKey._buildFromBuffers(arg) ⇒ HDPrivateKey

Receives a object with buffers in all the properties and populates the internal structure

Kind: instance method of HDPrivateKey
Returns: HDPrivateKey - this

Param Type Description
arg Object
arg.version buffer.Buffer
arg.depth buffer.Buffer
arg.parentFingerPrint buffer.Buffer
arg.childIndex buffer.Buffer
arg.chainCode buffer.Buffer
arg.privateKey buffer.Buffer
arg.checksum buffer.Buffer
[arg.xprivkey] string if set, don't recalculate the base58 representation

hdPrivateKey.toString() ⇒

Returns the string representation of this private key (a string starting with "xprv..."

Kind: instance method of HDPrivateKey
Returns: string

hdPrivateKey.inspect() ⇒

Returns the console representation of this extended private key.

Kind: instance method of HDPrivateKey
Returns: string

hdPrivateKey.toBuffer() ⇒ string

Returns a buffer representation of the HDPrivateKey

Kind: instance method of HDPrivateKey

HDPrivateKey.isValidPath(arg, hardened) ⇒ boolean

Verifies that a given path is valid.

Kind: static method of HDPrivateKey

Param Type
arg string | number
hardened boolean

HDPrivateKey._getDerivationIndexes(path) ⇒ Array

Internal function that splits a string path into a derivation index array. It will return null if the string path is malformed. It does not validate if indexes are in bounds.

Kind: static method of HDPrivateKey

Param Type
path string

HDPrivateKey.isValidSerialized(data, network) ⇒ boolean

Verifies that a given serialized private key in base58 with checksum format is valid.

Kind: static method of HDPrivateKey

Param Type Description
data string | Buffer the serialized private key
network string | Network optional, if present, checks that the network provided matches the network serialized.

HDPrivateKey.getSerializedError(data, network) ⇒ errors.InvalidArgument | null

Checks what's the error that causes the validation of a serialized private key in base58 with checksum to fail.

Kind: static method of HDPrivateKey

Param Type Description
data string | Buffer the serialized private key
network string | Network optional, if present, checks that the network provided matches the network serialized.

HDPrivateKey.fromSeed(hexa, network) ⇒

Generate a private key from a seed, as described in BIP32

Kind: static method of HDPrivateKey
Returns: HDPrivateKey

Param Type
hexa string | Buffer
network *

HDPrivateKey.fromBuffer(arg) ⇒ HDPrivateKey

Build a HDPrivateKey from a buffer

Kind: static method of HDPrivateKey

Param Type
arg Buffer

HDPublicKey

Kind: global class

new HDPublicKey(arg)

The representation of an hierarchically derived public key.

See https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki

Param Type
arg Object | string | Buffer

hdPublicKey.toObject

Returns a plain JavaScript object with information to reconstruct a key.

Fields are:

  • network: 'livenet' or 'testnet'
  • depth: a number from 0 to 255, the depth to the master extended key
  • fingerPrint: a number of 32 bits taken from the hash of the public key
  • fingerPrint: a number of 32 bits taken from the hash of this key's
  • parent's public key
  • childIndex: index with which this key was derived
  • chainCode: string in hexa encoding used for derivation
  • publicKey: string, hexa encoded, in compressed key format
  • checksum: BufferUtil.integerFromBuffer(this._buffers.checksum),
  • xpubkey: the string with the base58 representation of this extended key
  • checksum: the base58 checksum of xpubkey

Kind: instance property of HDPublicKey

hdPublicKey.derive(arg)

Get a derivated child based on a string or number.

If the first argument is a string, it's parsed as the full path of derivation. Valid values for this argument include "m" (which returns the same public key), "m/0/1/40/2/1000".

Note that hardened keys can't be derived from a public extended key.

If the first argument is a number, the child with that index will be derived. See the example usage for clarification.

Kind: instance method of HDPublicKey

Param Type
arg string | number

Example

var parent = new HDPublicKey('xpub...');
var child_0_1_2 = parent.derive(0).derive(1).derive(2);
var copy_of_child_0_1_2 = parent.derive("m/0/1/2");
assert(child_0_1_2.xprivkey === copy_of_child_0_1_2);

hdPublicKey._buildFromBuffers(arg) ⇒ HDPublicKey

Receives a object with buffers in all the properties and populates the internal structure

Kind: instance method of HDPublicKey
Returns: HDPublicKey - this

Param Type Description
arg Object
arg.version buffer.Buffer
arg.depth buffer.Buffer
arg.parentFingerPrint buffer.Buffer
arg.childIndex buffer.Buffer
arg.chainCode buffer.Buffer
arg.publicKey buffer.Buffer
arg.checksum buffer.Buffer
[arg.xpubkey] string if set, don't recalculate the base58 representation

hdPublicKey.toString() ⇒ string

Returns the base58 checked representation of the public key

Kind: instance method of HDPublicKey
Returns: string - a string starting with "xpub..." in livenet

hdPublicKey.inspect() ⇒

Returns the console representation of this extended public key.

Kind: instance method of HDPublicKey
Returns: string

hdPublicKey.toBuffer() ⇒ Buffer

Return a buffer representation of the xpubkey

Kind: instance method of HDPublicKey

HDPublicKey.isValidPath(arg) ⇒ boolean

Verifies that a given path is valid.

Kind: static method of HDPublicKey

Param Type
arg string | number

HDPublicKey.isValidSerialized(data, network) ⇒ boolean

Verifies that a given serialized public key in base58 with checksum format is valid.

Kind: static method of HDPublicKey

Param Type Description
data string | Buffer the serialized public key
network string | Network optional, if present, checks that the network provided matches the network serialized.

HDPublicKey.getSerializedError(data, network) ⇒ errors | null

Checks what's the error that causes the validation of a serialized public key in base58 with checksum to fail.

Kind: static method of HDPublicKey

Param Type Description
data string | Buffer the serialized public key
network string | Network optional, if present, checks that the network provided matches the network serialized.

HDPublicKey.fromBuffer(arg) ⇒ HDPublicKey

Create a HDPublicKey from a buffer argument

Kind: static method of HDPublicKey

Param Type
arg Buffer