bdk-bitcoind-client

A minimal bitcoind RPC client custom built for BDK.

Features

• Multiple Bitcoin Core Version Support: implements support for multiple Bitcoin Core versions in the backend:

  • Bitcoin Core v30.0
  • Bitcoin Core v29.0
  • Bitcoin Core v28.0

• Minimal Dependencies: by default, the minimal bitreq_http is used as the HTTP transport.

• Separation of Concerns: focused on emitting generic data structures, such as blocks, headers and mempool. Interpreting this data is left to wallets that use this crate as a chain-source.

• Robust Error Handling: implements specifc error variants for RPC, deserialization and transport errors.

Usage

Add this to your Cargo.toml manifest to use this crate with the default Bitcoin Core version v28.0 as the backend:

bdk-bitcoind-client = { version = "0.2.0" }

Alternatively, add this to your Cargo.toml manifest to use this crate with a specific Bitcoin Core version as the backend (v29.0 or v30.0):

# Bitcoin Core v29.0
bdk-bitcoind-client = { version = "0.2.0", default-features = false, features = ["29_0"] }

# Bitcoin Core v30.0
bdk-bitcoind-client = { version = "0.2.0", default-features = false, features = ["30_0"] }

Quick Start

use bdk_bitcoind_client::{Auth, Client};
use std::path::PathBuf;
fn main() -> anyhow::Result<()> {
    // Define how to authenticate with `bitcoind` (Cookie File or User/Pass)
    let auth = Auth::CookieFile(PathBuf::from("/path/to/regtest/.cookie"));
    let auth = Auth::UserPass("user".to_string(), "pass".to_string());
    let timeout = std::time::Duration::from_secs(15);

    // Instantiate a JSON-RPC `Client`
    let client = Client::with_auth_timeout("http://127.0.0.1:18443", auth, timeout)?;

    // Perform blockchain queries to `bitcoind` using the `Client`
    let block_count = client.get_block_count()?;
    let best_hash = client.get_block_hash(block_count)?;
    let best_header = client.get_block_header_verbose(&best_hash)?;

    println!("Block Count: {}", block_count);
    println!("Best Block Hash: {}", best_hash);
    println!("Chain Tip: {} at height {}", best_header.hash, best_header.height);

    Ok(())
}

Bitcoin Core Version Compatibility

Bitcoin Core often changes its JSON-RPC schema, such as the addition of the target and difficulty fields in the getmininginfo RPC on Bitcoin Core v29.0 and newer.

This crate manages this via compile-time feature flags:

Feature Flag	Bitcoin Core Version	Notes
30_0	v30.x
29_0	v29.x	Supports target and difficulty fields on getmininginfo
28_0 (default)	v28.x and older	Omits newer fields

Developing

This project uses cargo-rbmt to manage everything related to cargo, such as formatting, linting, testing and CI. To install it, run:

~$ cargo install cargo-rbmt

A justfile is provided for convenient command-running. You must have just installed.

Run just to see available commands:

~$ just
> bdk-bitcoind-client
> An experimental `bitcoind` RPC client for BDK

Available recipes:
    build                # Build the `bdk-bitcoind-client` [alias: b]
    check                # Check code formatting, compilation, and linting [alias: c]
    check-features       # Check that all feature combinations compile [alias: cf]
    check-sigs           # Checks whether all commits in this branch are PGP-signed [alias: cs]
    doc                  # Generate documentation [alias: d]
    doc-open             # Generate and open documetation [alias: do]
    fmt                  # Format code [alias: f]
    lock                 # Regenerate `Cargo-recent.lock` and `Cargo-minimal.lock` [alias: l]
    msrv                 # Verify the library builds with the MSRV toolchain (1.85.0) [alias: m]
    pre-push             # Run pre-push suite: lock, check-sigs, fmt, check, test, and msrv [alias: p]
    test                 # Run all tests on the workspace with all features [alias: t]
    test-version VERSION # Run tests against a specific Bitcoin Core version: 30_0, 29_0, 28_0 [alias: tv]

Minimum Supported Rust Version (MSRV)

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

To build with the MSRV toolchain, copy Cargo-minimal.lock to Cargo.lock.

License

Licensed under either of

• Apache License, Version 2.0 (Apache 2.0 or https://www.apache.org/licenses/LICENSE-2.0)
• MIT License (MIT or https://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.