feat: Add integration tests

- add integration tests for blockchain methods

Author: tvpeter

src/client.rs

@@ -2,32 +2,43 @@ use std::{
     fs::File,
     io::{BufRead, BufReader},
     path::PathBuf,
-    str::FromStr,
 };
 
 use crate::error::Error;
 use crate::jsonrpc::minreq_http::Builder;
 use corepc_types::{
     bitcoin::{
-        Block, BlockHash, Transaction, Txid, block::Header, consensus::deserialize, hex::FromHex,
+        block::Header,
+        consensus::{deserialize, encode::deserialize_hex},
+        hex::FromHex,
+        Block, BlockHash, Transaction, Txid,
     },
-    model::{GetBlockCount, GetBlockFilter, GetBlockVerboseOne, GetRawMempool},
+    model::{GetBlockCount, GetBlockFilter, GetRawMempool},
+    v29::GetBlockVerboseOne,
 };
 use jsonrpc::{
-    Transport, serde,
+    serde,
     serde_json::{self, json},
+    Transport,
 };
 
-/// client authentication methods
+/// Client authentication methods for the Bitcoin Core JSON-RPC server
 #[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
 pub enum Auth {
+    /// No authentication (not recommended)
     None,
+    /// Username and password authentication (RPC user/pass)
     UserPass(String, String),
+    /// Authentication via a cookie file
     CookieFile(PathBuf),
 }
 
 impl Auth {
-    /// Convert into the arguments that jsonrpc::Client needs.
+    /// Converts `Auth` enum into the optional username and password strings
+    /// required by JSON-RPC client transport.
+    ///
+    /// # Errors
+    /// Returns an error if the `CookieFile` cannot be read or invalid
     pub fn get_user_pass(self) -> Result<(Option<String>, Option<String>), Error> {
         match self {
             Auth::None => Ok((None, None)),
@@ -44,18 +55,28 @@ impl Auth {
     }
 }
 
-// RPC Client.
+/// Bitcoin Core JSON-RPC Client.
+///
+/// A wrapper for JSON-RPC client for interacting with the `bitcoind` RPC interface.
 #[derive(Debug)]
 pub struct Client {
     /// The inner JSON-RPC client.
     inner: jsonrpc::Client,
 }
 
 impl Client {
-    /// Creates a client to a bitcoind JSON-RPC server.
+    /// Creates a client connection to a bitcoind JSON-RPC server with authentication
     ///
     /// Requires authentication via username/password or cookie file.
     /// For connections without authentication, use `with_transport` instead.
+    /// # Arguments
+    /// * `url` - URL of the RPC server
+    /// * `auth` - authentication method (`UserPass` or `CookieFile`).
+    ///
+    /// # Errors
+    /// * Returns `Error::MissingAuthentication` if `Auth::None` is provided.
+    /// * Returns `Error::InvalidResponse` if the URL is invalid.
+    /// * Returns errors related to reading the cookie file.
     pub fn with_auth(url: &str, auth: Auth) -> Result<Self, Error> {
         if matches!(auth, Auth::None) {
             return Err(Error::MissingAuthentication);
@@ -95,7 +116,9 @@ impl Client {
         }
     }
 
-    /// Calls the RPC `method` with a given `args` list.
+    /// Calls the underlying RPC `method` with given `args` list
+    ///
+    /// This is the generic function used by all specific RPC methods.
     pub fn call<T>(&self, method: &str, args: &[serde_json::Value]) -> Result<T, Error>
     where
         T: for<'de> serde::Deserialize<'de>,
@@ -108,66 +131,82 @@ impl Client {
     }
 }
 
-// `bitcoind` RPC methods
+// `bitcoind` RPC methods implementation for `Client`
 impl Client {
-    /// Get block
+    /// Retrieves the raw block data for a given block hash (verbosity 0)
+    ///
+    /// # Arguments
+    /// * `block_hash`: The hash of the block to retrieve.
+    ///
+    /// # Returns
+    /// The deserialized `Block` struct.
     pub fn get_block(&self, block_hash: &BlockHash) -> Result<Block, Error> {
         let hex_string: String = self.call("getblock", &[json!(block_hash), json!(0)])?;
-
-        let bytes: Vec<u8> = Vec::<u8>::from_hex(&hex_string).map_err(Error::HexToBytes)?;
-
-        let block: Block = deserialize(&bytes)
-            .map_err(|e| Error::InvalidResponse(format!("failed to deserialize block: {e}")))?;
-
+        let block = deserialize_hex(&hex_string).map_err(Error::DecodeHex)?;
         Ok(block)
     }
 
-    /// Get block verboseone
+    /// Retrieves the verbose JSON representation of a block (verbosity 1)
+    /// # Arguments
+    /// * `block_hash`: The hash of the block to retrieve.
+    ///
+    /// # Returns
+    /// The verbose block data as a `GetBlockVerboseOne` struct.
     pub fn get_block_verbose(&self, block_hash: &BlockHash) -> Result<GetBlockVerboseOne, Error> {
-        let res: GetBlockVerboseOne = self.call("getblock", &[json!(block_hash), json!(1)])?;
-        Ok(res)
+        let block_verbose_one: GetBlockVerboseOne =
+            self.call("getblock", &[json!(block_hash), json!(1)])?;
+        Ok(block_verbose_one)
     }
 
-    /// Get best block hash
+    /// Retrieves the hash of the tip of the best block chain.
+    ///
+    /// # Returns
+    /// The `BlockHash` of the chain tip.
     pub fn get_best_block_hash(&self) -> Result<BlockHash, Error> {
         let res: String = self.call("getbestblockhash", &[])?;
         Ok(res.parse()?)
     }
 
-    /// Get block count
+    /// Retrieves the number of blocks in the longest chain
+    ///
+    /// # Returns
+    /// The block count as a `u64`
     pub fn get_block_count(&self) -> Result<u64, Error> {
         let res: GetBlockCount = self.call("getblockcount", &[])?;
         Ok(res.0)
     }
 
-    /// Get block hash
+    /// Retrieves the block hash at a given height
+    ///
+    /// # Arguments
+    /// * `height`: The block height
+    ///
+    /// # Returns
+    /// The `BlockHash` for the given height
     pub fn get_block_hash(&self, height: u32) -> Result<BlockHash, Error> {
-        let raw: serde_json::Value = self.call("getblockhash", &[json!(height)])?;
-
-        let hash_str = match raw {
-            serde_json::Value::String(s) => s,
-            serde_json::Value::Object(obj) => obj
-                .get("hash")
-                .and_then(|v| v.as_str())
-                .ok_or_else(|| Error::InvalidResponse("getblockhash: missing 'hash' field".into()))?
-                .to_string(),
-            _ => {
-                return Err(Error::InvalidResponse(
-                    "getblockhash: unexpected response type".into(),
-                ));
-            }
-        };
-
-        BlockHash::from_str(&hash_str).map_err(Error::HexToArray)
+        let hex: String = self.call("getblockhash", &[json!(height)])?;
+        Ok(hex.parse()?)
     }
 
-    /// Get block filter
-    pub fn get_block_filter(&self, block_hash: BlockHash) -> Result<GetBlockFilter, Error> {
+    /// Retrieves the compact block filter for a given block
+    ///
+    /// # Arguments
+    /// * `block_hash`: The hash of the block whose filter is requested
+    ///
+    /// # Returns
+    /// The `GetBlockFilter` structure containing the filter data
+    pub fn get_block_filter(&self, block_hash: &BlockHash) -> Result<GetBlockFilter, Error> {
         let res: GetBlockFilter = self.call("getblockfilter", &[json!(block_hash)])?;
         Ok(res)
     }
 
-    /// Get block header
+    /// Retrieves the raw block header for a given block hash.
+    ///
+    /// # Arguments
+    /// * `block_hash`: The hash of the block whose header is requested.
+    ///
+    /// # Returns
+    /// The deserialized `Header` struct
     pub fn get_block_header(&self, block_hash: &BlockHash) -> Result<Header, Error> {
         let hex_string: String = self.call("getblockheader", &[json!(block_hash), json!(false)])?;
 
@@ -180,13 +219,22 @@ impl Client {
         Ok(header)
     }
 
-    /// Get raw mempool
+    /// Retrieves the transaction IDs of all transactions currently in the mempool
+    ///
+    /// # Returns
+    /// A vector of `Txid`s in the raw mempool
     pub fn get_raw_mempool(&self) -> Result<Vec<Txid>, Error> {
         let res: GetRawMempool = self.call("getrawmempool", &[])?;
         Ok(res.0)
     }
 
-    /// Get raw transaction
+    /// Retrieves the raw transaction data for a given transaction ID.
+    ///
+    /// # Arguments
+    /// * `txid`: The transaction ID to retrieve.
+    ///
+    /// # Returns
+    /// The deserialized `Transaction` struct
     pub fn get_raw_transaction(&self, txid: &Txid) -> Result<Transaction, Error> {
         let hex_string: String = self.call("getrawtransaction", &[json!(txid)])?;
 

src/error.rs

@@ -2,7 +2,10 @@
 
 use std::{fmt, io};
 
-use corepc_types::bitcoin::hex::{HexToArrayError, HexToBytesError};
+use corepc_types::bitcoin::{
+    consensus,
+    hex::{HexToArrayError, HexToBytesError},
+};
 use jsonrpc::serde_json;
 
 /// Result type alias for the RPC client.
@@ -11,6 +14,9 @@ pub type Result<T> = std::result::Result<T, Error>;
 /// Errors that can occur when using the Bitcoin RPC client.
 #[derive(Debug)]
 pub enum Error {
+    /// Hex deserialization error
+    DecodeHex(consensus::encode::FromHexError),
+
     /// Missing authentication credentials.
     MissingAuthentication,
 
@@ -49,6 +55,7 @@ impl fmt::Display for Error {
             Error::JsonRpc(e) => write!(f, "JSON-RPC error: {e}"),
             Error::Json(e) => write!(f, "JSON error: {e}"),
             Error::Io(e) => write!(f, "I/O error: {e}"),
+            Error::DecodeHex(e) => write!(f, "Hex deserialization error: {e}"),
         }
     }
 }
@@ -61,6 +68,7 @@ impl std::error::Error for Error {
             Error::Io(e) => Some(e),
             Error::HexToBytes(e) => Some(e),
             Error::HexToArray(e) => Some(e),
+            Error::DecodeHex(e) => Some(e),
             _ => None,
         }
     }