grassrootseconomics/openethereum
5
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Merge pull request #315 from ethcore/gavdocs

Browse Source 
Additional documentation.
This commit is contained in:
Marek Kotewicz 2016-02-03 12:50:06 +01:00
commit 5a33602d34
3 changed files with 63 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

109
ethcore/src/error.rs
View File

@ -5,22 +5,22 @@ use header::BlockNumber;
use basic_types::LogBloom; use basic_types::LogBloom;
#[derive(Debug, PartialEq, Eq)] #[derive(Debug, PartialEq, Eq)]
/// TODO [Gav Wood] Please document me /// Error indicating an expected value was not found.
pub struct Mismatch<T: fmt::Debug> { pub struct Mismatch<T: fmt::Debug> {
/// TODO [Gav Wood] Please document me /// Value expected.
pub expected: T, pub expected: T,
/// TODO [Gav Wood] Please document me /// Value found.
pub found: T, pub found: T,
} }
#[derive(Debug, PartialEq, Eq)] #[derive(Debug, PartialEq, Eq)]
/// TODO [Gav Wood] Please document me /// Error indicating value found is outside of a valid range.
pub struct OutOfBounds<T: fmt::Debug> { pub struct OutOfBounds<T: fmt::Debug> {
/// TODO [Gav Wood] Please document me /// Minimum allowed value.
pub min: Option<T>, pub min: Option<T>,
/// TODO [Gav Wood] Please document me /// Maximum allowed value.
pub max: Option<T>, pub max: Option<T>,
/// TODO [Gav Wood] Please document me /// Value found.
pub found: T, pub found: T,
} }
@ -29,11 +29,10 @@ pub struct OutOfBounds<T: fmt::Debug> {
pub enum ExecutionError { pub enum ExecutionError {
/// Returned when there gas paid for transaction execution is /// Returned when there gas paid for transaction execution is
/// lower than base gas required. /// lower than base gas required.
/// TODO [Gav Wood] Please document me
NotEnoughBaseGas { NotEnoughBaseGas {
/// TODO [Gav Wood] Please document me /// Absolute minimum gas required.
required: U256, required: U256,
/// TODO [Gav Wood] Please document me /// Gas provided.
got: U256 got: U256
}, },
/// Returned when block (gas_used + gas) > gas_limit. /// 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 /// If gas =< gas_limit, upstream may try to execute the transaction
/// in next block. /// in next block.
BlockGasLimitReached { BlockGasLimitReached {
/// TODO [Gav Wood] Please document me /// Gas limit of block for transaction.
gas_limit: U256, gas_limit: U256,
/// TODO [Gav Wood] Please document me /// Gas used in block prior to transaction.
gas_used: U256, gas_used: U256,
/// TODO [Gav Wood] Please document me /// Amount of gas in block.
gas: U256 gas: U256
}, },
/// Returned when transaction nonce does not match state nonce. /// Returned when transaction nonce does not match state nonce.
InvalidNonce { InvalidNonce {
/// TODO [Gav Wood] Please document me /// Nonce expected.
expected: U256, expected: U256,
/// TODO [Gav Wood] Please document me /// Nonce found.
got: U256 got: U256
}, },
/// Returned when cost of transaction (value + gas_price * gas) exceeds /// Returned when cost of transaction (value + gas_price * gas) exceeds
/// current sender balance. /// current sender balance.
NotEnoughCash { NotEnoughCash {
/// TODO [Gav Wood] Please document me /// Minimum required balance.
required: U512, required: U512,
/// TODO [Gav Wood] Please document me /// Actual balance.
got: U512 got: U512
}, },
/// Returned when internal evm error occurs. /// Returned when internal evm error occurs.
@ -68,64 +67,68 @@ pub enum ExecutionError {
} }
#[derive(Debug)] #[derive(Debug)]
/// TODO [Gav Wood] Please document me /// Errors concerning transaction proessing.
pub enum TransactionError { pub enum TransactionError {
/// TODO [Gav Wood] Please document me /// Transaction's gas limit (aka gas) is invalid.
InvalidGasLimit(OutOfBounds<U256>), InvalidGasLimit(OutOfBounds<U256>),
} }
#[derive(Debug, PartialEq, Eq)] #[derive(Debug, PartialEq, Eq)]
/// TODO [arkpar] Please document me /// Errors concerning block processing.
pub enum BlockError { pub enum BlockError {
/// TODO [Gav Wood] Please document me /// Block has too many uncles.
TooManyUncles(OutOfBounds<usize>), TooManyUncles(OutOfBounds<usize>),
/// TODO [Gav Wood] Please document me /// Extra data is of an invalid length.
UncleWrongGeneration,
/// TODO [Gav Wood] Please document me
ExtraDataOutOfBounds(OutOfBounds<usize>), ExtraDataOutOfBounds(OutOfBounds<usize>),
/// TODO [arkpar] Please document me /// Seal is incorrect format.
InvalidSealArity(Mismatch<usize>), InvalidSealArity(Mismatch<usize>),
/// TODO [arkpar] Please document me /// Block has too much gas used.
TooMuchGasUsed(OutOfBounds<U256>), TooMuchGasUsed(OutOfBounds<U256>),
/// TODO [arkpar] Please document me /// Uncles hash in header is invalid.
InvalidUnclesHash(Mismatch<H256>), InvalidUnclesHash(Mismatch<H256>),
/// TODO [arkpar] Please document me /// An uncle is from a generation too old.
UncleTooOld(OutOfBounds<BlockNumber>), UncleTooOld(OutOfBounds<BlockNumber>),
/// TODO [arkpar] Please document me /// An uncle is from the same generation as the block.
UncleIsBrother(OutOfBounds<BlockNumber>), UncleIsBrother(OutOfBounds<BlockNumber>),
/// TODO [arkpar] Please document me /// An uncle is already in the chain.
UncleInChain(H256), UncleInChain(H256),
/// TODO [arkpar] Please document me /// An uncle has a parent not in the chain.
UncleParentNotInChain(H256), UncleParentNotInChain(H256),
/// TODO [arkpar] Please document me /// State root header field is invalid.
InvalidStateRoot(Mismatch<H256>), InvalidStateRoot(Mismatch<H256>),
/// TODO [arkpar] Please document me /// Gas used header field is invalid.
InvalidGasUsed(Mismatch<U256>), InvalidGasUsed(Mismatch<U256>),
/// TODO [arkpar] Please document me /// Transactions root header field is invalid.
InvalidTransactionsRoot(Mismatch<H256>), InvalidTransactionsRoot(Mismatch<H256>),
/// 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<U256>),
/// Difficulty header field is invalid; this is a strong error used after getting a definitive
/// value for difficulty (which is provided).
InvalidDifficulty(Mismatch<U256>), InvalidDifficulty(Mismatch<U256>),
/// 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<H256>),
/// Proof-of-work aspect of seal, which we assume is a 256-bit value, is invalid.
InvalidProofOfWork(OutOfBounds<U256>),
/// Gas limit header field is invalid.
InvalidGasLimit(OutOfBounds<U256>), InvalidGasLimit(OutOfBounds<U256>),
/// TODO [arkpar] Please document me /// Receipts trie root header field is invalid.
InvalidReceiptsStateRoot(Mismatch<H256>), InvalidReceiptsRoot(Mismatch<H256>),
/// TODO [arkpar] Please document me /// Timestamp header field is invalid.
InvalidTimestamp(OutOfBounds<u64>), InvalidTimestamp(OutOfBounds<u64>),
/// TODO [arkpar] Please document me /// Log bloom header field is invalid.
InvalidLogBloom(Mismatch<LogBloom>), InvalidLogBloom(Mismatch<LogBloom>),
/// TODO [arkpar] Please document me /// Parent hash field of header is invalid; this is an invalid error indicating a logic flaw in the codebase.
InvalidEthashDifficulty(Mismatch<U256>), /// TODO: remove and favour an assert!/panic!.
/// TODO [arkpar] Please document me
InvalidBlockNonce(Mismatch<H256>),
/// TODO [arkpar] Please document me
InvalidParentHash(Mismatch<H256>), InvalidParentHash(Mismatch<H256>),
/// TODO [arkpar] Please document me /// Number field of header is invalid.
InvalidNumber(Mismatch<BlockNumber>), InvalidNumber(Mismatch<BlockNumber>),
/// Block number isn't sensible. /// Block number isn't sensible.
RidiculousNumber(OutOfBounds<BlockNumber>), RidiculousNumber(OutOfBounds<BlockNumber>),
/// TODO [arkpar] Please document me /// Parent given is unknown.
UnknownParent(H256), UnknownParent(H256),
/// TODO [Gav Wood] Please document me /// Uncle parent given is unknown.
UnknownUncleParent(H256), UnknownUncleParent(H256),
} }
@ -154,15 +157,15 @@ pub type ImportResult = Result<H256, ImportError>;
#[derive(Debug)] #[derive(Debug)]
/// General error type which should be capable of representing all errors in ethcore. /// General error type which should be capable of representing all errors in ethcore.
pub enum Error { pub enum Error {
/// TODO [Gav Wood] Please document me /// Error concerning a utility.
Util(UtilError), Util(UtilError),
/// TODO [Gav Wood] Please document me /// Error concerning block processing.
Block(BlockError), Block(BlockError),
/// TODO [Gav Wood] Please document me /// Unknown engine given.
UnknownEngineName(String), UnknownEngineName(String),
/// TODO [Gav Wood] Please document me /// Error concerning EVM code execution.
Execution(ExecutionError), Execution(ExecutionError),
/// TODO [Gav Wood] Please document me /// Error concerning transaction processing.
Transaction(TransactionError), Transaction(TransactionError),
} }

10
ethcore/src/ethereum/ethash.rs
View File

@ -110,16 +110,18 @@ impl Engine for Ethash {
try!(UntrustedRlp::new(&header.seal[0]).as_val::<H256>()); try!(UntrustedRlp::new(&header.seal[0]).as_val::<H256>());
try!(UntrustedRlp::new(&header.seal[1]).as_val::<H64>()); try!(UntrustedRlp::new(&header.seal[1]).as_val::<H64>());
// TODO: consider removing these lines.
let min_difficulty = decode(self.spec().engine_params.get("minimumDifficulty").unwrap()); let min_difficulty = decode(self.spec().engine_params.get("minimumDifficulty").unwrap());
if header.difficulty < min_difficulty { 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( let difficulty = Ethash::boundary_to_difficulty(&Ethash::from_ethash(quick_get_difficulty(
&Ethash::to_ethash(header.bare_hash()), &Ethash::to_ethash(header.bare_hash()),
header.nonce().low_u64(), header.nonce().low_u64(),
&Ethash::to_ethash(header.mix_hash())))); &Ethash::to_ethash(header.mix_hash()))));
if difficulty < header.difficulty { 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(()) Ok(())
} }
@ -129,10 +131,10 @@ impl Engine for Ethash {
let mix = Ethash::from_ethash(result.mix_hash); let mix = Ethash::from_ethash(result.mix_hash);
let difficulty = Ethash::boundary_to_difficulty(&Ethash::from_ethash(result.value)); let difficulty = Ethash::boundary_to_difficulty(&Ethash::from_ethash(result.value));
if mix != header.mix_hash() { 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 { 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(()) Ok(())
} }

2
ethcore/src/verification.rs
View File

@ -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() }))) return Err(From::from(BlockError::InvalidStateRoot(Mismatch { expected: expected.state_root.clone(), found: got.state_root.clone() })))
} }
if expected.receipts_root != got.receipts_root { 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(()) Ok(())
} }