Merge #311: Address all TODO in v25

f675362 Add scanblocks method model and test (Jamil Lambert, PhD)

Pull request description:

  Go through all the TODO in the v25 types table. Add all the missing RPCs.

  One missing RPC in v25, `scanblocks` which has 3 different return shapes, one each  for `abort`, `start` and `status`. Create a struct for each one.

  `status` returns null if there is no ongoing scan, use an Option in the client macro to deal with this.

ACKs for top commit:
  tcharding:
    ACK f675362

Tree-SHA512: ad3fda4a9e7427d61925b2b0cc358259d3e1e24cfb28821e0aec117750ddbd800dd93b7a783ac7018c0a634fc56a7078757c96b214b6994bde4045381959ef6f

Author: tcharding

client/src/client_sync/v25/blockchain.rs

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: CC0-1.0
+
+//! Macros for implementing JSON-RPC methods on a client.
+//!
+//! Specifically this is methods found under the `== Blockchain ==` section of the
+//! API docs of Bitcoin Core `v25`.
+//!
+//! All macros require `Client` to be in scope.
+//!
+//! See or use the `define_jsonrpc_minreq_client!` macro to define a `Client`.
+
+/// Implements Bitcoin Core JSON-RPC API method `scanblocks`
+#[macro_export]
+macro_rules! impl_client_v25__scan_blocks {
+    () => {
+        impl Client {
+            /// Aborts an ongoing `scanblocks` scan.
+            pub fn scan_blocks_abort(&self) -> Result<ScanBlocksAbort> {
+                self.call("scanblocks", &[into_json("abort")?])
+            }
+
+            /// Starts a scan of blocks for specified descriptors.
+            pub fn scan_blocks_start(&self, scan_objects: &[&str]) -> Result<ScanBlocksStart> {
+                self.call("scanblocks", &[into_json("start")?, into_json(scan_objects)?])
+            }
+
+            /// Checks the status of an ongoing `scanblocks` scan.
+            pub fn scan_blocks_status(&self) -> Result<Option<ScanBlocksStatus>> {
+                self.call("scanblocks", &[into_json("status")?])
+            }
+        }
+    };
+}

client/src/client_sync/v25/mod.rs

@@ -4,6 +4,7 @@
 //!
 //! We ignore option arguments unless they effect the shape of the returned JSON data.
 
+pub mod blockchain;
 pub mod generating;
 
 use std::collections::BTreeMap;
@@ -54,6 +55,7 @@ crate::impl_client_v24__get_tx_spending_prevout!();
 crate::impl_client_v17__precious_block!();
 crate::impl_client_v17__prune_blockchain!();
 crate::impl_client_v23__save_mempool!();
+crate::impl_client_v25__scan_blocks!();
 crate::impl_client_v17__verify_chain!();
 crate::impl_client_v17__verify_tx_out_proof!();
 

client/src/client_sync/v26/mod.rs

@@ -56,6 +56,7 @@ crate::impl_client_v24__get_tx_spending_prevout!();
 crate::impl_client_v17__precious_block!();
 crate::impl_client_v17__prune_blockchain!();
 crate::impl_client_v23__save_mempool!();
+crate::impl_client_v25__scan_blocks!();
 crate::impl_client_v17__verify_chain!();
 crate::impl_client_v17__verify_tx_out_proof!();
 

client/src/client_sync/v27/mod.rs

@@ -52,6 +52,7 @@ crate::impl_client_v24__get_tx_spending_prevout!();
 crate::impl_client_v17__precious_block!();
 crate::impl_client_v17__prune_blockchain!();
 crate::impl_client_v23__save_mempool!();
+crate::impl_client_v25__scan_blocks!();
 crate::impl_client_v17__verify_chain!();
 crate::impl_client_v17__verify_tx_out_proof!();
 

client/src/client_sync/v28/mod.rs

@@ -54,6 +54,7 @@ crate::impl_client_v24__get_tx_spending_prevout!();
 crate::impl_client_v17__precious_block!();
 crate::impl_client_v17__prune_blockchain!();
 crate::impl_client_v23__save_mempool!();
+crate::impl_client_v25__scan_blocks!();
 crate::impl_client_v17__verify_chain!();
 crate::impl_client_v17__verify_tx_out_proof!();
 

client/src/client_sync/v29/mod.rs

@@ -54,6 +54,7 @@ crate::impl_client_v24__get_tx_spending_prevout!();
 crate::impl_client_v17__precious_block!();
 crate::impl_client_v17__prune_blockchain!();
 crate::impl_client_v23__save_mempool!();
+crate::impl_client_v25__scan_blocks!();
 crate::impl_client_v17__verify_chain!();
 crate::impl_client_v17__verify_tx_out_proof!();
 

integration_test/tests/blockchain.rs

@@ -373,6 +373,23 @@ fn blockchain__savemempool() {
     }
 }
 
+#[cfg(not(feature = "v24_and_below"))]
+#[test]
+fn blockchain__scan_blocks_modelled() {
+    let node = Node::with_wallet(Wallet::None, &["-blockfilterindex=1"]);
+
+    // Arbitrary scan descriptor
+    let scan_desc = "pkh(022afc20bf379bc96a2f4e9e63ffceb8652b2b6a097f63fbee6ecec2a49a48010e)";
+
+    let json: ScanBlocksStart = node.client.scan_blocks_start(&[scan_desc]).expect("scanblocks start");
+    let model: Result<mtype::ScanBlocksStart, ScanBlocksStartError> = json.into_model();
+    model.unwrap();
+
+    let _: Option<ScanBlocksStatus> = node.client.scan_blocks_status().expect("scanblocks status");
+
+    let _: ScanBlocksAbort = node.client.scan_blocks_abort().expect("scanblocks abort");
+}
+
 #[test]
 fn blockchain__verify_tx_out_proof__modelled() {
     let node = Node::with_wallet(Wallet::Default, &[]);

types/src/model/blockchain.rs

@@ -702,3 +702,14 @@ pub struct ReceiveActivity {
     /// The ScriptPubKey.
     pub output_spk: ScriptPubkey,
 }
+
+/// Models the result of the JSON-RPC method `scanblocks` start.
+#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
+pub struct ScanBlocksStart {
+    /// The height we started the scan from
+    pub from_height: u32,
+    /// The height we ended the scan at
+    pub to_height: u32,
+    /// Blocks that may have matched a scanobject
+    pub relevant_blocks: Vec<BlockHash>,
+}

types/src/model/mod.rs

@@ -29,8 +29,8 @@ pub use self::{
         GetMempoolAncestors, GetMempoolAncestorsVerbose, GetMempoolDescendants,
         GetMempoolDescendantsVerbose, GetMempoolEntry, GetMempoolInfo, GetRawMempool,
         GetRawMempoolVerbose, GetTxOut, GetTxOutSetInfo, GetTxSpendingPrevout,
-        GetTxSpendingPrevoutItem, MempoolEntry, MempoolEntryFees, ReceiveActivity, Softfork,
-        SoftforkType, SpendActivity, VerifyTxOutProof,
+        GetTxSpendingPrevoutItem, MempoolEntry, MempoolEntryFees, ReceiveActivity, ScanBlocksStart,
+        Softfork, SoftforkType, SpendActivity, VerifyTxOutProof,
     },
     generating::{Generate, GenerateBlock, GenerateToAddress, GenerateToDescriptor},
     mining::{

types/src/v25/blockchain/error.rs

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: CC0-1.0
+
+use core::fmt;
+
+use bitcoin::hex;
+
+use crate::error::write_err;
+use crate::NumericError;
+
+/// Error when converting a `ScanBlocksStart` type into the model type.
+#[derive(Debug)]
+pub enum ScanBlocksStartError {
+    /// Conversion of numeric type to expected type failed.
+    Numeric(NumericError),
+    /// Conversion of the `relevant_blocks` field failed.
+    RelevantBlocks(hex::HexToArrayError),
+}
+
+impl fmt::Display for ScanBlocksStartError {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        use ScanBlocksStartError as E;
+
+        match *self {
+            E::Numeric(ref e) => write_err!(f, "numeric"; e),
+            E::RelevantBlocks(ref e) =>
+                write_err!(f, "conversion of the `relevant_blocks` field failed"; e),
+        }
+    }
+}
+
+#[cfg(feature = "std")]
+impl std::error::Error for ScanBlocksStartError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        use ScanBlocksStartError as E;
+
+        match *self {
+            E::Numeric(ref e) => Some(e),
+            E::RelevantBlocks(ref e) => Some(e),
+        }
+    }
+}
+
+impl From<NumericError> for ScanBlocksStartError {
+    fn from(e: NumericError) -> Self { Self::Numeric(e) }
+}