Make async corepc-client

Edit the copy of the sync client created in the previous commit to be
async. Update the readme and cargo.toml files.

Create a new module for the bdk client that has the required RPCs in it
that all return the non-version specific model types.

Author: jamillambert

client/Cargo.toml

@@ -23,6 +23,8 @@ allowed_duplicates = ["base64"]
 [features]
 # Enable this feature to get a blocking JSON-RPC client.
 client-sync = ["jsonrpc", "jsonrpc/bitreq_http_sync"]
+# Enable this feature to get an async JSON-RPC client.
+client-async = ["jsonrpc", "jsonrpc/bitreq_http_async", "jsonrpc/client_async"]
 
 [dependencies]
 bitcoin = { version = "0.32.0", default-features = false, features = ["std", "serde"] }

client/README.md

@@ -1,7 +1,16 @@
 # corepc-client
 
-Rust client for the Bitcoin Core daemon's JSON-RPC API. Currently this
-is only a blocking client and is intended to be used in integration testing.
+Rust client for the Bitcoin Core daemon's JSON-RPC API.
+
+This crate provides:
+
+- A blocking client intended for integration testing (`client-sync`).
+- An async client intended for production (`client-async`).
+
+## Features
+
+- `client-sync`: Blocking JSON-RPC client.
+- `client-async`: Async JSON-RPC client.
 
 ## Minimum Supported Rust Version (MSRV)
 

client/src/bdk_client/error.rs

@@ -3,6 +3,15 @@
 use std::{error, fmt, io};
 
 use bitcoin::hex;
+use types::v17::{
+    GetBlockHeaderError, GetBlockHeaderVerboseError, GetBlockVerboseOneError,
+    GetRawTransactionVerboseError,
+};
+use types::v19::GetBlockFilterError;
+use types::v29::{
+    GetBlockHeaderVerboseError as GetBlockHeaderVerboseErrorV29,
+    GetBlockVerboseOneError as GetBlockVerboseOneErrorV29,
+};
 
 /// The error type for errors produced in this library.
 #[derive(Debug)]
@@ -48,6 +57,34 @@ impl From<io::Error> for Error {
     fn from(e: io::Error) -> Error { Error::Io(e) }
 }
 
+impl From<GetBlockHeaderError> for Error {
+    fn from(e: GetBlockHeaderError) -> Self { Self::Returned(e.to_string()) }
+}
+
+impl From<GetBlockHeaderVerboseError> for Error {
+    fn from(e: GetBlockHeaderVerboseError) -> Self { Self::Returned(e.to_string()) }
+}
+
+impl From<GetBlockVerboseOneError> for Error {
+    fn from(e: GetBlockVerboseOneError) -> Self { Self::Returned(e.to_string()) }
+}
+
+impl From<GetRawTransactionVerboseError> for Error {
+    fn from(e: GetRawTransactionVerboseError) -> Self { Self::Returned(e.to_string()) }
+}
+
+impl From<GetBlockHeaderVerboseErrorV29> for Error {
+    fn from(e: GetBlockHeaderVerboseErrorV29) -> Self { Self::Returned(e.to_string()) }
+}
+
+impl From<GetBlockVerboseOneErrorV29> for Error {
+    fn from(e: GetBlockVerboseOneErrorV29) -> Self { Self::Returned(e.to_string()) }
+}
+
+impl From<GetBlockFilterError> for Error {
+    fn from(e: GetBlockFilterError) -> Self { Self::Returned(e.to_string()) }
+}
+
 impl fmt::Display for Error {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         use Error::*;

client/src/bdk_client/mod.rs

@@ -1,29 +1,16 @@
 // SPDX-License-Identifier: CC0-1.0
 
-//! JSON-RPC clients for testing against specific versions of Bitcoin Core.
+//! Async JSON-RPC clients for Bitcoin Core v25 to v30.
 
 mod error;
-pub mod v17;
-pub mod v18;
-pub mod v19;
-pub mod v20;
-pub mod v21;
-pub mod v22;
-pub mod v23;
-pub mod v24;
-pub mod v25;
-pub mod v26;
-pub mod v27;
-pub mod v28;
-pub mod v29;
-pub mod v30;
-pub mod v31;
+mod rpcs;
 
+use std::fmt;
 use std::fs::File;
 use std::io::{BufRead, BufReader};
 use std::path::PathBuf;
 
-pub use crate::client_sync::error::Error;
+pub use crate::bdk_client::error::Error;
 
 /// Crate-specific Result type.
 ///
@@ -56,77 +43,63 @@ impl Auth {
     }
 }
 
-/// Defines a `jsonrpc::Client` using `bitreq`.
-#[macro_export]
-macro_rules! define_jsonrpc_bitreq_client {
-    ($version:literal) => {
-        use std::fmt;
+/// Client implements an async JSON-RPC client for the Bitcoin Core daemon or compatible APIs.
+pub struct Client {
+    pub(crate) inner: jsonrpc::client_async::Client,
+}
 
-        use $crate::client_sync::{log_response, Auth, Result};
-        use $crate::client_sync::error::Error;
+impl fmt::Debug for Client {
+    fn fmt(&self, f: &mut fmt::Formatter) -> core::fmt::Result {
+        write!(f, "corepc_client::client_async::Client({:?})", self.inner)
+    }
+}
 
-        /// Client implements a JSON-RPC client for the Bitcoin Core daemon or compatible APIs.
-        pub struct Client {
-            inner: jsonrpc::client::Client,
-        }
+impl Client {
+    /// Creates a client to a bitcoind JSON-RPC server without authentication.
+    pub fn new(url: &str) -> Self {
+        let transport = jsonrpc::bitreq_http_async::Builder::new()
+            .url(url)
+            .expect("jsonrpc v0.19, this function does not error")
+            .timeout(std::time::Duration::from_secs(60))
+            .build();
+        let inner = jsonrpc::client_async::Client::with_transport(transport);
+
+        Self { inner }
+    }
 
-        impl fmt::Debug for Client {
-            fn fmt(&self, f: &mut fmt::Formatter) -> core::fmt::Result {
-                write!(
-                    f,
-                    "corepc_client::client_sync::{}::Client({:?})", $version, self.inner
-                )
-            }
+    /// Creates a client to a bitcoind JSON-RPC server with authentication.
+    pub fn new_with_auth(url: &str, auth: Auth) -> Result<Self> {
+        if matches!(auth, Auth::None) {
+            return Err(Error::MissingUserPassword);
         }
+        let (user, pass) = auth.get_user_pass()?;
+        let user = user.ok_or(Error::MissingUserPassword)?;
+        let transport = jsonrpc::bitreq_http_async::Builder::new()
+            .url(url)
+            .expect("jsonrpc v0.19, this function does not error")
+            .timeout(std::time::Duration::from_secs(60))
+            .basic_auth(user, pass)
+            .build();
+        let inner = jsonrpc::client_async::Client::with_transport(transport);
+
+        Ok(Self { inner })
+    }
 
-        impl Client {
-            /// Creates a client to a bitcoind JSON-RPC server without authentication.
-            pub fn new(url: &str) -> Self {
-                let transport = jsonrpc::http::bitreq_http::Builder::new()
-                    .url(url)
-                    .expect("jsonrpc v0.19, this function does not error")
-                    .timeout(std::time::Duration::from_secs(60))
-                    .build();
-                let inner = jsonrpc::client::Client::with_transport(transport);
-
-                Self { inner }
-            }
-
-            /// Creates a client to a bitcoind JSON-RPC server with authentication.
-            pub fn new_with_auth(url: &str, auth: Auth) -> Result<Self> {
-                if matches!(auth, Auth::None) {
-                    return Err(Error::MissingUserPassword);
-                }
-                let (user, pass) = auth.get_user_pass()?;
-
-                let transport = jsonrpc::http::bitreq_http::Builder::new()
-                    .url(url)
-                    .expect("jsonrpc v0.19, this function does not error")
-                    .timeout(std::time::Duration::from_secs(60))
-                    .basic_auth(user.unwrap(), pass)
-                    .build();
-                let inner = jsonrpc::client::Client::with_transport(transport);
-
-                Ok(Self { inner })
-            }
-
-            /// Call an RPC `method` with given `args` list.
-            pub fn call<T: for<'a> serde::de::Deserialize<'a>>(
-                &self,
-                method: &str,
-                args: &[serde_json::Value],
-            ) -> Result<T> {
-                let raw = serde_json::value::to_raw_value(args)?;
-                let req = self.inner.build_request(&method, Some(&*raw));
-                if log::log_enabled!(log::Level::Debug) {
-                    log::debug!(target: "corepc", "request: {} {}", method, serde_json::Value::from(args));
-                }
-
-                let resp = self.inner.send_request(req).map_err(Error::from);
-                log_response(method, &resp);
-                Ok(resp?.result()?)
-            }
+    /// Call an RPC `method` with given `args` list.
+    pub async fn call<T: for<'a> serde::de::Deserialize<'a>>(
+        &self,
+        method: &str,
+        args: &[serde_json::Value],
+    ) -> Result<T> {
+        let raw = serde_json::value::to_raw_value(args)?;
+        let req = self.inner.build_request(method, Some(&*raw));
+        if log::log_enabled!(log::Level::Debug) {
+            log::debug!(target: "corepc", "request: {} {}", method, serde_json::Value::from(args));
         }
+
+        let resp = self.inner.send_request(req).await.map_err(Error::from);
+        log_response(method, &resp);
+        Ok(resp?.result()?)
     }
 }
 
@@ -139,14 +112,14 @@ macro_rules! define_jsonrpc_bitreq_client {
 ///
 /// - `$expected_versions`: An vector of expected server versions e.g., `[230100, 230200]`.
 #[macro_export]
-macro_rules! impl_client_check_expected_server_version {
+macro_rules! impl_async_client_check_expected_server_version {
     ($expected_versions:expr) => {
         impl Client {
             /// Checks that the JSON-RPC endpoint is for a `bitcoind` instance with the expected version.
-            pub fn check_expected_server_version(&self) -> Result<()> {
-                let server_version = self.server_version()?;
+            pub async fn check_expected_server_version(&self) -> Result<()> {
+                let server_version = self.server_version().await?;
                 if !$expected_versions.contains(&server_version) {
-                    return Err($crate::client_sync::error::UnexpectedServerVersionError {
+                    return Err($crate::bdk_client::error::UnexpectedServerVersionError {
                         got: server_version,
                         expected: $expected_versions.to_vec(),
                     })?;
@@ -158,7 +131,7 @@ macro_rules! impl_client_check_expected_server_version {
 }
 
 /// Shorthand for converting a variable into a `serde_json::Value`.
-fn into_json<T>(val: T) -> Result<serde_json::Value>
+pub(crate) fn into_json<T>(val: T) -> Result<serde_json::Value>
 where
     T: serde::ser::Serialize,
 {
@@ -181,10 +154,12 @@ fn log_response(method: &str, resp: &Result<jsonrpc::Response>) {
                         log::debug!(target: "corepc", "response error for {}: {:?}", method, e);
                     }
                 } else if log::log_enabled!(Trace) {
-                    let def =
-                        serde_json::value::to_raw_value(&serde_json::value::Value::Null).unwrap();
-                    let result = resp.result.as_ref().unwrap_or(&def);
-                    log::trace!(target: "corepc", "response for {}: {}", method, result);
+                    if let Ok(def) =
+                        serde_json::value::to_raw_value(&serde_json::value::Value::Null)
+                    {
+                        let result = resp.result.as_ref().unwrap_or(&def);
+                        log::trace!(target: "corepc", "response for {}: {}", method, result);
+                    }
                 },
         }
     }

client/src/bdk_client/rpcs.rs

@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: CC0-1.0
+
+//! RPC set used by BDK.
+//! All functions return the version nonspecific, strongly typed types.
+
+use bitcoin::{block, Block, BlockHash, Transaction, Txid};
+
+use crate::bdk_client::{into_json, Client, Result};
+use crate::types::model::{GetBlockFilter, GetBlockHeaderVerbose, GetBlockVerboseOne};
+
+impl Client {
+    /// Gets a block by blockhash.
+    pub async fn get_block(&self, hash: &BlockHash) -> Result<Block> {
+        let json: crate::types::v25::GetBlockVerboseZero =
+            self.call("getblock", &[into_json(hash)?, into_json(0)?]).await?;
+        Ok(json.into_model()?.0)
+    }
+
+    /// Gets the block count.
+    pub async fn get_block_count(&self) -> Result<u64> {
+        let json: crate::types::v25::GetBlockCount = self.call("getblockcount", &[]).await?;
+        Ok(json.into_model().0)
+    }
+
+    /// Gets the block hash for a height.
+    pub async fn get_block_hash(&self, height: u32) -> Result<BlockHash> {
+        let json: crate::types::v25::GetBlockHash =
+            self.call("getblockhash", &[into_json(height)?]).await?;
+        Ok(json.into_model()?.0)
+    }
+
+    /// Gets the hash of the chain tip.
+    pub async fn get_best_block_hash(&self) -> Result<BlockHash> {
+        let json: crate::types::v25::GetBestBlockHash = self.call("getbestblockhash", &[]).await?;
+        Ok(json.into_model()?.0)
+    }
+
+    /// Gets the block header by blockhash.
+    pub async fn get_block_header(&self, hash: &BlockHash) -> Result<block::Header> {
+        let json: crate::types::v25::GetBlockHeader =
+            self.call("getblockheader", &[into_json(hash)?, into_json(false)?]).await?;
+        Ok(json.into_model()?.0)
+    }
+
+    /// Gets the block header with verbose output.
+    pub async fn get_block_header_verbose(
+        &self,
+        hash: &BlockHash,
+    ) -> Result<GetBlockHeaderVerbose> {
+        let response: serde_json::Value =
+            self.call("getblockheader", &[into_json(hash)?, into_json(true)?]).await?;
+
+        if let Ok(json) =
+            serde_json::from_value::<crate::types::v29::GetBlockHeaderVerbose>(response.clone())
+        {
+            Ok(json.into_model()?)
+        } else {
+            let json: crate::types::v25::GetBlockHeaderVerbose = serde_json::from_value(response)?;
+            Ok(json.into_model()?)
+        }
+    }
+
+    /// Gets a block by blockhash with verbose set to 1.
+    pub async fn get_block_verbose(&self, hash: &BlockHash) -> Result<GetBlockVerboseOne> {
+        let response: serde_json::Value =
+            self.call("getblock", &[into_json(hash)?, into_json(1)?]).await?;
+
+        if let Ok(json) =
+            serde_json::from_value::<crate::types::v29::GetBlockVerboseOne>(response.clone())
+        {
+            Ok(json.into_model()?)
+        } else {
+            let json: crate::types::v25::GetBlockVerboseOne = serde_json::from_value(response)?;
+            Ok(json.into_model()?)
+        }
+    }
+
+    /// Gets the block filter for a blockhash.
+    pub async fn get_block_filter(&self, hash: &BlockHash) -> Result<GetBlockFilter> {
+        let json: crate::types::v25::GetBlockFilter =
+            self.call("getblockfilter", &[into_json(hash)?]).await?;
+        Ok(json.into_model()?)
+    }
+
+    /// Gets the transaction IDs currently in the mempool.
+    pub async fn get_raw_mempool(&self) -> Result<Vec<Txid>> {
+        let json: crate::types::v25::GetRawMempool = self.call("getrawmempool", &[]).await?;
+        Ok(json.into_model()?.0)
+    }
+
+    /// Gets the raw transaction by txid.
+    pub async fn get_raw_transaction(&self, txid: &Txid) -> Result<Transaction> {
+        let json: crate::types::v25::GetRawTransaction =
+            self.call("getrawtransaction", &[into_json(txid)?]).await?;
+        Ok(json.into_model()?.0)
+    }
+}

client/src/lib.rs

@@ -11,3 +11,6 @@ pub extern crate types;
 #[cfg(feature = "client-sync")]
 #[macro_use]
 pub mod client_sync;
+
+#[cfg(feature = "client-async")]
+pub mod bdk_client;