Document some stuff.

This commit is contained in:
Gav Wood 2016-02-02 23:43:29 +01:00
parent 27e585191e
commit 78adec5e53
6 changed files with 61 additions and 40 deletions

View File

@ -7,10 +7,9 @@
[coveralls-image]: https://coveralls.io/repos/github/ethcore/parity/badge.svg?branch=master&t=Fk0OuQ [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 [coveralls-url]: https://coveralls.io/r/ethcore/parity?branch=master
### Building from source ### Building from source
##### Ubuntu 14.04 and later ##### Ubuntu 14.04
```bash ```bash
# install rocksdb # 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 curl -sf https://raw.githubusercontent.com/brson/multirust/master/blastoff.sh | sh -s -- --yes
# install nightly and make it default # install nightly and make it default
multirust update nightly && multirust default nightly multirust update nightly
multirust default nightly
# export rust LIBRARY_PATH
export LIBRARY_PATH=/usr/local/lib
# download and build parity # download and build parity
git clone https://github.com/ethcore/parity git clone https://github.com/ethcore/parity
@ -33,7 +30,31 @@ cd parity
cargo build --release 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 ```bash
# install rocksdb && multirust # install rocksdb && multirust
@ -44,9 +65,6 @@ brew install multirust
# install nightly and make it default # install nightly and make it default
multirust update nightly && multirust default nightly multirust update nightly && multirust default nightly
# export rust LIBRARY_PATH
export LIBRARY_PATH=/usr/local/lib
# download and build parity # download and build parity
git clone https://github.com/ethcore/parity git clone https://github.com/ethcore/parity
cd parity cd parity

View File

@ -7,11 +7,11 @@ use pod_account::*;
/// Change in existance type. /// Change in existance type.
// TODO: include other types of change. // TODO: include other types of change.
pub enum Existance { pub enum Existance {
/// TODO [Gav Wood] Please document me /// Item came into existance.
Born, Born,
/// TODO [Gav Wood] Please document me /// Item stayed in existance.
Alive, Alive,
/// TODO [Gav Wood] Please document me /// Item went out of existance.
Died, Died,
} }
@ -27,20 +27,20 @@ impl fmt::Display for Existance {
} }
#[derive(Debug,Clone,PartialEq,Eq)] #[derive(Debug,Clone,PartialEq,Eq)]
/// TODO [Gav Wood] Please document me /// Account diff.
pub struct AccountDiff { pub struct AccountDiff {
/// TODO [Gav Wood] Please document me /// Change in balance, allowed to be `Diff::Same`.
pub balance: Diff<U256>, // Allowed to be Same pub balance: Diff<U256>,
/// TODO [Gav Wood] Please document me /// Change in nonce, allowed to be `Diff::Same`.
pub nonce: Diff<U256>, // Allowed to be Same pub nonce: Diff<U256>, // Allowed to be Same
/// TODO [Gav Wood] Please document me /// Change in code, allowed to be `Diff::Same`.
pub code: Diff<Bytes>, // Allowed to be Same pub code: Diff<Bytes>, // Allowed to be Same
/// TODO [Gav Wood] Please document me /// Change in storage, values are not allowed to be `Diff::Same`.
pub storage: BTreeMap<H256, Diff<H256>>,// Not allowed to be Same pub storage: BTreeMap<H256, Diff<H256>>,
} }
impl AccountDiff { impl AccountDiff {
/// TODO [Gav Wood] Please document me /// Get `Existance` projection.
pub fn existance(&self) -> Existance { pub fn existance(&self) -> Existance {
match self.balance { match self.balance {
Diff::Born(_) => Existance::Born, 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<AccountDiff> { pub fn diff_pod(pre: Option<&PodAccount>, post: Option<&PodAccount>) -> Option<AccountDiff> {
match (pre, post) { match (pre, post) {
(None, Some(x)) => Some(AccountDiff { (None, Some(x)) => Some(AccountDiff {

View File

@ -8,10 +8,10 @@ pub type LogBloom = H2048;
/// Constant 2048-bit datum for 0. Often used as a default. /// Constant 2048-bit datum for 0. Often used as a default.
pub static ZERO_LOGBLOOM: LogBloom = H2048([0x00; 256]); 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 { pub enum Seal {
/// TODO [Gav Wood] Please document me /// The seal/signature is included.
With, With,
/// TODO [Gav Wood] Please document me /// The seal/signature is not included.
Without, Without,
} }

View File

@ -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]) { pub fn copy_to(src: &[u8], dest: &mut[u8]) {
// NICE: optimise // NICE: optimise
for i in 0..min(src.len(), dest.len()) { for i in 0..min(src.len(), dest.len()) {

View File

@ -116,18 +116,18 @@ pub trait BlockChainClient : Sync + Send {
} }
#[derive(Default, Clone, Debug, Eq, PartialEq)] #[derive(Default, Clone, Debug, Eq, PartialEq)]
/// TODO [Gav Wood] Please document me /// Report on the status of a client.
pub struct ClientReport { pub struct ClientReport {
/// TODO [Gav Wood] Please document me /// How many blocks have been imported so far.
pub blocks_imported: usize, pub blocks_imported: usize,
/// TODO [Gav Wood] Please document me /// How many transactions have been applied so far.
pub transactions_applied: usize, pub transactions_applied: usize,
/// TODO [Gav Wood] Please document me /// How much gas has been processed so far.
pub gas_processed: U256, pub gas_processed: U256,
} }
impl ClientReport { 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) { pub fn accrue_block(&mut self, block: &PreVerifiedBlock) {
self.blocks_imported += 1; self.blocks_imported += 1;
self.transactions_applied += block.transactions.len(); self.transactions_applied += block.transactions.len();

View File

@ -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`. /// 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()) } 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 } 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()) } 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) {} 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) {} 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) /// 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. /// 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(()) } 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: Add flags for which bits of the transaction to check.
// TODO: consider including State in the params. // TODO: consider including State in the params.
fn verify_transaction_basic(&self, _t: &Transaction, _header: &Header) -> Result<(), Error> { Ok(()) } 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(()) } fn verify_transaction(&self, _t: &Transaction, _header: &Header) -> Result<(), Error> { Ok(()) }
/// Don't forget to call Super::populateFromParent when subclassing & overriding. /// 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 // 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. // 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) } 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()) } 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); } 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. // TODO: sealing stuff - though might want to leave this for later.