fix(types): add missing return fields for gettxoutsetinfo RPC

The RPC has missing fields which are enabled only when `coinstatsindex`
or muhash hash type is used. Argument list is also added to header coment.

Author: natobritto

types/src/model/blockchain.rs

@@ -684,8 +684,8 @@ pub struct GetTxOutSetInfo {
     pub height: u32,
     /// The hash of the block at the tip of the chain.
     pub best_block: BlockHash,
-    /// The number of transactions with unspent outputs.
-    pub transactions: u32,
+    /// The number of transactions with unspent outputs (not available when coinstatsindex is used).
+    pub transactions: Option<u32>,
     /// The number of unspent transaction outputs.
     pub tx_outs: u32,
     /// A meaningless metric for UTXO set size.
@@ -697,10 +697,44 @@ pub struct GetTxOutSetInfo {
     /// The serialized hash (only present if 'hash_serialized_3' hash_type is chosen).
     /// v26 and later only.
     pub hash_serialized_3: Option<String>,
-    /// The estimated size of the chainstate on disk.
-    pub disk_size: u32,
+    /// The estimated size of the chainstate on disk (not available when coinstatsindex is used).
+    pub disk_size: Option<u32>,
     /// The total amount.
     pub total_amount: Amount,
+    /// The serialized hash (only present if 'muhash' hash_type is chosen)
+    pub muhash: Option<String>,
+    /// The total amount of coins permanently excluded from the UTXO set (only available if coinstatsindex is used).
+    pub total_unspendable_amount: Option<Amount>,
+    /// Info on amounts in the block at this block height (only available if coinstatsindex is used).
+    pub block_info: Option<BlockInfo>,
+}
+
+/// Detailed block-level info.  Part of `gettxoutsetinfo`.
+#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
+pub struct BlockInfo {
+    /// Total amount of all prevouts spent in this block.
+    pub prevout_spent: Amount,
+    /// Coinbase subsidy amount of this block.
+    pub coinbase: Amount,
+    /// Total amount of new outputs created by this block.
+    pub new_outputs_ex_coinbase: Amount,
+    /// Total amount of unspendable outputs created in this block.
+    pub unspendable: Amount,
+    /// Detailed view of unspendable categories.
+    pub unspendables: Unspendables,
+}
+
+/// Categories of unspendable amounts. Part of `gettxoutsetinfo`.
+#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
+pub struct Unspendables {
+    /// The unspendable amount of the Genesis block subsidy.
+    pub genesis_block: Amount,
+    /// Transactions overridden by duplicates (no longer possible with BIP30).
+    pub bip30: Amount,
+    /// Amounts sent to scripts that are unspendable (for example OP_RETURN outputs).
+    pub scripts: Amount,
+    /// Fee rewards that miners did not claim in their coinbase transaction.
+    pub unclaimed_rewards: Amount,
 }
 
 /// Models the result of JSON-RPC method `gettxspendingprevout`.

types/src/model/mod.rs

@@ -27,16 +27,17 @@ use serde::{Deserialize, Serialize};
 pub use self::{
     blockchain::{
         ActivityEntry, Bip9Info, Bip9SoftforkInfo, Bip9SoftforkStatistics, Bip9SoftforkStatus,
-        Bip9Statistics, ChainState, ChainTips, ChainTipsStatus, DeploymentInfo, DumpTxOutSet,
-        GetBestBlockHash, GetBlockCount, GetBlockFilter, GetBlockHash, GetBlockHeader,
-        GetBlockHeaderVerbose, GetBlockStats, GetBlockVerboseOne, GetBlockVerboseZero,
-        GetBlockchainInfo, GetChainStates, GetChainTips, GetChainTxStats, GetDeploymentInfo,
-        GetDescriptorActivity, GetDifficulty, GetMempoolAncestors, GetMempoolAncestorsVerbose,
-        GetMempoolDescendants, GetMempoolDescendantsVerbose, GetMempoolEntry, GetMempoolInfo,
-        GetRawMempool, GetRawMempoolVerbose, GetTxOut, GetTxOutSetInfo, GetTxSpendingPrevout,
-        GetTxSpendingPrevoutItem, LoadTxOutSet, MempoolEntry, MempoolEntryFees, ReceiveActivity,
-        ScanBlocksStart, ScanTxOutSetStart, ScanTxOutSetUnspent, Softfork, SoftforkType,
-        SpendActivity, VerifyTxOutProof, WaitForBlock, WaitForBlockHeight, WaitForNewBlock,
+        Bip9Statistics, BlockInfo, ChainState, ChainTips, ChainTipsStatus, DeploymentInfo,
+        DumpTxOutSet, GetBestBlockHash, GetBlockCount, GetBlockFilter, GetBlockHash,
+        GetBlockHeader, GetBlockHeaderVerbose, GetBlockStats, GetBlockVerboseOne,
+        GetBlockVerboseZero, GetBlockchainInfo, GetChainStates, GetChainTips, GetChainTxStats,
+        GetDeploymentInfo, GetDescriptorActivity, GetDifficulty, GetMempoolAncestors,
+        GetMempoolAncestorsVerbose, GetMempoolDescendants, GetMempoolDescendantsVerbose,
+        GetMempoolEntry, GetMempoolInfo, GetRawMempool, GetRawMempoolVerbose, GetTxOut,
+        GetTxOutSetInfo, GetTxSpendingPrevout, GetTxSpendingPrevoutItem, LoadTxOutSet,
+        MempoolEntry, MempoolEntryFees, ReceiveActivity, ScanBlocksStart, ScanTxOutSetStart,
+        ScanTxOutSetUnspent, Softfork, SoftforkType, SpendActivity, Unspendables, VerifyTxOutProof,
+        WaitForBlock, WaitForBlockHeight, WaitForNewBlock,
     },
     generating::{Generate, GenerateBlock, GenerateToAddress, GenerateToDescriptor},
     hidden::{

types/src/v17/blockchain/into.rs

@@ -530,11 +530,11 @@ impl GetTxOutSetInfo {
 
         let height = crate::to_u32(self.height, "height")?;
         let best_block = self.best_block.parse::<BlockHash>().map_err(E::BestBlock)?;
-        let transactions = crate::to_u32(self.transactions, "transactions")?;
+        let transactions = Some(crate::to_u32(self.transactions, "transactions")?);
         let tx_outs = crate::to_u32(self.tx_outs, "tx_outs")?;
         let bogo_size = crate::to_u32(self.bogo_size, "bogo_size")?;
         let hash_serialized_2 = Some(self.hash_serialized_2); // TODO: Convert this to a hash type.
-        let disk_size = crate::to_u32(self.disk_size, "disk_size")?;
+        let disk_size = Some(crate::to_u32(self.disk_size, "disk_size")?);
         let total_amount = Amount::from_btc(self.total_amount).map_err(E::TotalAmount)?;
 
         Ok(model::GetTxOutSetInfo {
@@ -547,6 +547,9 @@ impl GetTxOutSetInfo {
             hash_serialized_3: None, // v26 and later only.
             disk_size,
             total_amount,
+            muhash: None,
+            total_unspendable_amount: None,
+            block_info: None,
         })
     }
 }

types/src/v26/blockchain/error.rs

@@ -96,16 +96,51 @@ pub enum GetTxOutSetInfoError {
     BestBlock(hex::HexToArrayError),
     /// Conversion of the transaction `total_amount` field failed.
     TotalAmount(amount::ParseAmountError),
+    /// Conversion of the `prevout_spent` field failed.
+    PrevoutSpent(amount::ParseAmountError),
+    /// Conversion of the `coinbase` field failed.
+    Coinbase(amount::ParseAmountError),
+    /// Conversion of the `new_outputs_ex_coinbase` field failed.
+    NewOutputsExCoinbase(amount::ParseAmountError),
+    /// Conversion of the `unspendable` field failed.
+    Unspendable(amount::ParseAmountError),
+    /// Conversion of the `unspendables.genesis_block` field failed.
+    UnspendablesGenesisBlock(amount::ParseAmountError),
+    /// Conversion of the `unspendables.bip30` field failed.
+    UnspendablesBip30(amount::ParseAmountError),
+    /// Conversion of the `unspendables.scripts` field failed.
+    UnspendablesScripts(amount::ParseAmountError),
+    /// Conversion of the `unspendables.unclaimed_rewards` field failed.
+    UnspendablesUnclaimedRewards(amount::ParseAmountError),
+    /// Conversion of the `total_unspendable_amount` field failed.
+    TotalUnspendableAmount(amount::ParseAmountError),
 }
 
 impl fmt::Display for GetTxOutSetInfoError {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         match *self {
             Self::Numeric(ref e) => write_err!(f, "numeric"; e),
             Self::BestBlock(ref e) =>
-                write_err!(f, "conversion of the `beast_block` field failed"; e),
+                write_err!(f, "conversion of the `best_block` field failed"; e),
             Self::TotalAmount(ref e) =>
                 write_err!(f, "conversion of the `total_amount` field failed"; e),
+            Self::PrevoutSpent(ref e) =>
+                write_err!(f, "conversion of the `prevout_spent` field failed"; e),
+            Self::Coinbase(ref e) => write_err!(f, "conversion of the `coinbase` field failed"; e),
+            Self::NewOutputsExCoinbase(ref e) =>
+                write_err!(f, "conversion of the `new_outputs_ex_coinbase` field failed"; e),
+            Self::Unspendable(ref e) =>
+                write_err!(f, "conversion of the `unspendable` field failed"; e),
+            Self::UnspendablesGenesisBlock(ref e) =>
+                write_err!(f, "conversion of the `unspendables.genesis_block` field failed"; e),
+            Self::UnspendablesBip30(ref e) =>
+                write_err!(f, "conversion of the `unspendables.bip30` field failed"; e),
+            Self::UnspendablesScripts(ref e) =>
+                write_err!(f, "conversion of the `unspendables.scripts` field failed"; e),
+            Self::UnspendablesUnclaimedRewards(ref e) =>
+                write_err!(f, "conversion of the `unspendables.unclaimed_rewards` field failed"; e),
+            Self::TotalUnspendableAmount(ref e) =>
+                write_err!(f, "conversion of the `total_unspendable_amount` field failed"; e),
         }
     }
 }
@@ -117,6 +152,15 @@ impl std::error::Error for GetTxOutSetInfoError {
             Self::Numeric(ref e) => Some(e),
             Self::BestBlock(ref e) => Some(e),
             Self::TotalAmount(ref e) => Some(e),
+            Self::PrevoutSpent(ref e) => Some(e),
+            Self::Coinbase(ref e) => Some(e),
+            Self::NewOutputsExCoinbase(ref e) => Some(e),
+            Self::Unspendable(ref e) => Some(e),
+            Self::UnspendablesGenesisBlock(ref e) => Some(e),
+            Self::UnspendablesBip30(ref e) => Some(e),
+            Self::UnspendablesScripts(ref e) => Some(e),
+            Self::UnspendablesUnclaimedRewards(ref e) => Some(e),
+            Self::TotalUnspendableAmount(ref e) => Some(e),
         }
     }
 }

types/src/v26/blockchain/into.rs

@@ -69,12 +69,18 @@ impl GetTxOutSetInfo {
     pub fn into_model(self) -> Result<model::GetTxOutSetInfo, GetTxOutSetInfoError> {
         use GetTxOutSetInfoError as E;
 
-        let height = crate::to_u32(self.height, "height")?;
+        let height = crate::to_u32(self.height, "height").map_err(E::Numeric)?;
         let best_block = self.best_block.parse::<BlockHash>().map_err(E::BestBlock)?;
-        let transactions = crate::to_u32(self.transactions, "transactions")?;
-        let tx_outs = crate::to_u32(self.tx_outs, "tx_outs")?;
-        let bogo_size = crate::to_u32(self.bogo_size, "bogo_size")?;
-        let disk_size = crate::to_u32(self.disk_size, "disk_size")?;
+        let transactions = self
+            .transactions
+            .map(|v| crate::to_u32(v, "transactions").map_err(E::Numeric))
+            .transpose()?;
+        let tx_outs = crate::to_u32(self.tx_outs, "tx_outs").map_err(E::Numeric)?;
+        let bogo_size = crate::to_u32(self.bogo_size, "bogo_size").map_err(E::Numeric)?;
+        let disk_size = self
+            .disk_size
+            .map(|v| crate::to_u32(v, "disk_size").map_err(E::Numeric))
+            .transpose()?;
         let total_amount = Amount::from_btc(self.total_amount).map_err(E::TotalAmount)?;
 
         Ok(model::GetTxOutSetInfo {
@@ -87,6 +93,40 @@ impl GetTxOutSetInfo {
             hash_serialized_3: self.hash_serialized_3,
             disk_size,
             total_amount,
+            muhash: self.muhash,
+            total_unspendable_amount: self
+                .total_unspendable_amount
+                .map(|v| Amount::from_btc(v).map_err(E::TotalUnspendableAmount))
+                .transpose()?,
+            block_info: match self.block_info {
+                Some(b) => {
+                    let prevout_spent =
+                        Amount::from_btc(b.prevout_spent).map_err(E::PrevoutSpent)?;
+                    let coinbase = Amount::from_btc(b.coinbase).map_err(E::Coinbase)?;
+                    let new_outputs_ex_coinbase = Amount::from_btc(b.new_outputs_ex_coinbase)
+                        .map_err(E::NewOutputsExCoinbase)?;
+                    let unspendable = Amount::from_btc(b.unspendable).map_err(E::Unspendable)?;
+                    let unspendables = model::Unspendables {
+                        genesis_block: Amount::from_btc(b.unspendables.genesis_block)
+                            .map_err(E::UnspendablesGenesisBlock)?,
+                        bip30: Amount::from_btc(b.unspendables.bip30)
+                            .map_err(E::UnspendablesBip30)?,
+                        scripts: Amount::from_btc(b.unspendables.scripts)
+                            .map_err(E::UnspendablesScripts)?,
+                        unclaimed_rewards: Amount::from_btc(b.unspendables.unclaimed_rewards)
+                            .map_err(E::UnspendablesUnclaimedRewards)?,
+                    };
+
+                    Some(model::BlockInfo {
+                        prevout_spent,
+                        coinbase,
+                        new_outputs_ex_coinbase,
+                        unspendable,
+                        unspendables,
+                    })
+                }
+                None => None,
+            },
         })
     }
 }

types/src/v26/blockchain/mod.rs

@@ -86,6 +86,11 @@ pub struct ChainState {
 /// >
 /// > Returns statistics about the unspent transaction output set.
 /// > Note this call may take some time.
+/// >
+/// > Arguments:
+/// > 1. hash_type         (string, optional, default="hash_serialized_3") Which UTXO set hash should be calculated. Options: 'hash_serialized_3' (the legacy algorithm), 'muhash', 'none'.
+/// > 2. hash_or_height    (string or numeric, optional, default=the current best block) The block hash or height of the target height (only available with coinstatsindex).
+/// > 3. use_index         (boolean, optional, default=true) Use coinstatsindex, if available.
 #[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
 #[cfg_attr(feature = "serde-deny-unknown-fields", serde(deny_unknown_fields))]
 pub struct GetTxOutSetInfo {
@@ -94,21 +99,59 @@ pub struct GetTxOutSetInfo {
     /// The hash of the block at the tip of the chain.
     #[serde(rename = "bestblock")]
     pub best_block: String,
-    /// The number of transactions with unspent outputs.
-    pub transactions: i64,
+    /// The number of transactions with unspent outputs (not available when coinstatsindex is used).
+    pub transactions: Option<i64>,
     /// The number of unspent transaction outputs.
     #[serde(rename = "txouts")]
     pub tx_outs: i64,
     /// A meaningless metric for UTXO set size.
     #[serde(rename = "bogosize")]
     pub bogo_size: i64,
-    /// The estimated size of the chainstate on disk.
-    pub disk_size: i64,
-    /// The total amount.
-    pub total_amount: f64,
     /// The serialized hash (only present if 'hash_serialized_3' hash_type is chosen).
     /// v26 and later only.
     pub hash_serialized_3: Option<String>,
+    /// The estimated size of the chainstate on disk (not available when coinstatsindex is used).
+    pub disk_size: Option<i64>,
+    /// The total amount.
+    pub total_amount: f64,
+    /// The serialized hash (only present if 'muhash' hash_type is chosen)
+    pub muhash: Option<String>,
+    /// The total amount of coins permanently excluded from the UTXO set (only available if coinstatsindex is used).
+    pub total_unspendable_amount: Option<f64>,
+    /// Info on amounts in the block at this block height (only available if coinstatsindex is used).
+    pub block_info: Option<BlockInfo>,
+}
+
+/// Detailed block-level info returned by `gettxoutsetinfo` when coinstatsindex is enabled.
+#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
+#[cfg_attr(feature = "serde-deny-unknown-fields", serde(deny_unknown_fields))]
+pub struct BlockInfo {
+    /// Total amount of all prevouts spent in this block.
+    #[serde(rename = "prevout_spent")]
+    pub prevout_spent: f64,
+    /// Coinbase subsidy amount of this block.
+    pub coinbase: f64,
+    /// Total amount of new outputs created by this block.
+    #[serde(rename = "new_outputs_ex_coinbase")]
+    pub new_outputs_ex_coinbase: f64,
+    /// Total amount of unspendable outputs created in this block.
+    pub unspendable: f64,
+    /// Detailed view of unspendable categories.
+    pub unspendables: Unspendables,
+}
+
+/// Categories of unspendable amounts returned inside `BlockInfo`.
+#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
+#[cfg_attr(feature = "serde-deny-unknown-fields", serde(deny_unknown_fields))]
+pub struct Unspendables {
+    /// The unspendable amount of the Genesis block subsidy.
+    pub genesis_block: f64,
+    /// Transactions overridden by duplicates (no longer possible with BIP30).
+    pub bip30: f64,
+    /// Amounts sent to scripts that are unspendable (for example OP_RETURN outputs).
+    pub scripts: f64,
+    /// Fee rewards that miners did not claim in their coinbase transaction.
+    pub unclaimed_rewards: f64,
 }
 
 /// Result of JSON-RPC method `loadtxoutset`.

types/src/v26/mod.rs

@@ -259,8 +259,9 @@ mod wallet;
 #[doc(inline)]
 pub use self::{
     blockchain::{
-        ChainState, DumpTxOutSet, DumpTxOutSetError, GetChainStates, GetChainStatesError,
-        GetTxOutSetInfo, GetTxOutSetInfoError, LoadTxOutSet, LoadTxOutSetError,
+        BlockInfo, ChainState, DumpTxOutSet, DumpTxOutSetError, GetChainStates,
+        GetChainStatesError, GetTxOutSetInfo, GetTxOutSetInfoError, LoadTxOutSet,
+        LoadTxOutSetError, Unspendables,
     },
     control::Logging,
     hidden::{GetRawAddrMan, RawAddrManEntry},

types/src/v27/mod.rs

@@ -333,14 +333,14 @@ pub use crate::{
         ScanTxOutSetUnspent, TestMempoolAccept, TestMempoolAcceptError,
     },
     v26::{
-        AddrManInfoNetwork, ChainState, CreateWallet, DescriptorProcessPsbt,
+        AddrManInfoNetwork, BlockInfo, ChainState, CreateWallet, DescriptorProcessPsbt,
         DescriptorProcessPsbtError, DumpTxOutSet, DumpTxOutSetError, GetAddrManInfo, GetBalances,
         GetBalancesError, GetChainStates, GetChainStatesError, GetPeerInfo, GetRawAddrMan,
         GetTransaction, GetTransactionError, GetTxOutSetInfo, GetTxOutSetInfoError, GetWalletInfo,
         GetWalletInfoError, GetWalletInfoScanning, LastProcessedBlock, LastProcessedBlockError,
         LoadTxOutSet, LoadTxOutSetError, LoadWallet, Logging, PeerInfo, RawAddrManEntry,
         SubmitPackage, SubmitPackageError, SubmitPackageTxResult, SubmitPackageTxResultError,
-        SubmitPackageTxResultFees, SubmitPackageTxResultFeesError, UnloadWallet, WalletProcessPsbt,
-        WalletProcessPsbtError,
+        SubmitPackageTxResultFees, SubmitPackageTxResultFeesError, UnloadWallet, Unspendables,
+        WalletProcessPsbt, WalletProcessPsbtError,
     },
 };

types/src/v28/mod.rs

@@ -354,12 +354,12 @@ pub use crate::{
         TestMempoolAcceptError,
     },
     v26::{
-        AddrManInfoNetwork, ChainState, CreateWallet, DescriptorProcessPsbt,
+        AddrManInfoNetwork, BlockInfo, ChainState, CreateWallet, DescriptorProcessPsbt,
         DescriptorProcessPsbtError, DumpTxOutSet, DumpTxOutSetError, GetAddrManInfo, GetBalances,
         GetBalancesError, GetChainStates, GetChainStatesError, GetPeerInfo, GetTransactionError,
         GetTxOutSetInfo, GetTxOutSetInfoError, GetWalletInfo, GetWalletInfoError,
         GetWalletInfoScanning, LastProcessedBlock, LastProcessedBlockError, LoadTxOutSet,
-        LoadTxOutSetError, LoadWallet, PeerInfo, UnloadWallet, WalletProcessPsbt,
+        LoadTxOutSetError, LoadWallet, PeerInfo, UnloadWallet, Unspendables, WalletProcessPsbt,
         WalletProcessPsbtError,
     },
     v27::{GetPrioritisedTransactions, PrioritisedTransaction},