Merge #19: Add new API call get_block_status

5fbabb8 Add API call get_block_status (Gabriel Comte)

Pull request description:

ACKs for top commit:
  notmandatory:
    ACK 5fbabb8

Tree-SHA512: 40eebc336eec45a10b904daae4a221f630669602e52113d241b643fc7222dcf8171536bb98d2456916be8da3fb5a7bfa1f3fcb99a4702a403ee2ce1577402a3e

Author: notmandatory

src/api.rs

@@ -55,6 +55,13 @@ pub struct OutputStatus {
     pub status: Option<TxStatus>,
 }
 
+#[derive(Deserialize, Clone, Debug, PartialEq, Eq)]
+pub struct BlockStatus {
+    pub in_best_chain: bool,
+    pub height: Option<u32>,
+    pub next_best: Option<BlockHash>,
+}
+
 #[derive(Deserialize, Clone, Debug)]
 pub struct Tx {
     pub txid: Txid,

src/async.rs

@@ -24,7 +24,7 @@ use log::{debug, error, info, trace};
 
 use reqwest::{Client, StatusCode};
 
-use crate::{Builder, Error, MerkleProof, OutputStatus, Tx, TxStatus};
+use crate::{BlockStatus, Builder, Error, MerkleProof, OutputStatus, Tx, TxStatus};
 
 #[derive(Debug)]
 pub struct AsyncClient {
@@ -136,6 +136,17 @@ impl AsyncClient {
         Ok(header)
     }
 
+    /// Get the [`BlockStatus`] given a particular [`BlockHash`].
+    pub async fn get_block_status(&self, block_hash: &BlockHash) -> Result<BlockStatus, Error> {
+        let resp = self
+            .client
+            .get(&format!("{}/block/{}/status", self.url, block_hash))
+            .send()
+            .await?;
+
+        Ok(resp.error_for_status()?.json().await?)
+    }
+
     /// Get a merkle inclusion proof for a [`Transaction`] with the given [`Txid`].
     pub async fn get_merkle_proof(&self, tx_hash: &Txid) -> Result<Option<MerkleProof>, Error> {
         let resp = self

src/blocking.rs

@@ -27,7 +27,7 @@ use bitcoin::hashes::hex::{FromHex, ToHex};
 use bitcoin::hashes::{sha256, Hash};
 use bitcoin::{BlockHash, BlockHeader, Script, Transaction, Txid};
 
-use crate::{Builder, Error, MerkleProof, OutputStatus, Tx, TxStatus};
+use crate::{BlockStatus, Builder, Error, MerkleProof, OutputStatus, Tx, TxStatus};
 
 #[derive(Debug, Clone)]
 pub struct BlockingClient {
@@ -150,6 +150,20 @@ impl BlockingClient {
         }
     }
 
+    /// Get the [`BlockStatus`] given a particular [`BlockHash`].
+    pub fn get_block_status(&self, block_hash: &BlockHash) -> Result<BlockStatus, Error> {
+        let resp = self
+            .agent
+            .get(&format!("{}/block/{}/status", self.url, block_hash))
+            .call();
+
+        match resp {
+            Ok(resp) => Ok(resp.into_json()?),
+            Err(ureq::Error::Status(code, _)) => Err(Error::HttpResponse(code)),
+            Err(e) => Err(Error::Ureq(e)),
+        }
+    }
+
     /// Get a merkle inclusion proof for a [`Transaction`] with the given [`Txid`].
     pub fn get_merkle_proof(&self, txid: &Txid) -> Result<Option<MerkleProof>, Error> {
         let resp = self

src/lib.rs

@@ -460,6 +460,51 @@ mod test {
         assert_eq!(block_header, block_header_async);
     }
 
+    #[cfg(all(feature = "blocking", any(feature = "async", feature = "async-https")))]
+    #[tokio::test]
+    async fn test_get_block_status() {
+        let (blocking_client, async_client) = setup_clients().await;
+
+        let block_hash = BITCOIND.client.get_block_hash(21).unwrap();
+        let next_block_hash = BITCOIND.client.get_block_hash(22).unwrap();
+
+        let expected = BlockStatus {
+            in_best_chain: true,
+            height: Some(21),
+            next_best: Some(next_block_hash),
+        };
+
+        let block_status = blocking_client.get_block_status(&block_hash).unwrap();
+        let block_status_async = async_client.get_block_status(&block_hash).await.unwrap();
+        assert_eq!(expected, block_status);
+        assert_eq!(expected, block_status_async);
+    }
+
+    #[cfg(all(feature = "blocking", any(feature = "async", feature = "async-https")))]
+    #[tokio::test]
+    async fn test_get_non_existing_block_status() {
+        // Esplora returns the same status for orphaned blocks as for non-existing blocks:
+        // non-existing: https://blockstream.info/api/block/0000000000000000000000000000000000000000000000000000000000000000/status
+        // orphaned: https://blockstream.info/api/block/000000000000000000181b1a2354620f66868a723c0c4d5b24e4be8bdfc35a7f/status
+        // (Here the block is cited as orphaned: https://bitcoinchain.com/block_explorer/block/000000000000000000181b1a2354620f66868a723c0c4d5b24e4be8bdfc35a7f/ )
+        // For this reason, we only test for the non-existing case here.
+
+        let (blocking_client, async_client) = setup_clients().await;
+
+        let block_hash = BlockHash::default();
+
+        let expected = BlockStatus {
+            in_best_chain: false,
+            height: None,
+            next_best: None,
+        };
+
+        let block_status = blocking_client.get_block_status(&block_hash).unwrap();
+        let block_status_async = async_client.get_block_status(&block_hash).await.unwrap();
+        assert_eq!(expected, block_status);
+        assert_eq!(expected, block_status_async);
+    }
+
     #[cfg(all(feature = "blocking", any(feature = "async", feature = "async-https")))]
     #[tokio::test]
     async fn test_get_merkle_proof() {