README

python-bitcoinlib
-----------------

This Python2/3 library provides an easy interface to the bitcoin data
structures and protocol. The approach is low-level and "ground up", with a
focus on providing tools to manipulate the internals of how Bitcoin works.


Structure
---------

Everything consensus critical is found in the modules under bitcoin.core. This
rule is followed pretty strictly, for instance chain parameters are split into
consensus critical and non-consensus-critical.

bitcoin.core            - Basic core definitions, datastructures, and
                          (context-independent) validation
bitcoin.core.bignum     - Bignum handling
bitcoin.core.key        - ECC pubkeys
bitcoin.core.script     - Scripts and opcodes
bitcoin.core.scripteval - Script evaluation/verification
bitcoin.core.serialize  - Serialization

In the future the bitcoin.core may use the Satoshi sourcecode directly as a
libary. Non-consensus critical modules include the following:

bitcoin            - Chain selection
bitcoin.base58     - Base58 encoding
bitcoin.bloom      - Bloom filters (incomplete)
bitcoin.net        - Network communication (broken currently)
bitcoin.messages   - Network messages (broken currently)
bitcoin.rpc        - Bitcoin Core RPC interface support
bitcoin.wallet     - Wallet code, currently just CBitcoinAddress

Effort has been made to follow the Satoshi source relatively closely, for
instance Python code and classes that duplicate the functionality of
corresponding Satoshi C++ code uses the same naming conventions: CTransaction,
CBlockHeader, nValue etc. Otherwise Python naming conventions are followed.


Example Code
------------

See examples/ directory.


Selecting the chain to use
--------------------------

Do the following:

    import bitcoin
    bitcoin.SelectChain(NAME)

Where NAME is one of 'testnet', 'mainnet', or 'regtest'. The chain currently
selected is a global variable that changes behavior everywhere, just like in
the Satoshi codebase.


Unit tests
----------

Under bitcoin/tests using test data from Bitcoin Core. To run them:

python -m unittest discover
python3 -m unittest discover