mnemonic

Documentation

Overview

Package mnemonic encodes a 32-byte seed as a 24-word BIP-39 recovery phrase and decodes it back. It is used to back up and restore a Freizone identity root key: the seed is the Ed25519 root private key's seed (ed25519.PrivateKey.Seed()), and account_id == hash(root_pubkey), so restoring the seed restores the exact same account (see pkg/address).

Only BIP-39's entropy<->words mapping is used, not its PBKDF2 seed derivation: the 32-byte value *is* the entropy. That keeps the phrase interoperable with standard BIP-39 word tooling (offline validation, autocomplete) while encoding exactly the bytes needed to rebuild the key.

For 256-bit entropy the checksum is 8 bits, giving 264 bits == 24 words of 11 bits each.

Index

• Constants
• Variables
• func Decode(words []string) ([]byte, error)
• func DecodeString(phrase string) ([]byte, error)
• func Encode(seed []byte) ([]string, error)
• func EncodeString(seed []byte) (string, error)
• func ValidWord(w string) bool
• func Wordlist() []string

Constants

const (
	// SeedSize is the entropy length this package encodes: 256 bits.
	SeedSize = 32
	// WordCount is the resulting phrase length: (256 + 8 checksum) / 11.
	WordCount = 24
	// WordlistSize is the number of words in the BIP-39 English list.
	WordlistSize = 2048
)

Variables

var (
	// ErrSeedSize is returned by Encode for a seed that is not SeedSize bytes.
	ErrSeedSize = fmt.Errorf("mnemonic: seed must be %d bytes", SeedSize)
	// ErrWordCount is returned by Decode for a phrase that is not WordCount words.
	ErrWordCount = fmt.Errorf("mnemonic: phrase must be %d words", WordCount)
	// ErrUnknownWord is returned by Decode when a word is not in the list.
	ErrUnknownWord = errors.New("mnemonic: unknown word")
	// ErrChecksum is returned by Decode when the phrase's checksum does not match.
	ErrChecksum = errors.New("mnemonic: invalid checksum")
)

Functions

func Decode

func Decode(words []string) ([]byte, error)

Decode validates a 24-word phrase and returns the 32-byte seed it encodes. Words are matched case-insensitively and trimmed of surrounding whitespace.

func DecodeString

func DecodeString(phrase string) ([]byte, error)

DecodeString splits a phrase on whitespace and decodes it (see Decode).

func Encode

func Encode(seed []byte) ([]string, error)

Encode turns a 32-byte seed into a 24-word BIP-39 phrase.

func EncodeString

func EncodeString(seed []byte) (string, error)

EncodeString is Encode with the words joined by single spaces.

func ValidWord

func ValidWord(w string) bool

ValidWord reports whether w is in the wordlist (case-insensitive).

func Wordlist

func Wordlist() []string

Wordlist returns a copy of the 2048-word BIP-39 English list, for a client to drive word autocomplete/validation locally.