C++ Bitcoin Blockchain to MySQL Database Interface

Crypto.BI Toolbox abstracts database access through a thin database access layer.

Every database operation required to run the system has been made into a separate function in db/dao/CBDAODriver.h

This traditional approach, used in many system architectures, allows us to switch storage solutions by creating new subclasses of CBDAODriver.

For instance, if a graph database was chosen instead of MySQL, all a developer would have to do is create a subclass of CBDAODriver and then implement every method for that specific database system.

Check out db/dao/mysql/CBMySQL.* for an example implementation.

Below you’ll find documentation on the main functions in a DAO interface.

CBDAODriver()

All DAO implementations must provide a default, empty, constructor. The singleton implementation on db/CBDB.h will instance the driver implementation using the default constructor.

Note: db/CBDB.his in charge of choosing which database back-end will be used based on user choice or configuration.

bool connect(const std::string &user, const std::string &pass, const std::string &host, const std::string &db)

connect() is pretty intuitive, it’s in charge of connecting the driver interface to the underlying database system. The parameters are pretty much self explanatory.

std::string test_connection()

Sends a trivial query to the database system and expects a known return string. An exception should be thrown if anything goes wrong. If the method reaches the return statement without errors then the returned string should contain a known value which can be checked.

bool insert_block(const model::blockchains::CBBlock &block)

Inserts a blockchain block into the database.

bool get_block_by_hash(const model::blockchains::CBHash &hash, model::blockchains::CBBlock &ret_block)

Retrieves a blockchain block from the database, keyed by its unique hash.

bool get_latest_block(model::blockchains::CBBlock &ret_block)

Retrieves the latest block stored on the blockchain.

Returns false if the blockchain database is empty or if any other error occurs.

bool insert_block_file(const boost::filesystem::path &filename, const model::blockchains::CBHash &hash, uint32_t byte_offset)

Saves a block file path, the block hash and the byte offset into the data file where this block can be found.

This table is analog to the block index in Bitcoin Core.

bool get_latest_block_file(boost::filesystem::path &filename, model::blockchains::CBHash &hash, uint32_t &byte_offset)

Retrieves the latest block file path in the database.

Returns false if an error occurs or if the block database is empty.

bool insert_tx(const model::blockchains::CBTx &tx)

Saves a transaction into the database.

bool get_tx_by_hash(const model::blockchains::CBHash &hash, model::blockchains::CBTx &ret_tx)

Retrieves a transaction from the database, keyed by its unique hash.

Note: An early Bitcoin bug allowed a TX to be mined in multiple blocks but the multiply-saved TX contain the same data, so this function returns the first found TX with this hash. But it may not be assumed a TX belongs to a single block in Bitcoin pre BIP30.

bool get_latest_tx(model::blockchains::CBTx &ret_tx)

Retrieves the latest TX read from disk block files.

This is *not* guaranteed to be the latest TX on the network, as TX’s may be locally stored out of order.

bool insert_tx_in(const model::blockchains::CBTxIn &tx)

Inserts a transaction input into the local database.

bool get_tx_in(const model::blockchains::CBTxPoint &vin, model::blockchains::CBTxIn &ret_txin)

Retrieves a transaction input from the local database.

bool get_latest_tx_in(model::blockchains::CBTxIn &ret_txin)

Get the latest transaction input that was read from disk universally. That is, the latest input that was read and stored on the local database, regardless of which transaction this input belongs to.

bool list_tx_in(const model::blockchains::CBHash &tx_hash, std::vector<model::blockchains::CBTxIn> &ret_txout)

List the transaction inputs in a given transaction, keyed by transaction hash.

bool insert_tx_out(const model::blockchains::CBTxOut &tx)

Complement to list_tx_in : lists outputs instead.

bool get_tx_out(const model::blockchains::CBTxPoint &vout, model::blockchains::CBTxOut &ret_txout)

Tries to retrieve a certain transaction output given a transaction hash and index.

bool get_latest_tx_out(model::blockchains::CBTxOut &ret_txout)

Retrieves the latest transaction output that was stored in the local database. As with the other *latest*  functions this does not guarantee this TX output is the latest on the network, instead this is the last output ever read from disk within the last TX that was stored on the block files and read by Toolbox into the database.

bool list_tx_out(const model::blockchains::CBHash &tx_hash, std::vector<model::blockchains::CBTxOut> &ret_txout)

List transaction outputs, keyed by a transaction hash.

bool insert_tx_out_address(const model::blockchains::CBHash &tx_hash, const uint32_t nvout, const std::string &addr, uint8_t req_sigs, uint8_t script_type)

The cb_tx_out_addresses table indexes the addresses used in each output.

This function adds an entry to that table.

bool list_tx_out_addresses(const model::blockchains::CBHash &tx_hash, std::vector<std::string> &ret_txout)

This function lists addresses on the cb_tx_out_addresses table.

bool insert_address_graph(const model::blockchains::CBTxPoint &vin, const model::blockchains::CBTxPoint &vout, const std::string &addr_from, const std::string &addr_to, const uint64_t satoshis, const uint32_t n_time)

The cb_address_graph table establishes links between addresses. This function inserts an entry into this table.

The address_from and address_to fields in the cb_address_graph table generate a directed graph which represents the flow of value from address to address.

bool insert_info_node(const CBInfoNode &inode)

The cb_info_nodes table stores general information about blocks, TX’s or addresses.

This function inserts an info node entry into the cb_info_nodes table.

bool get_info_node_by_id(const uint64_t id, CBInfoNode &ret_inode)

Retrieves a cb_info_nodes table entry by its 64 bit unique key.

bool list_info_node_by_address(const std::string &address)

Lists all information available for an address on the cb_info_nodes table. Information usually includes scam reports, famous addresses (Satoshi et al), vanity addresses and so on.

This information resides on your local server only and not available to the public. You can store sensitive or personal annotations here and they won’t be shared.

bool list_info_node_by_block_hash(const model::blockchains::CBHash &hash)

Lists all information available for a block on the cb_info_nodes table, keyed by block hash.

bool list_info_node_by_tx_hash(const model::blockchains::CBHash &hash)

Lists all information available for a transaction on the cb_info_nodes table, keyed by TX hash.

Annotations usually include scam TX’s, suspicious TX’s, famous TX’s and so on.

bool search_info_node(const std::string &q, std::vector<CBInfoNode> &ret_vector)

Searches the cb_info_nodes table looking for annotations that match q

bool update_info_node(const CBInfoNode &inode)

Updates an info node.

bool delete_info_node(const uint64_t id)

Deletes an info node.

bool disable_keys()

Disables database keys. This speeds up data loading from block files by a factor of 5 to 6x on average.

bool enable_keys()

Enables keys if they’ve been disabled.

Links

crypto.bi Toolbox Sources

crypto.bi Toolbox Home