btclib-wallet

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

PyPI version GitHub release development status license downloads supported Python versions implementation wheel

pre-commit.ci status lint workflow status test workflow status docs workflow status documentation build vendored-vectors workflow status mutation workflow status fuzz workflow status integration-bitcoind workflow status integration-hwi workflow status deps-latest workflow status pypi-install workflow status deps-oldest workflow status os-macos workflow status os-ubuntu workflow status os-windows workflow status links workflow status sdist-rebuild workflow status codeql workflow status

OpenSSF Scorecard OpenSSF Best Practices

btclib is the protocol: the encodings, 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 btclib runs them, so its libsecp256k1 bindings are the recommended install beside it, and btclib’s SECURITY.md says what happens without them.

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 mnemonics, and the seed-to-key functions over them

  • 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

  • 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

Architecture

ARCHITECTURE.md is the design: which module holds what, the one dependency on btclib, 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

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.