BIP32 hierarchical deterministic keys, output script descriptors and miniscript, in typed Python.
It is fully annotated and ships py.typed. It is built on
btclib, the protocol package, and
ecc, the curve package; its
secp256k1 extra adds the libsecp256k1 bindings, and without them the
Python arithmetic answers instead.
- BIP32
hierarchical deterministic keys: extended key serialization, private and
public derivation, derivation paths and key origins (
bip32) - BIP380
output script descriptors, from
pk()totr()with its script tree,musig()key expressions, and BIP388 wallet policies (descriptors) - BIP379
miniscript: parsing, type checking, the script it compiles to and the
witness that satisfies it (
descriptors.miniscript)
ARCHITECTURE.md says how these modules layer and which may import which.
Every refusal is btclib's BTClibValueError or BTClibTypeError, or
ecc's class of the same kind where an argument reaches that package.
Signing, partially signed transactions and wallets are not here: they are btclib-wallet's.
The suite answers to vectors their authors publish -- the BIPs', Bitcoin Core's and bitcoin-s's -- and tests/_data/README.md pins each vendored file to the upstream commit it was copied from.
python -m pip install --upgrade bip32-descriptorsand, for the libsecp256k1 bindings,
python -m pip install --upgrade "bip32-descriptors[secp256k1]"from bip32_descriptors.bip32 import derive, rootxprv_from_seed, xpub_from_xprv
from bip32_descriptors.descriptors import add_checksum, parse
# BIP32's test vector 1, and its m/0h/1 extended public key
xprv = rootxprv_from_seed("000102030405060708090a0b0c0d0e0f")
xpub = xpub_from_xprv(derive(xprv, "m/0h/1"))
assert xpub.startswith("xpub6ASuArnXKPbfEwhqN6e3mwBcDTgzisQN1wXN9BJcM47s")
# a ranged descriptor with its key origin, checksum included
descriptor = parse(add_checksum(f"wpkh([3442193e/0h/1]{xpub}/0/*)"))
assert descriptor.address(0) == "bc1qw47q2vtlewz7jyx970nvm8wy6p44mqepwqdj27"
# and a miniscript: the key, after 144 blocks
policy = parse(f"wsh(and_v(v:pk({xpub}/0/*),older(144)))")
assert policy.address(0).startswith("bc1q")tests/readme_test.py runs every Python block of this file, so the
example above is the one the suite checks.
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.
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.
- Documentation: https://bip32-descriptors.readthedocs.io/
- Source: https://github.com/btclib-org/bip32-descriptors
- Releases: https://github.com/btclib-org/bip32-descriptors/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.