Python Bitcoin blockchain analysis tools

Under the python/ subdirectory at the root of the Toolbox distribution you’ll find the … you guessed it … Python implementation of blockchain tools.

So, how do you know which tools are in the Python subdir and which ones are in the C++ tree? Rule of thumb is: if it must use Bitcoin Core, then it’s C++. Otherwise it’s likely written in Python for the sake of portability and to make the tools accessible to more developers (C++ as you probably know has a steep learning curve).

Setup

The Python tools are designed to have as few dependencies as possible.

You’ll need a 3rd party database driver, which for now is MySQL (more DB’s to be supported in the future).

To install Connector/Python on Linux:

$ sudo pip3 install mysql-connector-python

Now you just need to add the python/ subdirectory to the PYTHONPATH and CRYPTOBI_HOME environment variables.

On Linux:

$ export CRYPTOBI_HOME=/your/path/to/cryptobi_toolbox
$ export PYTHONPATH=$PYTHONPATH:$CRYPTOBI_HOME/python

Substitute the above path to where you downloaded Crypto.BI Toolbox, of course.

Note that CRYPTOBI_HOME setup is not specific to Python tools and should be set for C++ toolbox as well.

That’s it. The Python scripts should be ready to run now.

Toolbox

The Python directory structure follows the C++ tree. It was made that way so parallels could be easily drawn between the two systems. When a tool requires Bitcoin Core linkage, it uses C++. Otherwise you’ll find it in the Python tree. Most analysis and database-related tools are under the python/ directory. Here’s an overview of the Python toolbox.

Under python/cryptobi/toolbox/bitcoin :

address_query.py – Query a Bitcoin address and print out all information we have about it on the database. To get transaction flow information the cb_address_graph table must have been built before running this command.

Sample output:

$ python3 ./cryptobi/toolbox/bitcoin/address_query.py 1HLoD9E4SDFFPDiYfNYnkBLQ85Y51J3Zb1
{'cag_id': 2, 'n_vout': -1, 'tx_from': '0000000000000000000000000000000000000000000000000000000000000000', 'n_vin': 0, 'tx_to': '9b0fc92260312ce44e74ef369f5c66bbb85848f2eddd5a7a1cde251e54ccfdd5', 'address_from': '0000000000000000000000000000000000', 'address_to': '1HLoD9E4SDFFPDiYfNYnkBLQ85Y51J3Zb1', 'satoshis': 5000000000, 'n_time': 1231469744}

block_query.py – Given a hash, query information about a block on the local DB.

build_address_graph.py – This module reads the TX inputs and outputs and builds the cb_address_graph table. This table allows address explorers to quickly follow transaction paths starting with a given address.

build_blockchain.py – Walks the blockchain setting the hash_next_block column of cb_blockchain table pointing to the next block (making it a doubly linked list) and block_height to the appropriate value. This script can be safely run multiple times in case it’s interrupted. Enabling keys will greatly speed up the updates.

transaction_query.py – Query all information contained in the local database about a given TX.

Under python/cryptobi/toolbox :

export_infonodes.py – Export cb_info_nodes table contents so you can share it with other users or back up your own data.

import_infonodes.py – Import an infonodes dump/backup created with export_infonodes.py. Be careful before importing untrusted users’ data.

Tests

nose2 is the easiers way to run Python distribution tests. If you don’t have it installed yet, do so with this command:

$ pip install nose2

Now, cd to the python/ directory under the Toolbox distribution and issue the following command under Linux:

$ nose2 -v

All files beginning with test_ will be run by nose2.

Test coverage is being expanded with each Toolbox version.

Links

crypto.bi Toolbox Home