halfin

A {regtest} bitcoin node runner 🏃‍♂️

This crate makes it simple to run regtest bitcoind and utreexod instances from Rust code, useful in integration testing contexts.

Pretty much bitcoind with utreexod support.

Supported Implementations and Versions

Implementation	Version	Feature Flag
bitcoind	v30.2	bitcoind_30_2
utreexod	v0.5.0	utreexod_0_5_0

By default, the bitcoind_30_2 and utreexod_0_5_0 features are enabled.

Binaries are downloaded automatically at build time: see build.rs.

Running on CI

Since utreexod binaries are downloaded directly from its GitHub releases page, we can get 403'ed by GitHub itself. To curb this, you need to export the GITHUB_TOKEN environment variable in your CI workflow as such:

env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

BitcoinD

use halfin::bitcoind::BitcoinD;

// Use downloaded/cached binaries
let bitcoind_alpha = BitcoinD::new().unwrap();
// Use a local binary
let bin_path = PathBuf::from_str("/usr/local/bin/bitcoind").unwrap();
let bitcoind_beta = BitcoinD::from_bin(&bin_path).unwrap();

// Connect peers
bitcoind_alpha.add_peer(bitcoind_beta.get_p2p_socket()).unwrap();

// Mine blocks
bitcoind_alpha.generate(100).unwrap();
// Wait for a node to catch up with the other
wait_for_height(&bitcoind_beta, 100).unwrap();

assert_eq!(bitcoind_alpha.get_height().unwrap(), 100);
assert_eq!(bitcoind_beta.get_height().unwrap(), 100);

UtreexoD

use halfin::utreexod::UtreexoD;

let utreexod = UtreexoD::new().unwrap();

utreexod.generate(10).unwrap();
assert_eq!(utreexod.get_height().unwrap(), 10);

Developing

This project uses just for command running, and cargo-rbmt to manage everything related to cargo, such as formatting, linting, testing and CI. To install them, run:

~$ cargo install just

~$ cargo install cargo-rbmt

A justfile is provided for convenience. Run just to see available commands:

~$ just
> halfin
> A regtest runner for `bitcoind` and `utreexod`

Available recipes:
    build       # Build `halfin` [alias: b]
    check       # Check code formatting, compilation, and linting [alias: c]
    check-sigs  # Checks whether all commits in this branch are signed [alias: cs]
    delete-bins # Delete binaries under `target/bin/` [alias: db]
    doc         # Generate documentation [alias: d]
    doc-open    # Generate and open documentation [alias: do]
    fmt         # Format code [alias: f]
    lock        # Regenerate Cargo-recent.lock and Cargo-minimal.lock [alias: l]
    pre-push    # Run pre-push suite: lock, fmt, check, and test [alias: p]
    test        # Run tests across all toolchains and lockfiles [alias: t]

Minimum Supported Rust Version (MSRV)

This library should compile with any combination of features on Rust 1.85.0.

To build with the MSRV toolchain, copy Cargo-minimal.lock to Cargo.lock.

License

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.