feature: Make a CompactDifficulty wrapper

Wrap the compact difficulty "bits" field in a CompactDifficulty struct,
and rename the header field for clarity.

zebra-chain/src/block.rs

@@ -1,6 +1,7 @@
 //! Definitions of block datastructures.
 #![allow(clippy::unit_arg)]
 
+mod difficulty;
 mod hash;
 mod header;
 mod serialize;

zebra-chain/src/block/difficulty.rs

@@ -0,0 +1,26 @@
+//! Block difficulty data structures and calculations
+//!
+//! The block difficulty "target threshold" is stored in the block header as a
+//! 32-bit "compact bits" value. The `BlockHeaderHash` must be less than or equal
+//! to the expanded target threshold, when represented as a 256-bit integer in
+//! little-endian order.
+//!
+//! The target threshold is also used to calculate the "work" for each block.
+//! The block work is used to find the chain with the greatest total work. Each
+//! block's work value depends on the fixed threshold in the block header, not
+//! the actual work represented by the block header hash.
+
+#[cfg(test)]
+use proptest_derive::Arbitrary;
+
+/// A 32-bit "compact bits" value, which represents the difficulty threshold for
+/// a block header.
+///
+/// Used for:
+///   - checking the `difficulty_threshold` value in the block header,
+///   - calculating the 256-bit `ExpandedDifficulty` threshold, for comparison
+///     with the block header hash, and
+///   - calculating the block work.
+#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
+#[cfg_attr(test, derive(Arbitrary))]
+pub struct CompactDifficulty(pub u32);

zebra-chain/src/block/header.rs

@@ -1,4 +1,4 @@
-use super::{BlockHeaderHash, Error};
+use super::{difficulty::CompactDifficulty, BlockHeaderHash, Error};
 use crate::equihash_solution::EquihashSolution;
 use crate::merkle_tree::MerkleTreeRootHash;
 use crate::note_commitment_tree::SaplingNoteTreeRootHash;
@@ -61,8 +61,7 @@ pub struct BlockHeader {
     /// `ThresholdBits(height)`.
     ///
     /// [Bitcoin-nBits](https://bitcoin.org/en/developer-reference#target-nbits)
-    // See #572 for details.
-    pub bits: u32,
+    pub difficulty_threshold: CompactDifficulty,
 
     /// An arbitrary field that miners can change to modify the header
     /// hash in order to produce a hash less than or equal to the

zebra-chain/src/block/serialize.rs

@@ -2,6 +2,7 @@ use byteorder::{LittleEndian, ReadBytesExt, WriteBytesExt};
 use chrono::{TimeZone, Utc};
 use std::io;
 
+use crate::block::difficulty::CompactDifficulty;
 use crate::equihash_solution::EquihashSolution;
 use crate::merkle_tree::MerkleTreeRootHash;
 use crate::note_commitment_tree::SaplingNoteTreeRootHash;
@@ -23,7 +24,7 @@ impl ZcashSerialize for BlockHeader {
         // but u32 times are valid until 2106, and our block verification time
         // checks should detect any truncation.
         writer.write_u32::<LittleEndian>(self.time.timestamp() as u32)?;
-        writer.write_u32::<LittleEndian>(self.bits)?;
+        writer.write_u32::<LittleEndian>(self.difficulty_threshold.0)?;
         writer.write_all(&self.nonce[..])?;
         self.solution.zcash_serialize(&mut writer)?;
         Ok(())
@@ -69,7 +70,7 @@ impl ZcashDeserialize for BlockHeader {
             final_sapling_root_hash: SaplingNoteTreeRootHash(reader.read_32_bytes()?),
             // This can't panic, because all u32 values are valid `Utc.timestamp`s
             time: Utc.timestamp(reader.read_u32::<LittleEndian>()? as i64, 0),
-            bits: reader.read_u32::<LittleEndian>()?,
+            difficulty_threshold: CompactDifficulty(reader.read_u32::<LittleEndian>()?),
             nonce: reader.read_32_bytes()?,
             solution: EquihashSolution::zcash_deserialize(reader)?,
         })

zebra-chain/src/block/tests.rs

@@ -1,5 +1,6 @@
 use super::*;
 
+use crate::block::difficulty::CompactDifficulty;
 use crate::equihash_solution::EquihashSolution;
 use crate::merkle_tree::MerkleTreeRootHash;
 use crate::note_commitment_tree::SaplingNoteTreeRootHash;
@@ -28,7 +29,7 @@ impl Arbitrary for BlockHeader {
             any::<SaplingNoteTreeRootHash>(),
             // time is interpreted as u32 in the spec, but rust timestamps are i64
             (0i64..(u32::MAX as i64)),
-            any::<u32>(),
+            any::<CompactDifficulty>(),
             any::<[u8; 32]>(),
             any::<EquihashSolution>(),
         )
@@ -39,7 +40,7 @@ impl Arbitrary for BlockHeader {
                     merkle_root_hash,
                     final_sapling_root_hash,
                     timestamp,
-                    bits,
+                    difficulty_threshold,
                     nonce,
                     solution,
                 )| BlockHeader {
@@ -48,7 +49,7 @@ impl Arbitrary for BlockHeader {
                     merkle_root_hash,
                     final_sapling_root_hash,
                     time: Utc.timestamp(timestamp, 0),
-                    bits,
+                    difficulty_threshold,
                     nonce,
                     solution,
                 },