Merge rust-bitcoin#485: Add getblock verbosity 2/3 support for v29 onward

9c325ef feat: implement getblock verbosity levels 2-3 return types (renato)
515955e fix(types): remove comment for weight conversion in GetBlockVerbose (renato)
3532f06 feat(types): add coinbase tx support in RawTransactionInput type (renato)

Pull request description:

  This PR:
  - Adds full support for `getblock` RPC with verbosity levels 2 and 3 for v29 and later.
  - Add coinbase transaction support in `RawTransactionInput` type, to be fully compliant with the RPC specification.
  - Introduces versioned RPC types and model conversions, including transaction fees and prevout data, extends raw transaction input handling to correctly support coinbase inputs, and updates the client API with verbosity levels.
  - Adds integration tests to validate new models conversions.
  - Removes FIXME comment regarding weight units on getblock verbosity 0 and 1, the value really is weight units (WU).

  This partially fixes rust-bitcoin#474.

  Notably missing are the changes in implementation from v17 to v28 inclusive.

ACKs for top commit:
  tcharding:
    ACK 9c325ef

Tree-SHA512: 6f9a63fce50fae03218e338c59e4a723b001adb1fad2e38f242b7757098885ca358666fe458f49a1bf74e648b572f22bfc72a4a6f3ea5be3698b0c372a4e38ab

Author: tcharding

client/src/client_sync/v29/blockchain.rs

@@ -36,3 +36,37 @@ macro_rules! impl_client_v29__get_descriptor_activity {
         }
     };
 }
+
+/// Implements Bitcoin Core JSON-RPC API method `getblock`.
+#[macro_export]
+macro_rules! impl_client_v29__get_block {
+    () => {
+        impl Client {
+            /// Gets a block by blockhash. Kept for compatibility; uses verbose set to 0.
+            pub fn get_block(&self, hash: BlockHash) -> Result<Block> {
+                let json = self.get_block_verbose_zero(hash)?;
+                Ok(json.block()?)
+            }
+
+            /// Gets a block by blockhash with verbose set to 0.
+            pub fn get_block_verbose_zero(&self, hash: BlockHash) -> Result<GetBlockVerboseZero> {
+                self.call("getblock", &[into_json(hash)?, 0.into()])
+            }
+
+            /// Gets a block by blockhash with verbose set to 1.
+            pub fn get_block_verbose_one(&self, hash: BlockHash) -> Result<GetBlockVerboseOne> {
+                self.call("getblock", &[into_json(hash)?, 1.into()])
+            }
+
+            /// Gets a block by blockhash with verbose set to 2.
+            pub fn get_block_verbose_two(&self, hash: BlockHash) -> Result<GetBlockVerboseTwo> {
+                self.call("getblock", &[into_json(hash)?, 2.into()])
+            }
+
+            /// Gets a block by blockhash with verbose set to 3.
+            pub fn get_block_verbose_three(&self, hash: BlockHash) -> Result<GetBlockVerboseThree> {
+                self.call("getblock", &[into_json(hash)?, 3.into()])
+            }
+        }
+    };
+}

client/src/client_sync/v29/mod.rs

@@ -32,7 +32,7 @@ crate::impl_client_check_expected_server_version!({ [290000] });
 // == Blockchain ==
 crate::impl_client_v29__dump_tx_out_set!();
 crate::impl_client_v17__get_best_block_hash!();
-crate::impl_client_v17__get_block!();
+crate::impl_client_v29__get_block!();
 crate::impl_client_v17__get_blockchain_info!();
 crate::impl_client_v17__get_block_count!();
 crate::impl_client_v19__get_block_filter!();

client/src/client_sync/v30/mod.rs

@@ -28,7 +28,7 @@ crate::impl_client_check_expected_server_version!({ [300000, 300100, 300200] });
 // == Blockchain ==
 crate::impl_client_v29__dump_tx_out_set!();
 crate::impl_client_v17__get_best_block_hash!();
-crate::impl_client_v17__get_block!();
+crate::impl_client_v29__get_block!();
 crate::impl_client_v17__get_blockchain_info!();
 crate::impl_client_v17__get_block_count!();
 crate::impl_client_v19__get_block_filter!();

integration_test/tests/blockchain.rs

@@ -58,9 +58,54 @@ fn blockchain__get_block__modelled() {
     let model: Result<mtype::GetBlockVerboseOne, GetBlockVerboseOneError> = json.into_model();
     model.unwrap();
 
-    // TODO: Test getblock 2
-    // let json = node.client.get_block_with_verbosity(block_hash, 2).expect("getblock verbosity 2");
-    // assert!(json.into_model().is_ok());
+    #[cfg(not(feature = "v28_and_below"))]
+    {
+        let node = Node::with_wallet(Wallet::Default, &[]);
+        node.fund_wallet();
+        let (_address, mined_tx) = node.create_mined_transaction();
+        let block_hash = node.client.best_block_hash().expect("best_block_hash failed");
+
+        let json: GetBlockVerboseTwo =
+            node.client.get_block_verbose_two(block_hash).expect("getblock verbose=2");
+        let model: Result<mtype::GetBlockVerboseTwo, GetBlockVerboseTwoError> = json.into_model();
+        let block_v2 = model.unwrap();
+
+        assert_eq!(block_v2.tx.len(), block_v2.n_tx as usize);
+
+        let mined_txid = mined_tx.compute_txid();
+        let mined_entry = block_v2
+            .tx
+            .iter()
+            .find(|entry| entry.transaction.transaction.compute_txid() == mined_txid)
+            .expect("mined transaction should be present in verbosity=2 results");
+        assert!(mined_entry.fee.is_some());
+        assert!(!mined_entry.transaction.transaction.input.is_empty());
+        assert!(!mined_entry.transaction.transaction.output.is_empty());
+
+        let json: GetBlockVerboseThree =
+            node.client.get_block_verbose_three(block_hash).expect("getblock verbose=3");
+        let model: Result<mtype::GetBlockVerboseThree, GetBlockVerboseThreeError> =
+            json.into_model();
+        let block_v3 = model.unwrap();
+
+        assert_eq!(block_v3.tx.len(), block_v3.n_tx as usize);
+
+        let mined_entry = block_v3
+            .tx
+            .iter()
+            .find(|entry| entry.transaction.transaction.compute_txid() == mined_txid)
+            .expect("mined transaction should be present in verbosity=3 results");
+        assert!(
+            mined_entry.prevouts.iter().any(|prevout| prevout.is_some()),
+            "expected at least one prevout for the mined transaction"
+        );
+
+        for prevout in mined_entry.prevouts.iter().flatten() {
+            assert!(prevout.value.to_sat() > 0);
+            assert!(prevout.height <= block_v3.height);
+            assert!(!prevout.script_pubkey.script_pubkey.is_empty());
+        }
+    }
 }
 
 #[test]

types/src/model/blockchain.rs

@@ -15,7 +15,7 @@ use bitcoin::{
 };
 use serde::{Deserialize, Serialize};
 
-use super::ScriptPubkey;
+use super::{GetRawTransactionVerbose, ScriptPubkey};
 
 /// Models the result of JSON-RPC method `dumptxoutset`.
 #[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
@@ -69,7 +69,7 @@ pub struct GetBlockVerboseOne {
     pub median_time: Option<u32>,
     /// The nonce.
     pub nonce: u32,
-    /// The bits.
+    /// nBits: compact representation of the block difficulty target.
     pub bits: CompactTarget,
     /// The difficulty target.
     pub target: Option<Target>, // Only from v29 onwards
@@ -85,6 +85,126 @@ pub struct GetBlockVerboseOne {
     pub next_block_hash: Option<BlockHash>,
 }
 
+/// Models the result of JSON-RPC method `getblock` with verbosity set to 2.
+#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
+pub struct GetBlockVerboseTwo {
+    /// The block hash (same as provided).
+    pub hash: BlockHash,
+    /// The number of confirmations, or -1 if the block is not on the main chain.
+    pub confirmations: i64,
+    /// The block size.
+    pub size: u32,
+    /// The block size excluding witness data.
+    pub stripped_size: Option<u32>,
+    /// The block weight as defined in BIP-141.
+    pub weight: Weight,
+    /// The block height or index.
+    pub height: u32,
+    /// The block version.
+    pub version: block::Version,
+    /// The merkle root.
+    pub merkle_root: String,
+    /// The transactions.
+    pub tx: Vec<GetBlockVerboseTwoTransaction>,
+    /// The block time expressed in UNIX epoch time.
+    pub time: u32,
+    /// The median block time expressed in UNIX epoch time.
+    pub median_time: Option<u32>,
+    /// The nonce.
+    pub nonce: u32,
+    /// nBits: compact representation of the block difficulty target.
+    pub bits: CompactTarget,
+    /// The difficulty target.
+    pub target: Option<Target>,
+    /// The difficulty.
+    pub difficulty: f64,
+    /// Expected number of hashes required to produce the chain up to this block (in hex).
+    pub chain_work: Work,
+    /// The number of transactions in the block.
+    pub n_tx: u32,
+    /// The hash of the previous block (if available).
+    pub previous_block_hash: Option<BlockHash>,
+    /// The hash of the next block (if available).
+    pub next_block_hash: Option<BlockHash>,
+}
+
+/// A transaction entry for `getblock` verbosity 2.
+#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
+pub struct GetBlockVerboseTwoTransaction {
+    /// The transaction data (same as `getrawtransaction` verbose output).
+    pub transaction: GetRawTransactionVerbose,
+    /// The transaction fee in BTC (omitted if block undo data is not available).
+    pub fee: Option<Amount>,
+}
+
+/// Models the result of JSON-RPC method `getblock` with verbosity set to 3.
+#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
+pub struct GetBlockVerboseThree {
+    /// The block hash (same as provided) in RPC call.
+    pub hash: BlockHash,
+    /// The number of confirmations, or -1 if the block is not on the main chain.
+    pub confirmations: i64,
+    /// The block size.
+    pub size: u32,
+    /// The block size excluding witness data.
+    pub stripped_size: Option<u32>,
+    /// The block weight as defined in BIP-141.
+    pub weight: Weight,
+    /// The block height or index.
+    pub height: u32,
+    /// The block version.
+    pub version: block::Version,
+    /// The merkle root.
+    pub merkle_root: String,
+    /// The transactions.
+    pub tx: Vec<GetBlockVerboseThreeTransaction>,
+    /// The block time expressed in UNIX epoch time.
+    pub time: u32,
+    /// The median block time expressed in UNIX epoch time.
+    pub median_time: Option<u32>,
+    /// The nonce.
+    pub nonce: u32,
+    /// nBits: compact representation of the block difficulty target.
+    pub bits: CompactTarget,
+    /// The difficulty target.
+    pub target: Option<Target>,
+    /// The difficulty.
+    pub difficulty: f64,
+    /// Expected number of hashes required to produce the chain up to this block (in hex).
+    pub chain_work: Work,
+    /// The number of transactions in the block.
+    pub n_tx: u32,
+    /// The hash of the previous block (if available).
+    pub previous_block_hash: Option<BlockHash>,
+    /// The hash of the next block (if available).
+    pub next_block_hash: Option<BlockHash>,
+}
+
+/// A transaction entry for `getblock` verbosity 3.
+#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
+pub struct GetBlockVerboseThreeTransaction {
+    /// The transaction data (same as `getrawtransaction` verbose output).
+    pub transaction: GetRawTransactionVerbose,
+    /// The prevout data aligned with the transaction input order.
+    pub prevouts: Vec<Option<GetBlockVerboseThreePrevout>>,
+    /// The transaction fee in BTC, omitted if block undo data is not available.
+    pub fee: Option<Amount>,
+}
+
+/// The prevout information for a transaction input (verbosity 3 only).
+/// TODO: This type adding prevouts is exactly the same as the getrawtransaction's type with verbosity set to 2, which is not implemented yet. Consider reusing that structure when implemented.
+#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
+pub struct GetBlockVerboseThreePrevout {
+    /// Coinbase or not.
+    pub generated: bool,
+    /// The height of the prevout.
+    pub height: u32,
+    /// The value in BTC.
+    pub value: Amount,
+    /// The script pubkey.
+    pub script_pubkey: ScriptPubkey,
+}
+
 /// Models the result of JSON-RPC method `getblockchaininfo`.
 #[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
 pub struct GetBlockchainInfo {

types/src/model/mod.rs

@@ -29,11 +29,13 @@ pub use self::{
         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, GetRawMempoolSequence, GetRawMempoolVerbose, GetTxOut, GetTxOutSetInfo,
+        GetBlockHeaderVerbose, GetBlockStats, GetBlockVerboseOne, GetBlockVerboseThree,
+        GetBlockVerboseThreePrevout, GetBlockVerboseThreeTransaction, GetBlockVerboseTwo,
+        GetBlockVerboseTwoTransaction, GetBlockVerboseZero, GetBlockchainInfo, GetChainStates,
+        GetChainTips, GetChainTxStats, GetDeploymentInfo, GetDescriptorActivity, GetDifficulty,
+        GetMempoolAncestors, GetMempoolAncestorsVerbose, GetMempoolDescendants,
+        GetMempoolDescendantsVerbose, GetMempoolEntry, GetMempoolInfo, GetRawMempool,
+        GetRawMempoolSequence, GetRawMempoolVerbose, GetTxOut, GetTxOutSetInfo,
         GetTxOutSetInfoBlockInfo, GetTxOutSetInfoUnspendables, GetTxSpendingPrevout,
         GetTxSpendingPrevoutItem, LoadTxOutSet, MempoolEntry, MempoolEntryFees, ReceiveActivity,
         ScanBlocksStart, ScanTxOutSetStart, ScanTxOutSetUnspent, Softfork, SoftforkType,

types/src/psbt/error.rs

@@ -42,6 +42,12 @@ impl std::error::Error for RawTransactionError {
 pub enum RawTransactionInputError {
     /// Conversion of the input `txid` field failed.
     Txid(hex::HexToArrayError),
+    /// Input lacked both `txid` and `coinbase` data.
+    MissingTxid,
+    /// Input lacked the `vout` field for a non-coinbase input.
+    MissingVout,
+    /// Input lacked both `scriptSig` and `coinbase` data.
+    MissingScriptSig,
     /// Conversion of the input `script_sig` field failed.
     ScriptSig(hex::HexToBytesError),
     /// Conversion of one of the `witness` hex strings failed.
@@ -52,6 +58,12 @@ impl fmt::Display for RawTransactionInputError {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         match *self {
             Self::Txid(ref e) => write_err!(f, "conversion of the input `txid` field failed"; e),
+            Self::MissingTxid =>
+                write!(f, "missing both `txid` and `coinbase` fields for the transaction input"),
+            Self::MissingVout =>
+                write!(f, "missing `vout` field for non-coinbase transaction input"),
+            Self::MissingScriptSig =>
+                write!(f, "missing both `scriptSig` and `coinbase` data for the transaction input"),
             Self::ScriptSig(ref e) =>
                 write_err!(f, "conversion of the input `script_sig` field failed"; e),
             Self::Witness(ref e) =>
@@ -65,6 +77,9 @@ impl std::error::Error for RawTransactionInputError {
     fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
         match *self {
             Self::Txid(ref e) => Some(e),
+            Self::MissingTxid => None,
+            Self::MissingVout => None,
+            Self::MissingScriptSig => None,
             Self::ScriptSig(ref e) => Some(e),
             Self::Witness(ref e) => Some(e),
         }

types/src/psbt/mod.rs

@@ -76,13 +76,19 @@ impl RawTransaction {
 #[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
 #[cfg_attr(feature = "serde-deny-unknown-fields", serde(deny_unknown_fields))]
 pub struct RawTransactionInput {
-    /// The transaction id.
-    pub txid: String,
-    /// The output number.
-    pub vout: u32,
-    /// The script.
+    /// Coinbase data (present on coinbase transactions only).
+    #[serde(default)]
+    pub coinbase: Option<String>,
+    /// The transaction id (absent for coinbase inputs).
+    #[serde(default)]
+    pub txid: Option<String>,
+    /// The output number (absent for coinbase inputs).
+    #[serde(default)]
+    pub vout: Option<u32>,
+    /// The script (absent on coinbase inputs, the raw coinbase hex is available in `coinbase`).
     #[serde(rename = "scriptSig")]
-    pub script_sig: ScriptSig,
+    #[serde(default)]
+    pub script_sig: Option<ScriptSig>,
     /// Hex-encoded witness data (if any).
     #[serde(rename = "txinwitness")]
     pub txin_witness: Option<Vec<String>>,
@@ -95,16 +101,33 @@ impl RawTransactionInput {
     pub fn to_input(&self) -> Result<TxIn, RawTransactionInputError> {
         use RawTransactionInputError as E;
 
-        let txid = self.txid.parse::<Txid>().map_err(E::Txid)?;
-        let script_sig = self.script_sig.script_buf().map_err(E::ScriptSig)?;
+        // if txid is present, parse it
+        // if coinbase transaction, leave it empty
+        let previous_output = match (&self.txid, &self.coinbase) {
+            (Some(txid), _) => {
+                let parsed_txid = txid.parse::<Txid>().map_err(E::Txid)?;
+                let vout = self.vout.ok_or(RawTransactionInputError::MissingVout)?;
+                OutPoint { txid: parsed_txid, vout }
+            }
+            (None, Some(_)) => OutPoint::null(),
+            (None, None) => return Err(E::MissingTxid),
+        };
+
+        // if scriptSig is present, parse it
+        // if coinbase transaction, parse coinbase as scriptSig
+        let script_sig = match (&self.script_sig, &self.coinbase) {
+            (Some(script_sig), _) => script_sig.script_buf().map_err(E::ScriptSig)?,
+            (None, Some(coinbase)) => ScriptBuf::from_hex(coinbase).map_err(E::ScriptSig)?,
+            (None, None) => return Err(E::MissingScriptSig),
+        };
 
         let witness = match &self.txin_witness {
             Some(v) => crate::witness_from_hex_slice(v).map_err(E::Witness)?,
             None => Witness::new(),
         };
 
         Ok(TxIn {
-            previous_output: OutPoint { txid, vout: self.vout },
+            previous_output,
             script_sig,
             sequence: Sequence::from_consensus(self.sequence),
             witness,

types/src/v17/blockchain/into.rs

@@ -36,7 +36,7 @@ impl GetBlockVerboseOne {
         let hash = self.hash.parse::<BlockHash>().map_err(E::Hash)?;
         let stripped_size =
             self.stripped_size.map(|size| crate::to_u32(size, "stripped_size")).transpose()?;
-        let weight = Weight::from_wu(self.weight); // FIXME: Confirm this uses weight units.
+        let weight = Weight::from_wu(self.weight);
         let version = block::Version::from_consensus(self.version);
         let tx = self
             .tx