bip39

README

Bip39 package

Introduction

This package implements the BIP-0039 specification. This includes:

• Mnemonic generation from a specified number of words, using random entropy
• Mnemonic generation from a specified entropy
• Mnemonic validation
• Seed generation from a mnemonic with a specified passphrase

NOTE: only the English words list is currently supported.

Installation

The package can be installed by simply running:

go get -u github.com/ebellocchia/go-bip39

Usage

The package is pretty easy to use, so a code example is probably self-explanatory.

Example

package main

import (
  "github.com/ebellocchia/go-bip39"
  "fmt"
  "encoding/hex"
)

func main() {
    // Generate a random entropy with the specified number of bits
    // An error is returned if the entropy bit length is not valid
    entropy, err := bip39.GenerateEntropy(bip39.EntropyBits128)
    if err != nil {
        panic(err)
    }
    fmt.Println(hex.EncodeToString(entropy))

    // Generate a mnemonic from the entropy
    // An error is returned if the entropy bit length is not valid
    mnemonic, err := bip39.MnemonicFromEntropy(entropy)
    if err != nil {
        panic(err)
    }
    fmt.Println(mnemonic.Words)

    // Generate a mnemonic with a specified number of words (a random entropy will be generated internally)
    // An error is returned if the number of words is not valid
    mnemonic, err = bip39.MnemonicFromWordsNum(bip39.WordsNum12)
    if err != nil {
        panic(err)
    }
    fmt.Println(mnemonic.Words)

    // Create a mnemonic directly from an existent string
    mnemonic = bip39.MnemonicFromString("legal winner thank year wave sausage worth useful legal winner thank yellow")
    fmt.Println(mnemonic.Words)

    // Get entropy back from the mnemonic
    // An error is returned if the mnemonic is not valid
    entropy, err = mnemonic.ToEntropy()
    if err != nil {
        panic(err)
    }
    fmt.Println(hex.EncodeToString(entropy))

    // Validate a mnemonic, return an error if not valid
    err = mnemonic.Validate()
    if err != nil {
        panic(err)
    }

    // Get if the mnemonic is valid. Same of before but bool is returned instead of error.
    is_valid := mnemonic.IsValid()
    if !is_valid {
        // Do something...
    }

    // Generate a seed from the mnemonic using the specified passphrase (can be also empty)
    // An error is returned if the mnemonic is not valid
    seed, err := mnemonic.GenerateSeed("my_passphrase")
    if err != nil {
        panic(err)
    }
    fmt.Println(hex.EncodeToString(seed))
}

The valid bit lengths for entropy generation are:

• bip39.EntropyBits128
• bip39.EntropyBits160
• bip39.EntropyBits192
• bip39.EntropyBits224
• bip39.EntropyBits256

The valid words number for mnemonic generation are:

• bip39.WordsNum12
• bip39.WordsNum15
• bip39.WordsNum18
• bip39.WordsNum21
• bip39.WordsNum24

License

This software is available under the MIT license.

Documentation

Index

• Constants
• Variables
• func GenerateEntropy(bitLen int) ([]byte, error)
• type Mnemonic
  • func MnemonicFromEntropy(entropy []byte) (*Mnemonic, error)
  • func MnemonicFromString(mnemonic string) *Mnemonic
  • func MnemonicFromWordsNum(wordsNum int) (*Mnemonic, error)
  • func (mnemonic *Mnemonic) GenerateSeed(passphrase string) ([]byte, error)
  • func (mnemonic *Mnemonic) IsValid() bool
  • func (mnemonic *Mnemonic) ToEntropy() ([]byte, error)
  • func (mnemonic *Mnemonic) Validate() error

Constants

const (
	// Entropy bit lengths
	EntropyBits128 = 128
	EntropyBits160 = 160
	EntropyBits192 = 192
	EntropyBits224 = 224
	EntropyBits256 = 256
)

Constants

const (
	// Words number
	WordsNum12 = 12
	WordsNum15 = 15
	WordsNum18 = 18
	WordsNum21 = 21
	WordsNum24 = 24
)

Constants

Variables

var (
	// ErrWordsNum is returned when trying to generate mnemonic with invalid words number
	ErrWordsNum = errors.New("The specified words number is not valid for mnemonic generation")
	// ErrInvalidWord is returned when trying to get entropy or validating a mnemonic with invalid words
	ErrInvalidWord = errors.New("The mnemonic contains an invalid word")
	// ErrChecksum is returned when trying to get entropy or validating a mnemonic with invalid checksum
	ErrChecksum = errors.New("The checksum of the mnemonic is not valid")
)

Variables

var (
	// ErrBinaryString is returned when trying to convert an invalid binary string to byte slice
	ErrBinaryString = errors.New("The specified binary string is not valid")
)

Variables

var (
	// ErrEntropyBitLen is returned when trying to generate entropy with invalid bit length
	ErrEntropyBitLen = errors.New("The specified bit length is not valid for entropy generation")
)

Variables

Functions

func GenerateEntropy

func GenerateEntropy(bitLen int) ([]byte, error)

Generate entropy bytes with the specified bit length.

Types

type Mnemonic

type Mnemonic struct {
	Words string
}

Structure for mnemonic

func MnemonicFromEntropy

func MnemonicFromEntropy(entropy []byte) (*Mnemonic, error)

Generate mnemonic from the specific entropy. The entropy slice shall be of a valid length.

func MnemonicFromString

func MnemonicFromString(mnemonic string) *Mnemonic

Create mnemonic object from a mnemonic string.

func MnemonicFromWordsNum

func MnemonicFromWordsNum(wordsNum int) (*Mnemonic, error)

Generate mnemonic from the specified words number. A random entropy is used for generating mnemonic.

func (*Mnemonic) GenerateSeed

func (mnemonic *Mnemonic) GenerateSeed(passphrase string) ([]byte, error)

Generate the seed from a mnemonic using the specified passphrase for protection.

func (*Mnemonic) IsValid

func (mnemonic *Mnemonic) IsValid() bool

Get if a mnemonic is valid. It's the same of the Validate method but returns bool instead of error.

func (*Mnemonic) ToEntropy

func (mnemonic *Mnemonic) ToEntropy() ([]byte, error)

Convert a mnemonic back to entropy bytes. Error is returned if mnemonic or checksum is not valid.

func (*Mnemonic) Validate

func (mnemonic *Mnemonic) Validate() error

Validate a mnemonic. For being valid, all the mnemonic words shall exists in the words list and the checksum shall be valid.