chore(docs): add missing documentation

Author: luisschwab

src/api.rs

@@ -1,3 +1,14 @@
+// Bitcoin Dev Kit
+// Written in 2020 by Alekos Filini <[email protected]>
+//
+// Copyright (c) 2020-2025 Bitcoin Dev Kit Developers
+//
+// This file is licensed under the Apache License, Version 2.0 <LICENSE-APACHE
+// or http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your option.
+// You may not use this file except in accordance with one or both of these
+// licenses.
+
 //! Structs from the Esplora API
 //!
 //! See: <https://github.com/Blockstream/esplora/blob/master/API.md>
@@ -6,116 +17,157 @@ use bitcoin::hash_types;
 use serde::Deserialize;
 
 pub use bitcoin::consensus::{deserialize, serialize};
+use bitcoin::hash_types::TxMerkleNode;
 pub use bitcoin::hex::FromHex;
 pub use bitcoin::{
-    absolute, block, transaction, Amount, Block, BlockHash, CompactTarget, OutPoint, Script,
-    ScriptBuf, ScriptHash, Transaction, TxIn, TxOut, Txid, Weight, Witness,
+    absolute, block, transaction, Address, Amount, Block, BlockHash, CompactTarget, OutPoint,
+    Script, ScriptBuf, ScriptHash, Transaction, TxIn, TxOut, Txid, Weight, Witness,
 };
 
+/// Information about a previous output.
 #[derive(Deserialize, Clone, Debug, PartialEq, Eq)]
 pub struct PrevOut {
+    /// The value of the previous output, in satoshis.
     pub value: u64,
+    /// The ScriptPubKey that the previous output is locked to, as a [`ScriptBuf`].
     pub scriptpubkey: ScriptBuf,
 }
 
+/// Information about an input from a [`Transaction`].
 #[derive(Deserialize, Clone, Debug, PartialEq, Eq)]
 pub struct Vin {
+    /// The [`Txid`] of the previous [`Transaction`] this input spends from.
     pub txid: Txid,
+    /// The output index of the previous output in the [`Transaction`] that created it.
     pub vout: u32,
-    // None if coinbase
+    /// The previous output amount and ScriptPubKey.
+    /// `None` if this is a coinbase input.
     pub prevout: Option<PrevOut>,
+    /// The ScriptSig authorizes spending this input.
     pub scriptsig: ScriptBuf,
+    /// The Witness that authorizes spending this input, if this is a SegWit spend.
     #[serde(deserialize_with = "deserialize_witness", default)]
     pub witness: Vec<Vec<u8>>,
+    /// The sequence value for this input, used to set RBF and Locktime behavior.
     pub sequence: u32,
+    /// Whether this is a coinbase input.
     pub is_coinbase: bool,
 }
 
+/// Information about a [`Transaction`]s output.
 #[derive(Deserialize, Clone, Debug, PartialEq, Eq)]
 pub struct Vout {
+    /// The value of the output, in satoshis.
     pub value: u64,
+    /// The ScriptPubKey that the output is locked to, as a [`ScriptBuf`].
     pub scriptpubkey: ScriptBuf,
 }
 
+/// The confirmation status of a [`Transaction`].
 #[derive(Deserialize, Clone, Debug, PartialEq, Eq)]
 pub struct TxStatus {
+    /// Whether the [`Transaction`] is confirmed or not.
     pub confirmed: bool,
+    /// The block height the [`Transaction`] was confirmed in.
     pub block_height: Option<u32>,
+    /// The [`BlockHash`] of the block the [`Transaction`] was confirmed in.
     pub block_hash: Option<BlockHash>,
+    /// The time that the block was mined at, as a UNIX timestamp.
+    /// Note: this timestamp is set by the miner and may not reflect the exact time of mining.
     pub block_time: Option<u64>,
 }
 
+/// A Merkle inclusion proof for a transaction, given it's [`Txid`].
 #[derive(Deserialize, Clone, Debug, PartialEq, Eq)]
 pub struct MerkleProof {
+    /// The height of the block the [`Transaction`] was confirmed in.
     pub block_height: u32,
+    /// A list of transaction hashes the current hash is paired with,
+    /// recursively, in order to trace up to obtain the Merkle root of the
+    /// [`Block`], deepest pairing first.
     pub merkle: Vec<Txid>,
+    /// The 0-based index of the position of the [`Transaction`] in the
+    /// ordered list of [`Transaction`]s in the [`Block`].
     pub pos: usize,
 }
 
+/// The spend status of a [`TxOut`].
 #[derive(Deserialize, Clone, Debug, PartialEq, Eq)]
 pub struct OutputStatus {
+    /// Whether the [`TxOut`] is spent or not.
     pub spent: bool,
+    /// The [`Txid`] that spent this [`TxOut`].
     pub txid: Option<Txid>,
+    /// The input index of this [`TxOut`] in the [`Transaction`] that spent it.
     pub vin: Option<u64>,
+    /// Information about the [`Transaction`] that spent this [`TxOut`].
     pub status: Option<TxStatus>,
 }
 
+/// Information about a [`Block`]s status.
 #[derive(Deserialize, Clone, Debug, PartialEq, Eq)]
 pub struct BlockStatus {
+    /// Whether this [`Block`] belongs to the chain with the most
+    /// Proof-of-Work (false for [`Block`]s that belong to a stale chain).
     pub in_best_chain: bool,
+    /// The height of this [`Block`].
     pub height: Option<u32>,
+    /// The [`BlockHash`] of the [`Block`] that builds on top of this one.
     pub next_best: Option<BlockHash>,
 }
 
+/// A [`Transaction`] in the format returned by Esplora.
 #[derive(Deserialize, Clone, Debug, PartialEq, Eq)]
 pub struct Tx {
+    /// The [`Txid`] of the [`Transaction`].
     pub txid: Txid,
+    /// The version number of the [`Transaction`].
     pub version: i32,
+    /// The locktime of the [`Transaction`].
+    /// Sets a time or height after which the [`Transaction`] can be mined.
     pub locktime: u32,
+    /// The array of inputs in the [`Transaction`].
     pub vin: Vec<Vin>,
+    /// The array of outputs in the [`Transaction`].
     pub vout: Vec<Vout>,
-    /// Transaction size in raw bytes (NOT virtual bytes).
+    /// The [`Transaction`] size in raw bytes (NOT virtual bytes).
     pub size: usize,
-    /// Transaction weight units.
+    /// The [`Transaction`]'s weight units.
     pub weight: u64,
+    /// The confirmation status of the [`Transaction`].
     pub status: TxStatus,
+    /// The fee amount paid by the [`Transaction`], in satoshis.
     pub fee: u64,
 }
 
-#[derive(Deserialize, Clone, Debug, PartialEq, Eq)]
-pub struct BlockTime {
-    pub timestamp: u64,
-    pub height: u32,
-}
-
 /// Information about a bitcoin [`Block`].
 #[derive(Debug, Clone, Deserialize)]
 pub struct BlockInfo {
-    /// The block's [`BlockHash`].
+    /// The [`Block`]'s [`BlockHash`].
     pub id: BlockHash,
-    /// The block's height.
+    /// The [`Block`]'s height.
     pub height: u32,
-    /// The block's version.
+    /// The [`Block`]'s version.
     pub version: block::Version,
-    /// The block's timestamp.
+    /// The [`Block`]'s UNIX timestamp.
     pub timestamp: u64,
-    /// The block's transaction count.
+    /// The [`Block`]'s [`Transaction`] count.
     pub tx_count: u64,
-    /// The block's size, in bytes.
+    /// The [`Block`]'s size, in bytes.
     pub size: usize,
-    /// The block's weight.
+    /// The [`Block`]'s weight.
     pub weight: u64,
-    /// The merkle root of the transactions in the block.
+    /// 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).
+    /// The [`BlockHash`] of the previous [`Block`] (`None` for the genesis block).
     pub previousblockhash: Option<BlockHash>,
-    /// The block's MTP (Median Time Past).
+    /// The [`Block`]'s MTP (Median Time Past).
     pub mediantime: u64,
-    /// The block's nonce value.
+    /// The [`Block`]'s nonce value.
     pub nonce: u32,
-    /// The block's `bits` value as a [`CompactTarget`].
+    /// The [`Block`]'s `bits` value as a [`CompactTarget`].
     pub bits: CompactTarget,
-    /// The block's difficulty target value.
+    /// The [`Block`]'s difficulty target value.
     pub difficulty: f64,
 }
 
@@ -141,112 +193,127 @@ impl PartialEq for BlockInfo {
 }
 impl Eq for BlockInfo {}
 
+/// Time-related information about 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,
+}
+
+/// Summary about a [`Block`].
 #[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,
-    /// Hash of the previous block, will be `None` for the genesis block.
-    pub previousblockhash: Option<bitcoin::BlockHash>,
-    pub merkle_root: bitcoin::hash_types::TxMerkleNode,
+    /// 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,
 }
 
-/// Address statistics, includes the address, and the utxo information for the address.
+/// Statistics about an [`Address`].
 #[derive(Debug, Clone, Deserialize, PartialEq, Eq)]
 pub struct AddressStats {
-    /// The address.
+    /// The [`Address`].
     pub address: String,
-    /// The summary of transactions for this address, already on chain.
+    /// The summary of confirmed [`Transaction`]s for this [`Address`].
     pub chain_stats: AddressTxsSummary,
-    /// The summary of transactions for this address, currently in the mempool.
+    /// The summary of mempool [`Transaction`]s for this [`Address`].
     pub mempool_stats: AddressTxsSummary,
 }
 
-/// Contains a summary of the transactions for an address.
+/// A summary of [`Transaction`]s in which an [`Address`] was involved.
 #[derive(Debug, Copy, Clone, PartialEq, Eq, Deserialize)]
 pub struct AddressTxsSummary {
-    /// The number of funded transaction outputs.
+    /// The number of funded [`TxOut`]s.
     pub funded_txo_count: u32,
-    /// The sum of the funded transaction outputs, in satoshis.
+    /// The sum of the funded [`TxOut`]s, in satoshis.
     pub funded_txo_sum: u64,
-    /// The number of spent transaction outputs.
+    /// The number of spent [`TxOut`]s.
     pub spent_txo_count: u32,
-    /// The sum of the spent transaction outputs, in satoshis.
+    /// The sum of the spent [`TxOut`]s, in satoshis.
     pub spent_txo_sum: u64,
-    /// The total number of transactions.
+    /// The total number of [`Transaction`]s.
     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.
+    /// The summary of confirmed [`Transaction`]s for this [`Script`] hash.
     pub chain_stats: ScriptHashTxsSummary,
-    /// The summary of mempool transactions for this [`Script`] hash.
+    /// The summary of mempool [`Transaction`]s for this [`Script`] hash.
     pub mempool_stats: ScriptHashTxsSummary,
 }
 
-/// Contains a summary of the transactions for a particular [`Script`] hash.
+/// Contains a summary of the [`Transaction`]s for a particular [`Script`] hash.
 pub type ScriptHashTxsSummary = AddressTxsSummary;
 
-/// Information about an UTXO's status: confirmation status,
+/// Information about a [`TxOut`]'s status: confirmation status,
 /// confirmation height, confirmation block hash and confirmation block time.
 #[derive(Debug, Copy, Clone, PartialEq, Eq, Deserialize)]
 pub struct UtxoStatus {
-    /// Whether or not the UTXO is confirmed.
+    /// Whether or not the [`TxOut`] is confirmed.
     pub confirmed: bool,
-    /// The block height in which the UTXO was confirmed.
+    /// The block height in which the [`TxOut`] was confirmed.
     pub block_height: Option<u32>,
-    /// The block hash in which the UTXO was confirmed.
+    /// The block hash in which the [`TxOut`] was confirmed.
     pub block_hash: Option<BlockHash>,
-    /// The UNIX timestamp in which the UTXO was confirmed.
+    /// The UNIX timestamp in which the [`TxOut`] was confirmed.
     pub block_time: Option<u64>,
 }
 
-/// Information about an UTXO's outpoint, confirmation status and value.
+/// Information about an [`TxOut`]'s outpoint, confirmation status and value.
 #[derive(Debug, Copy, Clone, PartialEq, Eq, Deserialize)]
 pub struct Utxo {
-    /// The [`Txid`] of the transaction that created the UTXO.
+    /// The [`Txid`] of the [`Transaction`] that created the [`TxOut`].
     pub txid: Txid,
-    /// The output index of the UTXO on the transaction that created the it.
+    /// The output index of the [`TxOut`] in the [`Transaction`] that created it.
     pub vout: u32,
-    /// The confirmation status of the UTXO.
+    /// The confirmation status of the [`TxOut`].
     pub status: UtxoStatus,
-    /// The value of the UTXO as an [`Amount`].
+    /// The value of the [`TxOut`] as an [`Amount`].
     pub value: Amount,
 }
 
 /// Statistics about the mempool.
 #[derive(Clone, Debug, PartialEq, Deserialize)]
 pub struct MempoolStats {
-    /// The number of transactions in the mempool.
+    /// The number of [`Transaction`]s in the mempool.
     pub count: usize,
-    /// The total size of mempool transactions in virtual bytes.
+    /// The total size of mempool [`Transaction`]s, in virtual bytes.
     pub vsize: usize,
-    /// The total fee paid by mempool transactions, in sats.
+    /// The total fee paid by mempool [`Transaction`]s, in satoshis.
     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`
+    /// of [`Transaction`]s 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`].
+    /// The [`Transaction`]'s ID, as a [`Txid`].
     pub txid: Txid,
-    /// [`Amount`] of fees paid by the transaction, in satoshis.
+    /// The [`Amount`] of fees paid by the transaction, in satoshis.
     pub fee: u64,
-    /// The transaction size, in virtual bytes.
+    /// The [`Transaction`]'s size, in virtual bytes.
     pub vsize: usize,
-    /// Combined [`Amount`] of the transaction, in satoshis.
+    /// Combined [`Amount`] of the [`Transaction`], in satoshis.
     pub value: u64,
 }
 
 impl Tx {
+    /// Convert a transaction from the format returned by Esplora into a `rust-bitcoin`
+    /// [`Transaction`].
     pub fn to_tx(&self) -> Transaction {
         Transaction {
             version: transaction::Version::non_standard(self.version),
@@ -277,6 +344,7 @@ impl Tx {
         }
     }
 
+    /// Get the confirmation time from a [`Tx`].
     pub fn confirmation_time(&self) -> Option<BlockTime> {
         match self.status {
             TxStatus {
@@ -289,6 +357,7 @@ impl Tx {
         }
     }
 
+    /// Get a list of the [`Tx`]'s previous outputs.
     pub fn previous_outputs(&self) -> Vec<Option<TxOut>> {
         self.vin
             .iter()
@@ -302,10 +371,12 @@ impl Tx {
             .collect()
     }
 
+    /// Get the weight of a [`Tx`].
     pub fn weight(&self) -> Weight {
         Weight::from_wu(self.weight)
     }
 
+    /// Get the fee paid by a [`Tx`].
     pub fn fee(&self) -> Amount {
         Amount::from_sat(self.fee)
     }