btclib-mnemonics

The mnemonic schemes of bitcoin wallets -- BIP39, SLIP-0039 and Electrum's -- from the entropy to the seed, in typed Python.

It is fully annotated and ships py.typed, and it imports nothing but the standard library.

What is here

• BIP39 mnemonics, in every language of the reference implementation's word lists: from entropy to sentence and back, the language read off the words, and the seed a sentence and a passphrase stretch to (bip39)
• SLIP-0039 Shamir backups: a master secret split into groups of shares and put back together, the passphrase encryption and the extendable backup flag included (slip39)
• Electrum's own mnemonics: the versioned ones, generated and read the way Electrum generates and reads them, their seed, and the pre-2.0 scheme with its hex seed and master private key (electrum)
• which of those schemes a sentence belongs to, where more than one claims it (dispatch)
• the entropy the schemes are generated from, drawn from the operating system's CSPRNG or from dice rolls (entropy)
• the word lists and the normalization every scheme reads a sentence through (mnemonic)

What a seed derives to -- a BIP32 key, an address, a wallet -- is not here: btclib-wallet is the library above this one.

The suite answers to vectors their authors publish -- the reference implementations' own and Electrum's -- and tests/_data/README.md pins each vendored file to the upstream commit it was copied from.

Installing

python -m pip install --upgrade btclib-mnemonics

A seed from a mnemonic, and a secret split into shares

from btclib_mnemonics import bip39, dispatch, slip39

words = bip39.mnemonic_from_entropy(bytes(16))
assert words == "abandon " * 11 + "about"
seed = bip39.seed_from_mnemonic(words, "TREZOR")
assert seed.hex().startswith("c55257c360c07c72")
assert dispatch.seed_type_from_mnemonic(words) == "bip39"

# SLIP-0039's master secret is itself the seed a wallet derives from, so
# it is a secret of its own here: a 2-of-3 split, and two shares back
master_secret = bytes(range(16))
(shares,) = slip39.mnemonics_from_master_secret(master_secret, [(2, 3)])
assert slip39.master_secret_from_mnemonics(shares[1:]) == master_secret

tests/readme_test.py runs every Python block of this file, so the example above is the one the suite checks.

Security

SECURITY.md says how to report a vulnerability, which versions are supported, and how a published file is traced back to the run that built it. ASSURANCE_CASE.md argues why what it promises holds: the threat model, the trust boundaries, and the weaknesses a package of this kind is exposed to.

Contributing

CONTRIBUTING.md has the commands each CI job runs, verbatim. uv sync creates the environment; uv is the only tool that has to be installed. REVIEWING.md is what a pull request is answered against.

How the organization decides, and who holds which role, is its GOVERNANCE.md; what it intends to do, and what it deliberately does not, is its ROADMAP.md.

Links

• Documentation: https://btclib-mnemonics.readthedocs.io/
• Source: https://github.com/btclib-org/btclib-mnemonics
• Releases: https://github.com/btclib-org/btclib-mnemonics/releases
• CHANGELOG.md, and RELEASE_NOTES.md for what a release asks a user to act on

The btclib organization and its projects are actively supported by DGI and CheckSig.