From 61f95e0415122604a2b5221ffd0a439738e31f12 Mon Sep 17 00:00:00 2001 From: Gav Wood Date: Wed, 3 Feb 2016 12:18:12 +0100 Subject: [PATCH] Additional documentation. --- ethcore/src/error.rs | 109 +++++++++++++++++---------------- ethcore/src/ethereum/ethash.rs | 10 +-- ethcore/src/verification.rs | 2 +- 3 files changed, 63 insertions(+), 58 deletions(-) diff --git a/ethcore/src/error.rs b/ethcore/src/error.rs index 96a362025..2d6753e95 100644 --- a/ethcore/src/error.rs +++ b/ethcore/src/error.rs @@ -5,22 +5,22 @@ use header::BlockNumber; use basic_types::LogBloom; #[derive(Debug, PartialEq, Eq)] -/// TODO [Gav Wood] Please document me +/// Error indicating an expected value was not found. pub struct Mismatch { - /// TODO [Gav Wood] Please document me + /// Value expected. pub expected: T, - /// TODO [Gav Wood] Please document me + /// Value found. pub found: T, } #[derive(Debug, PartialEq, Eq)] -/// TODO [Gav Wood] Please document me +/// Error indicating value found is outside of a valid range. pub struct OutOfBounds { - /// TODO [Gav Wood] Please document me + /// Minimum allowed value. pub min: Option, - /// TODO [Gav Wood] Please document me + /// Maximum allowed value. pub max: Option, - /// TODO [Gav Wood] Please document me + /// Value found. pub found: T, } @@ -29,11 +29,10 @@ pub struct OutOfBounds { pub enum ExecutionError { /// Returned when there gas paid for transaction execution is /// lower than base gas required. - /// TODO [Gav Wood] Please document me NotEnoughBaseGas { - /// TODO [Gav Wood] Please document me + /// Absolute minimum gas required. required: U256, - /// TODO [Gav Wood] Please document me + /// Gas provided. got: U256 }, /// Returned when block (gas_used + gas) > gas_limit. @@ -41,26 +40,26 @@ pub enum ExecutionError { /// If gas =< gas_limit, upstream may try to execute the transaction /// in next block. BlockGasLimitReached { - /// TODO [Gav Wood] Please document me + /// Gas limit of block for transaction. gas_limit: U256, - /// TODO [Gav Wood] Please document me + /// Gas used in block prior to transaction. gas_used: U256, - /// TODO [Gav Wood] Please document me + /// Amount of gas in block. gas: U256 }, /// Returned when transaction nonce does not match state nonce. InvalidNonce { - /// TODO [Gav Wood] Please document me + /// Nonce expected. expected: U256, - /// TODO [Gav Wood] Please document me + /// Nonce found. got: U256 }, /// Returned when cost of transaction (value + gas_price * gas) exceeds /// current sender balance. NotEnoughCash { - /// TODO [Gav Wood] Please document me + /// Minimum required balance. required: U512, - /// TODO [Gav Wood] Please document me + /// Actual balance. got: U512 }, /// Returned when internal evm error occurs. @@ -68,64 +67,68 @@ pub enum ExecutionError { } #[derive(Debug)] -/// TODO [Gav Wood] Please document me +/// Errors concerning transaction proessing. pub enum TransactionError { - /// TODO [Gav Wood] Please document me + /// Transaction's gas limit (aka gas) is invalid. InvalidGasLimit(OutOfBounds), } #[derive(Debug, PartialEq, Eq)] -/// TODO [arkpar] Please document me +/// Errors concerning block processing. pub enum BlockError { - /// TODO [Gav Wood] Please document me + /// Block has too many uncles. TooManyUncles(OutOfBounds), - /// TODO [Gav Wood] Please document me - UncleWrongGeneration, - /// TODO [Gav Wood] Please document me + /// Extra data is of an invalid length. ExtraDataOutOfBounds(OutOfBounds), - /// TODO [arkpar] Please document me + /// Seal is incorrect format. InvalidSealArity(Mismatch), - /// TODO [arkpar] Please document me + /// Block has too much gas used. TooMuchGasUsed(OutOfBounds), - /// TODO [arkpar] Please document me + /// Uncles hash in header is invalid. InvalidUnclesHash(Mismatch), - /// TODO [arkpar] Please document me + /// An uncle is from a generation too old. UncleTooOld(OutOfBounds), - /// TODO [arkpar] Please document me + /// An uncle is from the same generation as the block. UncleIsBrother(OutOfBounds), - /// TODO [arkpar] Please document me + /// An uncle is already in the chain. UncleInChain(H256), - /// TODO [arkpar] Please document me + /// An uncle has a parent not in the chain. UncleParentNotInChain(H256), - /// TODO [arkpar] Please document me + /// State root header field is invalid. InvalidStateRoot(Mismatch), - /// TODO [arkpar] Please document me + /// Gas used header field is invalid. InvalidGasUsed(Mismatch), - /// TODO [arkpar] Please document me + /// Transactions root header field is invalid. InvalidTransactionsRoot(Mismatch), - /// TODO [arkpar] Please document me + /// Difficulty is out of range; this can be used as an looser error prior to getting a definitive + /// value for difficulty. This error needs only provide bounds of which it is out. + DifficultyOutOfBounds(OutOfBounds), + /// Difficulty header field is invalid; this is a strong error used after getting a definitive + /// value for difficulty (which is provided). InvalidDifficulty(Mismatch), - /// TODO [arkpar] Please document me + /// Seal element of type H256 (max_hash for Ethash, but could be something else for + /// other seal engines) is out of bounds. + MismatchedH256SealElement(Mismatch), + /// Proof-of-work aspect of seal, which we assume is a 256-bit value, is invalid. + InvalidProofOfWork(OutOfBounds), + /// Gas limit header field is invalid. InvalidGasLimit(OutOfBounds), - /// TODO [arkpar] Please document me - InvalidReceiptsStateRoot(Mismatch), - /// TODO [arkpar] Please document me + /// Receipts trie root header field is invalid. + InvalidReceiptsRoot(Mismatch), + /// Timestamp header field is invalid. InvalidTimestamp(OutOfBounds), - /// TODO [arkpar] Please document me + /// Log bloom header field is invalid. InvalidLogBloom(Mismatch), - /// TODO [arkpar] Please document me - InvalidEthashDifficulty(Mismatch), - /// TODO [arkpar] Please document me - InvalidBlockNonce(Mismatch), - /// TODO [arkpar] Please document me + /// Parent hash field of header is invalid; this is an invalid error indicating a logic flaw in the codebase. + /// TODO: remove and favour an assert!/panic!. InvalidParentHash(Mismatch), - /// TODO [arkpar] Please document me + /// Number field of header is invalid. InvalidNumber(Mismatch), /// Block number isn't sensible. RidiculousNumber(OutOfBounds), - /// TODO [arkpar] Please document me + /// Parent given is unknown. UnknownParent(H256), - /// TODO [Gav Wood] Please document me + /// Uncle parent given is unknown. UnknownUncleParent(H256), } @@ -154,15 +157,15 @@ pub type ImportResult = Result; #[derive(Debug)] /// General error type which should be capable of representing all errors in ethcore. pub enum Error { - /// TODO [Gav Wood] Please document me + /// Error concerning a utility. Util(UtilError), - /// TODO [Gav Wood] Please document me + /// Error concerning block processing. Block(BlockError), - /// TODO [Gav Wood] Please document me + /// Unknown engine given. UnknownEngineName(String), - /// TODO [Gav Wood] Please document me + /// Error concerning EVM code execution. Execution(ExecutionError), - /// TODO [Gav Wood] Please document me + /// Error concerning transaction processing. Transaction(TransactionError), } diff --git a/ethcore/src/ethereum/ethash.rs b/ethcore/src/ethereum/ethash.rs index ce40c5f42..9cb0c5825 100644 --- a/ethcore/src/ethereum/ethash.rs +++ b/ethcore/src/ethereum/ethash.rs @@ -110,16 +110,18 @@ impl Engine for Ethash { try!(UntrustedRlp::new(&header.seal[0]).as_val::()); try!(UntrustedRlp::new(&header.seal[1]).as_val::()); + // TODO: consider removing these lines. let min_difficulty = decode(self.spec().engine_params.get("minimumDifficulty").unwrap()); if header.difficulty < min_difficulty { - return Err(From::from(BlockError::InvalidDifficulty(Mismatch { expected: min_difficulty, found: header.difficulty }))) + return Err(From::from(BlockError::DifficultyOutOfBounds(OutOfBounds { min: Some(min_difficulty), max: None, found: header.difficulty }))) } + let difficulty = Ethash::boundary_to_difficulty(&Ethash::from_ethash(quick_get_difficulty( &Ethash::to_ethash(header.bare_hash()), header.nonce().low_u64(), &Ethash::to_ethash(header.mix_hash())))); if difficulty < header.difficulty { - return Err(From::from(BlockError::InvalidEthashDifficulty(Mismatch { expected: header.difficulty, found: difficulty }))); + return Err(From::from(BlockError::InvalidProofOfWork(OutOfBounds { min: Some(header.difficulty), max: None, found: difficulty }))); } Ok(()) } @@ -129,10 +131,10 @@ impl Engine for Ethash { let mix = Ethash::from_ethash(result.mix_hash); let difficulty = Ethash::boundary_to_difficulty(&Ethash::from_ethash(result.value)); if mix != header.mix_hash() { - return Err(From::from(BlockError::InvalidBlockNonce(Mismatch { expected: mix, found: header.mix_hash() }))); + return Err(From::from(BlockError::MismatchedH256SealElement(Mismatch { expected: mix, found: header.mix_hash() }))); } if difficulty < header.difficulty { - return Err(From::from(BlockError::InvalidEthashDifficulty(Mismatch { expected: header.difficulty, found: difficulty }))); + return Err(From::from(BlockError::InvalidProofOfWork(OutOfBounds { min: Some(header.difficulty), max: None, found: difficulty }))); } Ok(()) } diff --git a/ethcore/src/verification.rs b/ethcore/src/verification.rs index 020f1b40f..efed43b84 100644 --- a/ethcore/src/verification.rs +++ b/ethcore/src/verification.rs @@ -154,7 +154,7 @@ pub fn verify_block_final(expected: &Header, got: &Header) -> Result<(), Error> return Err(From::from(BlockError::InvalidStateRoot(Mismatch { expected: expected.state_root.clone(), found: got.state_root.clone() }))) } if expected.receipts_root != got.receipts_root { - return Err(From::from(BlockError::InvalidReceiptsStateRoot(Mismatch { expected: expected.receipts_root.clone(), found: got.receipts_root.clone() }))) + return Err(From::from(BlockError::InvalidReceiptsRoot(Mismatch { expected: expected.receipts_root.clone(), found: got.receipts_root.clone() }))) } Ok(()) }