bip39

README

go-bip39

A golang implementation of the BIP39 spec for mnemonic seeds.

⚠️ Important Notice

This is a modernized fork of the original go-bip39 library by tyler-smith, which has been removed from GitHub.

Changes from the original

• Fixed typos in error messages
• Updated dependencies

Installation

go get github.com/X-Vlad/go-bip39

Migration from tyler-smith/go-bip39

Add this to your go.mod:

replace github.com/tyler-smith/go-bip39 => github.com/X-Vlad/go-bip39 v1.0.0

Usage

package main

import (
    "fmt"
    
    "github.com/X-Vlad/go-bip39"
    "github.com/X-Vlad/go-bip32"
)

func main() {
    // Generate a mnemonic for memorization or user-friendly seeds
    entropy, _ := bip39.NewEntropy(256)
    mnemonic, _ := bip39.NewMnemonic(entropy)

    // Generate a Bip32 HD wallet for the mnemonic and a user supplied password
    seed := bip39.NewSeed(mnemonic, "Secret Passphrase")

    masterKey, _ := bip32.NewMasterKey(seed)
    publicKey := masterKey.PublicKey()

    // Display mnemonic and keys
    fmt.Println("Mnemonic: ", mnemonic)
    fmt.Println("Master private key: ", masterKey)
    fmt.Println("Master public key: ", publicKey)
}

API Reference

Functions

• NewEntropy(bitSize int) ([]byte, error) - Generate random entropy (bitSize must be 128-256, multiple of 32)
• NewMnemonic(entropy []byte) (string, error) - Generate mnemonic words from entropy
• NewSeed(mnemonic string, password string) []byte - Generate seed from mnemonic and password
• NewSeedWithErrorChecking(mnemonic string, password string) ([]byte, error) - Same as NewSeed but validates mnemonic first
• IsMnemonicValid(mnemonic string) bool - Check if mnemonic is valid
• EntropyFromMnemonic(mnemonic string) ([]byte, error) - Extract entropy from mnemonic
• MnemonicToByteArray(mnemonic string, raw ...bool) ([]byte, error) - Convert mnemonic to byte array

Word Lists

• SetWordList(list []string) - Set custom word list
• GetWordList() []string - Get current word list
• GetWordIndex(word string) (int, bool) - Get word index in current word list

Supported Languages

The library includes word lists for multiple languages in the wordlists package:

• English (default)
• Japanese
• Korean
• Spanish
• Chinese (Simplified & Traditional)
• French
• Italian
• Czech

Testing

go test -v ./...

License

MIT License - see LICENSE for details.

Credits

Based on the original go-bip39 by tyler-smith.

Wordlists are from the BIP39 spec.

Test vectors are from the Trezor python-mnemonic implementation.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Donate

If this project was helpful, you can support development:

Network	Address
BTC	bc1q3l4jcnplvcmvqh26pfh3qdkrw4flqevemsfed8
ETH, BSC, ... (EVM)	0x49999CD2B8F7Bc9309e5929a79799eA55a17e6Ce
Tron	TDxyjiittx9zzkHd25wmM12mvutTKBhZKS
Solana	ahiiQWz9eRLpFRpEFSPf7See7J46YBFhMgsADNmGRgt
TON	UQCfsCHBWq3_kD0D_mkfetuwIgACoSJ8YsYTZPKKkMprDlLD

Documentation

Overview

Package bip39 is the Golang implementation of the BIP39 spec.

The official BIP39 spec can be found at https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki

Index

• Variables
• func EntropyFromMnemonic(mnemonic string) ([]byte, error)
• func GetWordIndex(word string) (int, bool)
• func GetWordList() []string
• func IsMnemonicValid(mnemonic string) bool
• func MnemonicToByteArray(mnemonic string, raw ...bool) ([]byte, error)
• func NewEntropy(bitSize int) ([]byte, error)
• func NewMnemonic(entropy []byte) (string, error)
• func NewSeed(mnemonic string, password string) []byte
• func NewSeedWithErrorChecking(mnemonic string, password string) ([]byte, error)
• func SetWordList(list []string)

Examples

• NewMnemonic
• NewSeed

Variables

var (
	// ErrInvalidMnemonic is returned when trying to use a malformed mnemonic.
	ErrInvalidMnemonic = errors.New("invalid mnemonic")

	// ErrEntropyLengthInvalid is returned when trying to use an entropy set with
	// an invalid size.
	ErrEntropyLengthInvalid = errors.New("entropy length must be [128, 256] and a multiple of 32")

	// ErrValidatedSeedLengthMismatch is returned when a validated seed is not the
	// same size as the given seed. This should never happen is present only as a
	// sanity assertion.
	ErrValidatedSeedLengthMismatch = errors.New("seed length does not match validated seed length")

	// ErrChecksumIncorrect is returned when entropy has the incorrect checksum.
	ErrChecksumIncorrect = errors.New("checksum incorrect")
)

Functions

func EntropyFromMnemonic

func EntropyFromMnemonic(mnemonic string) ([]byte, error)

EntropyFromMnemonic takes a mnemonic generated by this library, and returns the input entropy used to generate the given mnemonic. An error is returned if the given mnemonic is invalid.

func GetWordIndex

func GetWordIndex(word string) (int, bool)

GetWordIndex gets word index in wordMap.

func GetWordList

func GetWordList() []string

GetWordList gets the list of words to use for mnemonics.

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 MnemonicToByteArray

func MnemonicToByteArray(mnemonic string, raw ...bool) ([]byte, error)

MnemonicToByteArray takes a mnemonic string and turns it into a byte array suitable for creating another mnemonic. An error is returned if the mnemonic is invalid.

func NewEntropy

func NewEntropy(bitSize int) ([]byte, error)

NewEntropy will create random entropy bytes so long as the requested size bitSize is an appropriate size.

bitSize has to be a multiple 32 and be within the inclusive range of {128, 256}

func NewMnemonic

func NewMnemonic(entropy []byte) (string, error)

NewMnemonic will return a string consisting of the mnemonic words for the given entropy. If the provide entropy is invalid, an error will be returned.

Example

// the entropy can be any byte slice, generated how pleased,
// as long its bit size is a multiple of 32 and is within
// the inclusive range of {128,256}
entropy, _ := hex.DecodeString("066dca1a2bb7e8a1db2832148ce9933eea0f3ac9548d793112d9a95c9407efad")

// generate a mnemonic
mnemonic, _ := bip39.NewMnemonic(entropy)
fmt.Println(mnemonic)

Output:
all hour make first leader extend hole alien behind guard gospel lava path output census museum junior mass reopen famous sing advance salt reform

func NewSeed

func NewSeed(mnemonic string, password string) []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.

Example

seed := bip39.NewSeed("all hour make first leader extend hole alien behind guard gospel lava path output census museum junior mass reopen famous sing advance salt reform", "TREZOR")
fmt.Println(hex.EncodeToString(seed))

Output:
26e975ec644423f4a4c4f4215ef09b4bd7ef924e85d1d17c4cf3f136c2863cf6df0a475045652c57eb5fb41513ca2a2d67722b77e954b4b3fc11f7590449191d

func NewSeedWithErrorChecking

func NewSeedWithErrorChecking(mnemonic string, password string) ([]byte, error)

NewSeedWithErrorChecking creates a hashed seed output given the mnemonic string and a password. An error is returned if the mnemonic is not convertible to a byte array.

func SetWordList

func SetWordList(list []string)

SetWordList sets the list of words to use for mnemonics. Currently the list that is set is used package-wide.