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

Commit f4c3396

Browse files
tchardingtcharding
committed
Import bitcoind crate
The `bitcoind` crate is provided for integration testing, it is tightly coupled to the `client` and `bitcoin` crates. It might as well just live here. Import `bitcoind` at tag `v.036.0` as well as the changes in: rust-bitcoin/bitcoind#164
1 parent 75d9143 commit f4c3396

23 files changed

+1689
-19
lines changed

‎Cargo.toml

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
[workspace]
2-
members = ["client", "json"]
2+
members = ["client", "json", "bitcoind"]
33
exclude = ["integration_test"]
44
resolver = "2"
55

@@ -10,5 +10,4 @@ path = "client"
1010
path = "json"
1111

1212
[patch.crates-io.bitcoind]
13-
git = "https://github.com/tcharding/bitcoind"
14-
branch = "bitcoind-json-rpc"
13+
path = "bitcoind"

‎bitcoind/CHANGELOG.md

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# Changelog
2+
3+
## 0.36.0
4+
5+
- Remove range dependencies for `bitcoincore-rpc` and depend on the
6+
latest version `v0.19.0` [#163](https://github.com/rust-bitcoin/bitcoind/pull/163).
7+
8+
## 0.35.2
9+
10+
- Use range dependencies for `bitcoincore-rpc` and `bitcoin_hashes`
11+
12+
## Release 0.35.1
13+
14+
- Bump MSRV to 1.56.1
15+
- Add `BITCOIND_SKIP_DOWNLOAD` build feature
16+
17+
## Release 0.34.2
18+
19+
- Support Bitcoin Core 26.0
20+
21+
## Release 0.34.1
22+
23+
- Optionally enable ZMQ
24+
25+
## Release 0.34.0
26+
27+
- upgrade bitcoincore dep to 0.18.0 and with it bitcoin to 0.31.0
28+
29+
## Release 0.28.0
30+
31+
### Changed
32+
33+
- bump `ureq`'s version to `2.5.0`
34+
- bump `flate2`'s version to `1.0.24`
35+
- bump `filetime`'s version to `0.2.18`
36+
37+
## Release 0.27.1
38+
39+
### Changed
40+
41+
- use bitcoin_hashes 0.11 also for build dep
42+
43+
## Release 0.27.0
44+
45+
### Added
46+
47+
- Introduced CHANGELOG
48+
- Supports windows OS
49+
- Provide errors if `rpcuser` and `rpcpassword` are provided
50+
51+
### Changed
52+
53+
- use bitcoin dep to 0.29.1
54+
55+
### Fixed
56+
57+
- fix bitcoin 0.23 on MacOS X
58+
- fix test flakiness
59+
60+
### Removed
61+
62+
- removed `datadir` from `ConnectionParams`, use equivalent `workdir()`

‎bitcoind/Cargo.toml

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
[package]
2+
name = "bitcoind"
3+
version = "0.37.0"
4+
authors = ["Riccardo Casatta <[email protected]>"]
5+
description = "Utility to run a regtest bitcoind process, useful in integration testing environment"
6+
license = "MIT"
7+
repository = "https://github.com/RCasatta/bitcoind"
8+
documentation = "https://docs.rs/bitcoind/"
9+
rust-version = "1.56.1"
10+
edition = "2018"
11+
categories = ["cryptography::cryptocurrencies", "development-tools::testing"]
12+
13+
[dependencies]
14+
bitcoind-json-rpc-client = { version = "0.1", features = ["client-sync"] }
15+
log = "0.4"
16+
which = "4.2.5"
17+
anyhow = "1.0.66"
18+
tempfile = "3"
19+
serde_json = { version = "1.0.117" }
20+
21+
[dev-dependencies]
22+
env_logger = "0.9.0"
23+
24+
[build-dependencies]
25+
bitcoin_hashes = { version = ">= 0.13, <= 0.14", optional = true }
26+
flate2 = { version = "1.0", optional = true }
27+
tar = { version = "0.4", optional = true }
28+
minreq = { version = "2.9.1", default-features = false, features = [
29+
"https",
30+
], optional = true }
31+
zip = { version = "0.6", optional = true }
32+
anyhow = "1.0.66"
33+
34+
[features]
35+
"default" = ["0_17_1"] # FIXME: Default to latest after we get 26_0 worknig (or better still 26_1).
36+
37+
# download is not supposed to be used directly only through selecting one of the version feature
38+
"download" = ["bitcoin_hashes", "flate2", "tar", "minreq", "zip"]
39+
40+
"26_0" = ["download", "25_2"]
41+
"25_2" = ["download", "25_1"]
42+
"25_1" = ["download", "25_0"]
43+
"25_0" = ["download", "24_2"]
44+
"24_2" = ["download", "24_0_1"]
45+
"24_0_1" = ["download", "23_2"]
46+
"23_2" = ["download", "23_1"]
47+
"23_1" = ["download", "22_1"]
48+
"22_1" = ["download", "0_21_2"]
49+
"0_21_2" = ["download", "0_20_2"]
50+
"0_20_2" = ["download", "0_19_1"]
51+
"0_19_1" = ["download", "0_18_1"]
52+
"0_18_1" = ["download", "0_17_1"]
53+
"0_17_1" = ["download"]
54+
55+
"doc" = [] # used only for documentation building
56+
57+
58+
[package.metadata.docs.rs]
59+
features = ["download", "doc"]
60+
rustdoc-args = ["--cfg", "docsrs"]

‎bitcoind/LICENSE

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2020 Riccardo Casatta
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎bitcoind/README.md

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
[![MIT license](https://img.shields.io/github/license/RCasatta/bitcoind)](https://github.com/RCasatta/bitcoind/blob/master/LICENSE)
2+
[![Crates](https://img.shields.io/crates/v/bitcoind.svg)](https://crates.io/crates/bitcoind)
3+
[![Docs](https://img.shields.io/badge/docs.rs-bitcoind-green)](https://docs.rs/bitcoind)
4+
5+
# Bitcoind
6+
7+
Utility to run a regtest bitcoind process, useful in integration testing environment.
8+
9+
When the auto-download feature is selected by activating one of the version feature, such as `25_1`
10+
for bitcoin core 25.1, starting a regtest node is as simple as that:
11+
12+
```rust
13+
// the download feature is enabled whenever a specific version is enabled, for example `25_1` or `24_0_1`
14+
#[cfg(feature = "download")]
15+
{
16+
use bitcoincore_rpc::RpcApi;
17+
let bitcoind = bitcoind::BitcoinD::from_downloaded().unwrap();
18+
assert_eq!(0, bitcoind.client.get_blockchain_info().unwrap().blocks);
19+
}
20+
```
21+
22+
The build script will automatically download the bitcoin core version 25.1 from [bitcoin core](https://bitcoincore.org),
23+
verify the hashes and place it in the build directory for this crate. If you wish to download from an
24+
alternate location, for example locally for CI, use the `BITCOIND_DOWNLOAD_ENDPOINT` env var.
25+
26+
When you don't use the auto-download feature you have the following options:
27+
28+
* have `bitcoind` executable in the `PATH`
29+
* provide the `bitcoind` executable via the `BITCOIND_EXE` env var
30+
31+
```rust
32+
use bitcoincore_rpc::RpcApi;
33+
if let Ok(exe_path) = bitcoind::exe_path() {
34+
let bitcoind = bitcoind::BitcoinD::new(exe_path).unwrap();
35+
assert_eq!(0, bitcoind.client.get_blockchain_info().unwrap().blocks);
36+
}
37+
```
38+
39+
Startup options could be configured via the [`Conf`] struct using [`BitcoinD::with_conf`] or
40+
[`BitcoinD::from_downloaded_with_conf`]
41+
42+
## Issues with traditional approach
43+
44+
I used integration testing based on external bash script launching needed external processes, there
45+
are many issues with this approach like:
46+
47+
* External script may interfere with local development environment [1](https://github.com/rust-bitcoin/rust-bitcoincore-rpc/blob/200fc8247c1896709a673b82a89ca0da5e7aa2ce/integration_test/run.sh#L9)
48+
* 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)
49+
* If test are separated, a failing test may fail to leave a clean situation, causing other test to
50+
fail (because of the initial situation, not a real failure)
51+
* bash script are hard, especially support different OS and versions
52+
53+
## Features
54+
55+
* It waits until bitcoind daemon become ready to accept RPC commands
56+
* `bitcoind` use a temporary directory as datadir. You can specify the root of your temp directories
57+
so that you have node's datadir in a RAM disk (eg `/dev/shm`)
58+
* Free ports are asked to the OS. Since you can't reserve the given port, a low probability race
59+
condition is still possible, for this reason the process is tried to be spawn 3 times with different
60+
ports.
61+
* The process is killed when the struct goes out of scope no matter how the test finishes
62+
* Allows easy spawning of dependent processes like:
63+
- [electrs](https://github.com/RCasatta/electrsd)
64+
- [cln](https://github.com/RCasatta/lightningd)
65+
- [elements](https://github.com/RCasatta/elementsd)
66+
67+
Thanks to these features every `#[test]` could easily run isolated with its own environment.
68+
69+
## Doc
70+
71+
To build docs:
72+
73+
```sh
74+
RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --features download,doc --open
75+
```
76+
77+
## MSRV
78+
79+
The MSRV is 1.56.1 for version 0.35.*
80+
81+
Note: to respect 1.56.1 MSRV you need to use and older version of some dependencies, in CI the below
82+
dependency versions are pinned:
83+
84+
```sh
85+
cargo update
86+
cargo update -p tempfile --precise 3.3.0
87+
cargo update -p log --precise 0.4.18
88+
```
89+
90+
Pinning in `Cargo.toml` is avoided because it could cause
91+
compilation issues downstream.
92+
93+
## Nix
94+
95+
For reproducibility reasons, Nix build scripts cannot hit the internet, but the
96+
auto-download feature does exactly that. To successfully build under Nix the
97+
user must provide the tarball locally and specify its location via the
98+
`BITCOIND_TARBALL_FILE` env var.
99+
100+
Another option is to specify the `BITCOIND_SKIP_DOWNLOAD` env var and provide the
101+
executable via the `PATH`.
102+
103+
Alternatively, use the dep without auto-download feature.
104+
105+
## Used by
106+
107+
* [firma](https://github.com/RCasatta/firma/)
108+
* [payjoin](https://github.com/Kixunil/payjoin)
109+
* [rust-miniscript](https://github.com/rust-bitcoin/rust-miniscript/tree/4a3ba11c2fd5063be960741d557f3f7a28041e1f/bitcoind-tests)
110+
111+
### Via bdk dependency
112+
113+
* [gun](https://github.com/LLFourn/gun)
114+
115+
### Via electrsd dependency:
116+
117+
* [bdk](https://github.com/bitcoindevkit/bdk)
118+
* [BEWallet](https://github.com/LeoComandini/BEWallet)
119+
* [gdk rust](https://github.com/Blockstream/gdk/blob/master/subprojects/gdk_rust/)

0 commit comments

Comments
 (0)