DashHD.js

Manage HD Keys from HD Wallet Seed and Extended (xprv, xpub) Key Paths.
(compatible with the Hierarchical Deterministic Keys (BIP-44) and BIP-32 specs)

A fully-functional, production-ready reference implementation of Dash HD - suitable for learning DASH specs and protocols, and porting to other languages.

HD Wallet Seed: ac27495480225222079d7be181583751e86f571027b0497b5b5d11218e0a8a13332572917f0f8e5a589620c6f15b11c61dee327651a14c34e18231052e48c069
(the canonical _Zeed_ seed, from the canonical _Zoomonic_)

 HD XKey Path: m/44'/5'/0'/0
XPrv: xprvA2L7qar7dyJNhxnE47gK5J6cc1oEHQuAk8WrZLnLeHTtnkeyP4w6
Eo6Tt65trtdkTRtx8opazGnLbpWrkhzNaL6ZsgG3sQmc2yS8AxoMjfZ
XPub: xpub6FKUF6P1ULrfvSrhA9DKSS3MA3digsd27MSTMjBxCczsfYz7vcFL
nbQwjP9CsAfEJsnD4UwtbU43iZaibv4vnzQNZmQAVcufN4r3pva8kTz
HD Key Path: m/44'/5'/0'/0/0
WIF: XCGKuZcKDjNhx8DaNKK4xwMMNzspaoToT6CafJAbBfQTi57buhLK
Address: XrZJJfEKRNobcuwWKTD3bDu8ou7XSWPbc9

 HD XKey Path: m/44'/5'/1'/1
XPrv: xprvA2ACWaqwADRtbkLsM6oQHzeWtqZVviBmKMKNRBFcwKGGRBgWHNeo
ZSKzduFMFkqvNsV5LaqRT9XRibzgSAweAAsfMF35PWy6beK3aL1BwTU
XPub: xpub6F9Yv6NpzazBpERLT8LQf8bFSsPzLAucgaEyDZfEVeoFHz1epuy4
7EeUVCRTNVToM1zgFZMxiGs2AFc9cNqZE2UVwJod2zPkG7W4ZGRuwJJ
HD Key Path: m/44'/5'/1'/1/1
WIF: XF9murLtNpJaZXbwMxqJ6BhigEtu9NxfBCJDBokCJcqFkYkz3itz
Address: XueHW2ELMxoXzXcaHMxmwVWhcADE1W5s8c

Install
- Node, Bun, & Bundlers
- Browser
Usage Overview
Production-Ready QuickStart
API
- Note on derivation exceptions
- DashHd derivations & encodings
- HD Key Types
Tutorial Walkthrough
- Recovery Phrase, Secret, Seed
- Wallet Derivation
  - HD Path Derivation
  - Wallet, Account, and X Key Derivation
    - XPrv and XPub Encoding
  - Address Key Derivation
    - WIF and Address Encoding
Glossary

Install

Notes:

secp256k1 is not a listed dependency in package.json for this -
because there are many decent implementations to choose from.
HOWEVER, DashKeys will use @dashincubator/secp256k1@1.x
by default, it if is installed.
See DashKeys if you prefer to use another implementation.
DashPhrase is recommended, but not strictly required.
(you can work with bare seeds without a word list)

Node, Bun, & Bundlers

npm install --save @dashincubator/secp256k1@1.x
npm install --save dashhd@3.x
npm install --save dashphrase

letDashHd=require("dashhd");letDashPhrase=require("dashphrase");

Browser

<scriptsrc="https://unpkg.com/@dashincubator/secp256k1@1.7.1-5/secp256k1.js"></script><scriptsrc="https://unpkg.com/dashkeys@1.x/dashkeys.js"></script><scriptsrc="https://unpkg.com/dashhd@3.x/dashhd.js"></script>

letDashHd=window.DashHd;letDashPhrase=window.DashPhrase;

Usage Overview

Already know what you're doing?

Clueless? Go to the QuickStart or Tutorial section.

Generate a Wallet

letwalletKey=awaitDashHd.fromSeed(seedBytes);

As a one-off, you can directly generate an Address Key by HD Path

lethdpath=`m/44'/5'/0'/0/0`;letkey=awaitDashHd.derivePath(walletKey,hdpath);letwif=awaitDashHd.toWif(key.privateKey);letaddress=awaitDashHd.toAddr(key.publicKey);

Generate an Account

letaccountIndex=0;letaccountKey=awaitwalletKey.deriveAccount(accountIndex);

Generate an XPrv or XPubX Key (Extended Private or Public Key)

// generally used for as a 'receive' address (as opposed to 'change' address)letuse=DashHd.RECEIVE;letxprvKey=awaitaccountKey.deriveXKey(use);

(Optional) Generate XPrv and XPubs

letxprv=awaitDashHd.toXPrv(xprvKey);letxpub=awaitDashHd.toXPub(xprvKey);

Generate an Address Key

letindex=0;letaddressKey=awaitxprvKey.deriveAddress(index);

Generate WIF & Address

letwif=awaitDashHd.toWif(key.privateKey);letaddress=awaitDashHd.toAddr(key.publicKey);

Production QuickStart

However, production code will look more like this:

Get a Seed from the user's Recovery Phrase and Secret Salt

letwordList="zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong";letsecretSalt="TREZOR";// Derive a Wallet SeedletseedBytes=awaitDashPhrase.toSeed(wordList,secretSalt);

Derive a Wallet, Account, and X Key, if possible.
(reject the Recovery Phrase or Seed if Account index 0 is not valid)

letaccountIndex=0;letxprvKey;try{letwalletKey=awaitDashHd.fromSeed(seedBytes);// from step 1letaccountKey=awaitwalletKey.deriveAccount(accountIndex);void(awaitaccountKey.deriveXKey(DashHd.CHANGE));xprvKey=awaitaccountKey.deriveXKey(DashHd.RECEIVE);}catch(e){window.alert("Error: The recovery phrase can't generate a valid 1st account!",);}

Note: For multi-Accounts apps, just mark failed indexes as invalid.

Derive a batch of Address keys (20 is the typical number)

letkeys=[];letpreviousIndex=0;letuse=DashHd.RECEIVE;letlast=previousIndex+20;for(leti=previousIndex;i<last;i+=1){letkey;try{key=awaitxprvKey.deriveAddress(i);// xprvKey from step 2}catch(e){// to make up for skipping on errorlast+=1;continue;}letwif=awaitDashHd.toWif(key.privateKey);letaddress=awaitDashHd.toAddr(key.publicKey);lethdpath=`m/44'/5'/${accountIndex}'/${use}/${i}`;// accountIndex from step 2keys.push({index: i,hdpath: hdpath,// useful for multi-account indexingaddress: address,// XrZJJfEKRNobcuwWKTD3bDu8ou7XSWPbc9wif: wif,// XCGKuZcKDjNhx8DaNKK4xwMMNzspaoToT6CafJAbBfQTi57buhLK});}

Note: it may be useful to indicate the path of the

API

IMPORTANT
- all derivations can fail

DashHd

ConstantsMAINNET,TESTNETHARDENED,PUBLICRECEIVE,CHANGEasyncfromSeed(seedBytes,opts)// depth-0 hdkey (Wallet)asyncfromXKey(xprv||xpub,opts)// depth-4 hdkey (XKey)asynctoPublic(xKey)asyncwipePrivateData(xKey)asynctoWif(privBytes,opts)asynctoAddr(pubBytes,opts)asynctoXPrv(xprvKey,opts)asynctoXPub(xKey,opts)

DashHd (BIP-32)

create(hdkey)// depth-n HDKey (any)asyncderivePath(hdkey,hdpath,)asyncderiveChild(// (mostly for debugging)hdkey,index,isHardened,)

HD Key Types

WalletKeyasyncderiveAccount(accountIndex)AccountKeyasyncderiveXKey(use=0)X(Extended)KeyasyncderiveAddress(keyIndex)AddressKey{privateKey,publicKey}HDKey(BaseType){versions,depth,parentFingerprint,index,chainCode,privateKey,publicKey}

IMPORTANT

All derive methods can fail (throw an error).

This is highly-unlikely, but normal (because maths).

It's recommended that:

Before accepting a seed as valid, derive these HD Paths:
```
m/44'/5'/0'/0/0
m/44'/5'/0'/0/1
m/44'/5'/0'/1/0
m/44'/5'/0'/1/1
```
If derivation fails, reject the seed.
When creating a new Account Index, always derive both Use Indexes:
```
m/44'/5'/n'/0
m/44'/5'/n'/1
```
If either the Account Index or Use Index derivation fails,
mark the whole Account Index as invalid.
If a key derivation ever fails, simply mark that key as invalid.
```
m/44'/5'/0'/0/n
```

Most likely you will never personally encounter this failure.

However, when your software is generating millions and billions of keys across thousands and millions of accounts, eventually one of the key expansion hashes will just so happen to hit Infinity or Zero on the curve.

Some libraries abstract this away by automatically incrementing to the next index on failure, but since the occurrence is so rare, and therefore will inevitably lead to highly confusing and difficult to track bugs (including address re-use, a privacy concern), we do not.

`DashHd`

This is the top-level export, and these methods are specific to the (modern & current) BIP-44 standard for HD Keys for:

Wallet Key
Account Key
X (Extended) Key (XPrv or XPub)
Address Key (WIF or Address)

Constants

MAINNET, TESTNET

The version byte that gets base58check encoded to a human-friendly prefix.

// "xprv" "xpub"DashHd.MAINNET={private: 0x0488ade4,public: 0x0488b21e};

// "tprv" "tpub"DashHd.TESTNET={private: 0x0488ade4,public: 0x0488b21e};

HARDENED, PUBLIC

Whether the HD Key should be derived as Hardened or Public (sharable).

DashHd.HARDENED=true;DashHd.PUBLIC=false;

RECEIVE, CHANGE

The intended use of the key - as a receiving address for external funds, or an internal change address.

DashHd.RECEIVE=0;DashHd.CHANGE=1;

`fromSeed(seedBytes, opts)`

Generate a Wallet (depth-0 HD Key)
with a default HD Path prefix of m/44'/5'.

letwords="zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong";letsecret="TREZOR";letseedBytes=awaitDashPhrase.toSeed(words,secret);

letwalletKey=awaitDashHd.fromSeed(seedBytes,options);// { deriveAccount,// versions,// depth: 0, parentFingerprint: 0, index: 0,// chainCode, privateKey, publicKey }

Options

{purpose: 44,// BIP-44 (default)coinType: 5,// DASH (default)versions: DashHd.MAINNET,// default}

`fromXKey(xprv || xpub, opts)`

Parses a Base58Check-encoded xprv or xpub (Extended Private or Public Key) into an X Key (depth-4 HD Key).

Only the depth is known. The prefix is not recoverable, but can be assumed to be something like m/44'/5'/0'/0.

letxprv="xprvA2L7qar7dyJNhxnE47gK5J6cc1oEHQuAk8WrZLnLeHTtnkeyP4w6Eo6Tt65trtdkTRtx8opazGnLbpWrkhzNaL6ZsgG3sQmc2yS8AxoMjfZ";

letxkey=awaitDashHd.fromXKey(xprvOrXPub,options);// { deriveAddress,// versions: v, depth: n, parentFingerprint: p, index: 0,// chainCode: c, privateKey: privOrNull, publicKey: pubBytes }

Options

{bip32: false,// allow arbitrary depth (Wallet, Purpose, Coin, Account, etc)normalizePublicKey: false,// validate pubkey by re-ploting X,Y on curveversions: DashHd.MAINNET,// must match the given version}

`toPublic(xkey)`

Creates a copy of the HD Key with privateKey set to null.

letxpubKey=awaitDashHd.toPublic(xprvKey);

`wipePrivateData(xkey)`

Performs an in-place secure erase of the private key memory.

awaitDashHd.wipePrivateData(xprvKey);

`toWif(privBytes, opts)`

Wrapper around DashKeys.encodeKey(keyBytes, options) to Base58Check-encode a Private Key as in WIF (Wallet Import Format).

letaddressIndex=0;letkey=awaitxprvKey.deriveAddress(addressIndex);

letwif=awaitDashHd.toWif(key.privateKey);// "XCGKuZcKDjNhx8DaNKK4xwMMNzspaoToT6CafJAbBfQTi57buhLK"

Options

{version: "cc",// (default) mainnet DASH Private Key}

`toAddr(pubBytes, opts)`

Wrapper around DashKeys.encodeKey(keyBytes, options) to Base58Check-encode a Public Key as an Address.

letaddressIndex=0;letaddressKey=awaitxkey.deriveAddress(addressIndex);

letaddr=awaitDashHd.toAddr(key.publicKey);// "XrZJJfEKRNobcuwWKTD3bDu8ou7XSWPbc9"

Options

{version: "4c",// (default) mainnet DASH PubKeyHash}

`toXPrv(hdkey)`

Encode an HD Key to eXtended Private Key format.
(Base58Check with xprv magic version bytes)

Wrapper around DashKeys.encodeKey(keyBytes, options) to Base58Check-encode an X Key as an XPrv.

Get your XKey (XPrv Key) by one of

Derive via HD Path directly from a Wallet Key

// `m/${purpose}'/${coinType}'/${accountIndex}'/${use}`lethdpath=`m/44'/5'/0'/0`;letxprvKey=awaitDashHd.derivePath(walletKey,hdpath);

Derived from Account Key

letuse=DashHd.RECEIVE;letxprvKey=awaitaccountKey.deriveXKey(use);

Decode an Extended Private Key (xprv)

letxprvKey=awaitDashHd.fromXKey(xprv);

Encode to Base58Check xprv

letxprv=awaitDashHd.toXPrv(xprvKey);// "xprvA2L7qar7dyJNhxnE47gK5J6cc1oEHQuAk8WrZLnLeHTtnkeyP4w6Eo6Tt65trtdkTRtx8opazGnLbpWrkhzNaL6ZsgG3sQmc2yS8AxoMjfZ"

`toXPub(hdkey)`

Encode an HD Key to eXtended Public Key format.
(Base58Check with xprv magic version bytes)

Wrapper around DashKeys.encodeKey(keyBytes, options) to Base58Check-encode an X Key as an XPub.

Get your XKey (XPub Key) by one of

Derive via HD Path directly from a Wallet Key

// `m/${purpose}'/${coinType}'/${accountIndex}'/${use}`lethdpath=`m/44'/5'/0'/0`;letxprvKey=awaitDashHd.derivePath(walletKey,hdpath);

Derived from Account Key

letuse=DashHd.RECEIVE;letxprvKey=awaitaccountKey.deriveXKey(use);

Decode an Extended Private Key (xprv)

letxpubKey=awaitDashHd.fromXKey(xprvOrXPub);

Encode to Base58Check xprv

letxpub=awaitDashHd.toXPub(xprvKeyOrXPubKey);// "xpub6FKUF6P1ULrfvSrhA9DKSS3MA3digsd27MSTMjBxCczsfYz7vcFLnbQwjP9CsAfEJsnD4UwtbU43iZaibv4vnzQNZmQAVcufN4r3pva8kTz"

`DashHd` (BIP-32)

These are the more rudimentary functions which can be used for either style of HD Keys:

BIP-44 / BIP-43 (Wallet, Account, XKey, Key)
or BIP-32 (generic HD Keys)

These do not enforce BIP-44 compliance, so they can be useful for testing and debugging.

`create(hdkey)`

Returns an HD Key with any missing values set to their default.

lethdkey=DashHd.create({chainCode: chainBytes,privateKey: privOrNull,publicKey: pubBytes,});

HD Key

{versions: DashHd.MAINNET,depth: 0,parentFingerprint: 0,// should be set if depth is setindex: 0,chainCode: chainBytes,// requiredprivateKey: privOrNull,// required (or null)publicKey: pubBytes,// required}

`deriveChild(hdkey, index, isHardened)`

Derives one additional depth of an HD Key, by index value and hardness.

lethdkey=awaitDashHd.fromXKey(xpub,{bip32: true});

letUNHARDENED=false;letnextIndex=42;letnextHdkey=awaitDashHd.deriveChild(hdkey,nextIndex,UNHARDENED);

`derivePath(hdkey, hdpath)`

Iterates over an HD Path, calling deriveChild(hdkey, index, isHardened) for each index.

Can derive any valid BIP-32 path, at any depth.
(even if nonsensical - such as a hardened key after an unhardened one)

lethdkey=awaitDashHd.fromSeed(seedBytes);

letchildKey=awaitDashHd.derivePath(hdkey,`m/0'/0/1'/1/0`);// { versions, depth, parentFingerprint,// index, chainCode, privateKey, publicKey }

This is the same as

letchildKey=hdkey;childKey=awaitDashHd.deriveChild(childKey,0,true);childKey=awaitDashHd.deriveChild(childKey,0,false);childKey=awaitDashHd.deriveChild(childKey,1,true);childKey=awaitDashHd.deriveChild(childKey,1,false);childKey=awaitDashHd.deriveChild(childKey,0,false);// { versions, depth, parentFingerprint,// index, chainCode, privateKey, publicKey }

Key Types

A BIP-44 HD Path has 5 depths, each with their own HD Key Type:

//0 1 2 3 4 5`m/${purpose}'/${coin}'/${account}'/${use}/${index}`;//m 44' 5' a' 0|1 i

Depth 0: Wallet (Root) Key - calculated from a Seed
Depth 1: Purpose Key - predefined as index 44' for BIP-44
Depth 2: Coin Key - predefined as index 5' for DASH (1' for testnet)
(this is also sometimes referred to as the "Wallet")
Depth 3: Account Key - derived by account index
Depth 4: X Key is for sharing, derived by Use (Receiving or Change)
Depth 5: Address Key is for paying and getting paid (WIF or Address)
Depth 6+: not defined by BIP-44, application specific

Keys can be derived

by instance (recommended: faster, maintains state):

letwalletKey=awaitDashHd.fromSeed(seedBytes);letaccountIndex=0;letaccountKey=awaitwalletKey.deriveAccount(accountIndex);letuse=DashHD.RECEIVE;letxkey=awaitaccountKey.deriveXKey(use);letaddressIndex=0;letkey=awaitxkey.deriveAddress(addressIndex);

by path (slow if used in for loops):

letwalletKey=awaitDashHd.fromSeed(seedBytes);lethdpath=`m/${purpose}'/${coin}'/${account}'/${use}/${index}`;letkey=awaitDashHd.derivePath(walletKey,hdpath);

The benefit of deriving by instance is that when you need to derive in a loop, such as multiple keys at the same depth - e.g. Addresses from the same X Key, or Accounts from the same Wallet - you're not deriving from the Wallet Root each time.

Since the key derivation process is intentionally somewhat slow, it's best to loop at the lowest level that you can. For example:

// ...letxkey=awaitaccountKey.deriveXKey(use);for(letaddressIndex=0;addressIndex<100;addressIndex+=1){letkey=awaitxkey.deriveAddress(addressIndex);// ...}

Wallet (depth 0)

A root HD Key with a deriveAccount(accountIndex) method.

Can also derive BIP-32 HD Keys.

From a Seed:

letwords="zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong";letsecret="TREZOR";letseedBytes=awaitDashPhrase.toSeed(words,secret);letwalletKey=awaitDashHd.fromSeed(seedBytes,{});

To a different Coin Type or non-BIP-44 scheme:

letpurpose=44;// depth 1 is always 44 for DASHletcoinType=0;// depth 2 is always 0 for DASHletaccountIndex=0;letaccountKey=awaitDashHd.derivePath(walletKey,`m/${purpose}'/${coinType}'/${accountIndex}'`,);

Purpose (depth 1)

Always 44', as in BIP-44 for DASH (and most other cryptocurrencies)

Purpose (depth 3)

Always 5', which is a magic number specifying DASH.

Except 1' for testnet, as per https://github.com/satoshilabs/slips/blob/master/slip-0044.md.

See fromSeed(seedBytes) for options to change purpose, coinType, and versions.

Account (depth 3)

A hardened HD Key with a deriveXKey(use) method.

From a Wallet:

letaccountIndex=0;letaccountKey=walletKey.deriveAccount(accountIndex);letuse=DashHd.RECEIVE;letxkey=awaitaccountKey.deriveXKey(use);

From an HD Path:

letaccountIndex=0;letaccountKey=awaitDashHd.derivePath(walletKey,`m/44'/5'/${accountIndex}'`,);letuse=DashHd.RECEIVE;letxkey=awaitaccountKey.deriveXKey(use);

XKey (XPrv or XPub) (depth 4)

An HD Key with a deriveAddress(addressIndex) method.

Represents a "public" (i.e. non-hardened) XPrv or XPub.

Share an XPub with a contact so that they can derive additional addresses to pay you repeatedly without sacrificing privacy, and without needing interaction from you to creat a new address each time.

Share an XPrv with an application so that you can load the XPub side and it can use the XPrv side to make payments on your behalf.

From an Account:

letuse=DashHd.RECEIVE;letxkey=awaitaccountKey.deriveXKey(use);letaddressIndex=0;letkey=awaitxkey.deriveAddress(addressIndex);// { ...,// privateKey: privBytes, publicKey: pubBytes }

From an xprv:

letxkey=awaitaccountKey.fromXKey(xprv);letaddressIndex=0;letkey=awaitxkey.deriveAddress(addressIndex);// { ...,// privateKey: privBytes, publicKey: pubBytes }

From an xpub:

letxkey=awaitaccountKey.fromXKey(xprv);letaddressIndex=0;letkey=awaitxkey.deriveAddress(addressIndex);// { ...,// privateKey: null, publicKey: pubBytes }

Key (depth 5)

The base HD Key type, but with no additional methods.

A fully-derived BIP-44 Address ("public" a.k.a. non-hardened).

{ ...,privateKey: privBytes,publicKey: pubBytes}

From a Wallet:

letaccountIndex=0;letaccountKey=awaitwalletKey.deriveAccount(accountIndex);letuse=DashHd.RECEIVE;letxkey=awaitaccountKey.deriveXKey(use);letaddressIndex=0;letkey=awaitxkey.deriveAddress(addressIndex);

From an XPrv:

letxkey=awaitaccountKey.fromXKey(xprv);letaddressIndex=0;letkey=awaitxkey.deriveAddress(addressIndex);// { ...,// privateKey: privBytes, publicKey: pubBytes }

From an XPub:

letxkey=awaitaccountKey.fromXKey(xpub);letaddressIndex=0;letkey=awaitxkey.deriveAddress(addressIndex);// { ...,// privateKey: null, publicKey: pubBytes }

HDKey

A generic HD Key at any depth.

{versions: DashHd.MAINNET,depth: 0,parentFingerprint: 0,// should be set if depth is non-zeroindex: 0,chainCode: chainBytes,// requiredprivateKey: privOrNull,// required (or null)publicKey: pubBytes,// required}

The same structure as Key, but documented separately - because BIP-32 doesn't define semantic differences between HD Keys at different depths (other than the root).

Walkthrough

This will focus on the most typical use case, where you intend to generate multiple addresses as part of your application's lifecycle.

Part 1: Recovery Phrase, Secret, Seed

The Recovery Phrase (or Seed), is the Wallet.

A Wallet is derived from a Seed.
A Seed is typically derived from a Recovery Phrase and Secret Salt.

From a code perspective:

If your user doesn't supply a Recovery Phrase, you can generate one:

lettargetBitEntropy=128;letwordList=awaitDashPhrase.generate(targetBitEntropy);// "cat swing flag economy stadium alone churn speed unique patch report train"

Typically the Secret Salt is left as an empty string:
```
letsecretSalt="";
```
HOWEVER, for this demo we'll use the Zoomonic and Zecret
(these values are specified by BIP-39's test suite for demos, debugging, etc)
```
letwordList="zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong";letsecretSalt="TREZOR";
```
Key Expansion derives the Seed from the Recovery Phrase + Secret
(FYI: it's a specific configuration of PBKDF2 under the hood)
```
letseedBytes=awaitDashPhrase.toSeed(wordList,secretSalt);
```

Prompt the user to make a backup of their Recovery Phrase.
(or their Seed, if you're not implementing Recovery Phrases)

It's common to print this out and put it in a safe.

If the Recovery Phrase is lost, the Wallet (and all money) is unrecoverable.

Part 2: The Wallet Derivation

As mentioned in the API section, it is, in fact, possible for any derivation to fail.

It's highly unlikely that you'll ever encounter it, but it should be handled nonetheless.

Generate a Wallet Key
(uses an HMAC-style Key Expansion, defined in BIP-32 )

letwalletKey;try{walletKey=awaitDashHd.fromSeed(seedBytes);}catch(e){window.alert("the recovery phrase (or seed) could not be used to derive keys",);}

Notify the user and retry a different Recovery Phrase on failure.

Part 2a: HD Path Derivation

As a one-off, HD Path Derivation can be very convenient:

Note: this approach would be 5x slower for deriving multiple keys because each key will derive from the Root Wallet Key each time.

Define the target HD Path indexes to Depth 4 (Use a.k.a. X Key)

letaccountIndex=0;letuse=DashHd.RECEIVE;letaddressIndex=0;letmaxTries=3;lethdPartial=`m/44'/5'/${accountIndex}'/${use}`;

Derive the Address Key (Depth 5)

letkey;for(leti=addressIndex;i<maxTries;i+=1){try{lethdpath=`${hdPartial}/${addressIndex}`;key=awaitDashHd.derivePath(wallet,hdpath);// as defined abovebreak;}catch(e){// ignore}}if(!key){// more than 1 failure in a row would indicate// the accountIndex or use index could not be derived// (and hence no addressIndex will ever derive)thrownewError(`'${hdPartial}': 'account' or 'use' index cannot be derived`,);}

Mark the Account index as invalid and advance to the next on failure.
(or fail hard if it's the first account)

Part 2b: Wallet, Account, X Key

This is the more typical and efficient use - for when you intend to generate multiple addresses as part of your application's lifecycle.

Derive an Account Key and X Key
(reject the seed if the account at index 0 fails)

letaccountIndex=0;letaccountKey;letuse=DashHd.RECEIVE;// 0 = receive, 1 = changeletxkey;while(!accountKey){try{accountKey=awaitwalletKey.deriveAccount(accountIndex);xkey=awaitaccountKey.deriveXKey(use);break;}catch(e){accountIndex+=1;// if your app handles multiple accounts, just try the next}}

Note: technically you could advance the Use index,
but that's more complicated than just advancing to the next account

(optional) Encode the X Key as XPrv or XPub for sharing

letxprv=awaitDashHd.toXPrv(xkey);// "xprv......"letxpub=awaitDashHd.toXPub(xkey);// "xpub......"

Part 3: Address Key

This is final piece, which you use for making and receiving payments.

Derive an Address Key

letindex=0;letmaxTries=3;letlast=index+maxTries;letkey;for(leti=index;i<last;i+=1){try{key=awaitxkey.deriveAddress(index);}catch(e){// you may wish to mark the index as failed}}

Encode the Address Key as WIF or Address for use or sharing

letwif=DashKeys.toWif(keys.privateKey);// "X....."letaddr=DashKeys.toAddr(keys.publicKey);// "X..."

Glossary

Base2048

Also: Base2048, BIP39, BIP-0039

Rather than a bank of 2, 16, 32, 58, 62, or 64 characters,
you can encode data using a bank of whole words.
If you use 2048 words, each word represents 11 bits.
12 words represent 131 bits of information.
Any extra bits are used for checksumming the data. \

See HD Recovery Phrase.

Base58Check

The encoding format used for sharing XPrv and XPub Keys (X Keys).
(among other things, such as WIF and Address)

xprvA2L7qar7dyJNhxnE47gK5J6cc1oEHQuAk8WrZLnLeHTtnkeyP4w6Eo6Tt65trtdkTRtx8opazGnLbpWrkhzNaL6ZsgG3sQmc2yS8AxoMjfZ

xpub6FKUF6P1ULrfvSrhA9DKSS3MA3digsd27MSTMjBxCczsfYz7vcFLnbQwjP9CsAfEJsnD4UwtbU43iZaibv4vnzQNZmQAVcufN4r3pva8kTz

BIP

Also: BIPs

Bitcoin Improvement Proposal(s).
Specification Drafts / RFCs (Request For Comments).

BIP-32

See HD Keys.

BIP-39

Also: Base2048, BIP39, BIP-0039

BIP for HD Recovery Phrase.

BIP-43

BIP for the Purpose index of the HD Path.

`m/${purpose}'`;

This is the basis of [BIP-44][#bip-44] defining HD Paths as m/44'/.

See HD Keys.

BIP-44

See HD Path.

Curve

Related to parameters of Elliptic Curve (ECDSA) cryptography / algorithms.

A single X value produces two Y values on a curve (rather than 1 on a line).

In rare instances, an X value may produce no points on the curve.

Derive (by Path)

To split an HD Path by / and then iterate to derive each index (Child) in turn.

Cannot be reversed.

See [derivePath(hdkey, hdpath)][#derivePath-hdkey-hdpath].

Derived Child

A key directly derived from another key by an HD Path index.
(typically referring to a single index of the path, not the whole)

See [deriveChild(hdkey, index, isHardened)][#derivePath-hdkey-index-ishardened].

Key Expansion

An algorithm that creates a larger (byte-size) output than its input.
Typically uses hashing algos: HMAC, SHA-2, SHA-3, etc.
May combine multiple algos together.
Usually intentionally slow.
May run a high number of "Rounds" in succession.
(typically hundreds or thousands).

Recovery Phrase to Seed (BIP-39) uses PBKDF2.
HD Keys (BIP-44) use HMAC and Secp256k1 Tweaking for each index.

HD Account

An HD Key derived at m/44'/5'/n' (Depth 3) of the HD Path.

See API: Key Types.

HD Address Key

Also: Key, HD Private Key, WIF, Address

An HD Key at final depth m/44'/5'/0'/0/0 (Depth 5) of an HD Path.
Can be encoded as WIF or Address for making or receiving payments.

See also API: Key Types.

HD Keys

Also: Hierarchical Deterministic Keys, BIP-32, BIP-44

Any of generic or purpose-specific keys derived deterministically form a seed.

See more at API: Key Types (code above) and HD Path.

HD Recovery Phrase

Also: Recovery Phrase, Mnemonic for Generating Hierarchical Deterministic Keys, HD Wallet, BIP-39

12 words used to derive an HD Seed.
(11¾ for entropy, ¼ for checksum)

Ex: zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong

Not used directly in this library, but...
it is how the HD Seeds used here are typically generated.

See DashPhrase.js.

HD Path

The path that defines an HD Key - typically of the BIP-44 variety:

a Root, ex: m (depth 0, the Wallet Key, straight from the seed)
an Coin Key, ex: m/44'/5' (depth 2)
an Account, ex: m/44'/5'/0' (depth 3)
an X Key (XPrv or XPub), ex: m/44'/5'/0'/0 (depth 4, a.k.a. Use)
an Address Key, ex: m/44'/5'/0'/0/0 (depth 5, the end)
' is used for "hardened" (parent) key segments,
but not for "public" (shareable) child key segments

In general:

lethdpath=`m/${purpose}'/${coinType}'/${account}'/${use}/${index}`;

For DASH:

lethdpath=`m/44'/5'/${account}'/${use}/${index}`;

HD Wallet

Either the Root Key at m (Depth 0), directly from the Seed,
or the Coin Key at m/44'/5' (Depth 2), of the HD Path.
Sometimes also used to mean HD Account at m/44'/5'/n'.

Here we typically use it to mean the Root Key.
(because we're focus on DASH more so than other coins)

See also API: Key Types.

HD X Key

Also: XKey, XPrv, XPub, Use Key, Use Index, Extended Key.

An HD Key derived at m/44'/5'/0'/n (Depth 4), of the HD Path.

Here we typically use it to mean the Root Key.
(because we're focus on DASH more so than other coins)

See also API: Key Types.

Root Seed

Also: Master Seed, Seed, HD Seed

Either:

64 random bytes
a 64-byte hash derived from a Recovery Phrase

Cannot be reversed.

Root Key

Also: HD Wallet, Master Key, HD Master

An HD Key of m (Depth 0), as derived directly from the Seed.

See also API: Key Types.

Secp256k1

A specific set of parameters "the curve" used by most cryptocurrencies.

See Curve.

Test Vectors

The well-known values used for testing, demos, debugging, and development:

DashPhrase / BIP-39:
- https://github.com/trezor/python-mnemonic/blob/master/vectors.json
- Includes the Zoomonic, Zecret, and Zeed.
Generic HD Key / BIP-32:
- https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki#test-vectors
DashKeys / BIP-44:
- Zoomonic

XPrv

Also: Extended Private Key, XPriv, X Prv, X Priv

Specifically the Base58Check-encoded form of an HD Key at Depth 4.
(the X Key, a.k.a. Use Key, including the Private Key)_
Can be used to derive any number of WIFs and Addresses.

xprvA2L7qar7dyJNhxnE47gK5J6cc1oEHQuAk8WrZLnLeHTtnkeyP4w6Eo6Tt65trtdkTRtx8opazGnLbpWrkhzNaL6ZsgG3sQmc2yS8AxoMjfZ

See HD X Key.

XPub

Also: Extended Pubilc Key, X Pub

Specifically the Base58Check-encoded form of an HD Key.
(just the public key) Can be used to derive any number of receiving Addresses.

xpub6FKUF6P1ULrfvSrhA9DKSS3MA3digsd27MSTMjBxCczsfYz7vcFLnbQwjP9CsAfEJsnD4UwtbU43iZaibv4vnzQNZmQAVcufN4r3pva8kTz

See XPrv, HD X Key.

Zecret

The Secret Salt used for the BIP-32 Test Vectors.

TREZOR

letsecretSalt="TREZOR";

Comes from the fact that the company Trezor (a hardware wallet) was involved in creating the reference implementation and Test Vectors.

Zeed

The canonical Seed (generated from the Zoomonic salted with "TREZOR"),
to be used in documentation, examples, and test fixtures.

ac27495480225222079d7be181583751e86f571027b0497b5b5d11218e0a8a13332572917f0f8e5a589620c6f15b11c61dee327651a14c34e18231052e48c069

Zoomonic

Recovery Phrase (Mnemonic) : zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo wrong
Secret (Salt Password) : TREZOR
Seed : ac27495480225222079d7be181583751e86f571027b0497b5b5d11218e0a8a13332572917f0f8e5a589620c6f15b11c61dee327651a14c34e18231052e48c069

References

License

MIT License

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
cli @ 974d1d6		cli @ 974d1d6
test		test
.gitignore		.gitignore
.gitmodules		.gitmodules
.jshintrc		.jshintrc
.min-wd		.min-wd
.npmignore		.npmignore
.prettierignore		.prettierignore
.prettierrc.json		.prettierrc.json
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
dashhd.js		dashhd.js
jsconfig.json		jsconfig.json
package-lock.json		package-lock.json
package.json		package.json
test.js		test.js

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

DashHD.js

Table of Contents

Install

Node, Bun, & Bundlers

Browser

Usage Overview

Production QuickStart

API

IMPORTANT

DashHd

Constants

fromSeed(seedBytes, opts)

fromXKey(xprv || xpub, opts)

toPublic(xkey)

wipePrivateData(xkey)

toWif(privBytes, opts)

toAddr(pubBytes, opts)

toXPrv(hdkey)

toXPub(hdkey)

DashHd (BIP-32)

create(hdkey)

deriveChild(hdkey, index, isHardened)

derivePath(hdkey, hdpath)

Key Types

Wallet (depth 0)

Purpose (depth 1)

Purpose (depth 3)

Account (depth 3)

XKey (XPrv or XPub) (depth 4)

Key (depth 5)

HDKey

Walkthrough

Part 1: Recovery Phrase, Secret, Seed

Part 2: The Wallet Derivation

Part 2a: HD Path Derivation

Part 2b: Wallet, Account, X Key

Part 3: Address Key

Glossary

Base2048

Base58Check

BIP

BIP-32

BIP-39

BIP-43

BIP-44

Curve

Derive (by Path)

Derived Child

Key Expansion

HD Account

HD Address Key

HD Keys

HD Recovery Phrase

HD Path

HD Wallet

HD X Key

Root Seed

Root Key

Secp256k1

Test Vectors

XPrv

XPub

Zecret

Zeed

Zoomonic

References

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

`DashHd`

`fromSeed(seedBytes, opts)`

`fromXKey(xprv || xpub, opts)`

`toPublic(xkey)`

`wipePrivateData(xkey)`

`toWif(privBytes, opts)`

`toAddr(pubBytes, opts)`

`toXPrv(hdkey)`

`toXPub(hdkey)`

`DashHd` (BIP-32)

`create(hdkey)`

`deriveChild(hdkey, index, isHardened)`

`derivePath(hdkey, hdpath)`