josibake / rust-bitcoinkernel

Rust bindings for the bitcoin kernel library

rust-bitcoinkernel

⚠️🚧 This library is still under contruction. ⚠️🚧

rust-bitcoinkernel is a wrapper around libbitcoinkernel, a C++ library exposing Bitcoin Core's validation engine.

Building

To build this library, first build the kernel library on my kernelApi branch. It produces a C-compatible header that is used by this project to create the FFI.

git clone https://github.com/TheCharlatan/bitcoin
git checkout kernelApi
./autogen.sh
./configure --with-experimental-kernel-lib --enable-shared --prefix ~/bitcoin/install_dir
make install -j 24

This will install the library in $HOME/bitcoin/install_dir. Change the value after --prefix to control where the library will be installed or leave it unchanged to install it system-wide.

Then, to compile rust-bitcoinkernel (add the PKG_CONFIG_PATH if libbitcoinkernel is not installed in /usr/local):

PKG_CONFIG_PATH=/path/to/bitcoin/install_dir/lib/pkgconfig cargo b

And similarly for running it (env variables only required if not installed in /usr/local):

PKG_CONFIG_PATH=/path/to/bitcoin/install_dir/lib/pkgconfig LD_LIBRARY_PATH=/path/to/bitcoin/install_dir/lib cargo run

Fuzzing

Fuzzing is done with cargo fuzz.

There are currently three supported fuzzing targets: fuzz_target_block, fuzz_target_chainman and fuzz_target_verify. The chainman target requires the user to first mount a temporary ramdisk:

sudo mkdir -p /mnt/tmp/kernel
sudo mount -t tmpfs -o size=4g tmpfs /mnt/tmp/kernel

Once done the user can unmount the ramdisk again with:

sudo umount /mnt/tmp/kernel

To get fuzzing run (in this case the verify target):

LD_LIBRARY_PATH=/usr/local/lib cargo fuzz run fuzz_target_verify

Coverage

Once fuzzed, a coverage report can be generated with (picking the verify target as an example):

LD_LIBRARY_PATH=/usr/local/lib RUSTFLAGS="-C instrument-coverage" cargo fuzz coverage fuzz_target_verify
llvm-cov show \
  -format=html \
  -instr-profile=fuzz/coverage/fuzz_target_verify/coverage.profdata \
  target/x86_64-unknown-linux-gnu/coverage/x86_64-unknown-linux-gnu/release/fuzz_target_verify \
  -show-line-counts-or-regions \
  -Xdemangler=rustfilt \
  -output-dir=coverage_report \
  -ignore-filename-regex="/rustc"

You may have to install the following tooling:

rustup component add llvm-tools-preview
cargo install rustfilt