From 9093e58a8d9e6aa15c2da9b7a74e76c69e6ed6bd Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Mon, 17 Jun 2024 14:29:48 +1000 Subject: [PATCH] regtest: Update readme The readme is stale because it is the one we grabbed when importing `bitcoind`. Since this crate is currently being release under a different name remove the stale docs that are specific to `bitcoind`. --- regtest/README.md | 57 ++++++++++++----------------------------------- 1 file changed, 14 insertions(+), 43 deletions(-) diff --git a/regtest/README.md b/regtest/README.md index 74752ff..a5366a2 100644 --- a/regtest/README.md +++ b/regtest/README.md @@ -1,7 +1,3 @@ -[![MIT license](https://img.shields.io/github/license/RCasatta/bitcoind)](https://github.com/RCasatta/bitcoind/blob/master/LICENSE) -[![Crates](https://img.shields.io/crates/v/bitcoind.svg)](https://crates.io/crates/bitcoind) -[![Docs](https://img.shields.io/badge/docs.rs-bitcoind-green)](https://docs.rs/bitcoind) - # Bitcoind Utility to run a regtest bitcoind process, useful in integration testing environment. @@ -19,8 +15,7 @@ for bitcoin core 25.1, starting a regtest node is as simple as that: ``` The build script will automatically download the bitcoin core version 25.1 from [bitcoin core](https://bitcoincore.org), -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. +verify the binary hash and place it in the build directory for this crate. When you don't use the auto-download feature you have the following options: @@ -37,22 +32,15 @@ if let Ok(exe_path) = bitcoind::exe_path() { 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](https://github.com/rust-bitcoin/rust-bitcoincore-rpc/blob/200fc8247c1896709a673b82a89ca0da5e7aa2ce/integration_test/run.sh#L9) -* Use of a single huge test to test everything [2](https://github.com/rust-bitcoin/rust-bitcoincore-rpc/blob/200fc8247c1896709a673b82a89ca0da5e7aa2ce/integration_test/src/main.rs#L122-L203) -* 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 + * Waits until bitcoind daemon becomes ready to accept RPC commands + * `bitcoind` uses a temporary directory as datadir. You can specify the root of your temp + directories so that you have the node's datadir in a RAM disk (eg `/dev/shm`) + * Free ports are requested from the OS. Since you can't reserve the given port, a low probability + race condition is still possible, for this reason the process attempts spawning 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: - [electrs](https://github.com/RCasatta/electrsd) - [cln](https://github.com/RCasatta/lightningd) @@ -85,28 +73,11 @@ Pinning in `Cargo.toml` is avoided because it could cause compilation issues dow ## 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 - -* [firma](https://github.com/RCasatta/firma/) -* [payjoin](https://github.com/Kixunil/payjoin) -* [rust-miniscript](https://github.com/rust-bitcoin/rust-miniscript/tree/4a3ba11c2fd5063be960741d557f3f7a28041e1f/bitcoind-tests) - -### Via bdk dependency - -* [gun](https://github.com/LLFourn/gun) +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. -### Via electrsd dependency: +Another option is to specify the `BITCOIND_SKIP_DOWNLOAD` env var and provide the executable via the +`PATH`. -* [bdk](https://github.com/bitcoindevkit/bdk) -* [BEWallet](https://github.com/LeoComandini/BEWallet) -* [gdk rust](https://github.com/Blockstream/gdk/blob/master/subprojects/gdk_rust/) +Alternatively, use the dep without the auto-download feature.