btclib-wallet¶

From a seed to a signed, broadcast bitcoin transaction, on top of the btclib library.

btclib is the protocol: the encodings other than Base58Check and bech32, the scripts, the transactions and the signature schemes, what a node consumes. This package is what a wallet does with them, and every module with a counterparty outside the process — a device, a node, a server, a file from another wallet. It depends on btclib and on bitcoin-core-rpc, and re-exports nothing of btclib’s: a name btclib defines is imported from btclib.

It is fully annotated and ships py.typed, and the test suite answers to vectors their authors publish: the BIPs’ and the SLIPs’ own, HWI’s, and trezor’s for BIP39 and SLIP39. tests/_data/README.md pins each vendored file to the upstream commit it was copied from, and says whether the two still match.

Installing¶

python -m pip install --upgrade btclib-wallet

Signing and verifying run where ecc runs them, so its libsecp256k1 bindings are the recommended install beside it, and ecc’s SECURITY.md says what happens without them.

A ledger’s encryption at rest, Ledger.encrypt, needs the cryptography package, which an install on Windows arm64 leaves out: its release in uv.lock has no wheel there. Without it a ledger works unencrypted, and refuses to encrypt and to load an encrypted file. The encryption extra asks for it on every platform, built from source where there is no wheel, which needs OpenSSL:

python -m pip install --upgrade "btclib-wallet[encryption]"

An address from a mnemonic¶

from btclib_wallet import bip44
from btclib_wallet.mnemonic import bip39

words = "abandon " * 11 + "about"
xprv = bip39.mxprv_from_mnemonic(words)
assert (
    bip44.address_from_der_path(xprv, "m/84h/0h/0h/0/0")
    == "bc1qcr8te4kr609gcawutmrza0j4xv80jy8z306fyu"
)

The address is the first one BIP84 lists for that mnemonic.

What is here¶

BIP32 hierarchical deterministic key chains, and SLIP132 key versions with their mapping to address types
BIP39, Electrum and SLIP39 master keys from a mnemonic, whose scheme up to the seed is bip39-slip39’
BIP44 addresses from an extended key and a m/purpose'/coin_type'/account'/change/address_index path
BIP85 deterministic entropy, one root key behind many wallets
BIP38 password-protected private keys, and Casascius minikeys
BIP380 output descriptors and BIP379 miniscript
BIP174 and BIP370 partially signed transactions, with the taproot, MuSig2, FROST and silent payment fields
BIP352 silent payments
BIP322 signed messages
BIP21 payment URIs, and the BOLT11 invoices and BOLT9 feature bits they carry
dlcspecs discreet log contracts: the funding, execution and refund transactions, the CETs’ adaptor signatures, and an oracle’s announcements and attestations
coin selection and a transaction builder
wallets: an extended key at a BIP44 account, a set of individual keys, an output descriptor per chain, a script template
an external signer behind one contract, with Bitcoin Core’s HWI behind it for a hardware wallet, and the requests that import a wallet into Bitcoin Core
a chain backend behind one interface, over a full node’s JSON-RPC or a block explorer’s or an Electrum server’s API, or a peer’s BIP157 compact filters over p2p

Architecture¶

ARCHITECTURE.md is the design: which module holds what, the dependencies and why each, and every place a module crosses out of the process it runs in. ASSURANCE_CASE.md is why the security section below holds.

Security¶

A mnemonic, an extended private key and a PSBT being signed are secrets, and where they are handled is this package. SECURITY.md says what that promises, where constant time ends, and how to report a vulnerability.

Contributing¶

Development is LLM-based: humans are welcome, as long as they are comfortable with agentic development ;-). A contribution must have been read and understood by the person who submits it. CONTRIBUTING.md has the rules.

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.