bip32-descriptors

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.

What is here

• BIP32 hierarchical deterministic keys: extended key serialization, private and public derivation, derivation paths and key origins (bip32)
• BIP380 output script descriptors, from pk() to tr() 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: btclib-wallet is the library above this one, and its psbt updater reads what a descriptor expanded at an index knows.

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.

Installing

python -m pip install --upgrade bip32-descriptors

and, for the libsecp256k1 bindings,

python -m pip install --upgrade "bip32-descriptors[secp256k1]"

A key, a descriptor, an address

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

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

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.

Links

• 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.