feat(interfaces): better documentation for ConsensusError (#4725)

crates/interfaces/src/consensus.rs

@@ -81,87 +81,250 @@ pub trait Consensus: Debug + Send + Sync {
 #[allow(missing_docs)]
 #[derive(thiserror::Error, Debug, PartialEq, Eq, Clone)]
 pub enum ConsensusError {
+    /// Error when the gas used in the header exceeds the gas limit.
     #[error("Block used gas ({gas_used}) is greater than gas limit ({gas_limit}).")]
-    HeaderGasUsedExceedsGasLimit { gas_used: u64, gas_limit: u64 },
+    HeaderGasUsedExceedsGasLimit {
+        /// The gas used in the block header.
+        gas_used: u64,
+        /// The gas limit in the block header.
+        gas_limit: u64,
+    },
+
+    /// Error when the hash of block ommer is different from the expected hash.
     #[error("Block ommer hash ({got:?}) is different from expected: ({expected:?})")]
-    BodyOmmersHashDiff { got: H256, expected: H256 },
+    BodyOmmersHashDiff {
+        /// The actual ommer hash.
+        got: H256,
+        /// The expected ommer hash.
+        expected: H256,
+    },
+
+    /// Error when the state root in the block is different from the expected state root.
     #[error("Block state root ({got:?}) is different from expected: ({expected:?})")]
-    BodyStateRootDiff { got: H256, expected: H256 },
+    BodyStateRootDiff {
+        /// The actual state root.
+        got: H256,
+        /// The expected state root.
+        expected: H256,
+    },
+
+    /// Error when the transaction root in the block is different from the expected transaction
+    /// root.
     #[error("Block transaction root ({got:?}) is different from expected ({expected:?})")]
-    BodyTransactionRootDiff { got: H256, expected: H256 },
+    BodyTransactionRootDiff {
+        /// The actual transaction root.
+        got: H256,
+        /// The expected transaction root.
+        expected: H256,
+    },
+
+    /// Error when the withdrawals root in the block is different from the expected withdrawals
+    /// root.
     #[error("Block withdrawals root ({got:?}) is different from expected ({expected:?})")]
-    BodyWithdrawalsRootDiff { got: H256, expected: H256 },
+    BodyWithdrawalsRootDiff {
+        /// The actual withdrawals root.
+        got: H256,
+        /// The expected withdrawals root.
+        expected: H256,
+    },
+
+    /// Error when a block with a specific hash and number is already known.
     #[error("Block with [hash:{hash:?},number: {number}] is already known.")]
-    BlockKnown { hash: BlockHash, number: BlockNumber },
+    BlockKnown {
+        /// The hash of the known block.
+        hash: BlockHash,
+        /// The block number of the known block.
+        number: BlockNumber,
+    },
+
+    /// Error when the parent hash of a block is not known.
     #[error("Block parent [hash:{hash:?}] is not known.")]
-    ParentUnknown { hash: BlockHash },
+    ParentUnknown {
+        /// The hash of the unknown parent block.
+        hash: BlockHash,
+    },
+
+    /// Error when the block number does not match the parent block number.
     #[error(
         "Block number {block_number} does not match parent block number {parent_block_number}"
     )]
-    ParentBlockNumberMismatch { parent_block_number: BlockNumber, block_number: BlockNumber },
+    ParentBlockNumberMismatch {
+        /// The parent block number.
+        parent_block_number: BlockNumber,
+        /// The block number.
+        block_number: BlockNumber,
+    },
+
+    /// Error when the parent hash does not match the expected parent hash.
     #[error(
         "Parent hash {got_parent_hash:?} does not match the expected {expected_parent_hash:?}"
     )]
-    ParentHashMismatch { expected_parent_hash: H256, got_parent_hash: H256 },
+    ParentHashMismatch {
-    #[error(
+        /// The expected parent hash.
-        "Block timestamp {timestamp} is in the past compared to the parent timestamp {parent_timestamp}."
+        expected_parent_hash: H256,
-    )]
+        /// The actual parent hash.
-    TimestampIsInPast { parent_timestamp: u64, timestamp: u64 },
+        got_parent_hash: H256,
+    },
+
+    /// Error when the block timestamp is in the past compared to the parent timestamp.
+    #[error("Block timestamp {timestamp} is in the past compared to the parent timestamp {parent_timestamp}.")]
+    TimestampIsInPast {
+        /// The parent block's timestamp.
+        parent_timestamp: u64,
+        /// The block's timestamp.
+        timestamp: u64,
+    },
+
+    /// Error when the block timestamp is in the future compared to our clock time.
     #[error("Block timestamp {timestamp} is in the future compared to our clock time {present_timestamp}.")]
-    TimestampIsInFuture { timestamp: u64, present_timestamp: u64 },
+    TimestampIsInFuture {
+        /// The block's timestamp.
+        timestamp: u64,
+        /// The current timestamp.
+        present_timestamp: u64,
+    },
+
+    /// Error when the child gas limit exceeds the maximum allowed increase.
     #[error("Child gas_limit {child_gas_limit} max increase is {parent_gas_limit}/1024.")]
-    GasLimitInvalidIncrease { parent_gas_limit: u64, child_gas_limit: u64 },
+    GasLimitInvalidIncrease {
+        /// The parent gas limit.
+        parent_gas_limit: u64,
+        /// The child gas limit.
+        child_gas_limit: u64,
+    },
+
+    /// Error when the child gas limit exceeds the maximum allowed decrease.
     #[error("Child gas_limit {child_gas_limit} max decrease is {parent_gas_limit}/1024.")]
-    GasLimitInvalidDecrease { parent_gas_limit: u64, child_gas_limit: u64 },
+    GasLimitInvalidDecrease {
+        /// The parent gas limit.
+        parent_gas_limit: u64,
+        /// The child gas limit.
+        child_gas_limit: u64,
+    },
+
+    /// Error when the base fee is missing.
     #[error("Base fee missing.")]
     BaseFeeMissing,
+
+    /// Error when the block's base fee is different from the expected base fee.
     #[error("Block base fee ({got}) is different than expected: ({expected}).")]
-    BaseFeeDiff { expected: u64, got: u64 },
+    BaseFeeDiff {
+        /// The expected base fee.
+        expected: u64,
+        /// The actual base fee.
+        got: u64,
+    },
+
+    /// Error when there is a transaction signer recovery error.
     #[error("Transaction signer recovery error.")]
     TransactionSignerRecoveryError,
-    #[error("Extra data {len} exceeds max length: ")]
+
-    ExtraDataExceedsMax { len: usize },
+    /// Error when the extra data length exceeds the maximum allowed.
+    #[error("Extra data {len} exceeds max length.")]
+    ExtraDataExceedsMax {
+        /// The length of the extra data.
+        len: usize,
+    },
+
+    /// Error when the difficulty after a merge is not zero.
     #[error("Difficulty after merge is not zero")]
     TheMergeDifficultyIsNotZero,
+
+    /// Error when the nonce after a merge is not zero.
     #[error("Nonce after merge is not zero")]
     TheMergeNonceIsNotZero,
+
+    /// Error when the ommer root after a merge is not empty.
     #[error("Ommer root after merge is not empty")]
     TheMergeOmmerRootIsNotEmpty,
+
+    /// Error when the withdrawals root is missing.
     #[error("Missing withdrawals root")]
     WithdrawalsRootMissing,
+
+    /// Error when an unexpected withdrawals root is encountered.
     #[error("Unexpected withdrawals root")]
     WithdrawalsRootUnexpected,
+
+    /// Error when the withdrawal index is invalid.
     #[error("Withdrawal index #{got} is invalid. Expected: #{expected}.")]
-    WithdrawalIndexInvalid { got: u64, expected: u64 },
+    WithdrawalIndexInvalid {
+        /// The actual withdrawal index.
+        got: u64,
+        /// The expected withdrawal index.
+        expected: u64,
+    },
+
+    /// Error when withdrawals are missing.
     #[error("Missing withdrawals")]
     BodyWithdrawalsMissing,
+
+    /// Error when blob gas used is missing.
     #[error("Missing blob gas used")]
     BlobGasUsedMissing,
+
+    /// Error when unexpected blob gas used is encountered.
     #[error("Unexpected blob gas used")]
     BlobGasUsedUnexpected,
+
+    /// Error when excess blob gas is missing.
     #[error("Missing excess blob gas")]
     ExcessBlobGasMissing,
+
+    /// Error when unexpected excess blob gas is encountered.
     #[error("Unexpected excess blob gas")]
     ExcessBlobGasUnexpected,
+
+    /// Error when the parent beacon block root is missing.
     #[error("Missing parent beacon block root")]
     ParentBeaconBlockRootMissing,
+
+    /// Error when an unexpected parent beacon block root is encountered.
     #[error("Unexpected parent beacon block root")]
     ParentBeaconBlockRootUnexpected,
+
+    /// Error when blob gas used exceeds the maximum allowed.
     #[error("Blob gas used {blob_gas_used} exceeds maximum allowance {max_blob_gas_per_block}")]
-    BlobGasUsedExceedsMaxBlobGasPerBlock { blob_gas_used: u64, max_blob_gas_per_block: u64 },
+    BlobGasUsedExceedsMaxBlobGasPerBlock {
+        /// The actual blob gas used.
+        blob_gas_used: u64,
+        /// The maximum allowed blob gas per block.
+        max_blob_gas_per_block: u64,
+    },
+
+    /// Error when blob gas used is not a multiple of blob gas per blob.
     #[error(
         "Blob gas used {blob_gas_used} is not a multiple of blob gas per blob {blob_gas_per_blob}"
     )]
-    BlobGasUsedNotMultipleOfBlobGasPerBlob { blob_gas_used: u64, blob_gas_per_blob: u64 },
+    BlobGasUsedNotMultipleOfBlobGasPerBlob {
+        /// The actual blob gas used.
+        blob_gas_used: u64,
+        /// The blob gas per blob.
+        blob_gas_per_blob: u64,
+    },
+
+    /// Error when the blob gas used in the header does not match the expected blob gas used.
     #[error("Blob gas used in the header {header_blob_gas_used} does not match the expected blob gas used {expected_blob_gas_used}")]
-    BlobGasUsedDiff { header_blob_gas_used: u64, expected_blob_gas_used: u64 },
+    BlobGasUsedDiff {
+        /// The blob gas used in the header.
+        header_blob_gas_used: u64,
+        /// The expected blob gas used.
+        expected_blob_gas_used: u64,
+    },
+
+    /// Error when there is an invalid excess blob gas.
     #[error("Invalid excess blob gas. Expected: {expected}, got: {got}. Parent excess blob gas: {parent_excess_blob_gas}, parent blob gas used: {parent_blob_gas_used}.")]
     ExcessBlobGasDiff {
+        /// The expected excess blob gas.
         expected: u64,
+        /// The actual excess blob gas.
         got: u64,
+        /// The parent excess blob gas.
         parent_excess_blob_gas: u64,
+        /// The parent blob gas used.
         parent_blob_gas_used: u64,
     },
+
     /// Error for a transaction that violates consensus.
     #[error(transparent)]
     InvalidTransaction(#[from] InvalidTransactionError),