fix(api)!: re-add BlockSummary and get_blocks

Add `BlockSummary` and `get_blocks` with a deprecation warning.

These should be removed for the v0.14.0 release.

Author: luisschwab

src/api.rs

@@ -26,8 +26,8 @@ pub use bitcoin::consensus::{deserialize, serialize};
 pub use bitcoin::hex::FromHex;
 pub use bitcoin::{
     absolute, block, transaction, Address, Amount, Block, BlockHash, CompactTarget, FeeRate,
-    OutPoint, Script, ScriptBuf, ScriptHash, Transaction, TxIn, TxOut, Txid, Weight, Witness,
-    Wtxid,
+    OutPoint, Script, ScriptBuf, ScriptHash, Transaction, TxIn, TxMerkleNode, TxOut, Txid, Weight,
+    Witness, Wtxid,
 };
 
 // ----> TRANSACTION
@@ -219,6 +219,15 @@ pub struct OutputStatus {
 
 // ----> BLOCK
 
+/// The timestamp and height of a [`Block`].
+#[derive(Deserialize, Clone, Debug, PartialEq, Eq)]
+pub struct BlockTime {
+    /// The [`Block`]'s timestamp.
+    pub timestamp: u64,
+    /// The [`Block`]'s height.
+    pub height: u32,
+}
+
 /// The status of a [`Block`].
 #[derive(Deserialize, Clone, Debug, PartialEq, Eq)]
 pub struct BlockStatus {
@@ -231,6 +240,22 @@ pub struct BlockStatus {
     pub next_best: Option<BlockHash>,
 }
 
+// TODO(@luisschwab): remove on `v0.14.0`
+/// Summary about a [`Block`].
+#[deprecated(since = "0.12.3", note = "use `BlockInfo` instead")]
+#[derive(Debug, Clone, Deserialize, PartialEq, Eq)]
+pub struct BlockSummary {
+    /// The [`Block`]'s hash.
+    pub id: BlockHash,
+    /// The [`Block`]'s timestamp and height.
+    #[serde(flatten)]
+    pub time: BlockTime,
+    /// The [`BlockHash`] of the previous [`Block`] (`None` for the genesis [`Block`]).
+    pub previousblockhash: Option<BlockHash>,
+    /// The Merkle root of the [`Block`]'s [`Transaction`]s.
+    pub merkle_root: TxMerkleNode,
+}
+
 /// A summary of a bitcoin [`Block`].
 ///
 /// Contains block metadata as returned by the Esplora API, but not the
@@ -292,15 +317,6 @@ impl PartialEq for BlockInfo {
 }
 impl Eq for BlockInfo {}
 
-/// The timestamp and height of a [`Block`].
-#[derive(Deserialize, Clone, Debug, PartialEq, Eq)]
-pub struct BlockTime {
-    /// The [`Block`]'s timestamp.
-    pub timestamp: u64,
-    /// The [`Block`]'s height.
-    pub height: u32,
-}
-
 // ----> ADDRESS
 
 /// Statistics about an [`Address`].

src/async.rs

@@ -47,6 +47,10 @@ use crate::{
     SubmitPackageResult, TxStatus, Utxo, BASE_BACKOFF_MILLIS, RETRYABLE_ERROR_CODES,
 };
 
+// TODO(@luisschwab): remove on `v0.14.0`
+#[allow(deprecated)]
+use crate::BlockSummary;
+
 /// Returns `true` if the given HTTP status code should trigger a retry.
 ///
 /// See [`RETRYABLE_ERROR_CODES`] for the list of retryable status codes.
@@ -564,6 +568,26 @@ impl<S: Sleeper> AsyncClient<S> {
             .await
     }
 
+    // TODO(@luisschwab): remove on `v0.14.0`
+    /// Gets some recent block summaries starting at the tip or at `height` if
+    /// provided.
+    ///
+    /// The maximum number of summaries returned depends on the backend itself:
+    /// esplora returns `10` while [mempool.space](https://mempool.space/docs/api) returns `15`.
+    #[allow(deprecated)]
+    #[deprecated(since = "0.12.3", note = "use `get_block_infos` instead")]
+    pub async fn get_blocks(&self, height: Option<u32>) -> Result<Vec<BlockSummary>, Error> {
+        let path = match height {
+            Some(height) => format!("/blocks/{height}"),
+            None => "/blocks".to_string(),
+        };
+        let blocks: Vec<BlockSummary> = self.get_response_json(&path).await?;
+        if blocks.is_empty() {
+            return Err(Error::InvalidResponse);
+        }
+        Ok(blocks)
+    }
+
     /// Get a [`BlockInfo`] summary for the [`Block`] with the given [`BlockHash`].
     ///
     /// [`BlockInfo`] includes metadata such as the height, timestamp,

src/blocking.rs

@@ -44,6 +44,10 @@ use crate::{
     TxStatus, Utxo, BASE_BACKOFF_MILLIS, RETRYABLE_ERROR_CODES,
 };
 
+// TODO(@luisschwab): remove on `v0.14.0`
+#[allow(deprecated)]
+use crate::BlockSummary;
+
 /// Returns `true` if the given HTTP status code indicates a successful response.
 fn is_status_ok(status: i32) -> bool {
     status == 200
@@ -554,6 +558,26 @@ impl BlockingClient {
         self.get_response_json(&format!("/block/{block_hash}/status"))
     }
 
+    // TODO(@luisschwab): remove on `v0.14.0`
+    /// Gets some recent block summaries starting at the tip or at `height` if
+    /// provided.
+    ///
+    /// The maximum number of summaries returned depends on the backend itself:
+    /// esplora returns `10` while [mempool.space](https://mempool.space/docs/api) returns `15`.
+    #[allow(deprecated)]
+    #[deprecated(since = "0.12.3", note = "use `get_block_infos` instead")]
+    pub fn get_blocks(&self, height: Option<u32>) -> Result<Vec<BlockSummary>, Error> {
+        let path = match height {
+            Some(height) => format!("/blocks/{height}"),
+            None => "/blocks".to_string(),
+        };
+        let blocks: Vec<BlockSummary> = self.get_response_json(&path)?;
+        if blocks.is_empty() {
+            return Err(Error::InvalidResponse);
+        }
+        Ok(blocks)
+    }
+
     /// Get a [`BlockInfo`] summary for the [`Block`] with the given [`BlockHash`].
     ///
     /// [`BlockInfo`] includes metadata such as the height, timestamp,

src/lib.rs

@@ -767,6 +767,42 @@ mod test {
         assert_eq!(expected, block_status_async);
     }
 
+    // TODO(@luisschwab): remove on `v0.14.0`
+    #[allow(deprecated)]
+    #[cfg(all(feature = "blocking", feature = "async"))]
+    #[tokio::test]
+    async fn test_get_blocks() {
+        let env = TestEnv::new();
+        let (blocking_client, async_client) = env.setup_clients();
+
+        let start_height = env.bitcoind_client().get_block_count().unwrap().0;
+        let blocks1 = blocking_client.get_blocks(None).unwrap();
+        let blocks_async1 = async_client.get_blocks(None).await.unwrap();
+        assert_eq!(blocks1[0].time.height, start_height as u32);
+        assert_eq!(blocks1, blocks_async1);
+        env.mine_and_wait(1);
+
+        let blocks2 = blocking_client.get_blocks(None).unwrap();
+        let blocks_async2 = async_client.get_blocks(None).await.unwrap();
+        assert_eq!(blocks2, blocks_async2);
+        assert_ne!(blocks2, blocks1);
+
+        let blocks3 = blocking_client
+            .get_blocks(Some(start_height as u32))
+            .unwrap();
+        let blocks_async3 = async_client
+            .get_blocks(Some(start_height as u32))
+            .await
+            .unwrap();
+        assert_eq!(blocks3, blocks_async3);
+        assert_eq!(blocks3[0].time.height, start_height as u32);
+        assert_eq!(blocks3, blocks1);
+
+        let blocks_genesis = blocking_client.get_blocks(Some(0)).unwrap();
+        let blocks_genesis_async = async_client.get_blocks(Some(0)).await.unwrap();
+        assert_eq!(blocks_genesis, blocks_genesis_async);
+    }
+
     #[cfg(all(feature = "blocking", feature = "async"))]
     #[tokio::test]
     async fn test_get_block_by_hash() {