btclib-org / btclib

btclib: a python3 library for 'bitcoin cryptography'

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.

It is rigorously and extensively tested: the test suite covers 100% of the code base and reproduces results from both informal and major reference sources.

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 bitcon elliptic curve secp256k1; anyway, FFI bindings to libsecp256k1 (the optimized C library used by Bitcoin Core) are available for this curve and used by default.

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 simmetry 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)
  • MuSig multi-signature (see test-suite)
• Borromean ring signature
• Sign-to-contract commitment
• Diffie-Hellman
• Pedersen committment
• 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
• BIP39 wordlists and mnemonic for generating deterministic keys
• Electrum standard for mnemonic
• 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, PbstOut, and Psbt data classes

---

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

See SECURITY if you have found a security vulnerability.

btclib's Issues

Error that no btclib module

Hello,
Your code looks useful. However, I've installed the btclib under the python 3.6.5 and all went well with installation but when I try to run some of the files I get errors that there is no btclib module.

Re-import Tx subclasses into btclib.tx

It should be possible to write:

from btclib.tx import Tx, TxIn, TxOut

instead of manually importing each from btclib.tx.tx_whatever.

remove warning from release process

see RELEASE.md

/Users/ferdi/.pyenv/versions/btclib_3.11.1/lib/python3.11/site-packages/setuptools/command/build_py.py:202: SetuptoolsDeprecationWarning:     Installing 'btclib.mnemonic._data' as data is deprecated, please list it in `packages`.
    !!


    ############################
    # Package would be ignored #
    ############################
    Python recognizes 'btclib.mnemonic._data' as an importable package,
    but it is not listed in the `packages` configuration of setuptools.

    'btclib.mnemonic._data' has been automatically added to the distribution only
    because it may contain data files, but this behavior is likely to change
    in future versions of setuptools (and therefore is considered deprecated).

    Please make sure that 'btclib.mnemonic._data' is included as a package by using
    the `packages` configuration field or the proper discovery methods
    (for example by using `find_namespace_packages(...)`/`find_namespace:`
    instead of `find_packages(...)`/`find:`).

    You can read more about "package discovery" and "data files" on setuptools
    documentation page.


!!

  check.warn(importable)
copying btclib/py.typed -> build/lib/btclib
creating build/lib/btclib/_data
copying btclib/_data/mainnet.json -> build/lib/btclib/_data
copying btclib/_data/regtest.json -> build/lib/btclib/_data
copying btclib/_data/testnet.json -> build/lib/btclib/_data
creating build/lib/btclib/mnemonic/_data
copying btclib/mnemonic/_data/english.txt -> build/lib/btclib/mnemonic/_data
copying btclib/mnemonic/_data/italian.txt -> build/lib/btclib/mnemonic/_data
creating build/lib/btclib/ecc/_data
copying btclib/ecc/_data/ec_Brainpool.json -> build/lib/btclib/ecc/_data
copying btclib/ecc/_data/ec_NIST.json -> build/lib/btclib/ecc/_data
copying btclib/ecc/_data/ec_SEC2v1_insecure.json -> build/lib/btclib/ecc/_data
copying btclib/ecc/_data/ec_SEC2v2.json -> build/lib/btclib/ecc/_data
/Users/ferdi/.pyenv/versions/btclib_3.11.1/lib/python3.11/site-packages/setuptools/command/install.py:34: SetuptoolsDeprecationWarning: setup.py install is deprecated. Use build and pip and other standards-based tools.
  warnings.warn(
installing to build/bdist.macosx-13.1-x86_64/wheel
running install

Import Error when try from btclib.tx import Tx

Describe the bug
When I try to import Tx from btclib.tx, Import Error raised.

To Reproduce
Steps to reproduce the behavior:
1.py

from btclib.tx import Tx

In [1]: from btclib.tx import Tx                                                                                                                                          
---------------------------------------------------------------------------
ImportError                               Traceback (most recent call last)
<ipython-input-1-28f1196e232b> in <module>
----> 1 from btclib.tx import Tx

~/.local/lib/python3.8/site-packages/btclib/tx/__init__.py in <module>
     12 
     13 from btclib.tx.out_point import OutPoint
---> 14 from btclib.tx.tx import Tx, join_txs
     15 from btclib.tx.tx_in import TxIn
     16 from btclib.tx.tx_out import TxOut

~/.local/lib/python3.8/site-packages/btclib/tx/tx.py in <module>
     37 from btclib.exceptions import BTClibValueError
     38 from btclib.hashes import hash256
---> 39 from btclib.script import Witness
     40 from btclib.tx.tx_in import TX_IN_COMPARES_WITNESS, TxIn
     41 from btclib.tx.tx_out import TxOut

~/.local/lib/python3.8/site-packages/btclib/script/__init__.py in <module>
     12 
     13 from btclib.script.script import Command, Script, op_int, parse, serialize
---> 14 from btclib.script.script_pub_key import (
     15     ScriptPubKey,
     16     address,

~/.local/lib/python3.8/site-packages/btclib/script/script_pub_key.py in <module>
     15 from typing import Callable, Sequence
     16 
---> 17 from btclib import b32, b58, var_bytes
     18 from btclib.alias import Octets, String
     19 from btclib.ec import point_from_octets

~/.local/lib/python3.8/site-packages/btclib/b32.py in <module>
     52 from btclib.hashes import hash160, sha256
     53 from btclib.network import NETWORKS, network_from_key_value
---> 54 from btclib.script import TaprootScriptTree, output_pubkey
     55 from btclib.to_pub_key import Key, pub_keyinfo_from_key
     56 from btclib.utils import bytes_from_octets

ImportError: cannot import name 'TaprootScriptTree' from partially initialized module 'btclib.script' (most likely due to a circular import) (/home/wanlin_wang_cobo_com/.local/lib/python3.8/site-packages/btclib/script/__init__.py)

Expected behavior
Successfully imported.

Screenshots
N/A

Environment (please complete the following information):

• OS: Ubuntu 20.04 LTS
• Python version 3.8.10
• btclib version latest(2023.2.3)

Additional context
I've tried 2023.1.17 version, still have this problem. I'm curious nobody else occur this problem?

Valid taproot signature may not must has length of 64

Describe the bug
It seems not right to check signature of taproot is valid by assert length of it equals 64:

btclib/btclib/psbt/psbt_utils.py

Line 307 in da0cfc1

if any(signature and len(signature) != 64 for signature in signatures):

To Reproduce
There is an example on how to make a valid taproot signature which length is not 64:
bitcoinjs/bitcoinjs-lib#1934

Environment (please complete the following information):

• OS: ubuntu
• Python version: 3.10.13
• btclib version: da0cfc1 master 2023.12.12

For beginners, more specific documentation can be created.

I hope to create a detailed example document to help beginners learn BTC better.
For example, sending transactions, deriving wallets, etc.

Help wanted: Creating a list of derived addresses from a xPub string

Hey,

I'm just starting out with Python, so I'm not sure how to accomplish this:

For example, I would have string key = 'zpub6rLtzSoXnXKPXHroRKGCwuRVHjgA5YL6oUkdZnCfbDLdtAKNXb1FX1EmPUYR1uYMRBpngvkdJwxqhLvM46trRy5MRb7oYdSLbb4w5VC4i3z'

How would I make the btclib package return a list like this?

0: bc1qvqatyv2xynyanrej2fcutj6w5yugy0gc9jx2nn
1: bc1q360p67y3jvards9f2eud5rlu07q8ampfp35vp7
2: bc1qs4k3p9w4ke5np3lr3lgnma9jcaxedau8mpwawu
3: bc1qpk48z0s7gvyrupm2wmd7nr0fdzkxa42372ver2

Any help would be appreciated. Thanks! :-)

How could we restore the private key from extended private key in bip32.py

There is a function address_from_xpub to generate the address from xpub.
Could we have a key_from_xprv to generate the private key from xprv in bip32.py as well?

b58 package missing

Hello, I installed the package via pip but when I want to use the b58 module like
from btclib import b58
I got the following error:
ImportError: cannot import name 'b58' from 'btclib' (/usr/local/lib/python3.9/site-packages/btclib/__init__.py)

Checking the packages shows that indeed it is not present

Any ideas what is wrong or how can I get that module installed?