From d57390d265c3941afd027f016d0b7ac62e2edb2f Mon Sep 17 00:00:00 2001 From: Henry de Valence Date: Sun, 16 Aug 2020 12:08:24 -0700 Subject: [PATCH] chain: doc tweaks (mostly block::) --- zebra-chain/src/amount.rs | 2 +- zebra-chain/src/block.rs | 7 +------ zebra-chain/src/block/hash.rs | 15 ++++----------- zebra-chain/src/block/header.rs | 20 +++++++++++--------- zebra-chain/src/block/height.rs | 2 +- zebra-chain/src/block/merkle.rs | 3 +-- 6 files changed, 19 insertions(+), 30 deletions(-) diff --git a/zebra-chain/src/amount.rs b/zebra-chain/src/amount.rs index 857d04bf1..23b6e9c6f 100644 --- a/zebra-chain/src/amount.rs +++ b/zebra-chain/src/amount.rs @@ -3,7 +3,7 @@ //! The [`Amount`] type is parameterized by a [`Constraint`] implementation that //! declares the range of allowed values. In contrast to regular arithmetic //! operations, which return values, arithmetic on [`Amount`]s returns -//! [`Result`]s. +//! [`Result`](std::result::Result)s. use std::{ convert::{TryFrom, TryInto}, diff --git a/zebra-chain/src/block.rs b/zebra-chain/src/block.rs index 5bf636e13..72bc908bd 100644 --- a/zebra-chain/src/block.rs +++ b/zebra-chain/src/block.rs @@ -28,12 +28,7 @@ use crate::transaction::Transaction; #[cfg(test)] use proptest_derive::Arbitrary; -/// A block in your blockchain. -/// -/// A block is a data structure with two fields: -/// -/// Block header: a data structure containing the block's metadata -/// Transactions: an array (vector in Rust) of transactions +/// A Zcash block, containing a header and a list of transactions. #[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)] #[cfg_attr(test, derive(Arbitrary))] pub struct Block { diff --git a/zebra-chain/src/block/hash.rs b/zebra-chain/src/block/hash.rs index 966047fe8..1c40cb974 100644 --- a/zebra-chain/src/block/hash.rs +++ b/zebra-chain/src/block/hash.rs @@ -10,18 +10,11 @@ use crate::serialization::{ use super::Header; -/// A SHA-256d hash of a BlockHeader. +/// A hash of a block, used to identify blocks and link blocks into a chain. ⛓️ /// -/// 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. +/// Technically, this is the (SHA256d) hash of a block *header*, but since the +/// block header includes the Merkle root of the transaction Merkle tree, it +/// binds the entire contents of the block and is used to identify entire blocks. #[derive(Copy, Clone, Eq, PartialEq, Hash, Serialize, Deserialize)] #[cfg_attr(test, derive(Arbitrary))] pub struct Hash(pub [u8; 32]); diff --git a/zebra-chain/src/block/header.rs b/zebra-chain/src/block/header.rs index f0ff49bdd..9be278622 100644 --- a/zebra-chain/src/block/header.rs +++ b/zebra-chain/src/block/header.rs @@ -5,7 +5,7 @@ use crate::work::{difficulty::CompactDifficulty, equihash::Solution}; use super::{merkle, Error, Hash}; -/// Block header. +/// A block header, containing metadata about a block. /// /// How are blocks chained together? They are chained together via the /// backwards reference (previous header hash) present in the block @@ -23,16 +23,18 @@ pub struct Header { /// 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. + /// The hash of the previous block, used to create a chain of blocks back to + /// the genesis block. + /// + /// This ensures no previous block can be changed without also changing this + /// block’s header. pub previous_block_hash: Hash, - /// 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. + /// The root of the transaction Merkle tree. + /// + /// 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: merkle::Root, /// Some kind of root hash. diff --git a/zebra-chain/src/block/height.rs b/zebra-chain/src/block/height.rs index 223685869..1399f990f 100644 --- a/zebra-chain/src/block/height.rs +++ b/zebra-chain/src/block/height.rs @@ -1,6 +1,6 @@ use crate::serialization::SerializationError; -/// A u32 which represents a block height value. +/// The height of a block is the length of the chain back to the genesis block. /// /// # Invariants /// diff --git a/zebra-chain/src/block/merkle.rs b/zebra-chain/src/block/merkle.rs index a5f763584..8bd4e9fe6 100644 --- a/zebra-chain/src/block/merkle.rs +++ b/zebra-chain/src/block/merkle.rs @@ -1,5 +1,4 @@ -//! A binary hash tree of SHA256d (two rounds of SHA256) hashes for -//! node values. +//! The Bitcoin-inherited Merkle tree of transactions. #![allow(clippy::unit_arg)] use std::{fmt, io};