bitcoin-utils 0.8.5

Security model

This library is intentionally pure Python and educational. Private-key operations, including ECDSA signing and Taproot/Schnorr signing, are not side-channel hardened and should not be used to protect real funds in timing-observable environments.

The python-ecdsa dependency has a known Minerva timing-attack advisory (CVE-2024-23342) with no patched pure-Python release. Keeping the library pure Python means this class of side-channel risk cannot be fully eliminated. Use the library for learning, tests, testnet, offline experiments, and transaction construction; use production wallets, hardware signers, or hardened native cryptographic libraries for real funds.

Private-key warnings are enabled by default on mainnet and can be disabled with bitcoinutils.setup.set_security_warnings(False). Testnet, testnet4, signet and regtest do not emit the warning by default, so educational examples stay quiet.

Notes

• For schnorr, bech32[m], ripemd160 the python Bitcoin Core reference implementations are used.

• For Hierarchical Deterministic keys we include minimal native BIP-32/BIP-39 functionality to acquire a PrivateKey object that is used throughtout the library.

Installation

Python version 3.10 and above is required. Then just install with:

$ pip install bitcoin-utils

Examples

Keys and Addresses

Legacy Keys and Addresses

https://github.com/karask/python-bitcoin-utils/blob/master/examples/keys_addresses.py - creates a private key which we use to derive a public key and in turn an address. We also use the private key to sign a message and then verify it using the public key.

Segwit Addresses

https://github.com/karask/python-bitcoin-utils/blob/master/examples/keys_segwit_addresses.py - creates P2WPKH, P2SH-P2WPKH, P2WSH and P2SH-P2WSH addresses.

Hierarchical Deterministic Keys

https://github.com/karask/python-bitcoin-utils/blob/master/examples/hd_keys.py - creates an extended private key, from an xpriv/tpriv and path, which we use to derive a public key and in turn all different address (legacy, segwit v0 and taproot (segwit v1).

Legacy Transactions (P2PKH, P2SH)

Transaction with P2PKH input and outputs

https://github.com/karask/python-bitcoin-utils/blob/master/examples/p2pkh_transaction.py - creates a simple transaction with one input and two outputs.

Create a P2PKH Transaction with different SIGHASHes

https://github.com/karask/python-bitcoin-utils/blob/master/examples/multi_input_sighash_transaction.py - creates a 2-input 2-output transaction with different signature types.

Create a P2SH Address

https://github.com/karask/python-bitcoin-utils/blob/master/examples/send_to_p2sh_transaction.py - creates a P2SH address that corresponds to a P2PK redeem script and sends some funds to it.

Create (spent) a P2SH Transaction

https://github.com/karask/python-bitcoin-utils/blob/master/examples/spend_p2sh_transaction.py - creates a transaction that spends a P2SH output.

Non-standard Transactions

Create a non-standard tx

https://github.com/karask/python-bitcoin-utils/blob/master/examples/create_non_std_tx.py - sends funds to an address with a non-standard tx (script: OP_ADD OP_5 OP_EQUAL)

Spend a non-standard tx

https://github.com/karask/python-bitcoin-utils/blob/master/examples/spend_non_std_tx.py - spends funds from script OP_ADD OP_5 OP_EQUAL

Segwit Transactions

Transaction to pay to a P2WPKH

http://github.com/karask/python-bitcoin-utils/blob/master/examples/send_to_p2wpkh_transaction.py - send coins from two P2PKH UTXOs to a native segwit address (P2WPKH)

Spend from a P2SH(P2WPKH) nested segwit address

http://github.com/karask/python-bitcoin-utils/blob/master/examples/spend_p2sh_p2wpkh_address.py - spend a P2WPKH that is nested into a P2SH for old client compatibility

Transaction to pay to a P2SH(P2WSH(P2PK))

http://github.com/karask/python-bitcoin-utils/blob/master/examples/send_to_p2sh_p2wsh_p2pk_address.py - send coins from a P2PKH UTXO to a P2SH(P2WSH(P2PK))

Spend from a P2SH(P2WPKH) nested segwit address

http://github.com/karask/python-bitcoin-utils/blob/master/examples/spend_from_p2sh_p2wsh_p2pk_address.py - spend a P2WSH with a P2PK as witness script that is nested into a P2SH for old client compatibility

Timelock Transactions

Create a P2SH address with a relative timelock

https://github.com/karask/python-bitcoin-utils/blob/master/examples/create_p2sh_csv_p2pkh_address.py - creates a P2SH address that locks funds (sent to it) with a private key (P2PKH) and a relative locktime of 200 blocks in the future.

Spend from a timelocked address

https://github.com/karask/python-bitcoin-utils/blob/master/examples/spend_p2sh_csv_p2pkh.py - spends from a P2SH(CSV+P2PKH) address as created from above.

Taproot (segwit v1) Transactions

Taproot combines Schnorr signatures, Merkle trees, and a new scripting language to improve Bitcoin’s privacy, efficiency, and smart contract capabilities. The library fully supports Taproot addresses, key path spending, and script path spending with multiple script options.

Taproot Keys and Addresses https://github.com/karask/python-bitcoin-utils/blob/master/examples/keys_taproot_addresses.py - creates a public key, derives its corresponding tweaked taproot public key (x-only) and taproot address.

Spend from a taproot address (key path) https://github.com/karask/python-bitcoin-utils/blob/master/examples/spend_p2tr_default_path.py - spends a taproot UTXO using the key path, which is the most efficient and private approach.

Spend a multi input that contains both taproot and legacy UTXOs https://github.com/karask/python-bitcoin-utils/blob/master/examples/spend_multi_input_p2tr_and_p2pkh.py - three inputs (two taproot and one legacy), single legacy output.

Taproot with Single Script Path

Send to taproot address that contains a single script path spend https://github.com/karask/python-bitcoin-utils/blob/master/examples/send_to_p2tr_with_single_script.py - single input, single output (key path and single script path).

Spend taproot from key path (has single alternative script path spend) https://github.com/karask/python-bitcoin-utils/blob/master/examples/spend_p2tr_single_script_by_key_path.py - single input, single output, spend key path.

Spend taproot from script path (has single alternative script path spend) https://github.com/karask/python-bitcoin-utils/blob/master/examples/spend_p2tr_single_script_by_script_path.py - single input, single output, spend script path.

Taproot with Multiple Script Paths

Send to taproot address that contains two scripts path spends https://github.com/karask/python-bitcoin-utils/blob/master/examples/send_to_p2tr_with_two_scripts.py - single input, single output (key path and two script paths - A and B).

Spend taproot from script path (has two alternative script path spend - A and B) https://github.com/karask/python-bitcoin-utils/blob/master/examples/spend_p2tr_two_scripts_by_script_path.py - single input, single output, spend script path A.

Send to taproot address that contains three scripts path spends https://github.com/karask/python-bitcoin-utils/blob/master/examples/send_to_p2tr_with_three_scripts.py - single input, single output (key path and three script paths - A, B and C).

Spend taproot from script path (has three alternative script path spends - A, B and C) https://github.com/karask/python-bitcoin-utils/blob/master/examples/spend_p2tr_three_scripts_by_script_path.py - single input, single output, spend script path B.

Send to Taproot address that contains four script path spends https://github.com/aaron-recompile/python-bitcoin-utils/blob/taproot-4leaf-example/examples/send_to_p2tr_with_four_scripts.py - builds a Taproot address with four scripts (hashlock, multisig, CSV, siglock).

Spend Taproot from script path (has four alternative script path spends - A, B, C, and D) https://github.com/aaron-recompile/python-bitcoin-utils/blob/taproot-4leaf-example/examples/spend_p2tr_four_scripts_by_script_path.py - spends from any of the 4 script paths using control blocks and full validation.

Partially Signed Bitcoin Transactions (PSBT)

Multisig (2-of-3) example with PSBT to transfer intermediate tx states https://github.com/karask/python-bitcoin-utils/blob/master/examples/psbt/ - folder explains workflow and script usage

Output Descriptors

Fixed-key output descriptors are supported through bitcoinutils.descriptors. The module parses a practical educational subset of Bitcoin Core descriptors, validates/generates descriptor checksums, and converts descriptors to Script and address objects.

Other

Use NodeProxy to make calls to a Bitcoin node

https://github.com/karask/python-bitcoin-utils/blob/master/examples/node_proxy.py - make Bitcoin command-line interface calls programmatically (NodeProxy wraps jsonrpc-requests library)

Please explore the codebase or the API documentation (BitcoinUtilities.pdf) for supported functionality and other options.