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