A Python library for 'bitcoin cryptography'

Project
Package
Supported platforms
Formatting standards
Coding standards
Type checking
Documentation
CI/CD
Conversations

Browse GitHub Code Repository

btclib is a Python3 type annotated library intended for teaching, learning, and using bitcoin; the focus is on elliptic curve cryptography and bitcoin's blockchain.

The test suite covers virtually the whole code base — a coverage floor the build enforces — and reproduces the published vectors of the BIPs, of RFC 6979, and of Bitcoin Core.

Originally developed for the Bitcoin and Blockchain Technology course at the University of Milano-Bicocca, btclib is not intended for production environments: it is often refactored for improved clarity, without care for backward compatibility; moreover, some of its algorithms could be broken using side-channel attacks.

The library is not limited to the bitcoin elliptic curve secp256k1; for that curve, though, it always relies on btclib_libsecp256k1, FFI bindings to libsecp256k1 (the optimized C library used by Bitcoin Core): they are a required dependency, not an optional accelerator, so installing btclib needs either one of their wheels or a C toolchain to build them. The Python implementation is what every other curve uses, and the test suite validates it against the bindings: it is libsecp256k1 that says what the right answer is, being the implementation bitcoin consensus itself relies on.

Included features are:

• modulo algebra functions (gcd, inverse, legendre symbol, square root)
• octets / integer / point / var_int / var_bytes helper functions
• elliptic curve class
  • fast algebra implemented using Jacobian coordinates
  • double scalar multiplication (Straus's algorithm, also known as Shamir's trick)
  • multi scalar multiplication (Bos-coster's algorithm)
  • point symmetry solution: odd/even, low/high, and quadratic residue
  • elliptic curves: SEC 1 v1 and v2, NIST, Brainpool, and low cardinality test curves
• ECDSA signature with (transaction) DER encoding
• ECDSA signature with (message) compact encoding: standard p2pkh and BIP137/Electrum extensions to p2wpkh and p2wpkh-p2sh
• RFC 6979 for deterministic signature schemes
• EC Schnorr signature (according to BIP340 bitcoin standardization)
  • batch validation
  • threshold signature (see test-suite)
  • MuSig2 multi-signature: key aggregation with plain and x-only tweaking, nonce aggregation, partial signatures and their aggregation, one primitive per round of the protocol
• Borromean ring signature
• Sign-to-contract commitment
• Diffie-Hellman
• Pedersen commitment
• Base58 encoding/decoding
• p2pkh/p2sh addresses and WIFs
• Bech32 encoding/decoding
• p2wpkh/p2wsh native segwit addresses and their legacy p2sh-wrapped versions
• BIP32 hierarchical deterministic key chains
• SLIP132 key versions (xprv, yprv, zprv, Yprv, Zprv, tprv, uprv, vprv, and Uprv) with corresponding mapping to p2pkh/p2sh, p2wpkh-p2sh, p2wpkh, p2wsh-p2sh, p2wsh and p2tr addresses
• BIP44 address from an extended key and a m/purpose'/coin_type'/account'/change/address_index path, the purpose selecting the encoding: 44 p2pkh, 49 p2wpkh-p2sh, 84 p2wpkh (BIP84), 86 p2tr (BIP86)
• BIP39 mnemonic for generating deterministic keys, in the twelve wordlists of the reference implementation, with the language read off the words
• Electrum standard for mnemonic, in the five wordlists Electrum reads
• SLIP39 Shamir backup: a master secret split into mnemonic shares, of which a threshold number recovers it
• Script encoding/decoding
• nulldata, p2pk, p2ms, p2pkh, p2sh, p2wpkh, p2wsh and p2tr ScriptPubKeys
• BlockHeader and Block data classes
• OutPoint, TxIn, TxOut, and TX data classes
• legacy, segwit_v0 and taproot transaction hash signatures
• BIP174 partially signed bitcoin transactions (PSBT): PsbtIn, PsbtOut, and Psbt data classes
• BIP370 PSBT version 2, where the unsigned transaction is computed from the fields rather than carried as one: the lock time its inputs require, the identifier that ignores their sequences, the modifiable flags a Constructor must obey, and conversion either way
• fee rates carrying their unit (sat/kvB and sat/vB), the fee a virtual size owes at one, and the dust threshold of any output type — computed the way Bitcoin Core computes it, rather than tabulated
• keystore: the addresses an extended key or a set of individual keys has handed out, the derivation path of each, and the private key that signs for one — which is what sign(address, msg) needs and what a message signature by address had no way to find
• a chain backend behind one interface — a transaction by id, the output an outpoint names, the chain tip — over a full node's JSON-RPC or a block explorer's HTTP api, written on the standard library so that it adds no dependency

Module layout

Three pairs of modules are one idea split in two, and each split runs one way only. Knowing which half is which is most of finding your way around:

The right column imports the left one; the left never imports the right.

So from btclib.ecc import dsa for a signature and from btclib.curves import mult for a point multiplication; btclib.b58 for an address and btclib.base58 only if you want the encoding on its own. It is the split the standard library draws between base64 and whatever uses it. Each of the six modules repeats the rule in its own docstring.

The rest, roughly bottom-up: to_prv_key and to_pub_key accept any key representation and hand back one; bip32 and mnemonic derive keys; script, tx, block and psbt build and validate what goes on the chain. bip21 parses and builds bitcoin: payment URIs, and sits on top of everything: it imports b58, b32, amount and network, and nothing in the library imports it. bip44 is up there as well, and for the same reason: an address from an extended key and a derivation path is bip32 and script.taproot and both address encodings composed, so it imports all four and nothing imports it. keystore is one level above even that: it remembers which addresses bip44 has handed out and signs for one with ecc.bms, so it imports bip44 and nothing imports it. fetch sits up there too, and is the one package that goes out to the network: nothing below it imports it.

The Bitcoin Core rpc client fetch speaks through is not in that stack at all: it is bitcoin-core-rpc, a package of its own that btclib depends on. One file with nothing but the standard library behind it, installable or copyable, and usable without btclib by anyone who wants a node client and no bitcoin library. What btclib adds on top is btclib.fetch: the answers turned into Tx and TxOut, and the chain the node reports checked against the network those are labelled for.

The dependency stops at btclib/fetch/. The exceptions a Fetcher raises are btclib.exceptions' own — the package declares its own FetchError, importing nothing of btclib's being what lets its one file be vendored, and btclib.fetch.fetcher.client_errors re-raises them as btclib's with the status and the code carried across. So an except FetchError written against btclib catches what a fetcher raises, and no module outside that package loads urllib.request to find out. Nothing connects to anything either: constructing a client opens no socket, and the first call is what does.

To install (and/or upgrade) btclib:

python -m pip install --upgrade btclib

You might want to install btclib into a Python virtual environment; e.g. from the root folder:

Shell:

python -m venv venv_btclib
source ./venv_btclib/bin/activate
python -m pip install --upgrade btclib

Windows CMD or PowerShell:

python -m venv venv_btclib
.\venv_btclib\Scripts\activate
python -m pip install --upgrade btclib

Windows Git bash shell:

python -m venv venv_btclib
cd ./venv_btclib/Scripts
. activate
cd ../..
python -m pip install --upgrade btclib

See CONTRIBUTING if you are interested in btclib development.

See SECURITY if you have found a security vulnerability.