Use trait methods for RPCs

Use trait methods instead of inherent methods to define the RPCs to
better allow downstream clients that define their own RPCs. This helps
when different implementations of the ones defined in the client are
required.

Move the error module to the crate root. Create a new `IntoModelError`
error type that carries the RPC method name as context and the original
conversion error as a boxed `source`. Use this error type in both sync
and async clients.

Assisted-by: GPT-5.4

Author: jamillambert

client/src/client_async/error.rs

@@ -3,15 +3,6 @@
 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)]
@@ -27,6 +18,8 @@ pub enum Error {
     UnexpectedStructure,
     /// The daemon returned an error string.
     Returned(String),
+    /// A model conversion error.
+    Model(IntoModelError),
     /// The server version did not match what was expected.
     ServerVersion(UnexpectedServerVersionError),
     /// Missing user/password.
@@ -57,34 +50,6 @@ 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::*;
@@ -99,6 +64,7 @@ impl fmt::Display for Error {
             InvalidCookieFile => write!(f, "invalid cookie file"),
             UnexpectedStructure => write!(f, "the JSON result had an unexpected structure"),
             Returned(ref s) => write!(f, "the daemon returned an error string: {}", s),
+            Model(ref e) => write!(f, "model conversion error: {e}"),
             ServerVersion(ref e) => write!(f, "server version: {}", e),
             MissingUserPassword => write!(f, "missing user and/or password"),
         }
@@ -117,6 +83,7 @@ impl error::Error for Error {
             BitcoinSerialization(ref e) => Some(e),
             Io(ref e) => Some(e),
             ServerVersion(ref e) => Some(e),
+            Model(ref e) => Some(e),
             InvalidCookieFile | UnexpectedStructure | Returned(_) | MissingUserPassword => None,
         }
     }
@@ -147,3 +114,37 @@ impl error::Error for UnexpectedServerVersionError {}
 impl From<UnexpectedServerVersionError> for Error {
     fn from(e: UnexpectedServerVersionError) -> Self { Self::ServerVersion(e) }
 }
+
+/// Error returned when converting an RPC response into a model type fails.
+#[derive(Debug)]
+pub struct IntoModelError {
+    context: &'static str,
+    source: Box<dyn error::Error + Send + Sync + 'static>,
+}
+
+impl IntoModelError {
+    /// Creates a new model conversion error with caller-provided context.
+    pub fn new<E>(context: &'static str, source: E) -> Self
+    where
+        E: error::Error + Send + Sync + 'static,
+    {
+        Self { context, source: Box::new(source) }
+    }
+
+    /// Returns the context for the failed conversion.
+    pub fn context(&self) -> &'static str { self.context }
+}
+
+impl fmt::Display for IntoModelError {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        write!(f, "conversion of {} into a model type failed", self.context)
+    }
+}
+
+impl error::Error for IntoModelError {
+    fn source(&self) -> Option<&(dyn error::Error + 'static)> { Some(&*self.source) }
+}
+
+impl From<IntoModelError> for Error {
+    fn from(e: IntoModelError) -> Self { Self::Model(e) }
+}

client/src/client_async/mod.rs

@@ -10,7 +10,9 @@ use std::fs::File;
 use std::io::{BufRead, BufReader};
 use std::path::PathBuf;
 
-pub use crate::client_async::error::Error;
+pub use error::{Error, IntoModelError, UnexpectedServerVersionError};
+pub use rpcs::BitcoinRpcs;
+
 pub(crate) use crate::{into_json, log_response};
 
 /// Crate-specific Result type.

client/src/client_async/rpcs.rs

@@ -1,100 +1,129 @@
 // SPDX-License-Identifier: CC0-1.0
 
-//! RPC set used by BDK.
+//! RPC methods for the async Bitcoin Core client.
 //! All functions return the version nonspecific, strongly typed types.
 
 use bitcoin::{block, Block, BlockHash, Transaction, Txid};
 use serde_json::value::RawValue;
 
-use crate::client_async::{into_json, Client, Result};
+use super::{into_json, Client, IntoModelError, Result};
 use crate::types::model::{GetBlockFilter, GetBlockHeaderVerbose, GetBlockVerboseOne};
 
-impl Client {
+/// Bitcoin Core RPC methods (v25 to v30).
+///
+/// This trait exposes the Bitcoin Core RPC methods available on [`Client`]. Downstream users
+/// can define their own extension traits with additional methods without risk of
+/// name collision with the methods defined here.
+// `async fn` in traits produces non-`Send` futures by default; we suppress this lint because
+// `BitcoinRpcs` is intended only for use with concrete types (never `dyn BitcoinRpcs`).
+#[allow(async_fn_in_trait)]
+pub trait BitcoinRpcs {
     /// Gets a block by blockhash.
-    pub async fn get_block(&self, hash: &BlockHash) -> Result<Block> {
+    async fn get_block(&self, hash: &BlockHash) -> Result<Block>;
+
+    /// Gets the block count.
+    async fn get_block_count(&self) -> Result<u64>;
+
+    /// Gets the block hash for a height.
+    async fn get_block_hash(&self, height: u32) -> Result<BlockHash>;
+
+    /// Gets the hash of the chain tip.
+    async fn get_best_block_hash(&self) -> Result<BlockHash>;
+
+    /// Gets the block header by blockhash.
+    async fn get_block_header(&self, hash: &BlockHash) -> Result<block::Header>;
+
+    /// Gets the block header with verbose output.
+    async fn get_block_header_verbose(&self, hash: &BlockHash) -> Result<GetBlockHeaderVerbose>;
+
+    /// Gets a block by blockhash with verbose set to 1.
+    async fn get_block_verbose(&self, hash: &BlockHash) -> Result<GetBlockVerboseOne>;
+
+    /// Gets the block filter for a blockhash.
+    async fn get_block_filter(&self, hash: &BlockHash) -> Result<GetBlockFilter>;
+
+    /// Gets the transaction IDs currently in the mempool.
+    async fn get_raw_mempool(&self) -> Result<Vec<Txid>>;
+
+    /// Gets the raw transaction by txid.
+    async fn get_raw_transaction(&self, txid: &Txid) -> Result<Transaction>;
+
+    /// Returns the version integer reported by the server (e.g. `250200` for v25.2.0).
+    async fn server_version(&self) -> Result<usize>;
+}
+
+impl BitcoinRpcs for Client {
+    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)
+        Ok(json.into_model().map_err(|e| IntoModelError::new("`getblock`", e))?.0)
     }
 
-    /// Gets the block count.
-    pub async fn get_block_count(&self) -> Result<u64> {
+    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> {
+    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)
+        Ok(json.into_model().map_err(|e| IntoModelError::new("`getblockhash`", e))?.0)
     }
 
-    /// Gets the hash of the chain tip.
-    pub async fn get_best_block_hash(&self) -> Result<BlockHash> {
+    async fn get_best_block_hash(&self) -> Result<BlockHash> {
         let json: crate::types::v25::GetBestBlockHash = self.call("getbestblockhash", &[]).await?;
-        Ok(json.into_model()?.0)
+        Ok(json.into_model().map_err(|e| IntoModelError::new("`getbestblockhash`", e))?.0)
     }
 
-    /// Gets the block header by blockhash.
-    pub async fn get_block_header(&self, hash: &BlockHash) -> Result<block::Header> {
+    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)
+        Ok(json.into_model().map_err(|e| IntoModelError::new("`getblockheader`", e))?.0)
     }
 
-    /// Gets the block header with verbose output.
-    pub async fn get_block_header_verbose(
-        &self,
-        hash: &BlockHash,
-    ) -> Result<GetBlockHeaderVerbose> {
+    async fn get_block_header_verbose(&self, hash: &BlockHash) -> Result<GetBlockHeaderVerbose> {
         let raw: Box<RawValue> =
             self.call("getblockheader", &[into_json(hash)?, into_json(true)?]).await?;
 
         if let Ok(json) =
             serde_json::from_str::<crate::types::v29::GetBlockHeaderVerbose>(raw.get())
         {
-            Ok(json.into_model()?)
+            Ok(json.into_model().map_err(|e| IntoModelError::new("`getblockheader` verbose", e))?)
         } else {
             let json: crate::types::v25::GetBlockHeaderVerbose = serde_json::from_str(raw.get())?;
-            Ok(json.into_model()?)
+            Ok(json.into_model().map_err(|e| IntoModelError::new("`getblockheader` verbose", e))?)
         }
     }
 
-    /// Gets a block by blockhash with verbose set to 1.
-    pub async fn get_block_verbose(&self, hash: &BlockHash) -> Result<GetBlockVerboseOne> {
+    async fn get_block_verbose(&self, hash: &BlockHash) -> Result<GetBlockVerboseOne> {
         let raw: Box<RawValue> = self.call("getblock", &[into_json(hash)?, into_json(1)?]).await?;
 
         if let Ok(json) = serde_json::from_str::<crate::types::v29::GetBlockVerboseOne>(raw.get()) {
-            Ok(json.into_model()?)
+            Ok(json.into_model().map_err(|e| IntoModelError::new("`getblock` verbose=1", e))?)
         } else {
             let json: crate::types::v25::GetBlockVerboseOne = serde_json::from_str(raw.get())?;
-            Ok(json.into_model()?)
+            Ok(json.into_model().map_err(|e| IntoModelError::new("`getblock` verbose=1", e))?)
         }
     }
 
-    /// Gets the block filter for a blockhash.
-    pub async fn get_block_filter(&self, hash: &BlockHash) -> Result<GetBlockFilter> {
+    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()?)
+        Ok(json.into_model().map_err(|e| IntoModelError::new("`getblockfilter`", e))?)
     }
 
-    /// Gets the transaction IDs currently in the mempool.
-    pub async fn get_raw_mempool(&self) -> Result<Vec<Txid>> {
+    async fn get_raw_mempool(&self) -> Result<Vec<Txid>> {
         let json: crate::types::v25::GetRawMempool = self.call("getrawmempool", &[]).await?;
-        Ok(json.into_model()?.0)
+        Ok(json.into_model().map_err(|e| IntoModelError::new("`getrawmempool`", e))?.0)
     }
 
-    /// Gets the raw transaction by txid.
-    pub async fn get_raw_transaction(&self, txid: &Txid) -> Result<Transaction> {
+    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)
+        Ok(json.into_model().map_err(|e| IntoModelError::new("`getrawtransaction`", e))?.0)
     }
 
-    /// Returns the version integer reported by the server (e.g. `250200` for v25.2.0).
-    pub async fn server_version(&self) -> Result<usize> {
+    async fn server_version(&self) -> Result<usize> {
         // Use a minimal type to read only the `version` field; the shape of other fields
         // (e.g. `warnings` changed from String to Vec<String> at v28) differs across the
         // supported version range.

integration_test/tests/bdk_client.rs

@@ -9,7 +9,7 @@
 use bitcoin::address::KnownHrp;
 use bitcoin::{Address, CompressedPublicKey, PrivateKey};
 use bitcoind::mtype;
-use corepc_client::client_async::{Auth, Client, Error as AsyncClientError};
+use corepc_client::client_async::{Auth, BitcoinRpcs as _, Client, Error as AsyncClientError};
 use integration_test::{BitcoinD, BitcoinDExt as _, Wallet};
 
 fn async_client_for(node: &BitcoinD) -> Client {