diff --git a/zebra-chain/src/block.rs b/zebra-chain/src/block.rs index 4392db12..e73e312f 100644 --- a/zebra-chain/src/block.rs +++ b/zebra-chain/src/block.rs @@ -1,206 +1,24 @@ //! Definitions of block datastructures. #![allow(clippy::unit_arg)] +mod hash; +mod header; +mod serialize; + #[cfg(test)] mod tests; -use byteorder::{LittleEndian, ReadBytesExt, WriteBytesExt}; -use chrono::{DateTime, TimeZone, Utc}; use serde::{Deserialize, Serialize}; -use std::{fmt, io, sync::Arc}; +use std::sync::Arc; #[cfg(test)] use proptest_derive::Arbitrary; -use crate::equihash_solution::EquihashSolution; -use crate::merkle_tree::MerkleTreeRootHash; -use crate::note_commitment_tree::SaplingNoteTreeRootHash; -use crate::serialization::{ReadZcashExt, SerializationError, ZcashDeserialize, ZcashSerialize}; -use crate::sha256d_writer::Sha256dWriter; use crate::transaction::Transaction; use crate::types::BlockHeight; -/// A SHA-256d hash of a BlockHeader. -/// -/// This is useful when one block header is pointing to its parent -/// block header in the block chain. ⛓️ -/// -/// This is usually called a 'block hash', as it is frequently used -/// to identify the entire block, since the hash preimage includes -/// the merkle root of the transactions in this block. But -/// _technically_, this is just a hash of the block _header_, not -/// the direct bytes of the transactions as well as the header. So -/// for now I want to call it a `BlockHeaderHash` because that's -/// more explicit. -#[derive(Copy, Clone, Eq, PartialEq, Hash, Serialize, Deserialize)] -#[cfg_attr(test, derive(Arbitrary))] -pub struct BlockHeaderHash(pub [u8; 32]); - -impl fmt::Debug for BlockHeaderHash { - fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { - f.debug_tuple("BlockHeaderHash") - .field(&hex::encode(&self.0)) - .finish() - } -} - -impl<'a> From<&'a BlockHeader> for BlockHeaderHash { - fn from(block_header: &'a BlockHeader) -> Self { - let mut hash_writer = Sha256dWriter::default(); - block_header - .zcash_serialize(&mut hash_writer) - .expect("Sha256dWriter is infallible"); - Self(hash_writer.finish()) - } -} - -impl ZcashSerialize for BlockHeaderHash { - fn zcash_serialize(&self, mut writer: W) -> Result<(), io::Error> { - writer.write_all(&self.0)?; - Ok(()) - } -} - -impl ZcashDeserialize for BlockHeaderHash { - fn zcash_deserialize(mut reader: R) -> Result { - Ok(BlockHeaderHash(reader.read_32_bytes()?)) - } -} - -impl std::str::FromStr for BlockHeaderHash { - type Err = SerializationError; - fn from_str(s: &str) -> Result { - let mut bytes = [0; 32]; - if hex::decode_to_slice(s, &mut bytes[..]).is_err() { - Err(SerializationError::Parse("hex decoding error")) - } else { - Ok(BlockHeaderHash(bytes)) - } - } -} - -/// Block header. -/// -/// How are blocks chained together? They are chained together via the -/// backwards reference (previous header hash) present in the block -/// header. Each block points backwards to its parent, all the way -/// back to the genesis block (the first block in the blockchain). -#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)] -pub struct BlockHeader { - /// The block's version field. This is supposed to be `4`: - /// - /// > The current and only defined block version number for Zcash is 4. - /// - /// but this was not enforced by the consensus rules, and defective mining - /// software created blocks with other versions, so instead it's effectively - /// a free field. The only constraint is that it must be at least `4` when - /// interpreted as an `i32`. - pub version: u32, - - /// A SHA-256d hash in internal byte order of the previous block’s - /// header. This ensures no previous block can be changed without - /// also changing this block’s header. - pub previous_block_hash: BlockHeaderHash, - - /// A SHA-256d hash in internal byte order. The merkle root is - /// derived from the SHA256d hashes of all transactions included - /// in this block as assembled in a binary tree, ensuring that - /// none of those transactions can be modied without modifying the - /// header. - pub merkle_root_hash: MerkleTreeRootHash, - - /// [Sapling onward] The root LEBS2OSP256(rt) of the Sapling note - /// commitment tree corresponding to the final Sapling treestate of - /// this block. - pub final_sapling_root_hash: SaplingNoteTreeRootHash, - - /// The block timestamp is a Unix epoch time (UTC) when the miner - /// started hashing the header (according to the miner). - pub time: DateTime, - - /// An encoded version of the target threshold this block’s header - /// hash must be less than or equal to, in the same nBits format - /// used by Bitcoin. - /// - /// For a block at block height height, bits MUST be equal to - /// ThresholdBits(height). - /// - /// [Bitcoin-nBits](https://bitcoin.org/en/developer-reference#target-nbits) - // pzec has their own wrapper around u32 for this field: - // https://github.com/ZcashFoundation/zebra/blob/master/zebra-primitives/src/compact.rs - pub bits: u32, - - /// An arbitrary field that miners can change to modify the header - /// hash in order to produce a hash less than or equal to the - /// target threshold. - pub nonce: [u8; 32], - - /// The Equihash solution. - pub solution: EquihashSolution, -} - -impl ZcashSerialize for BlockHeader { - fn zcash_serialize(&self, mut writer: W) -> Result<(), io::Error> { - writer.write_u32::(self.version)?; - self.previous_block_hash.zcash_serialize(&mut writer)?; - writer.write_all(&self.merkle_root_hash.0[..])?; - writer.write_all(&self.final_sapling_root_hash.0[..])?; - // this is a truncating cast, rather than a saturating cast - // but u32 times are valid until 2106, and our block verification time - // checks should detect any truncation. - writer.write_u32::(self.time.timestamp() as u32)?; - writer.write_u32::(self.bits)?; - writer.write_all(&self.nonce[..])?; - self.solution.zcash_serialize(&mut writer)?; - Ok(()) - } -} - -impl ZcashDeserialize for BlockHeader { - fn zcash_deserialize(mut reader: R) -> Result { - // The Zcash specification says that - // "The current and only defined block version number for Zcash is 4." - // but this is not actually part of the consensus rules, and in fact - // broken mining software created blocks that do not have version 4. - // There are approximately 4,000 blocks with version 536870912; this - // is the bit-reversal of the value 4, indicating that that mining pool - // reversed bit-ordering of the version field. Because the version field - // was not properly validated, these blocks were added to the chain. - // - // The only possible way to work around this is to do a similar hack - // as the overwintered field in transaction parsing, which we do here: - // treat the high bit (which zcashd interprets as a sign bit) as an - // indicator that the version field is meaningful. - // - // - let (version, future_version_flag) = { - const LOW_31_BITS: u32 = (1 << 31) - 1; - let raw_version = reader.read_u32::()?; - (raw_version & LOW_31_BITS, raw_version >> 31 != 0) - }; - - if future_version_flag { - return Err(SerializationError::Parse( - "high bit was set in version field", - )); - } - if version < 4 { - return Err(SerializationError::Parse("version must be at least 4")); - } - - Ok(BlockHeader { - version, - previous_block_hash: BlockHeaderHash::zcash_deserialize(&mut reader)?, - merkle_root_hash: MerkleTreeRootHash(reader.read_32_bytes()?), - 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::()? as i64, 0), - bits: reader.read_u32::()?, - nonce: reader.read_32_bytes()?, - solution: EquihashSolution::zcash_deserialize(reader)?, - }) - } -} +pub use hash::BlockHeaderHash; +pub use header::BlockHeader; /// A block in your blockchain. /// @@ -244,25 +62,3 @@ impl<'a> From<&'a Block> for BlockHeaderHash { (&block.header).into() } } - -impl ZcashSerialize for Block { - fn zcash_serialize(&self, mut writer: W) -> Result<(), io::Error> { - // All block structs are validated when they are parsed. - // So we don't need to check MAX_BLOCK_BYTES here, until - // we start generating our own blocks (see #483). - self.header.zcash_serialize(&mut writer)?; - self.transactions.zcash_serialize(&mut writer)?; - Ok(()) - } -} - -impl ZcashDeserialize for Block { - fn zcash_deserialize(reader: R) -> Result { - // If the limit is reached, we'll get an UnexpectedEof error - let mut limited_reader = reader.take(MAX_BLOCK_BYTES); - Ok(Block { - header: BlockHeader::zcash_deserialize(&mut limited_reader)?, - transactions: Vec::zcash_deserialize(&mut limited_reader)?, - }) - } -} diff --git a/zebra-chain/src/block/hash.rs b/zebra-chain/src/block/hash.rs new file mode 100644 index 00000000..5b0472bd --- /dev/null +++ b/zebra-chain/src/block/hash.rs @@ -0,0 +1,71 @@ +use std::{fmt, io}; + +#[cfg(test)] +use proptest_derive::Arbitrary; +use serde::{Deserialize, Serialize}; + +use crate::{ + serialization::{ReadZcashExt, SerializationError, ZcashDeserialize, ZcashSerialize}, + sha256d_writer::Sha256dWriter, +}; + +use super::BlockHeader; + +/// A SHA-256d hash of a BlockHeader. +/// +/// This is useful when one block header is pointing to its parent +/// block header in the block chain. ⛓️ +/// +/// This is usually called a 'block hash', as it is frequently used +/// to identify the entire block, since the hash preimage includes +/// the merkle root of the transactions in this block. But +/// _technically_, this is just a hash of the block _header_, not +/// the direct bytes of the transactions as well as the header. So +/// for now I want to call it a `BlockHeaderHash` because that's +/// more explicit. +#[derive(Copy, Clone, Eq, PartialEq, Hash, Serialize, Deserialize)] +#[cfg_attr(test, derive(Arbitrary))] +pub struct BlockHeaderHash(pub [u8; 32]); + +impl fmt::Debug for BlockHeaderHash { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.debug_tuple("BlockHeaderHash") + .field(&hex::encode(&self.0)) + .finish() + } +} + +impl<'a> From<&'a BlockHeader> for BlockHeaderHash { + fn from(block_header: &'a BlockHeader) -> Self { + let mut hash_writer = Sha256dWriter::default(); + block_header + .zcash_serialize(&mut hash_writer) + .expect("Sha256dWriter is infallible"); + Self(hash_writer.finish()) + } +} + +impl ZcashSerialize for BlockHeaderHash { + fn zcash_serialize(&self, mut writer: W) -> Result<(), io::Error> { + writer.write_all(&self.0)?; + Ok(()) + } +} + +impl ZcashDeserialize for BlockHeaderHash { + fn zcash_deserialize(mut reader: R) -> Result { + Ok(BlockHeaderHash(reader.read_32_bytes()?)) + } +} + +impl std::str::FromStr for BlockHeaderHash { + type Err = SerializationError; + fn from_str(s: &str) -> Result { + let mut bytes = [0; 32]; + if hex::decode_to_slice(s, &mut bytes[..]).is_err() { + Err(SerializationError::Parse("hex decoding error")) + } else { + Ok(BlockHeaderHash(bytes)) + } + } +} diff --git a/zebra-chain/src/block/header.rs b/zebra-chain/src/block/header.rs new file mode 100644 index 00000000..9966b3c4 --- /dev/null +++ b/zebra-chain/src/block/header.rs @@ -0,0 +1,67 @@ +use chrono::{DateTime, Utc}; + +use crate::equihash_solution::EquihashSolution; +use crate::merkle_tree::MerkleTreeRootHash; +use crate::note_commitment_tree::SaplingNoteTreeRootHash; + +use super::BlockHeaderHash; + +/// Block header. +/// +/// How are blocks chained together? They are chained together via the +/// backwards reference (previous header hash) present in the block +/// header. Each block points backwards to its parent, all the way +/// back to the genesis block (the first block in the blockchain). +#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)] +pub struct BlockHeader { + /// The block's version field. This is supposed to be `4`: + /// + /// > The current and only defined block version number for Zcash is 4. + /// + /// but this was not enforced by the consensus rules, and defective mining + /// software created blocks with other versions, so instead it's effectively + /// a free field. The only constraint is that it must be at least `4` when + /// interpreted as an `i32`. + pub version: u32, + + /// A SHA-256d hash in internal byte order of the previous block’s + /// header. This ensures no previous block can be changed without + /// also changing this block’s header. + pub previous_block_hash: BlockHeaderHash, + + /// A SHA-256d hash in internal byte order. The merkle root is + /// derived from the SHA256d hashes of all transactions included + /// in this block as assembled in a binary tree, ensuring that + /// none of those transactions can be modied without modifying the + /// header. + pub merkle_root_hash: MerkleTreeRootHash, + + /// [Sapling onward] The root LEBS2OSP256(rt) of the Sapling note + /// commitment tree corresponding to the final Sapling treestate of + /// this block. + pub final_sapling_root_hash: SaplingNoteTreeRootHash, + + /// The block timestamp is a Unix epoch time (UTC) when the miner + /// started hashing the header (according to the miner). + pub time: DateTime, + + /// An encoded version of the target threshold this block’s header + /// hash must be less than or equal to, in the same nBits format + /// used by Bitcoin. + /// + /// For a block at block height height, bits MUST be equal to + /// ThresholdBits(height). + /// + /// [Bitcoin-nBits](https://bitcoin.org/en/developer-reference#target-nbits) + // pzec has their own wrapper around u32 for this field: + // https://github.com/ZcashFoundation/zebra/blob/master/zebra-primitives/src/compact.rs + pub bits: u32, + + /// An arbitrary field that miners can change to modify the header + /// hash in order to produce a hash less than or equal to the + /// target threshold. + pub nonce: [u8; 32], + + /// The Equihash solution. + pub solution: EquihashSolution, +} diff --git a/zebra-chain/src/block/serialize.rs b/zebra-chain/src/block/serialize.rs new file mode 100644 index 00000000..c5eafa44 --- /dev/null +++ b/zebra-chain/src/block/serialize.rs @@ -0,0 +1,98 @@ +use byteorder::{LittleEndian, ReadBytesExt, WriteBytesExt}; +use chrono::{TimeZone, Utc}; +use std::io; + +use crate::equihash_solution::EquihashSolution; +use crate::merkle_tree::MerkleTreeRootHash; +use crate::note_commitment_tree::SaplingNoteTreeRootHash; +use crate::serialization::{ReadZcashExt, SerializationError, ZcashDeserialize, ZcashSerialize}; + +use super::Block; +use super::BlockHeader; +use super::BlockHeaderHash; +use super::MAX_BLOCK_BYTES; + +impl ZcashSerialize for BlockHeader { + fn zcash_serialize(&self, mut writer: W) -> Result<(), io::Error> { + writer.write_u32::(self.version)?; + self.previous_block_hash.zcash_serialize(&mut writer)?; + writer.write_all(&self.merkle_root_hash.0[..])?; + writer.write_all(&self.final_sapling_root_hash.0[..])?; + // this is a truncating cast, rather than a saturating cast + // but u32 times are valid until 2106, and our block verification time + // checks should detect any truncation. + writer.write_u32::(self.time.timestamp() as u32)?; + writer.write_u32::(self.bits)?; + writer.write_all(&self.nonce[..])?; + self.solution.zcash_serialize(&mut writer)?; + Ok(()) + } +} + +impl ZcashDeserialize for BlockHeader { + fn zcash_deserialize(mut reader: R) -> Result { + // The Zcash specification says that + // "The current and only defined block version number for Zcash is 4." + // but this is not actually part of the consensus rules, and in fact + // broken mining software created blocks that do not have version 4. + // There are approximately 4,000 blocks with version 536870912; this + // is the bit-reversal of the value 4, indicating that that mining pool + // reversed bit-ordering of the version field. Because the version field + // was not properly validated, these blocks were added to the chain. + // + // The only possible way to work around this is to do a similar hack + // as the overwintered field in transaction parsing, which we do here: + // treat the high bit (which zcashd interprets as a sign bit) as an + // indicator that the version field is meaningful. + // + // + let (version, future_version_flag) = { + const LOW_31_BITS: u32 = (1 << 31) - 1; + let raw_version = reader.read_u32::()?; + (raw_version & LOW_31_BITS, raw_version >> 31 != 0) + }; + + if future_version_flag { + return Err(SerializationError::Parse( + "high bit was set in version field", + )); + } + if version < 4 { + return Err(SerializationError::Parse("version must be at least 4")); + } + + Ok(BlockHeader { + version, + previous_block_hash: BlockHeaderHash::zcash_deserialize(&mut reader)?, + merkle_root_hash: MerkleTreeRootHash(reader.read_32_bytes()?), + 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::()? as i64, 0), + bits: reader.read_u32::()?, + nonce: reader.read_32_bytes()?, + solution: EquihashSolution::zcash_deserialize(reader)?, + }) + } +} + +impl ZcashSerialize for Block { + fn zcash_serialize(&self, mut writer: W) -> Result<(), io::Error> { + // All block structs are validated when they are parsed. + // So we don't need to check MAX_BLOCK_BYTES here, until + // we start generating our own blocks (see #483). + self.header.zcash_serialize(&mut writer)?; + self.transactions.zcash_serialize(&mut writer)?; + Ok(()) + } +} + +impl ZcashDeserialize for Block { + fn zcash_deserialize(reader: R) -> Result { + // If the limit is reached, we'll get an UnexpectedEof error + let mut limited_reader = reader.take(MAX_BLOCK_BYTES); + Ok(Block { + header: BlockHeader::zcash_deserialize(&mut limited_reader)?, + transactions: Vec::zcash_deserialize(&mut limited_reader)?, + }) + } +} diff --git a/zebra-chain/src/block/tests.rs b/zebra-chain/src/block/tests.rs index 98c2fd77..54456210 100644 --- a/zebra-chain/src/block/tests.rs +++ b/zebra-chain/src/block/tests.rs @@ -1,11 +1,15 @@ +use chrono::{DateTime, NaiveDateTime, TimeZone, Utc}; use std::io::{Cursor, ErrorKind, Write}; -use chrono::NaiveDateTime; use proptest::{ arbitrary::{any, Arbitrary}, prelude::*, }; +use crate::equihash_solution::EquihashSolution; +use crate::merkle_tree::MerkleTreeRootHash; +use crate::note_commitment_tree::SaplingNoteTreeRootHash; +use crate::serialization::{SerializationError, ZcashDeserialize, ZcashSerialize}; use crate::sha256d_writer::Sha256dWriter; use super::*;