Bitcoin-ruby-blockchain

This is a bitcoin blockchain storage based on bitcoin-ruby with support for several different backends and database adapters.

It also provides Validation functionality to ensure that only valid data is stored.

Backends

The :archive and :utxo backends can both use any SQL database supported by sequel.

Archive

The Archive backend stores a complete, fully-indexed blockchain.

This backend produces a very large DB, but holds the data in a completely normalized schema and can be queried arbitrarily.

Postgres is the recommended adapter since it is the most optimized.

Webbtc.com is based on this backend, and you can grab a postgres dump from dumps.webbtc.com to get started more quickly (hours instead of days).

Utxo

The Utxo backend stores only the utxos (“Unspent TX Outputs”) needed to validate the blockchain on its own.

This backend produces a much smaller DB than the `:archive` backend, but can only be queried for addresses it has been told to watch previously.

Configuration

Specify which sequel adapter and database to use like this:

sqlite:/                                          # sqlite in-memory database
sqlite://bitcoin.db                               # sqlite db in current directory
sqlite:///tmp/bitcoin.db                          # sqlite with absolute path
postgres:/bitcoin                                 # local postgres database
postgres://<user>:<pass>@<host>:<port>/<database> # remote postgres db with authentication

Installation

We assume you already have a ruby 1.9 or 2.0 compatible interpreter and rubygems environment.

gem install bitcoin-ruby-blockchain

Or add it to your Gemfile and

require 'bitcoin/blockchain'

Usage

Initialize a blockchain with the desired backend and DB adapter:

# use :utxo backend with in-memory sqlite DB
chain = Bitcoin::Blockchain::Utxo.new(db: "sqlite:/")

# use :archive backend with local postgres DB
chain = Bitcoin::Blockchain::Archive.new(db: "postgres:/bitcoin")

Give it a Block to store:

chain.store_block(block) #=> [height, branch]

And query objects from the blockchain:

chain.get_head   #=> current best block
chain.get_height #=> height of current best block
block = chain.get_block(block_hash)
tx = chain.get_tx(tx_hash)

See Bitcoin::Blockchain::Backends::Base for a complete list of methods common to all backends.

These return Bitcoin::Blockchain::Models objects, which are like Bitcoin::Protocol objects with extra features to query related data from the blockchain, like so:

block.get_prev_block  #=> the previous block this one is based upon
block.get_next_block  #=> the next block based upon this one
tx.get_block          #=> the block this tx is in
tx.confirmations      #=> number of blocks in the main chain that confirm this tx
tx.in[0].get_prev_out #=> the previous output that is spent by this input
tx.out[0].get_next_in #=> the next input that is spending this output

Documentation

Always trying to improve, any help appreciated! If anything is unclear to you, let us know!

Documentation is generated using yardoc:

rake doc

The specs are also a good place to see how things are supposed to work.

Specs

The specs can be run with

rake

or, if you want to run a single spec

rspec spec/blockchain/models_spec.rb

Coverage information is automatically generated and can be found in coverage/ after the test run.

Contributing

Any help or feedback is greatly appreciated! Just open an issue, submit a pull-request, or come to #bitcoin-ruby on irc.freenode.net if you want to chat.

License

This software is licensed under the terms of the MIT license. See COPYING for details.