Add /blocks API

Not all the fields have been added yet.

Author: LLFourn

src/api.rs

@@ -73,12 +73,22 @@ pub struct Tx {
     pub fee: u64,
 }
 
-#[derive(Deserialize, Clone, Debug)]
+#[derive(Deserialize, Clone, Debug, PartialEq)]
 pub struct BlockTime {
     pub timestamp: u64,
     pub height: u32,
 }
 
+#[derive(Debug, Clone, Deserialize, PartialEq)]
+pub struct BlockSummary {
+    pub id: BlockHash,
+    #[serde(flatten)]
+    pub time: BlockTime,
+    /// Hash of the previous block, will be `None` for the genesis block.
+    pub previousblockhash: Option<bitcoin::BlockHash>,
+    pub merkle_root: bitcoin::TxMerkleNode,
+}
+
 impl Tx {
     pub fn to_tx(&self) -> Transaction {
         Transaction {

src/async.rs

@@ -24,7 +24,7 @@ use log::{debug, error, info, trace};
 
 use reqwest::{Client, StatusCode};
 
-use crate::{BlockStatus, Builder, Error, MerkleProof, OutputStatus, Tx, TxStatus};
+use crate::{BlockStatus, BlockSummary, Builder, Error, MerkleProof, OutputStatus, Tx, TxStatus};
 
 #[derive(Debug)]
 pub struct AsyncClient {
@@ -303,4 +303,24 @@ impl AsyncClient {
             .json::<HashMap<String, f64>>()
             .await?)
     }
+
+    /// 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`.
+    pub async fn get_blocks(&self, height: Option<u32>) -> Result<Vec<BlockSummary>, Error> {
+        let url = match height {
+            Some(height) => format!("{}/blocks/{}", self.url, height),
+            None => format!("{}/blocks", self.url),
+        };
+
+        Ok(self
+            .client
+            .get(&url)
+            .send()
+            .await?
+            .error_for_status()?
+            .json()
+            .await?)
+    }
 }

src/blocking.rs

@@ -27,7 +27,7 @@ use bitcoin::hashes::hex::{FromHex, ToHex};
 use bitcoin::hashes::{sha256, Hash};
 use bitcoin::{Block, BlockHash, BlockHeader, MerkleBlock, Script, Transaction, Txid};
 
-use crate::{BlockStatus, Builder, Error, MerkleProof, OutputStatus, Tx, TxStatus};
+use crate::{BlockStatus, BlockSummary, Builder, Error, MerkleProof, OutputStatus, Tx, TxStatus};
 
 #[derive(Debug, Clone)]
 pub struct BlockingClient {
@@ -344,6 +344,19 @@ impl BlockingClient {
         };
         Ok(self.agent.get(&url).call()?.into_json()?)
     }
+
+    /// 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`.
+    pub fn get_blocks(&self, height: Option<u32>) -> Result<Vec<BlockSummary>, Error> {
+        let url = match height {
+            Some(height) => format!("{}/blocks/{}", self.url, height),
+            None => format!("{}/blocks", self.url),
+        };
+
+        Ok(self.agent.get(&url).call()?.into_json()?)
+    }
 }
 
 fn is_status_not_found(status: u16) -> bool {

src/lib.rs

@@ -756,4 +756,33 @@ mod test {
             .collect();
         assert_eq!(scripthash_txs_txids, scripthash_txs_txids_async);
     }
+
+    #[cfg(all(feature = "blocking", any(feature = "async", feature = "async-https")))]
+    #[tokio::test]
+    async fn test_get_blocks() {
+        let (blocking_client, async_client) = setup_clients().await;
+        let start_height = BITCOIND.client.get_block_count().unwrap();
+        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);
+        generate_blocks_and_wait(10);
+        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);
+    }
 }