Skip to content
This repository has been archived by the owner on Nov 26, 2024. It is now read-only.

Commit

Permalink
regtest: Update readme
Browse files Browse the repository at this point in the history
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`.
  • Loading branch information
tcharding committed Jun 17, 2024
1 parent b867626 commit 9093e58
Showing 1 changed file with 14 additions and 43 deletions.
57 changes: 14 additions & 43 deletions regtest/README.md
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -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:

Expand All @@ -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)
Expand Down Expand Up @@ -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.

0 comments on commit 9093e58

Please sign in to comment.