Coder Social home page Coder Social logo

bitcoind's Introduction

MIT license Crates Docs

Bitcoind

Utility to run a regtest bitcoind process, useful in integration testing environment.

When the auto-download feature is selected by activating one of the version feature, such as 25_1 for bitcoin core 25.1, starting a regtest node is as simple as that:

// the download feature is enabled whenever a specific version is enabled, for example `25_1` or `24_0_1`
#[cfg(feature = "download")]
{
  use bitcoincore_rpc::RpcApi;
  let bitcoind = bitcoind::BitcoinD::from_downloaded().unwrap();
  assert_eq!(0, bitcoind.client.get_blockchain_info().unwrap().blocks);
}

The build script will automatically download the bitcoin core version 25.1 from bitcoin core, verify the hashes and place it in the build directory for this crate. If you wish to download from an alternate location, for example locally for CI, use the BITCOIND_DOWNLOAD_ENDPOINT env var.

When you don't use the auto-download feature you have the following options:

  • have bitcoind executable in the PATH
  • provide the bitcoind executable via the BITCOIND_EXE env var
use bitcoincore_rpc::RpcApi;
if let Ok(exe_path) = bitcoind::exe_path() {
  let bitcoind = bitcoind::BitcoinD::new(exe_path).unwrap();
  assert_eq!(0, bitcoind.client.get_blockchain_info().unwrap().blocks);
}

Startup options could be configured via the [Conf] struct using [BitcoinD::with_conf] or [BitcoinD::from_downloaded_with_conf]

Issues with traditional approach

I used integration testing based on external bash script launching needed external processes, there are many issues with this approach like:

  • External script may interfere with local development environment 1
  • Use of a single huge test to test everything 2
  • If test are separated, a failing test may fail to leave a clean situation, causing other test to fail (because of the initial situation, not a real failure)
  • bash script are hard, especially support different OS and versions

Features

  • It waits until bitcoind daemon become ready to accept RPC commands
  • bitcoind use a temporary directory as datadir. You can specify the root of your temp directories so that you have node's datadir in a RAM disk (eg /dev/shm)
  • Free ports are asked to the OS. Since you can't reserve the given port, a low probability race condition is still possible, for this reason the process is tried to be spawn 3 times with different ports.
  • The process is killed when the struct goes out of scope no matter how the test finishes
  • Allows easy spawning of dependent processes like:

Thanks to these features every #[test] could easily run isolated with its own environment.

Doc

To build docs:

RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --features download,doc --open

MSRV

The MSRV is 1.56.1 for version 0.35.*

Note: to respect 1.56.1 MSRV you need to use and older version of some dependencies, in CI the below dependency versions are pinned:

cargo update
cargo update -p tempfile --precise 3.3.0
cargo update -p log --precise 0.4.18

Pinning in Cargo.toml is avoided because it could cause compilation issues downstream.

Nix

For reproducibility reasons, Nix build scripts cannot hit the internet, but the auto-download feature does exactly that. To successfully build under Nix the user must provide the tarball locally and specify its location via the BITCOIND_TARBALL_FILE env var.

Another option is to specify the BITCOIND_SKIP_DOWNLOAD env var and provide the executable via the PATH.

Alternatively, use the dep without auto-download feature.

Used by

Via bdk dependency

Via electrsd dependency:

bitcoind's People

Contributors

rcasatta avatar notmandatory avatar noib3 avatar tnull avatar oleonardolima avatar tcharding avatar andrewtoth avatar llfourn avatar shesek avatar rajarshimaitra avatar cwlittle avatar terror avatar adoerr avatar evanlinjin avatar afilini avatar apoelstra avatar leocomandini avatar ulrichard avatar romanz avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.