diff --git a/crates/interfaces/src/consensus.rs b/crates/interfaces/src/consensus.rs index 5bc212bd7..e151e42c2 100644 --- a/crates/interfaces/src/consensus.rs +++ b/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 }, - #[error( - "Block timestamp {timestamp} is in the past compared to the parent timestamp {parent_timestamp}." - )] - TimestampIsInPast { parent_timestamp: u64, timestamp: u64 }, + ParentHashMismatch { + /// The expected parent hash. + expected_parent_hash: H256, + /// The actual parent hash. + 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),