From 78adec5e53716d5a8eead8de3d374bbeed6e39b0 Mon Sep 17 00:00:00 2001 From: Gav Wood Date: Tue, 2 Feb 2016 23:43:29 +0100 Subject: [PATCH] Document some stuff. --- README.md | 38 +++++++++++++++++++++++++++---------- ethcore/src/account_diff.rs | 25 ++++++++++++------------ ethcore/src/basic_types.rs | 6 +++--- ethcore/src/builtin.rs | 3 ++- ethcore/src/client.rs | 10 +++++----- ethcore/src/engine.rs | 19 ++++++++++--------- 6 files changed, 61 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index f442338db..c223921f1 100644 --- a/README.md +++ b/README.md @@ -7,10 +7,9 @@ [coveralls-image]: https://coveralls.io/repos/github/ethcore/parity/badge.svg?branch=master&t=Fk0OuQ [coveralls-url]: https://coveralls.io/r/ethcore/parity?branch=master - ### Building from source -##### Ubuntu 14.04 and later +##### Ubuntu 14.04 ```bash # install rocksdb @@ -22,10 +21,8 @@ apt-get install -y --force-yes librocksdb curl -sf https://raw.githubusercontent.com/brson/multirust/master/blastoff.sh | sh -s -- --yes # install nightly and make it default -multirust update nightly && multirust default nightly - -# export rust LIBRARY_PATH -export LIBRARY_PATH=/usr/local/lib +multirust update nightly +multirust default nightly # download and build parity git clone https://github.com/ethcore/parity @@ -33,7 +30,31 @@ cd parity cargo build --release ``` -##### OSX +##### Linux + +```bash +# install rocksdb +git clone --tag v4.1 --depth=1 https://github.com/facebook/rocksdb.git +cd rocksdb +make shared_lib +sudo cp -a librocksdb.so* /usr/lib +sudo ldconfig +cd .. + +# install rust nightly +curl -sf https://raw.githubusercontent.com/brson/multirust/master/blastoff.sh | sudo sh -s -- --yes + +# install nightly and make it default +sudo multirust update nightly +sudo multirust default nightly + +# download and build parity +git clone https://github.com/ethcore/parity +cd parity +cargo build --release +``` + +##### OSX with Homebrew ```bash # install rocksdb && multirust @@ -44,9 +65,6 @@ brew install multirust # install nightly and make it default multirust update nightly && multirust default nightly -# export rust LIBRARY_PATH -export LIBRARY_PATH=/usr/local/lib - # download and build parity git clone https://github.com/ethcore/parity cd parity diff --git a/ethcore/src/account_diff.rs b/ethcore/src/account_diff.rs index c349ade84..411150739 100644 --- a/ethcore/src/account_diff.rs +++ b/ethcore/src/account_diff.rs @@ -7,11 +7,11 @@ use pod_account::*; /// Change in existance type. // TODO: include other types of change. pub enum Existance { - /// TODO [Gav Wood] Please document me + /// Item came into existance. Born, - /// TODO [Gav Wood] Please document me + /// Item stayed in existance. Alive, - /// TODO [Gav Wood] Please document me + /// Item went out of existance. Died, } @@ -27,20 +27,20 @@ impl fmt::Display for Existance { } #[derive(Debug,Clone,PartialEq,Eq)] -/// TODO [Gav Wood] Please document me +/// Account diff. pub struct AccountDiff { - /// TODO [Gav Wood] Please document me - pub balance: Diff, // Allowed to be Same - /// TODO [Gav Wood] Please document me + /// Change in balance, allowed to be `Diff::Same`. + pub balance: Diff, + /// Change in nonce, allowed to be `Diff::Same`. pub nonce: Diff, // Allowed to be Same - /// TODO [Gav Wood] Please document me + /// Change in code, allowed to be `Diff::Same`. pub code: Diff, // Allowed to be Same - /// TODO [Gav Wood] Please document me - pub storage: BTreeMap>,// Not allowed to be Same + /// Change in storage, values are not allowed to be `Diff::Same`. + pub storage: BTreeMap>, } impl AccountDiff { - /// TODO [Gav Wood] Please document me + /// Get `Existance` projection. pub fn existance(&self) -> Existance { match self.balance { Diff::Born(_) => Existance::Born, @@ -49,7 +49,8 @@ impl AccountDiff { } } - /// TODO [Gav Wood] Please document me + /// Determine difference between two optionally existance `Account`s. Returns None + /// if they are the same. pub fn diff_pod(pre: Option<&PodAccount>, post: Option<&PodAccount>) -> Option { match (pre, post) { (None, Some(x)) => Some(AccountDiff { diff --git a/ethcore/src/basic_types.rs b/ethcore/src/basic_types.rs index 7bab6e7f1..49a5c9556 100644 --- a/ethcore/src/basic_types.rs +++ b/ethcore/src/basic_types.rs @@ -8,10 +8,10 @@ pub type LogBloom = H2048; /// Constant 2048-bit datum for 0. Often used as a default. pub static ZERO_LOGBLOOM: LogBloom = H2048([0x00; 256]); -/// TODO [Gav Wood] Please document me +/// Semantic boolean for when a seal/signature is included. pub enum Seal { - /// TODO [Gav Wood] Please document me + /// The seal/signature is included. With, - /// TODO [Gav Wood] Please document me + /// The seal/signature is not included. Without, } diff --git a/ethcore/src/builtin.rs b/ethcore/src/builtin.rs index 00d0bbeb5..297f734b5 100644 --- a/ethcore/src/builtin.rs +++ b/ethcore/src/builtin.rs @@ -63,7 +63,8 @@ impl Builtin { } } -/// TODO [Gav Wood] Please document me +/// Copy a bunch of bytes to a destination; if the `src` is too small to fill `dest`, +/// leave the rest unchanged. pub fn copy_to(src: &[u8], dest: &mut[u8]) { // NICE: optimise for i in 0..min(src.len(), dest.len()) { diff --git a/ethcore/src/client.rs b/ethcore/src/client.rs index 8d1584e32..ebc33ed9c 100644 --- a/ethcore/src/client.rs +++ b/ethcore/src/client.rs @@ -116,18 +116,18 @@ pub trait BlockChainClient : Sync + Send { } #[derive(Default, Clone, Debug, Eq, PartialEq)] -/// TODO [Gav Wood] Please document me +/// Report on the status of a client. pub struct ClientReport { - /// TODO [Gav Wood] Please document me + /// How many blocks have been imported so far. pub blocks_imported: usize, - /// TODO [Gav Wood] Please document me + /// How many transactions have been applied so far. pub transactions_applied: usize, - /// TODO [Gav Wood] Please document me + /// How much gas has been processed so far. pub gas_processed: U256, } impl ClientReport { - /// TODO [Gav Wood] Please document me + /// Alter internal reporting to reflect the additional `block` has been processed. pub fn accrue_block(&mut self, block: &PreVerifiedBlock) { self.blocks_imported += 1; self.transactions_applied += block.transactions.len(); diff --git a/ethcore/src/engine.rs b/ethcore/src/engine.rs index 1fb6ef0ca..7017989e7 100644 --- a/ethcore/src/engine.rs +++ b/ethcore/src/engine.rs @@ -31,17 +31,16 @@ pub trait Engine : Sync + Send { /// Some intrinsic operation parameters; by default they take their value from the `spec()`'s `engine_params`. fn maximum_extra_data_size(&self) -> usize { decode(&self.spec().engine_params.get("maximumExtraDataSize").unwrap()) } - /// TODO [Gav Wood] Please document me + /// Maximum number of uncles a block is allowed to declare. fn maximum_uncle_count(&self) -> usize { 2 } - /// TODO [Gav Wood] Please document me + /// The nonce with which accounts begin. fn account_start_nonce(&self) -> U256 { decode(&self.spec().engine_params.get("accountStartNonce").unwrap()) } - /// Block transformation functions, before and after the transactions. + /// Block transformation functions, before the transactions. fn on_new_block(&self, _block: &mut ExecutedBlock) {} - /// TODO [Gav Wood] Please document me + /// Block transformation functions, after the transactions. fn on_close_block(&self, _block: &mut ExecutedBlock) {} - // TODO: consider including State in the params for verification functions. /// Phase 1 quick block verification. Only does checks that are cheap. `block` (the header's full block) /// may be provided for additional checks. Returns either a null `Ok` or a general error detailing the problem with import. fn verify_block_basic(&self, _header: &Header, _block: Option<&[u8]>) -> Result<(), Error> { Ok(()) } @@ -58,7 +57,7 @@ pub trait Engine : Sync + Send { // TODO: Add flags for which bits of the transaction to check. // TODO: consider including State in the params. fn verify_transaction_basic(&self, _t: &Transaction, _header: &Header) -> Result<(), Error> { Ok(()) } - /// TODO [Gav Wood] Please document me + /// Verify a particular transaction is valid. fn verify_transaction(&self, _t: &Transaction, _header: &Header) -> Result<(), Error> { Ok(()) } /// Don't forget to call Super::populateFromParent when subclassing & overriding. @@ -67,11 +66,13 @@ pub trait Engine : Sync + Send { // TODO: builtin contract routing - to do this properly, it will require removing the built-in configuration-reading logic // from Spec into here and removing the Spec::builtins field. - /// TODO [Gav Wood] Please document me + /// Determine whether a particular address is a builtin contract. fn is_builtin(&self, a: &Address) -> bool { self.spec().builtins.contains_key(a) } - /// TODO [Gav Wood] Please document me + /// Determine the code execution cost of the builtin contract with address `a`. + /// Panics if `is_builtin(a)` is not true. fn cost_of_builtin(&self, a: &Address, input: &[u8]) -> U256 { self.spec().builtins.get(a).unwrap().cost(input.len()) } - /// TODO [Gav Wood] Please document me + /// Execution the builtin contract `a` on `input` and return `output`. + /// Panics if `is_builtin(a)` is not true. fn execute_builtin(&self, a: &Address, input: &[u8], output: &mut [u8]) { self.spec().builtins.get(a).unwrap().execute(input, output); } // TODO: sealing stuff - though might want to leave this for later.