@iacobus/bip39 v2.1.1

TypeScript | BIP39 - Iacobus

An extended implementation of BIP39.

This library supports an extended implementation of the Bitcoin Improvement Proposal 39, Mnemonic code for generating deterministic keys. TypeScript, ESM, and CommonJS compatible. To get started, install the library:

# Deno
deno add jsr:@iacobus/bip39

# Node.js
npm install @iacobus/bip39

Important Note: As an extended implementation of BIP39, the toMnemonic function of @iacobus/bip39 supports an optional ext parameter, that when true, permits any initial entropy length that does not exceed 8192 bits, and will generate mnemonic sentences that fall outside the scope of the proposal. When ext is undefined or false, only mnemonic sentences within the scope of the proposal may be generated.

BIP39

TypeScript/ESM import:

import * as bip39 from "@iacobus/bip39";

CommonJS require:

const bip39 = require("@iacobus/bip39");

The @iacobus/bip39 entry point exports functions for mnemonic sentence generation, verification, conversion of mnemonic sentences back to initial entropy, and seed creation. Every function of this entry point requires a wordlist be provided, with the following BIP39 wordlists available in this library:

• English, imported as english.
• Chinese (Simplified) imported as chinese_simplified.
• Chinese (Traditional) imported as chinese_traditional.
• Czech, imported as czech.
• French, imported as french.
• Italian, imported as italian.
• Japanese, imported as japanese.
• Korean, imported as korean.
• Portuguese, imported as portuguese.
• Spanish, imported as spanish.

Every supported wordlist is available under its own entry point, following the pattern @iacobus/bip39/wordlist/{wordlist_name}. As an example, the English wordlist may be imported as follows:

import { english } from "@iacobus/bip39/wordlist/english";

Mnemonic Sentence Generation

Two functions are available for mnemonic sentence generation. One supports the creation of random mnemonic sentences, and the other supports the creation of mnemonic sentences from supplied entropy.

generateMnemonic

A random mnemonic sentence is generated from cryptographically secure entropy obtained internally from the randomBytes util of @noble/hashes, using the generateMnemonic function.

The generateMnemonic function has two input parameters:

function generateMnemonic(wordlist, msLen) {};

Where:

• wordlist is a BIP39 wordlist (e.g. the English wordlist).
• msLen is the length of the mnemonic sentence.

The wordlist parameter is expected as an array (string[]) containing 2048 words, and the msLen parameter is expected as a number, corresponding to the length of the mnemonic sentence as a number of words (12, 15, 18, 21, or 24). The generateMnemonic function is synchronous, and returns a string.

Example use:

import { generateMnemonic } from "@iacobus/bip39";
import { english } from "@iacobus/bip39/wordlist/english";

const ms = generateMnemonic(english, 12); // word breeze hope phrase year road nature copy face forest tumble coin

toMnemonic

A mnemonic sentence from supplied entropy is generated using the toMnemonic function.

The toMnemonic function has three input parameters:

function toMnemonic(wordlist, ent, ext?) {};

Where:

• wordlist is a BIP39 wordlist (e.g. the English wordlist).
• ent is initial entropy (raw entropy without a checksum applied).
• ext is an optional value to enable the extended implementation.

The wordlist parameter is expected as an array (string[]) containing 2048 words, the ent parameter is expected as a Uint8Array of the initial entropy, and the ext parameter is expected as a boolean value, that when true enables the extended implementation of BIP39. When enabled, any initial entropy length that does not exceed 8192 bits is supported, padding is applied to the initial entropy when it is not suitable for mnemonic sentence generation as supplied, and sentences at lengths other than 12, 15, 18, 21, and 24 words may be generated. The toMnemonic function is synchronous, and returns a string.

Example use, non-extended:

import { toMnemonic } from "@iacobus/bip39";
import { english } from "@iacobus/bip39/wordlist/english";

const ent: Uint8Array = Uint8Array.from([66, 111, 101, 105, 110, 103, 32, 65, 51, 50, 49, 32, 77, 65, 88, 33]);
const ms = toMnemonic(english, ent); // draw kite fog system improve calm smoke economy cake head figure drastic

Mnemonic Sentence Verification

Mnemonic sentences are verified for validity via the verification of their appended checksums, using the verifyMnemonic function.

The verifyMnemonic function has two input parameters:

function verifyMnemonic(wordlist, ms) {};

Where:

• wordlist is a BIP39 wordlist (e.g. the English wordlist).
• ms is a mnemonic sentence.

The wordlist parameter is expected as an array (string[]) containing 2048 words, and the ms parameter expects a mnemonic sentence as a string. The verifyMnemonic function is synchronous, and returns the verification result as a boolean value.

Example use:

import { verifyMnemonic } from "@iacobus/bip39";
import { english } from "@iacobus/bip39/wordlist/english";

const ms: string = "draw kite fog system improve calm smoke economy cake head figure drastic";
const verified = verifyMnemonic(english, ms); // true

Mnemonic Sentence to Entropy

A mnemonic sentence can be converted back to the initial entropy (as a bitstream string) from which it was generated using the fromMnemonic function.

The fromMnemonic function has two input parameters:

function fromMnemonic(wordlist, ms) {};

Where:

• wordlist is a BIP39 wordlist (e.g. the English wordlist).
• ms is a mnemonic sentence.

The wordlist parameter is expected as an array (string[]) containing 2048 words, and the ms parameter expects a mnemonic sentence as a string. The fromMnemonic function is synchronous, and returns a Uint8Array.

Example use:

const { fromMnemonic } = require("@iacobus/bip39");
const { english } = require("@iacobus/bip39/wordlist/english");

const ms: string = "draw kite fog system improve calm smoke economy cake head figure drastic";
const ent = fromMnemonic(english, ms); // Uint8Array(16) [66, 111, 101, 105, 110, 103, 32, 65, 51, 50, 49, 32, 77, 65, 88, 33]

Creating a Seed

A 64 byte seed can be created from a mnemonic sentence and optional passphrase using the createSeed function. An asynchronous version of this function also exists, as the createSeedAsync function. For demonstration purposes, the synchronous version will be used.

The createSeed function has three input parameters:

function createSeed(wordlist, ms, passphrase?) {};

Where:

• wordlist is a BIP39 wordlist (e.g. the English wordlist).
• ms is a mnemonic sentence.
• passphrase is an optional passphrase.

The wordlist parameter is expected as an array (string[]) containing 2048 words, the ms parameter expects a mnemonic sentence as a string, and the optional passphrase parameter expects a passphrase as a string. The createSeed function is synchronous, and returns a Uint8Array. The createSeedAsync function is asynchronous, and returns a Promise that resolves to a Uint8Array.

Example use, without a passphrase:

import { createSeed } from "@iacobus/bip39";
import { english } from "@iacobus/bip39/wordlist/english";

const ms: string = "draw kite fog system improve calm smoke economy cake head figure drastic";
const seed = createSeed(english, ms);

/*
Uint8Array(64) [
  253,  45, 107, 175, 229, 231, 200, 244, 219, 156,
  214, 195,  80, 123, 225, 239,  74, 191, 246, 248,
  124, 112, 215,  56, 230, 179, 228, 122, 213, 131,
  223, 214, 162, 143,  65, 209,  58,  65, 155, 186,
  174,  37,  33,  27,  13, 218,  11, 124, 237, 231,
  165, 224, 183, 218,  60,  70, 238, 138,  62, 205,
   18, 148,  30, 121
]
*/

BIP39 Lite

TypeScript/ESM import:

import * as bip39 from "@iacobus/bip39/lite";

CommonJS require:

const bip39 = require("@iacobus/bip39/lite");

The @iacobus/bip39/lite entry point exports lite functions for mnemonic generation, verification, and seed creation. Lite denotes that these functions are more minimal than those of the @iacobus/bip39 entry point, with the main distinction being that the lite functions do not accept a wordlist parameter, instead only using the English wordlist. This aims to provide a simple "one stop" option for core functionality.

Mnemonic Sentence Generation

Mnemonic sentences can be generated with internally obtained or supplied entropy using the generateMnemonic function. This acts as a combination of the generateMnemonic and toMnemonic (without the ext option) functions from the @iacobus/bip39 entry point.

The generateMnemonic function has two input parameters:

function generateMnemonic(msLen, ent?) {};

Where:

• msLen is the length of the mnemonic sentence.
• ent is the optional initial entropy (raw entropy without a checksum applied).

The msLen parameter is expected as a number, corresponding to the length of the mnemonic sentence as a number of words (12, 15, 18, 21, or 24), and the optional ent parameter is expected as a Uint8Array of the initial entropy. The generateMnemonic function is synchronous, returning a string.

Example use, with entropy provided:

import { generateMnemonic } from "@iacobus/bip39/lite";

const ent: Uint8Array = Uint8Array.from([66, 111, 101, 105, 110, 103, 32, 65, 51, 50, 49, 32, 77, 65, 88, 33]);
const ms = generateMnemonic(12, ent); // draw kite fog system improve calm smoke economy cake head figure drastic

Other Lite Functions

The remainder of the functions from the @iacobus/bip39/lite entry point are near identical to those from the @iacobus/bip39 entry point, with the only difference being the lack of a wordlist parameter. Internally, they are exactly the same. They replace the need to obtain a wordlist from a parameter with direct use of the English wordlist. For this reason, example use of these functions is not needed, as their use mirrors the non-lite functions of the same name, just with the wordlist parameter removed.

Verifying a mnemonic sentence:

function verifyMnemonic(ms: string): boolean {};

Creating a seed:

// Synchronous
function createSeed(ms: string, passphrase?: string): Uint8Array {};

// Asynchronous
async function createSeedAsync(ms: string, passphrase?: string): Promise<Uint8Array> {};

Utilities

TypeScript/ESM import:

import * as utils from "@iacobus/bip39/utils";

CommonJS require:

const utils = require("@iacobus/bip39/utils");

BIP39 utility functions are available under the @iacobus/bip39/utils entry point. This includes functionality for bitstream conversion, checksum calculation & verification, entropy padding, mnemonic sentence conversion, and the creation of seeds from mnemonic sentences.

Bitstream String Conversion

Two functions are included for the conversion between Uint8Arrays and Bitstream Strings. The toBitstream function accepts a Uint8Array and returns a bitstream string, and the fromBitstream function accepts a bitstream string and returns a Uint8Array.

Convert from a Uint8Array to a bitstream string:

import { toBitstream } from "@iacobus/bip39/utils";

const bytes: Uint8Array = Uint8Array.from([9, 8, 7, 6]);
const bits = toBitstream(bytes); // 00001001000010000000011100000110

Convert from a bitstream string to a Uint8Array:

import { fromBitstream } from "@iacobus/bip39/utils";

const bits: string = "00001001000010000000011100000110";
const bytes = fromBitstream(bits); // Uint8Array(4) [ 9, 8, 7, 6 ]

Checksum Calculation & Verification

Two functions are included for Bitstream String checksum calculation and verification of appended checksums. The calcCsum function accepts a bitstream string and returns a bitstream string of the checksum, and the verifyCsum function accepts a bitstream string and returns the verification result as a boolean value.

Calculate a checksum:

import { calcCsum } from "@iacobus/bip39/utils";

const bits: string = "01000010011011110110010101101001011011100110011100100000010000010011001100110010001100010010000001001101010000010101100000100001"
const csum = calcCsum(bits); // 0010

Verify an appended checksum:

import { verifyCsum } from "@iacobus/bip39/utils";

const bits: string = "010000100110111101100101011010010110111001100111001000000100000100110011001100100011000100100000010011010100000101011000001000010010"
const verified = verifyCsum(bits); // true

Padding

Two functions are included for applying padding to Uint8Arrays and Bitstream Strings. The padBytes function accepts a Uint8Array and returns a padded Uint8Array, padding to reach a permitted initial entropy length (ENT), so that ENT / 32 can yield an integer CS, and that ENT + CS are a multiple of 11. The padBits function accepts a bitstream string and returns a padded bitstream string, padding to reach a multiple of 11.

Apply padding to a Uint8Array:

import { padBytes } from "@iacobus/bip39/utils";

const ent: Uint8Array = Uint8Array.from([68, 105, 110, 111, 115, 97, 117, 114, 115]);
const padded = padBytes(ent); // Uint8Array(12) [68, 105, 110, 111, 115, 97, 117, 114, 115, 0, 0, 0]

Apply padding to a bitstream string:

import { padBitstream } from "@iacobus/bip39/utils";

const ent: string = "010001000110100101101110011011110111001101100001011101010111001001110011";
const padded = padBitstream(ent); // 01000100011010010110111001101111011100110110000101110101011100100111001100000

Mnemonic Sentence Conversion

Two functions are included for the conversion between Bitstream Strings and Mnemonic Sentences. The bitstreamToMs function accepts a bitstream string and returns a mnemonic sentence string, and the msToBitstream function accepts a mnemonic sentence string and returns a bitstream string. Unlike the mnemonic generation functions of the @iacobus/bip39 and @iacobus/bip39/lite entry points, no internal validation takes place before returning the mnemonic sentence from the bitstreamToMs function.

Convert from a bitstream string to a mnemonic sentence:

import { bitstreamToMs } from "@iacobus/bip39/utils";
import { english } from "@iacobus/bip39/wordlist/english";

const bits: string = "01000010011011110110010101101001011011100110";
const ms = bitstreamToMs(english, bits); // draw kite fog system

Convert from a mnemonic sentence to a bitstream string:

import { msToBitstream } from "@iacobus/bip39/utils";
import { english } from "@iacobus/bip39/wordlist/english";

const ms: string = "draw kite fog system";
const bits = msToBitstream(english, ms); // 01000010011011110110010101101001011011100110

Creating a Seed

A 64 byte seed can be created from a mnemonic sentence and optional passphrase using the msToSeed function. An asynchronous version of this function also exists, as the msToSeedAsync function. Unlike the createSeed and createSeedAsync functions of the @iacobus/bip39 and @iacobus/bip39/lite entry points, no internal validation takes place.

Create a seed (synchronous):

import { msToSeed } from "@iacobus/bip39/utils";

const ms: string = "draw kite fog system improve calm smoke economy cake head figure drastic";
const seed = msToSeed(ms); // Uint8Array(64) [253, 45, 107, 175...]

Create a seed (asynchronous):

import { msToSeedAsync } from "@iacobus/bip39/utils";

const ms: string = "draw kite fog system improve calm smoke economy cake head figure drastic";
const seed = await msToSeedAsync(ms); // Uint8Array(64) [253, 45, 107, 175...]