bip39

README

Bitcoin BIP39 - Mnemonic code for generating deterministic keys

Implementation in Go (golang) based on original specs.

This BIP describes the implementation of a mnemonic code or mnemonic sentence -- a group of easy to remember words -- for the generation of deterministic wallets. It consists of two parts: generating the mnemonic, and converting it into a binary seed. This seed can be later used to generate deterministic wallets using BIP-0032 or similar methods

Example

A basic example, more on go docs.

package main

import (
	"fmt"
	"log"
	"strings"
	"github.com/bgadrian/go-mnemonic/bip39"
)

func main() {
	/*
		128 bits -> 12 words
		160 bits -> 15 words
		192 bits -> 18 words
		224 bits -> 21 words
		256 bits -> 24 words
	*/
	//generate a new random 12 english words password (mnemonic)
	newRandomMnemonic, err := bip39.NewMnemonicRandom(128, "")
	if err != nil {
		log.Panic(err)
	}

	password, err := newRandomMnemonic.GetSentence()
	if err != nil {
		log.Panic(err)
	}
	fmt.Printf("the password has %v words\n", len(strings.Split(password, " ")))

	// Output:
	//the password has 12 words
}

TODO

• create a Mnemonic from a seed
• implement all word lists

Currently the library only supports the English dictionary, if enough interests is shown it's easy to implement the rest of the word lists.

Documentation

Overview

Package bip39 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.

Index

• func NewSeed(mnecmonic, passphrase string) []byte
• type Mnemonic
  • func NewMnemonicFromEntropy(ent []byte, passphrase string) (code *Mnemonic, err error)
  • func NewMnemonicFromSentence(sentence string, passphrase string) (code *Mnemonic, e error)
  • func NewMnemonicRandom(size int, passphrase string) (code *Mnemonic, e error)
  • func (m *Mnemonic) GetEntropyStrHex() (string, error)
  • func (m *Mnemonic) GetSeed() (seed string, e error)
  • func (m *Mnemonic) GetSentence() (string, error)

Examples

• NewMnemonicFromEntropy
• NewMnemonicFromSentence
• NewMnemonicRandom

Functions

func NewSeed

func NewSeed(mnecmonic, passphrase string) []byte

NewSeed Based on a code (word list) returns the seed (hex bytes)

Types

type Mnemonic

type Mnemonic struct {
	// contains filtered or unexported fields
}

Mnemonic ...

func NewMnemonicFromEntropy

func NewMnemonicFromEntropy(ent []byte, passphrase string) (code *Mnemonic, err error)

NewMnemonicFromEntropy Generates a Mnemonic based on a known entropy (stored as hex bytes)

Example

//we ignore the errors returned for Example simplicity sake, don't do this on, production
entHexBytes := []byte{94, 127, 194, 94, 217, 163, 84, 91, 112, 158, 206, 144, 80, 5, 219, 134}

mnemonic, _ := NewMnemonicFromEntropy(entHexBytes, "")
password, _ := mnemonic.GetSentence()
seed, _ := mnemonic.GetSeed()

fmt.Printf("entropy can be stored as '%v'\n", hex.EncodeToString(entHexBytes))
fmt.Printf("password is '%v'\n", password)
fmt.Printf("seed is '%v'\n", seed)

Output:

entropy can be stored as '5e7fc25ed9a3545b709ece905005db86'
password is 'fury wrap nut rebuild crystal color second supply motion lens ivory around'
seed is 'b5f87c4020dde5e83f73dd89ceb49b2700437008fe6593dd675ea856be1d687e3bc17a4cf9c070f7e469d704942f137ae4eea7ad2c9189edffd991e0075b44ee'

func NewMnemonicFromSentence

func NewMnemonicFromSentence(sentence string, passphrase string) (code *Mnemonic, e error)

NewMnemonicFromSentence Generates a menmonic based on a known code (list of words).

Example

//we ignore the errors returned for Example simplicity sake, don't do this on, production
password := "fury wrap nut rebuild crystal color second supply motion lens ivory around"

mnemonic, _ := NewMnemonicFromSentence(password, "")
seed, _ := mnemonic.GetSeed()
ent, _ := mnemonic.GetEntropyStrHex()

fmt.Printf("seed is '%v'\n", seed)
fmt.Printf("entropy can be stored as '%v'\n", ent)

Output:

seed is 'b5f87c4020dde5e83f73dd89ceb49b2700437008fe6593dd675ea856be1d687e3bc17a4cf9c070f7e469d704942f137ae4eea7ad2c9189edffd991e0075b44ee'
entropy can be stored as '5e7fc25ed9a3545b709ece905005db86'

func NewMnemonicRandom

func NewMnemonicRandom(size int, passphrase string) (code *Mnemonic, e error)

NewMnemonicRandom creates a new random (crypto safe) Mnemonic.Use size 128 for a 12 words code.

Example

/*
	128 bits -> 12 words
	160 bits -> 15 words
	192 bits -> 18 words
	224 bits -> 21 words
	256 bits -> 24 words
*/
//generate a new random 12 english words password (mnemonic)
newRandomMnemonic, err := NewMnemonicRandom(128, "")
if err != nil {
	log.Panic(err)
}

password, err := newRandomMnemonic.GetSentence()
if err != nil {
	log.Panic(err)
}
fmt.Printf("the password has %v words\n", len(strings.Split(password, " ")))

Output:

the password has 12 words

func (*Mnemonic) GetEntropyStrHex

func (m *Mnemonic) GetEntropyStrHex() (string, error)

GetEntropyStrHex get the entryope as hex in a string, for easy storage

func (*Mnemonic) GetSeed

func (m *Mnemonic) GetSeed() (seed string, e error)

GetSeed Returns the seed for this Mnemonic (as hex in string)

func (*Mnemonic) GetSentence

func (m *Mnemonic) GetSentence() (string, error)

GetSentence Return the words from this Mnemonic.