bip39

Documentation

Overview

Package bip39 validates and decodes a BIP-39 mnemonic — the 12/15/18/21/24-word "seed phrase" used by virtually every cryptocurrency wallet (Bitcoin, Ethereum, hardware wallets) — into its entropy, checksum validity, word indices, and the derived BIP-39 seed. A captured seed phrase is prime forensic / IR / pentest loot: it is the root secret from which every wallet key descends, so validating one (real mnemonic vs. typo / wrong order / non-wordlist word) and deriving its seed is a high-value offline step. Pure offline transform; no network or device.

Wrap-vs-native judgement

Native. BIP-39 is a public specification: 11-bit word indices over the embedded 2048-word list, a SHA-256 checksum over the entropy, and a PBKDF2-HMAC-SHA512 seed derivation — all stdlib crypto + the in-tree internal/wpa.PBKDF2 (no new runtime dependency; x/text's NFKD normaliser was already an indirect module dependency). Nothing is wrapped or shelled out.

What this covers / defers

• English wordlist only (the default and overwhelmingly most common; the embedded english.txt is the official BIP-39 list, SHA-256 2f5eed53a4727b4bf8880d8f3f199efc90e58503646d9ff8eff3a2ed3b24dbda). Other language lists are deferred — a phrase is rejected as "not in the wordlist" rather than guessed against a list we did not validate.
• Validation (word count, every word in the list, SHA-256 checksum) and seed derivation. BIP-32 master-key / address derivation from the seed is a separate, larger surface left to the caller.

Verifiable / no confidently-wrong output

Anchored to the official Trezor BIP-39 test vectors (e.g. the all-"abandon … about" mnemonic → entropy 00000000000000000000000000000000, and with passphrase "TREZOR" → seed c55257c3…7463b04). A phrase whose checksum does not validate is reported as such (likely a typo / wrong order) rather than asserted as a genuine mnemonic; the seed is still derived from the words as given (BIP-39 derives a seed from any phrase) but clearly flagged. A non-wordlist word or an invalid word count is rejected.

Index

• func WordCount() int
• type Result
  • func Decode(mnemonic, passphrase string) (*Result, error)

Functions

func WordCount

func WordCount() int

WordCount returns the number of words in the embedded list (2048). Exposed for the package's own invariant test.

Types

type Result

type Result struct {
	// WordCount is the mnemonic length (12/15/18/21/24).
	WordCount int `json:"word_count"`
	// EntropyBits is the entropy strength (128/160/192/224/256).
	EntropyBits int `json:"entropy_bits"`
	// EntropyHex is the recovered entropy, lowercase hex.
	EntropyHex string `json:"entropy_hex"`
	// ChecksumValid is true when the trailing checksum bits match SHA-256 of the
	// entropy — i.e. this is a genuine BIP-39 mnemonic, not a typo'd phrase.
	ChecksumValid bool `json:"checksum_valid"`
	// Indices is the 11-bit list index of each word, in order.
	Indices []int `json:"indices"`
	// SeedHex is the 64-byte BIP-39 seed: PBKDF2-HMAC-SHA512(mnemonic,
	// "mnemonic"+passphrase, 2048). Derived from the words as given regardless of
	// checksum validity (per BIP-39).
	SeedHex string `json:"seed_hex"`
	// Note flags a non-validating checksum.
	Note string `json:"note,omitempty"`
}

Result is the decoded view of a BIP-39 mnemonic.

func Decode

func Decode(mnemonic, passphrase string) (*Result, error)

Decode validates the mnemonic against the embedded English wordlist, recovers its entropy, checks the SHA-256 checksum, and derives the BIP-39 seed (with the optional passphrase). A bad word count or a non-wordlist word is an error; a non-validating checksum is reported (not an error) so the operator still gets the entropy and seed of a near-miss phrase.