Struct bitcoin_explorer::BitcoinDB

pub struct BitcoinDB(_);

This is the main struct of this crate!! Click and read the doc.

All queries start from initializing BitcoinDB.

Note: This is an Arc wrap around InnerDB.

Implementations

impl BitcoinDB

pub fn get_connected_block<T: BlockConnectable>(
    &self,
    height: i32
) -> OpResult<T>

Get a block with inputs replaced by connected outputs.

This function requires txindex to be set to true, and txindex=1 when running Bitcoin Core.

Caveat!!

This is a very slow function!! For massive processing of connected blocks, use iter.

pub fn get_connected_transaction<T: TxConnectable>(
    &self,
    txid: &Txid
) -> OpResult<T>

Get a transaction with outpoints replaced by outputs.

Format: full (FConnectedTransaction) / simple (SConnectedTransaction).

Caveats

Slow! Not suitable for massive computation. Use iter.

pub fn iter_connected_block<TBlock>(
    &self,
    end: u32
) -> ConnectedBlockIter<TBlock> where
    TBlock: 'static + BlockConnectable + Send, 

Iterate through all blocks for a given heights (excluded).

Format: full (FConnectedBlock) / simple (SConnectedBlock).

This iterator use unspent output to track down the connected outputs of each outpoints.

Note

This does NOT require txindex=true.

Performance

Using default feature:

Requires 4 GB memory, finishes in 2.5 hours from 0-70000 block.

Using non-default feature

Requires 32 GB memory, finished in 30 minutes from 0-70000 block.

Example

use bitcoin_explorer::{BitcoinDB, FConnectedBlock, SConnectedBlock};
use std::path::Path;

let path = Path::new("/Users/me/bitcoin");

// launch without reading txindex
let db = BitcoinDB::new(path, false).unwrap();

// iterate over block from 0 to 700000, (simple format)
for block in db.iter_connected_block::<SConnectedBlock>(700000) {
    for tx in block.txdata {
        println!("do something for this transaction");
    }
}

impl BitcoinDB

pub fn new(p: &Path, tx_index: bool) -> OpResult<BitcoinDB>

This is the main structure for reading Bitcoin blockchain data.

Instantiating this class by passing the -datadir directory of Bitcoin core to the new() method. tx_index: whether to try to open tx_index levelDB.

Example

use bitcoin_explorer::BitcoinDB;
use std::path::Path;

let path = Path::new("/Users/me/bitcoin");

// launch without reading txindex
let db = BitcoinDB::new(path, false).unwrap();

// launch attempting to read txindex
let db = BitcoinDB::new(path, true).unwrap();

pub fn get_max_height(&self) -> usize

Get the maximum height found in block index.

pub fn get_header(&self, height: usize) -> OpResult<&BlockIndexRecord>

Get block header information.

This is an in-memory query, thus very fast. This method is useful for computing blockchain statistics.

Example

Compute total number of transactions

use bitcoin_explorer::BitcoinDB;
use std::path::Path;

let path = Path::new("/Users/me/bitcoin");

// launch without reading txindex
let db = BitcoinDB::new(path, false).unwrap();

let mut total_number: usize = 0;

// This computation should finish immediately. No Disk Access.
for i in 0..700000 {
    let header = db.get_header(i).unwrap();
    total_number += header.n_tx as usize;
}
println!("total tx from block 0 to 700000: {}.", total_number);

pub fn get_hash_from_height(&self, height: usize) -> OpResult<BlockHash>

Get block hash of a certain height.

pub fn get_height_from_hash(&self, hash: &str) -> OpResult<i32>

Get block height of certain hash.

Note that the hash is a hex string of the block hash.

pub fn get_block<T: From<Block>>(&self, height: i32) -> OpResult<T>

Get a block (in different formats (Block, FBlock, SBlock))

Example

use bitcoin_explorer::{BitcoinDB, FBlock, SBlock, Block};
use std::path::Path;

let path = Path::new("/Users/me/bitcoin");

// launch without reading txindex
let db = BitcoinDB::new(path, false).unwrap();

// get block of height 600000 (in different formats)
let block: Block = db.get_block(600000).unwrap();
let block: FBlock = db.get_block(600000).unwrap();
let block: SBlock = db.get_block(600000).unwrap();

pub fn get_transaction<T: From<Transaction>>(&self, txid: &Txid) -> OpResult<T>

Get a transaction by providing txid.

This function requires txindex to be set to true, and txindex=1 when running Bitcoin Core.

Example

use bitcoin_explorer::{BitcoinDB, Transaction, FTransaction, STransaction, Txid, FromHex};
use std::path::Path;

let path = Path::new("/Users/me/bitcoin");

// !!must launch with txindex=true!!
let db = BitcoinDB::new(path, true).unwrap();

// get transaction
// e3bf3d07d4b0375638d5f1db5255fe07ba2c4cb067cd81b84ee974b6585fb468
let txid_str = "e3bf3d07d4b0375638d5f1db5255fe07ba2c4cb067cd81b84ee974b6585fb468";
let txid = Txid::from_hex(txid_str).unwrap();

// get transactions in different formats
let tx: Transaction = db.get_transaction(&txid).unwrap();
let tx: FTransaction = db.get_transaction(&txid).unwrap();
let tx: STransaction = db.get_transaction(&txid).unwrap();

pub fn get_height_of_transaction(&self, txid: &Txid) -> OpResult<i32>

Get the height of the block containing a particular transaction.

This function requires txindex to be set to true, and txindex=1 when running Bitcoin Core.

pub fn iter_block<T>(&self, start: u32, end: u32) -> BlockIter<T> where
    T: From<Block> + Send + 'static, 

Iterate through all blocks from start to end (excluded).

Formats: Block / FBlock / SBlock.

Performance

This iterator is implemented to read the blocks in concurrency, but the result is still produced in sequential order. Results read are stored in a synced queue for next() to get.

The iterator stops automatically when a block cannot be read (i.e., when the max height in the database met).

This is a very efficient implementation. Using SSD and intel core i7 (4 core, 8 threads) Iterating from height 0 to 700000 takes about 10 minutes.

Example

use bitcoin_explorer::{BitcoinDB, Block, SBlock, FBlock};
use std::path::Path;

let path = Path::new("/Users/me/bitcoin");

// launch without reading txindex
let db = BitcoinDB::new(path, false).unwrap();

// iterate over block from 600000 to 700000
for block in db.iter_block::<Block>(600000, 700000) {
    for tx in block.txdata {
        println!("do something for this transaction");
    }
}

// iterate over block from 600000 to 700000
for block in db.iter_block::<FBlock>(600000, 700000) {
    for tx in block.txdata {
        println!("do something for this transaction");
    }
}

// iterate over block from 600000 to 700000
for block in db.iter_block::<SBlock>(600000, 700000) {
    for tx in block.txdata {
        println!("do something for this transaction");
    }
}

pub fn iter_heights<T: 'static + From<Block> + Send>(
    &self,
    heights: Vec<u32>
) -> BlockIter<T>

Iterate through all blocks for a given heights (excluded).

Formats: Block / FBlock / SBlock.

Performance

This iterator is implemented to read the blocks in concurrency, but the result is still produced in the given order in heights. Results read are stored in a synced queue for next() to get.

This is a very efficient implementation. Using SSD and intel core i7 (4 core, 8 threads) Iterating from height 0 to 700000 takes about 10 minutes.

Fails Fast

The iterator stops immediately when a height cannot be found.

Example

use bitcoin_explorer::{BitcoinDB, Block, FBlock, SBlock};
use std::path::Path;

let path = Path::new("/Users/me/bitcoin");

// launch without reading txindex
let db = BitcoinDB::new(path, false).unwrap();

let some_heights = vec![3, 5, 7, 9];

// iterate over blocks from 600000 to 700000
for block in db.iter_heights::<Block>(some_heights.clone()) {
    for tx in block.txdata {
        println!("do something for this transaction");
    }
}

// iterate over simple blocks from 600000 to 700000
for block in db.iter_heights::<SBlock>(some_heights.clone()) {
    for tx in block.txdata {
        println!("do something for this transaction");
    }
}

// iterate over full blocks from 600000 to 700000
for block in db.iter_heights::<FBlock>(some_heights.clone()) {
    for tx in block.txdata {
        println!("do something for this transaction");
    }
}

Trait Implementations

impl Clone for BitcoinDB

fn clone(&self) -> BitcoinDB

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Deref for BitcoinDB

type Target = InnerDB

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.