An exploration bringing together Scala and Bitcoin.
Clone or download

README.org

Bitcoin Graph Explorer

Probably the first project bringing together Scala and bitcoin, Bitcoin Graph Explorer (BGE) parses the blockchain, stores the relevant data in databases, and gives the user access to powerful analysis tools like the closure of an address with regard to probable co-ownership. We offer a REST API for easy access.

Please see https://bitcoinprivacy.net/ for a reference project using BGE. There you can also find a publicly running example of the API under https://api.bitcoinprivacy.net.

REQUIREMENTS

postgres

BGE uses postgres for storing its main database. Install and run the service according to your OS.

bitcoind

BGE uses a locally running bitcoin daemon in order to read its raw files and connect to it via bitcoin protocol. Install, run and let sync before starting BGE.

hardware

Using LMDB for UTXOs means that this should work ok even on machines with not too much RAM. BGE is heavily disk bound, though:

We recommend an SSD with at least three times the space the raw blockchain needs. At the moment that means about 600G including everything and takes about 24 hours to catch up.

INSTALLATION

Install sbt first, then

git clone https://github.com/bitcoinprivacy/Bitcoin-Graph-Explorer bge
cd bge

If necessary, change build.sbt in order to import the correct LMDB JNI architecture library. E.g., for mac use lmdbjni-osx64 instead of lmdbjni-linux64. Then

sbt stage publish-local
cd api
sbt stage

This puts executables at target/universal/stage/bin/bge and api/target/universal/stage/bin/bgeapi. We use sbt native packager for packaging, so you can replace both sbt stage commands above by something like sbt universal:packageBin to receive a zip File, sbt debian:packageBin or sbt rpm:packageBin for a package or even sbt docker:publishLocal to have a docker file published to your local repo. See the native packager docs for more options!

LMDB JNI needs access to libstdc++.so.6, so you might need to set LD_LIBRARY_PATH accordingly before running bge manually.

USAGE

Configuration

Per default, bge assumes user “postgres” with password “trivial” in psql. Either configure psql like this or override configuration file reference.conf with application.conf, changing this line

password = "trivial"

with the password you have defined in the psql installation. The configuration is done via typesafe config. Read the doc for all the possibilities or simply include -Dconfig.file=<your config file> in the java -jar call.

Start

bge start [--force]

If the database is not populated yet (or you –force), initializes everything in the background and begins populating the database with all blocks available in the bitcoind raw data at the moment. Then, it automatically does

bge resume

to keep up with the incoming new blocks.

If you just want to populate the DB, do

bge populate

.

In order to gently stop the machine say

bge stop

Note that this only halts after the current iteration, so it could take a few days if you have just started the populate process.

Logs are written to bge.log in the current directory per default. This can be changed in the config.

API

bgeapi [-Dapi.port=PORT] [-Dapi.mode=development]

starts the api on localhost, default port is 8080, default mode is production.

These are all available queries:

GET /blocks/:from/:until
GET /blocks/summary
GET /distribution/:limit
GET /inputs/:tx/:from/:until
GET /inputs/:tx/summary
GET /movements/:ad/:from/:until
GET /movements/:ad/summary
GET /outputs/:tx/:from/:until
GET /outputs/:tx/summary
GET /richlist/addresses/:block_height/:from/:until
GET /richlist/addresses/:block_height/summary
GET /richlist/wallets/:block_height/:from/:until
GET /richlist/wallets/:block_height/summary
GET /stats
GET /stats/history
GET /tx_utxos/:tx/:from/:until
GET /tx_utxos/:tx/summary
GET /txs/:block_height/:from/:until
GET /txs/:block_height/summary
GET /utxos/:ad/:from/:until
GET /utxos/:ad/summary
GET /wallet/:ad/:from/:until
GET /wallet/:ad/summary

For more usage examples, please take a look here