Mnemonic

The Mnemonic class provides an implementation of a mnemonic code or mnemonic sentence – a group of easy to remember words – for the generation of deterministic keys. The class handles code generation and its later conversion to a HDPrivateKey. See the official BIP-0039 for technical background information.

Installation

Mnemonics is implemented as a separate module and you must add it to your dependencies:

For node projects:

npm install bitcore-mnemonic --save

For client-side projects:

bower install bitcore-mnemonic --save

Mnemonic generation

For creating a new random mnemonic code you just create a new instance.

var Mnemonic = require('bitcore-mnemonic');
var code = new Mnemonic();

code.toString(); // 'select scout crash enforce riot rival spring whale hollow radar rule sentence'

Multi-language support

The Mnemonic class can use any list of 2048 unique words to generate the mnemonic code. For convenience the class provides default word lists for the following languages: English (default), Chinese, French, Japanese and Spanish. Those word list are published under Mnemonic.Words.LANGUAGE, take a look at the following example:

var Mnemonic = require('bitcore-mnemonic');
var code = new Mnemonic(Mnemonic.Words.SPANISH);
code.toString(); // natal hada sutil año sólido papel jamón combate aula flota ver esfera...

var myWordList = [ 'abandon', 'ability', 'able', 'about', 'above', ... ];
var customCode = new Mnemonic(myWordList);

Validating a mnemonic

The Mnemonic class provides a static method to check if a mnemonic string is valid. If you generated the mnemonic code using any of the default word list, the class will identify it, otherwise you must provide the word list used.

var Mnemonic = require('bitcore-mnemonic');

var code = 'select scout crash enforce riot rival spring whale hollow radar rule sentence';
var valid = Mnemonic.isValid(code);

// using a custom word list
var validCutom = Mnemonic.isValid(code, customWordlist);

Generating a private key

A mnemonic encodes entropy that can be used for creating a seed and later a HDPrivateKey. During the seed generation process a passphrase can be used. The code for doing so looks like this:

var Mnemonic = require('bitcore-mnemonic');
var code = new Mnemonic('select scout crash enforce riot rival spring whale hollow radar rule sentence');

var xpriv1 = code.toHDPrivateKey(); // no passphrase
var xpriv2 = code.toHDPrivateKey('my passphrase'); // using a passphrase

Mnemonic

Kind: global class

new Mnemonic([data], [wordlist])

This is an immutable class that represents a BIP39 Mnemonic code. See BIP39 specification for more info: https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki A Mnemonic code is a a group of easy to remember words used for the generation of deterministic wallets. A Mnemonic can be used to generate a seed using an optional passphrase, for later generate a HDPrivateKey.

Returns: Mnemonic - A new instance of Mnemonic

Param Type Description
[data] * a seed, phrase, or entropy to initialize (can be skipped)
[wordlist] Array the wordlist to generate mnemonics from

Example

// generate a random mnemonic
var mnemonic = new Mnemonic();
var phrase = mnemonic.phrase;

// use a different language
var mnemonic = new Mnemonic(Mnemonic.Words.SPANISH);
var xprivkey = mnemonic.toHDPrivateKey();

mnemonic.toSeed([passphrase]) ⇒ Buffer

Will generate a seed based on the mnemonic and optional passphrase.

Kind: instance method of Mnemonic

Param Type
[passphrase] String

mnemonic.toHDPrivateKey([passphrase], [network]) ⇒ HDPrivateKey

Generates a HD Private Key from a Mnemonic. Optionally receive a passphrase and bitcoin network.

Kind: instance method of Mnemonic

Param Type Description
[passphrase] String
[network] Network | String | number The network: 'livenet' or 'testnet'

mnemonic.toString() ⇒ String

Will return a the string representation of the mnemonic

Kind: instance method of Mnemonic
Returns: String - Mnemonic

mnemonic.inspect() ⇒ String

Will return a string formatted for the console

Kind: instance method of Mnemonic
Returns: String - Mnemonic

Mnemonic.isValid(mnemonic, [wordlist]) ⇒ boolean

Will return a boolean if the mnemonic is valid

Kind: static method of Mnemonic

Param Type Description
mnemonic String The mnemonic string
[wordlist] String The wordlist used

Example

var valid = Mnemonic.isValid('lab rescue lunch elbow recall phrase perfect donkey biology guess moment husband');
// true

Mnemonic._belongsToWordlist(mnemonic, wordlist) ⇒ boolean

Internal function to check if a mnemonic belongs to a wordlist.

Kind: static method of Mnemonic

Param Type Description
mnemonic String The mnemonic string
wordlist String The wordlist

Mnemonic._getDictionary(mnemonic) ⇒ Array

Internal function to detect the wordlist used to generate the mnemonic.

Kind: static method of Mnemonic
Returns: Array - the wordlist or null

Param Type Description
mnemonic String The mnemonic string

Mnemonic.fromSeed([seed], [wordlist]) ⇒ Mnemonic

Will generate a Mnemonic object based on a seed.

Kind: static method of Mnemonic

Param Type
[seed] Buffer
[wordlist] string

Mnemonic._mnemonic(ENT, wordlist) ⇒ String

Internal function to generate a random mnemonic

Kind: static method of Mnemonic
Returns: String - Mnemonic string

Param Type Description
ENT Number Entropy size, defaults to 128
wordlist Array Array of words to generate the mnemonic

Mnemonic._entropy2mnemonic(entropy, wordlist) ⇒ String

Internal function to generate mnemonic based on entropy

Kind: static method of Mnemonic
Returns: String - Mnemonic string

Param Type Description
entropy Number Entropy buffer
wordlist Array Array of words to generate the mnemonic

pbkdf2()

PDKBF2 Credit to: https://github.com/stayradiated/pbkdf2-sha512 Copyright (c) 2014, JP Richardson Copyright (c) 2010-2011 Intalio Pte, All Rights Reserved

Kind: global function