Crate corepc_node

Expand description

§Rust Bitcoin Core node harness

Utilities used to spin up, configure and drive bitcoind instances.

§Bitcoind

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

When the auto-download feature is enabled, starting a regtest node is as simple as that:

// the download feature must be enabled with a specific version, for example `25_1` or `24_0_1`
#[cfg(feature = "download")]
{
  let node = corepc_node::Node::from_downloaded().unwrap();
  assert_eq!(0, node.client.get_blockchain_info().unwrap().blocks);
}

The build script will automatically download the bitcoin core version 25.1 from bitcoin core, 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:

have bitcoind executable in the PATH
provide the bitcoind executable via the BITCOIND_EXE env var

if let Ok(exe_path) = corepc_node::exe_path() {
  let node = corepc_node::Node::new(exe_path).unwrap();
  assert_eq!(0, node.client.get_blockchain_info().unwrap().blocks);
}

Startup options could be configured via the Conf struct using Node::with_conf or Node::from_downloaded_with_conf

§Features

Waits until bitcoind daemon becomes ready to accept RPC commands
node 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
- cln
- elements

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

§Minimum Supported Rust Version (MSRV)

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

§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 the auto-download feature.

Re-exports§

pub extern crate corepc_client as client;

`Re-exports§`

pub use anyhow;
pub use serde_json;
pub use tempfile;
pub use which;

`Modules§`

mtype: Models of the data returned by the JSON-RPC API of Bitcoin Core.
raw_transactions: Macros for implementing JSON-RPC methods on a client.
vtype: JSON-RPC types for Bitcoin Core v28
wallet: Macros for implementing JSON-RPC methods on a client.

`Structs§`

Client: Client implements a JSON-RPC client for the Bitcoin Core daemon or compatible APIs.
Conf: The node configuration parameters, implements a convenient Default for most common use.
ConnectParams: Contains all the information to connect to this node.
CookieValues
ImportDescriptorsRequest: Request object for the importdescriptors method.
ImportMultiRequest: Args for the importmulti method.
Input: Input used as parameter to create_raw_transaction.
Node: Struct representing the bitcoind process with related information.
Output: Output used as parameter to create_raw_transaction.
TemplateRequest: Arg for the getblocktemplate method.
WalletCreateFundedPsbtInput: An element in the inputs argument of method walletcreatefundedpsbt.

`Enums§`

AddNodeCommand: Args for the addnode method.
AddressType: Argument to the Client::get_new_address_with_type function.
DataDir: The DataDir struct defining the kind of data directory the node will contain. Data directory can be either persistent, or temporary.
Error: All the possible error in this crate.
ImportMultiScriptPubKey: scriptPubKey can be a string for script or json for address.
ImportMultiTimestamp: timestamp can be a number (UNIX epoch time) or the string "now".
P2P: Enum to specify p2p settings.
SetBanCommand: Args for the setban method.
TemplateRules: Client side supported softfork deployment.

`Constants§`

VERSION

`Functions§`

downloaded_exe_path: Provide the bitcoind executable path if a version feature has been specified.
exe_path: Returns the daemon bitcoind executable with the following precedence:
get_available_port: Returns a non-used local port if available.
validate_args: Validate the specified arg if there is any unavailable or deprecated one.