Mnemonic Bytes

Mnemonic Bytes encode and decode binary data to and from mnemonic words using a base-256 encoding scheme. This is great for turning things like UUIDs, encryption keys, and wallet addresses into something that humans can actually remember and type.

To install, do the npm thing:

$ npm install mnemonic-bytes

To use it, call .encode and .decode:

1import { encode, decode } from 'mnemonic-bytes'
2
3const someBytes = new Uint8Array([ 0x01, 0x02, 0x03, 0x04 ])
4const mnemonics = encode(someBytes)
5console.log(mnemonics) // Result: [ 'affix', 'agony', 'ajar', 'alike' ]
6
7const bytes = decode([ 'affix', 'agony', 'ajar', 'alike' ])
8console.log(bytes) // Result: Uint8Array(4) [ 1, 2, 3, 4 ]

Encoding

The .encode function takes either an ArrayBuffer or a JavaScript object that has a .buffer property that contains an ArrayBuffer—like a DataView or a TypedArray. It returns a string[].

1const bytes = new Uint8Array([ 0x01, 0x02, 0x03, 0x04 ])
2const buffer = bytes.buffer
3
4let mnemonics
5
6mnemonics = encode(bytes)
7console.log(mnemonics) // Result: [ 'affix', 'agony', 'ajar', 'alike' ]
8
9mnemonics = encode(buffer)
10console.log(mnemonics) // Result: [ 'affix', 'agony', 'ajar', 'alike' ]

Decoding

The .decode function takes either a string containing whitespace-delimited mnemonics or a string[] containing mnemonics. It returns a Uint8Array.

1let bytes
2
3bytes = decode('affix agony ajar alike')
4console.log(bytes) // Result: Uint8Array(4) [ 1, 2, 3, 4 ]
5
6bytes = decode('affix\tagony\tajar\talike')
7console.log(bytes) // Result: Uint8Array(4) [ 1, 2, 3, 4 ]
8
9bytes = decode([ 'affix', 'agony', 'ajar', 'alike' ])
10console.log(bytes) // Result: Uint8Array(4) [ 1, 2, 3, 4 ]

It ignores empty strings:

1bytes = decode('')
2console.log(bytes) // Result: Uint8Array(0) []
3
4bytes = decode('\t')
5console.log(bytes) // Result: Uint8Array(0) []
6
7bytes = decode([ '', 'affix', 'agony', 'ajar', 'alike' ])
8console.log(bytes) // Result: Uint8Array(4) [ 1, 2, 3, 4 ]
9
10bytes = decode([ '\t', 'affix', 'agony', 'ajar', 'alike' ])
11console.log(bytes) // Result: Uint8Array(4) [ 1, 2, 3, 4 ]

It ignores casing in the mnemonics:

1bytes = decode('affix Agony AJAR AlIkE')
2console.log(bytes) // Result: Uint8Array(4) [ 1, 2, 3, 4 ]
3
4bytes = decode([ 'affix', 'Agony', 'AJAR', 'AlIkE' ])
5console.log(bytes) // Result: Uint8Array(4) [ 1, 2, 3, 4 ]

It throws an error if an invalid word is encountered:

1try {
2  bytes = decode('foo bar baz')
3} catch (err) {
4  console.log(err) // Result: Error: Invalid value 'foo' found at index 0
5}

Contributing

If you find a bug, typo, or some third thing, feel free to send me a pull request.