Merge #143: feat: implement missing methods

cb0f920 refactor(api): rename BlockInformation -> BlockInfo (valued mammal)
e4d9e4b docs: update rustdoc links (valued mammal)
5d8bcf8 chore(deps): pin `tracing` to 0.1.41, pin `log` to 0.4.28 for MSRV (Luis Schwab)
eed3bdb feat(test): add unified test for mempool methods (Luis Schwab)
cd1cbf6 feat(client): add `get_scripthash_utxos` method (Luis Schwab)
758e157 feat(client): add `get_block_txs` method (Luis Schwab)
29df7f3 feat(client): add `get_block_txids` method (Luis Schwab)
b1930eb feat(client): add `get_block_info` method (Luis Schwab)
d623d46 feat(client): add `get_mempool_txids` method (Luis Schwab)
1043e01 feat(client): add `get_mempool_recent_txs` method (Luis Schwab)
68aadc4 feat(client): add `get_mempool_stats` method (Luis Schwab)
ab4fdde feat(client): add `get_mempool_scripthash_txs` method (Luis Schwab)
b24fe96 feat(client): add `get_mempool_address_txs` method (Luis Schwab)
d2c1128 feat(client): add `get_scripthash_stats` method (Luis Schwab)
35f6a04 feat(client): add `get_tx_outspends` method (Luis Schwab)
a5af9f8 feat(api): add `MempoolStats` and `MempoolRecentTx` structs (Luis Schwab)
c910ab0 feat(api): add `ScriptHashStats` and `ScriptHashTxsSummary` structs (Luis Schwab)
1bb149e feat(api): add `BlockInformation` struct (Luis Schwab)
49b8276 chore(cargo): add `Bitcoin Dev Kit Developers` to `authors` field (Luis Schwab)

Pull request description:

  This PR implements the missing methods needed to be feature complete with the [Esplora API specification](https://github.com/Blockstream/esplora/blob/master/API.md).

  Also adds `Bitcoin Dev Kit Developers` to `authors` on `Cargo.toml`, pins tracing to 0.1.41, and log to 0.4.28 for the 1.63.0 MSRV.

  ## Changelog
  - Add `OutputSpendStatus` struct
  - Add `ScriptHashTxsSummary` and `ScriptHashStats` structs
  - Add `BlockInformation` struct
  - Add `MempoolStats` struct
  - Add `MempoolRecentTxs` struct
  - Add `InvalidStartIndexValue` error variant
  - Add `get_tx_outspends` method (`GET /tx/:txid/outspends`)
  - Add `get_scripthash_stats` method (`GET /scripthash/:hash`)
  - Add `get_mempool_address_txs` method (`GET /address/:address/txs/mempool`)
  - Add `get_mempool_scripthash_txs` method (`GET /scripthash/:hash/txs/mempool`)
  - Add `get_scripthash_utxos` method (`GET /scripthash/:hash/utxo`)
  - Add `get_block_info` method (`GET /block/:hash`)
  - Add `get_block_txids` method (`GET /block/:hash/txids`)
  - Add `get_block_txs` method (`GET /block/:hash/txs[/:start_index]`)
  - Add `get_mempool_stats` method (`GET /mempool`)
  - Add `get_mempool_txids` method (`GET /mempool/txids`)
  - Add `get_mempool_recent_txids` method (`GET /mempool/recent`)

ACKs for top commit:
  ValuedMammal:
    ACK cb0f920

Tree-SHA512: 08e8452cf1100b33b07120ec736f0ccd1d05687b55cdbc7a2ee93229ad32d18fb4d62942208f6dadf85eca73790f9739382d32716492020ccfee6af803165ea1

Author: ValuedMammal

.github/workflows/cont_integration.yml

@@ -60,6 +60,7 @@ jobs:
         cargo update -p ring --precise "0.17.12"
         cargo update -p flate2 --precise "1.0.35"
         cargo update -p once_cell --precise "1.20.3"
+        cargo update -p tracing --precise "0.1.41"
         cargo update -p tracing-core --precise "0.1.33"
         cargo update -p parking_lot --precise "0.12.3"
         cargo update -p parking_lot_core --precise "0.9.10"
@@ -70,6 +71,7 @@ jobs:
         cargo update -p openssl-sys --precise "0.9.109"
         cargo update -p syn --precise "2.0.106"
         cargo update -p quote --precise "1.0.41"
+        cargo update -p log --precise "0.4.28"
 
         cargo update -p bzip2-sys --precise "0.1.12+1.0.8" # dev-dependency
     - name: Build

Cargo.toml

@@ -2,7 +2,10 @@
 name = "esplora-client"
 version = "0.12.1"
 edition = "2021"
-authors = ["Alekos Filini <alekos.filini@gmail.com>"]
+authors = [
+  "Alekos Filini <alekos.filini@gmail.com>",
+  "Bitcoin Dev Kit Developers"
+]
 license = "MIT"
 homepage = "https://github.com/bitcoindevkit/rust-esplora-client"
 repository = "https://github.com/bitcoindevkit/rust-esplora-client"

README.md

@@ -29,6 +29,7 @@ cargo update -p native-tls --precise "0.2.13"
 cargo update -p ring --precise "0.17.12"
 cargo update -p flate2 --precise "1.0.35"
 cargo update -p once_cell --precise "1.20.3"
+cargo update -p tracing --precise "0.1.41"
 cargo update -p tracing-core --precise "0.1.33"
 cargo update -p parking_lot --precise "0.12.3"
 cargo update -p parking_lot_core --precise "0.9.10"
@@ -39,4 +40,5 @@ cargo update -p openssl --precise "0.10.73"
 cargo update -p openssl-sys --precise "0.9.109"
 cargo update -p syn --precise "2.0.106"
 cargo update -p quote --precise "1.0.41"
+cargo update -p log --precise "0.4.28"
 ```

src/api.rs

@@ -2,15 +2,16 @@
 //!
 //! See: <https://github.com/Blockstream/esplora/blob/master/API.md>
 
+use bitcoin::hash_types;
+use serde::Deserialize;
+
 pub use bitcoin::consensus::{deserialize, serialize};
 pub use bitcoin::hex::FromHex;
-use bitcoin::Weight;
 pub use bitcoin::{
-    transaction, Amount, BlockHash, OutPoint, ScriptBuf, Transaction, TxIn, TxOut, Txid, Witness,
+    absolute, block, transaction, Amount, Block, BlockHash, CompactTarget, OutPoint, Script,
+    ScriptBuf, ScriptHash, Transaction, TxIn, TxOut, Txid, Weight, Witness,
 };
 
-use serde::Deserialize;
-
 #[derive(Deserialize, Clone, Debug, PartialEq, Eq)]
 pub struct PrevOut {
     pub value: u64,
@@ -87,6 +88,59 @@ pub struct BlockTime {
     pub height: u32,
 }
 
+/// Information about a bitcoin [`Block`].
+#[derive(Debug, Clone, Deserialize)]
+pub struct BlockInfo {
+    /// The block's [`BlockHash`].
+    pub id: BlockHash,
+    /// The block's height.
+    pub height: u32,
+    /// The block's version.
+    pub version: block::Version,
+    /// The block's timestamp.
+    pub timestamp: u64,
+    /// The block's transaction count.
+    pub tx_count: u64,
+    /// The block's size, in bytes.
+    pub size: usize,
+    /// The block's weight.
+    pub weight: u64,
+    /// The merkle root of the transactions in the block.
+    pub merkle_root: hash_types::TxMerkleNode,
+    /// The [`BlockHash`] of the previous block (`None` for the genesis block).
+    pub previousblockhash: Option<BlockHash>,
+    /// The block's MTP (Median Time Past).
+    pub mediantime: u64,
+    /// The block's nonce value.
+    pub nonce: u32,
+    /// The block's `bits` value as a [`CompactTarget`].
+    pub bits: CompactTarget,
+    /// The block's difficulty target value.
+    pub difficulty: f64,
+}
+
+impl PartialEq for BlockInfo {
+    fn eq(&self, other: &Self) -> bool {
+        let Self { difficulty: d1, .. } = self;
+        let Self { difficulty: d2, .. } = other;
+
+        self.id == other.id
+            && self.height == other.height
+            && self.version == other.version
+            && self.timestamp == other.timestamp
+            && self.tx_count == other.tx_count
+            && self.size == other.size
+            && self.weight == other.weight
+            && self.merkle_root == other.merkle_root
+            && self.previousblockhash == other.previousblockhash
+            && self.mediantime == other.mediantime
+            && self.nonce == other.nonce
+            && self.bits == other.bits
+            && ((d1.is_nan() && d2.is_nan()) || (d1 == d2))
+    }
+}
+impl Eq for BlockInfo {}
+
 #[derive(Debug, Clone, Deserialize, PartialEq, Eq)]
 pub struct BlockSummary {
     pub id: BlockHash,
@@ -123,6 +177,18 @@ pub struct AddressTxsSummary {
     pub tx_count: u32,
 }
 
+/// Statistics about a particular [`Script`] hash's confirmed and mempool transactions.
+#[derive(Debug, Copy, Clone, PartialEq, Eq, Deserialize)]
+pub struct ScriptHashStats {
+    /// The summary of confirmed transactions for this [`Script`] hash.
+    pub chain_stats: ScriptHashTxsSummary,
+    /// The summary of mempool transactions for this [`Script`] hash.
+    pub mempool_stats: ScriptHashTxsSummary,
+}
+
+/// Contains a summary of the transactions for a particular [`Script`] hash.
+pub type ScriptHashTxsSummary = AddressTxsSummary;
+
 /// Information about an UTXO's status: confirmation status,
 /// confirmation height, confirmation block hash and confirmation block time.
 #[derive(Debug, Copy, Clone, PartialEq, Eq, Deserialize)]
@@ -150,6 +216,36 @@ pub struct Utxo {
     pub value: Amount,
 }
 
+/// Statistics about the mempool.
+#[derive(Clone, Debug, PartialEq, Deserialize)]
+pub struct MempoolStats {
+    /// The number of transactions in the mempool.
+    pub count: usize,
+    /// The total size of mempool transactions in virtual bytes.
+    pub vsize: usize,
+    /// The total fee paid by mempool transactions, in sats.
+    pub total_fee: u64,
+    /// The mempool's fee rate distribution histogram.
+    ///
+    /// An array of `(feerate, vsize)` tuples, where each entry's `vsize` is the total vsize
+    /// of transactions paying more than `feerate` but less than the previous entry's `feerate`
+    /// (except for the first entry, which has no upper bound).
+    pub fee_histogram: Vec<(f64, usize)>,
+}
+
+/// A [`Transaction`] that recently entered the mempool.
+#[derive(Clone, Debug, PartialEq, Eq, Deserialize)]
+pub struct MempoolRecentTx {
+    /// Transaction ID as a [`Txid`].
+    pub txid: Txid,
+    /// [`Amount`] of fees paid by the transaction, in satoshis.
+    pub fee: u64,
+    /// The transaction size, in virtual bytes.
+    pub vsize: usize,
+    /// Combined [`Amount`] of the transaction, in satoshis.
+    pub value: u64,
+}
+
 impl Tx {
     pub fn to_tx(&self) -> Transaction {
         Transaction {

src/async.rs

@@ -15,22 +15,20 @@ use std::collections::HashMap;
 use std::marker::PhantomData;
 use std::str::FromStr;
 
+use bitcoin::block::Header as BlockHeader;
 use bitcoin::consensus::{deserialize, serialize, Decodable, Encodable};
 use bitcoin::hashes::{sha256, Hash};
 use bitcoin::hex::{DisplayHex, FromHex};
-use bitcoin::Address;
-use bitcoin::{
-    block::Header as BlockHeader, Block, BlockHash, MerkleBlock, Script, Transaction, Txid,
-};
+use bitcoin::{Address, Block, BlockHash, MerkleBlock, Script, Transaction, Txid};
 
 #[allow(unused_imports)]
 use log::{debug, error, info, trace};
 
 use reqwest::{header, Client, Response};
 
-use crate::api::AddressStats;
 use crate::{
-    BlockStatus, BlockSummary, Builder, Error, MerkleProof, OutputStatus, Tx, TxStatus, Utxo,
+    AddressStats, BlockInfo, BlockStatus, BlockSummary, Builder, Error, MempoolRecentTx,
+    MempoolStats, MerkleProof, OutputStatus, ScriptHashStats, Tx, TxStatus, Utxo,
     BASE_BACKOFF_MILLIS, RETRYABLE_ERROR_CODES,
 };
 
@@ -315,6 +313,12 @@ impl<S: Sleeper> AsyncClient<S> {
         self.get_opt_response_json(&format!("/tx/{txid}")).await
     }
 
+    /// Get the spend status of a [`Transaction`]'s outputs, given it's [`Txid`].
+    pub async fn get_tx_outspends(&self, txid: &Txid) -> Result<Vec<OutputStatus>, Error> {
+        self.get_response_json(&format!("/tx/{txid}/outspends"))
+            .await
+    }
+
     /// Get a [`BlockHeader`] given a particular block hash.
     pub async fn get_header_by_hash(&self, block_hash: &BlockHash) -> Result<BlockHeader, Error> {
         self.get_response_hex(&format!("/block/{block_hash}/header"))
@@ -391,7 +395,14 @@ impl<S: Sleeper> AsyncClient<S> {
         self.get_response_json(&path).await
     }
 
-    /// Get transaction history for the specified address/scripthash, sorted with newest first.
+    /// Get statistics about a particular [`Script`] hash's confirmed and mempool transactions.
+    pub async fn get_scripthash_stats(&self, script: &Script) -> Result<ScriptHashStats, Error> {
+        let script_hash = sha256::Hash::hash(script.as_bytes());
+        let path = format!("/scripthash/{script_hash}");
+        self.get_response_json(&path).await
+    }
+
+    /// Get transaction history for the specified address, sorted with newest first.
     ///
     /// Returns up to 50 mempool transactions plus the first 25 confirmed transactions.
     /// More can be requested by specifying the last txid seen by the previous query.
@@ -408,7 +419,14 @@ impl<S: Sleeper> AsyncClient<S> {
         self.get_response_json(&path).await
     }
 
-    /// Get confirmed transaction history for the specified address/scripthash,
+    /// Get mempool [`Transaction`]s for the specified [`Address`], sorted with newest first.
+    pub async fn get_mempool_address_txs(&self, address: &Address) -> Result<Vec<Tx>, Error> {
+        let path = format!("/address/{address}/txs/mempool");
+
+        self.get_response_json(&path).await
+    }
+
+    /// Get transaction history for the specified address/scripthash,
     /// sorted with newest first. Returns 25 transactions per page.
     /// More can be requested by specifying the last txid seen by the previous
     /// query.
@@ -426,12 +444,70 @@ impl<S: Sleeper> AsyncClient<S> {
         self.get_response_json(&path).await
     }
 
+    /// Get mempool [`Transaction`] history for the
+    /// specified [`Script`] hash, sorted with newest first.
+    pub async fn get_mempool_scripthash_txs(&self, script: &Script) -> Result<Vec<Tx>, Error> {
+        let script_hash = sha256::Hash::hash(script.as_bytes());
+        let path = format!("/scripthash/{script_hash:x}/txs/mempool");
+
+        self.get_response_json(&path).await
+    }
+
+    /// Get statistics about the mempool.
+    pub async fn get_mempool_stats(&self) -> Result<MempoolStats, Error> {
+        self.get_response_json("/mempool").await
+    }
+
+    // Get a list of the last 10 [`Transaction`]s to enter the mempool.
+    pub async fn get_mempool_recent_txs(&self) -> Result<Vec<MempoolRecentTx>, Error> {
+        self.get_response_json("/mempool/recent").await
+    }
+
+    /// Get the full list of [`Txid`]s in the mempool.
+    ///
+    /// The order of the [`Txid`]s is arbitrary.
+    pub async fn get_mempool_txids(&self) -> Result<Vec<Txid>, Error> {
+        self.get_response_json("/mempool/txids").await
+    }
+
     /// Get an map where the key is the confirmation target (in number of
     /// blocks) and the value is the estimated feerate (in sat/vB).
     pub async fn get_fee_estimates(&self) -> Result<HashMap<u16, f64>, Error> {
         self.get_response_json("/fee-estimates").await
     }
 
+    /// Get a summary about a [`Block`], given it's [`BlockHash`].
+    pub async fn get_block_info(&self, blockhash: &BlockHash) -> Result<BlockInfo, Error> {
+        let path = format!("/block/{blockhash}");
+
+        self.get_response_json(&path).await
+    }
+
+    /// Get all [`Txid`]s that belong to a [`Block`] identified by it's [`BlockHash`].
+    pub async fn get_block_txids(&self, blockhash: &BlockHash) -> Result<Vec<Txid>, Error> {
+        let path = format!("/block/{blockhash}/txids");
+
+        self.get_response_json(&path).await
+    }
+
+    /// Get up to 25 [`Transaction`]s from a [`Block`], given it's [`BlockHash`],
+    /// beginning at `start_index` (starts from 0 if `start_index` is `None`).
+    ///
+    /// The `start_index` value MUST be a multiple of 25,
+    /// else an error will be returned by Esplora.
+    pub async fn get_block_txs(
+        &self,
+        blockhash: &BlockHash,
+        start_index: Option<u32>,
+    ) -> Result<Vec<Tx>, Error> {
+        let path = match start_index {
+            None => format!("/block/{blockhash}/txs"),
+            Some(start_index) => format!("/block/{blockhash}/txs/{start_index}"),
+        };
+
+        self.get_response_json(&path).await
+    }
+
     /// Gets some recent block summaries starting at the tip or at `height` if
     /// provided.
     ///
@@ -451,8 +527,17 @@ impl<S: Sleeper> AsyncClient<S> {
 
     /// Get all UTXOs locked to an address.
     pub async fn get_address_utxos(&self, address: &Address) -> Result<Vec<Utxo>, Error> {
-        self.get_response_json(&format!("/address/{address}/utxo"))
-            .await
+        let path = format!("/address/{address}/utxo");
+
+        self.get_response_json(&path).await
+    }
+
+    /// Get all [`Utxo`]s locked to a [`Script`].
+    pub async fn get_scripthash_utxos(&self, script: &Script) -> Result<Vec<Utxo>, Error> {
+        let script_hash = sha256::Hash::hash(script.as_bytes());
+        let path = format!("/scripthash/{script_hash}/utxo");
+
+        self.get_response_json(&path).await
     }
 
     /// Get the underlying base URL.