bip39

README

bip39

A pure Golang implementation of the BIP39 protocol that automatically detects and supports mnemonic phrases in multiple languages.

Basic Usage

Installation

To get the package, execute:

go get github.com/gofika/bip39

Example

package main

import (
	"github.com/gofika/bip39"
)

func main() {
	// Detect for English
	{
		languages, ok := bip39.DetectLanguage("carbon elder drip best unlock pool athlete fortune mixture exist bachelor quick faculty obey cliff")
		if !ok {
			panic("invalid language")
		}
		if len(languages) != 1 || languages[0] != bip39.English {
			panic("invalid language")
		}
	}
	// Detect for Japanese
	{
		languages, ok := bip39.DetectLanguage("おさえる　けむり　けしごむ　うせつ　もちろん　とさか　いはつ　ざっか　たりる　こさめ　いわい　にいがた　こてい　ちんもく　がぞう")
		if !ok {
			panic("invalid language")
		}
		if len(languages) != 1 || languages[0] != bip39.Japanese {
			panic("invalid language")
		}
	}
	// Detect for ChineseSimplified and ChineseTraditional
	{
		languages, ok := bip39.DetectLanguage("露 水 域 耀 搜 船 良 摘 士 近 桃 案")
		if !ok {
			panic("invalid language")
		}
		if len(languages) != 2 {
			panic("invalid language")
		}
	}
	// Detect WithLanguages
	{
		languages, ok := bip39.DetectLanguage("露 水 域 耀 搜 船 良 摘 士 近 桃 案", bip39.WithLanguages([]bip39.Language{bip39.ChineseSimplified}))
		if !ok {
			panic("invalid language")
		}
		if len(languages) != 1 || languages[0] != bip39.ChineseSimplified {
			panic("invalid language")
		}
	}

	// NewMnemonic
	{
		// default language is English
		m, err := bip39.NewMnemonic()
		if err != nil {
			panic(err)
		}
		// default entropy 128 bits
		mnemonic, err := m.GenerateMnemonic()
		if err != nil {
			panic(err)
		}
		// default passphrase is empty
		seed := bip39.NewSeed(mnemonic)
		if len(seed) != 64 {
			panic("invalid seed")
		}
	}
	// NewMnemonic with Japanese
	{
		// generate mnemonic with Japanese
		m, err := bip39.NewMnemonic(bip39.WithLanguage(bip39.Japanese))
		if err != nil {
			panic(err)
		}
		// set entropy 256 bits
		mnemonic, err := m.GenerateMnemonic(bip39.WithEntropyBits(256))
		if err != nil {
			panic(err)
		}
		// set passphrase "gofika"
		seed := bip39.NewSeed(mnemonic, bip39.WithPassphrase("gofika"))
		if len(seed) != 64 {
			panic("invalid seed")
		}
	}
}

Documentation

Index

• Variables
• func IsMnemonicValid(mnemonic string) bool
• func NewSeed(mnemonic string, opts ...NewSeedOption) []byte
• func NormalizeMnemonic(mnemonic string) string
• func SplitMnemonic(mnemonic string) (words []string, delimiter string)
• func WithEntropyBits(entropyBits int) func(*GenerateMnemonicOptions)
• func WithLanguage(language Language) func(*NewMnemonicOptions)
• func WithLanguages(languages []Language) func(*DetectLanguageOptions)
• func WithPassphrase(passphrase string) func(*NewSeedOptions)
• type DetectLanguageOption
• type DetectLanguageOptions
• type GenerateMnemonicOption
• type GenerateMnemonicOptions
• type Language
  • func DetectLanguage(mnemonic string, opts ...DetectLanguageOption) (languages []Language, ok bool)
• type Mnemonic
  • func NewMnemonic(opts ...NewMnemonicOption) (*Mnemonic, error)
  • func (m *Mnemonic) EntropyFromMnemonic(mnemonic string) ([]byte, error)
  • func (m *Mnemonic) EntropyToMnemonic(entropy []byte) (string, error)
  • func (m *Mnemonic) GenerateMnemonic(opts ...GenerateMnemonicOption) (string, error)
• type NewMnemonicOption
• type NewMnemonicOptions
• type NewSeedOption
• type NewSeedOptions

Variables

var (
	ErrInvalidEntropy       = errors.New("invalid entropy")
	ErrInvalidMnemonic      = errors.New("invalid mnemonic")
	ErrInvalidNumberWords   = errors.New("invalid number of words")
	ErrInvalidNumberEntropy = errors.New("invalid number of entropy")
	ErrChecksumIncorrect    = errors.New("checksum incorrect")
)

Functions

func IsMnemonicValid

func IsMnemonicValid(mnemonic string) bool

IsMnemonicValid attempts to verify that the provided mnemonic is valid. Validity is determined by both the number of words being appropriate, and that all the words in the mnemonic are present in the word list.

func NewSeed

func NewSeed(mnemonic string, opts ...NewSeedOption) []byte

NewSeed creates a hashed seed output given a provided string and password. No checking is performed to validate that the string provided is a valid mnemonic. default passphrase is empty string. if you want to set passphrase, use WithPassphrase() option.

func NormalizeMnemonic

func NormalizeMnemonic(mnemonic string) string

NormalizeMnemonic normalizes the mnemonic.

Example:

mnemonic := "おさえる　けむり　　けしごむ　うせつ　もちろん　　とさか　いはつ　ざっか　たりる　　こさめ　いわい　　にいがた　こてい　ちんもく　がぞう　"
mnemonic = NormalizeMnemonic(mnemonic)
fmt.Println(mnemonic) // おさえる　けむり　けしごむ　うせつ　もちろん　とさか　いはつ　ざっか　たりる　こさめ　いわい　にいがた　こてい　ちんもく　がぞう

Example:

mnemonic := "carbon     elder  drip best unlock pool athlete   fortune mixture exist   bachelor quick faculty    obey cliff"
mnemonic = NormalizeMnemonic(mnemonic)
fmt.Println(mnemonic) // carbon elder drip best unlock pool athlete fortune mixture exist bachelor quick faculty obey cliff

func SplitMnemonic

func SplitMnemonic(mnemonic string) (words []string, delimiter string)

SplitMnemonic splits a mnemonic into words and delimiter. If the delimiter is a Japanese space, then the language must be Japanese.

Example:

words, delimiter := SplitMnemonic("おさえる　けむり　けしごむ　うせつ　もちろん　とさか　いはつ　ざっか　たりる　こさめ　いわい　にいがた　こてい　ちんもく　がぞう")
fmt.Println(words) // ["おさえる", "けむり", "けしごむ", "うせつ", "もちろん", "とさか", "いはつ", "ざっか", "たりる", "こさめ", "いわい", "にいがた", "こてい", "ちんもく", "がぞう"]
fmt.Println(delimiter) // "　"

Example:

words, delimiter := SplitMnemonic("carbon elder drip best unlock pool athlete fortune mixture exist bachelor quick faculty obey cliff")
fmt.Println(words) // ["carbon", "elder", "drip", "best", "unlock", "pool", "athlete", "fortune", "mixture", "exist", "bachelor", "quick", "faculty", "obey", "cliff"]
fmt.Println(delimiter) // " "

func WithEntropyBits

func WithEntropyBits(entropyBits int) func(*GenerateMnemonicOptions)

WithEntropyBits sets the bits of the entropy.

func WithLanguage

func WithLanguage(language Language) func(*NewMnemonicOptions)

WithLanguage sets the language of the mnemonic.

func WithLanguages

func WithLanguages(languages []Language) func(*DetectLanguageOptions)

WithLanguages sets the languages to detect. If not set, all languages are possible.

func WithPassphrase

func WithPassphrase(passphrase string) func(*NewSeedOptions)

WithPassphrase sets the passphrase used to generate the seed.

Types

type DetectLanguageOption

type DetectLanguageOption func(*DetectLanguageOptions)

DetectLanguageOption a function that modifies DetectLanguageOptions

type DetectLanguageOptions

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

DetectLanguageOptions options for DetectLanguage function

type GenerateMnemonicOption

type GenerateMnemonicOption func(*GenerateMnemonicOptions)

GenerateMnemonicOption a function that modifies GenerateMnemonicOptions

type GenerateMnemonicOptions

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

GenerateMnemonicOptions options for GenerateMnemonic function

type Language

type Language byte

const (
	English Language = iota
	Japanese
	Korean
	Spanish
	ChineseSimplified
	ChineseTraditional
	French
	Italian
	Czech
	Portuguese
)

func DetectLanguage

func DetectLanguage(mnemonic string, opts ...DetectLanguageOption) (languages []Language, ok bool)

DetectLanguage detect and return the languages of the mnemonic. Default all languages are possible. In some cases, multiple languages might be matched simultaneously, such as Simplified Chinese and Traditional Chinese. If you only want to perform detection within a specified list of languages. use WithLanguages() option.

type Mnemonic

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

Mnemonic

func NewMnemonic

func NewMnemonic(opts ...NewMnemonicOption) (*Mnemonic, error)

NewMnemonic creates a new Mnemonic instance.

The default language is English. If you want to set the language, use WithLanguage() option.

func (*Mnemonic) EntropyFromMnemonic

func (m *Mnemonic) EntropyFromMnemonic(mnemonic string) ([]byte, error)

EntropyFromMnemonic converts a mnemonic to entropy.

func (*Mnemonic) EntropyToMnemonic

func (m *Mnemonic) EntropyToMnemonic(entropy []byte) (string, error)

EntropyToMnemonic converts entropy to a mnemonic.

The entropy must be in [16, 20, 24, 28, 32] bytes. Corresponding to [128, 160, 192, 224, 256] bits.

func (*Mnemonic) GenerateMnemonic

func (m *Mnemonic) GenerateMnemonic(opts ...GenerateMnemonicOption) (string, error)

GenerateMnemonic generates a new mnemonic.

The default entropy bits is 128. If you want to set the entropy bits, use WithEntropyBits() option. The entropy bits must be in [128, 160, 192, 224, 256]. Corresponding to [16, 20, 24, 28, 32] bytes.

type NewMnemonicOption

type NewMnemonicOption func(*NewMnemonicOptions)

NewMnemonicOption a function that modifies NewMnemonicOptions

type NewMnemonicOptions

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

NewMnemonicOptions options for NewMnemonic function

type NewSeedOption

type NewSeedOption func(*NewSeedOptions)

NewSeedOption a function that modifies NewSeedOptions

type NewSeedOptions

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

NewSeedOptions options for NewSeed function