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

Merge pull request #301 from ethcore/ethcore_docs

Browse Source 
ethcore docs
This commit is contained in:
Gav Wood 2016-02-02 18:11:38 +01:00
commit 9ff75df73c
17 changed files with 126 additions and 181 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
ethcore/src/account.rs
View File

@ -1,3 +1,5 @@
//! Single account in the system.
use util::*;
use pod_account::*;

2
ethcore/src/account_diff.rs
View File

@ -1,3 +1,5 @@
//! Diff between two accounts.
use util::*;
use pod_account::*;

2
ethcore/src/basic_types.rs
View File

@ -1,3 +1,5 @@
//! Ethcore basic typenames.
use util::*;
/// Type for a 2048-bit log-bloom, as used by our blocks.

17
ethcore/src/block.rs
View File

@ -1,3 +1,5 @@
//! Blockchain block.
#![allow(ptr_arg)] // Because of &LastHashes -> &Vec<_>
use common::*;
@ -18,7 +20,7 @@ pub struct Block {
}
impl Block {
/// Returns true iff the given bytes form a valid encoding of a block in RLP.
/// Returns true if the given bytes form a valid encoding of a block in RLP.
// TODO: implement Decoder for this and have this use that.
pub fn is_good(b: &[u8]) -> bool {
/*
@ -71,16 +73,15 @@ pub struct ExecutedBlock {
/// A set of references to `ExecutedBlock` fields that are publicly accessible.
pub struct BlockRefMut<'a> {
/// TODO [Gav Wood] Please document me
/// Block header.
pub header: &'a Header,
/// TODO [Gav Wood] Please document me
/// Block transactions.
pub transactions: &'a Vec<Transaction>,
/// TODO [Gav Wood] Please document me
/// Block uncles.
pub uncles: &'a Vec<Header>,
/// TODO [Gav Wood] Please document me
/// Transaction receipts.
pub receipts: &'a Vec<Receipt>,
/// TODO [Gav Wood] Please document me
/// State.
pub state: &'a mut State,
}
@ -394,4 +395,4 @@ mod tests {
assert_eq!(orig_db.keys(), db.keys());
assert!(orig_db.keys().iter().filter(|k| orig_db.get(k.0) != db.get(k.0)).next() == None);
}
}
}

24
ethcore/src/blockchain.rs
View File

@ -1,4 +1,4 @@
//! Fast access to blockchain data.
//! Blockchain database.
use util::*;
use rocksdb::{DB, WriteBatch, Writable};
@ -8,33 +8,27 @@ use transaction::*;
use views::*;
/// Represents a tree route between `from` block and `to` block:
///
/// - `blocks` - a vector of hashes of all blocks, ordered from `from` to `to`.
///
/// - `ancestor` - best common ancestor of these blocks.
///
/// - `index` - an index where best common ancestor would be.
pub struct TreeRoute {
/// TODO [debris] Please document me
/// A vector of hashes of all blocks, ordered from `from` to `to`.
pub blocks: Vec<H256>,
/// TODO [debris] Please document me
/// Best common ancestor of these blocks.
pub ancestor: H256,
/// TODO [debris] Please document me
/// An index where best common ancestor would be.
pub index: usize
}
/// Represents blockchain's in-memory cache size in bytes.
#[derive(Debug)]
pub struct CacheSize {
/// TODO [debris] Please document me
/// Blocks cache size.
pub blocks: usize,
/// TODO [debris] Please document me
/// BlockDetails cache size.
pub block_details: usize,
/// TODO [debris] Please document me
/// Transaction addresses cache size.
pub transaction_addresses: usize,
/// TODO [debris] Please document me
/// Logs cache size.
pub block_logs: usize,
/// TODO [debris] Please document me
/// Blooms cache size.
pub blocks_blooms: usize
}

2
ethcore/src/client.rs
View File

@ -1,3 +1,5 @@
//! Blockchain database client.
use util::*;
use rocksdb::{Options, DB};
use blockchain::{BlockChain, BlockProvider, CacheSize};

1
ethcore/src/evm/evm.rs
View File

@ -44,6 +44,7 @@ pub enum Error {
},
/// Returned on evm internal error. Should never be ignored during development.
/// Likely to cause consensus issues.
#[allow(dead_code)] // created only by jit
Internal,
}

5
ethcore/src/evm/factory.rs
View File

@ -1,4 +1,6 @@
//! Evm factory.
//!
//! TODO: consider spliting it into two separate files.
use std::fmt;
use evm::Evm;
@ -6,6 +8,7 @@ use evm::Evm;
/// TODO [Tomusdrw] Please document me
pub enum VMType {
/// TODO [Tomusdrw] Please document me
#[allow(dead_code)] // crated only by jit
Jit,
/// TODO [Tomusdrw] Please document me
Interpreter
@ -20,6 +23,7 @@ impl fmt::Display for VMType {
}
}
#[cfg(test)]
impl VMType {
/// Return all possible VMs (JIT, Interpreter)
#[cfg(feature="jit")]
@ -53,6 +57,7 @@ impl Factory {
}
/// Create new instance of specific `VMType` factory
#[cfg(test)]
pub fn new(evm: VMType) -> Factory {
Factory {
evm: evm

2
ethcore/src/executive.rs
View File

@ -129,7 +129,7 @@ impl<'a> Executive<'a> {
let mut substate = Substate::new();
let res = match *t.action() {
let res = match t.action {
Action::Create => {
let new_address = contract_address(&sender, &nonce);
let params = ActionParams {

2
ethcore/src/extras.rs
View File

@ -1,3 +1,5 @@
//! Blockchain DB extras.
use util::*;
use header::BlockNumber;
use rocksdb::{DB, Writable};

2
ethcore/src/header.rs
View File

@ -1,3 +1,5 @@
//! Block header.
use util::*;
use basic_types::*;
use time::now_utc;

193
ethcore/src/lib.rs
View File

@ -2,82 +2,66 @@
#![feature(cell_extras)]
#![feature(augmented_assignments)]
#![feature(plugin)]
//#![plugin(interpolate_idents)]
#![plugin(clippy)]
#![allow(needless_range_loop, match_bool)]
//! Ethcore's ethereum implementation
//! Ethcore library
//!
//! ### Rust version
//! - beta
//! ### Rust version:
//! - nightly
//!
//! ### Supported platforms:
//! - OSX
//! - Linux/Ubuntu
//! - Linux
//!
//! ### Dependencies:
//! - RocksDB 3.13
//! - LLVM 3.7 (optional, required for `jit`)
//! - evmjit (optional, required for `jit`)
//! ### Building:
//!
//! ### Dependencies Installation
//! - Ubuntu 14.04 and later:
//!
//! - OSX
//!
//! - rocksdb
//! ```bash
//! brew install rocksdb
//! # install rocksdb
//! add-apt-repository "deb http://ppa.launchpad.net/giskou/librocksdb/ubuntu trusty main"
//! apt-get update
//! apt-get install -y --force-yes librocksdb
//!
//! # install multirust
//! 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
//!
//! # download and build parity
//! git clone https://github.com/ethcore/parity
//! cd parity
//! cargo build --release
//! ```
//!
//! - OSX:
//!
//! - llvm
//! ```bash
//! # install rocksdb && multirust
//! brew update
//! brew install rocksdb
//! brew install multirust
//!
//! - download llvm 3.7 from http://llvm.org/apt/
//! # install nightly and make it default
//! multirust update nightly && multirust default nightly
//!
//! ```bash
//! cd llvm-3.7.0.src
//! mkdir build && cd $_
//! cmake -G "Unix Makefiles" .. -DCMAKE_C_FLAGS_RELEASE= -DCMAKE_CXX_FLAGS_RELEASE= -DCMAKE_INSTALL_PREFIX=/usr/local/Cellar/llvm/3.7 -DCMAKE_BUILD_TYPE=Release
//! make && make install
//! ```
//! - evmjit
//! # export rust LIBRARY_PATH
//! export LIBRARY_PATH=/usr/local/lib
//!
//! - download from https://github.com/debris/evmjit
//!
//! ```bash
//! cd evmjit
//! mkdir build && cd $_
//! cmake -DLLVM_DIR=/usr/local/lib/llvm-3.7/share/llvm/cmake ..
//! make && make install
//! ```
//!
//! - Linux/Ubuntu
//!
//! - rocksdb
//!
//! ```bash
//! wget https://github.com/facebook/rocksdb/archive/rocksdb-3.13.tar.gz
//! tar xvf rocksdb-3.13.tar.gz && cd rocksdb-rocksdb-3.13 && make shared_lib
//! sudo make install
//! ```
//!
//! - llvm
//!
//! - install using packages from http://llvm.org/apt/
//!
//! - evmjit
//!
//! - download from https://github.com/debris/evmjit
//!
//! ```bash
//! cd evmjit
//! mkdir build && cd $_
//! cmake .. && make
//! sudo make install
//! sudo ldconfig
//! ```
#[macro_use]
extern crate log;
//! # download and build parity
//! git clone https://github.com/ethcore/parity
//! cd parity
//! cargo build --release
//! ```
#[macro_use] extern crate log;
#[macro_use] extern crate ethcore_util as util;
#[macro_use] extern crate lazy_static;
extern crate rustc_serialize;
extern crate flate2;
extern crate rocksdb;
@ -86,73 +70,42 @@ extern crate crypto;
extern crate time;
extern crate env_logger;
extern crate num_cpus;
#[cfg(feature = "jit" )]
extern crate evmjit;
#[macro_use]
extern crate ethcore_util as util;
extern crate crossbeam;
#[macro_use]
extern crate lazy_static;
// NOTE: Add doc parser exception for these pub declarations.
#[cfg(feature = "jit" )] extern crate evmjit;
/// TODO [Gav Wood] Please document me
pub mod common;
/// TODO [Tomusdrw] Please document me
pub mod basic_types;
#[macro_use]
pub mod evm;
pub mod block;
pub mod blockchain;
pub mod block_queue;
pub mod client;
pub mod error;
/// TODO [Gav Wood] Please document me
pub mod log_entry;
/// TODO [Gav Wood] Please document me
pub mod env_info;
/// TODO [Gav Wood] Please document me
pub mod pod_account;
/// TODO [Gav Wood] Please document me
pub mod pod_state;
/// TODO [Gav Wood] Please document me
pub mod account_diff;
/// TODO [Gav Wood] Please document me
pub mod state_diff;
/// TODO [Gav Wood] Please document me
pub mod engine;
/// TODO [Gav Wood] Please document me
pub mod state;
/// TODO [Gav Wood] Please document me
pub mod account;
pub mod action_params;
/// TODO [debris] Please document me
pub mod ethereum;
pub mod header;
/// TODO [Gav Wood] Please document me
pub mod transaction;
/// TODO [Gav Wood] Please document me
pub mod receipt;
/// TODO [Gav Wood] Please document me
pub mod null_engine;
/// TODO [Gav Wood] Please document me
pub mod builtin;
/// TODO [debris] Please document me
pub mod service;
pub mod spec;
pub mod views;
pub mod blockchain;
/// TODO [Gav Wood] Please document me
pub mod extras;
/// TODO [arkpar] Please document me
pub mod substate;
/// TODO [Gav Wood] Please document me
pub mod service;
pub mod executive;
pub mod externalities;
#[cfg(test)]
mod tests;
mod common;
mod basic_types;
#[macro_use] mod evm;
mod log_entry;
mod env_info;
mod pod_account;
mod pod_state;
mod account_diff;
mod state_diff;
mod engine;
mod state;
mod account;
mod action_params;
mod transaction;
mod receipt;
mod null_engine;
mod builtin;
mod extras;
mod substate;
mod executive;
mod externalities;
mod verification;
/// TODO [arkpar] Please document me
pub mod client;
/// TODO [arkpar] Please document me
pub mod block;
/// TODO [arkpar] Please document me
pub mod verification;
pub mod block_queue;
pub mod ethereum;
#[cfg(test)] mod tests;

15
ethcore/src/log_entry.rs
View File

@ -31,21 +31,6 @@ impl LogEntry {
}
}
/// Returns reference to address.
pub fn address(&self) -> &Address {
&self.address
}
/// Returns reference to topics.
pub fn topics(&self) -> &Vec<H256> {
&self.topics
}
/// Returns reference to data.
pub fn data(&self) -> &Bytes {
&self.data
}
/// Calculates the bloom of this log entry.
pub fn bloom(&self) -> LogBloom {
self.topics.iter().fold(LogBloom::from_bloomed(&self.address.sha3()), |b, t| b.with_bloomed(&t.sha3()))

4
ethcore/src/service.rs
View File

@ -1,3 +1,5 @@
//! Creates and registers client and network services.
use util::*;
use spec::Spec;
use error::*;
@ -109,4 +111,4 @@ mod tests {
let service = ClientService::start(spec, NetworkConfiguration::new());
assert!(service.is_ok());
}
}
}

4
ethcore/src/spec.rs
View File

@ -1,3 +1,5 @@
//! Parameters for a block chain.
use common::*;
use flate2::read::GzDecoder;
use engine::*;
@ -5,7 +7,7 @@ use pod_state::*;
use null_engine::*;
/// Converts file from base64 gzipped bytes to json
pub fn gzip64res_to_json(source: &[u8]) -> Json {
fn gzip64res_to_json(source: &[u8]) -> Json {
// there is probably no need to store genesis in based64 gzip,
// but that's what go does, and it was easy to load it this way
let data = source.from_base64().expect("Genesis block is malformed!");

3
ethcore/src/substate.rs
View File

@ -1,3 +1,4 @@
//! Execution environment substate.
use common::*;
/// State changes which should be applied in finalize,
@ -57,4 +58,4 @@ mod tests {
assert_eq!(sub_state.sstore_clears_count, x!(12));
assert_eq!(sub_state.suicides.len(), 1);
}
}
}

27
ethcore/src/transaction.rs
View File

@ -1,3 +1,5 @@
//! Transaction data structure.
use util::*;
use basic_types::*;
use error::*;
@ -20,17 +22,17 @@ impl Default for Action {
/// or contract creation operation.
#[derive(Default, Debug, Clone)]
pub struct Transaction {
/// TODO [debris] Please document me
/// Nonce.
pub nonce: U256,
/// TODO [debris] Please document me
/// Gas price.
pub gas_price: U256,
/// TODO [debris] Please document me
/// Gas paid up front for transaction execution.
pub gas: U256,
/// TODO [debris] Please document me
/// Action, can be either call or contract create.
pub action: Action,
/// TODO [debris] Please document me
/// Transfered value.
pub value: U256,
/// TODO [Gav Wood] Please document me
/// Transaction data.
pub data: Bytes,
// signature
@ -96,19 +98,6 @@ impl Transaction {
}
}
/// Get the nonce of the transaction.
pub fn nonce(&self) -> &U256 { &self.nonce }
/// Get the gas price of the transaction.
pub fn gas_price(&self) -> &U256 { &self.gas_price }
/// Get the gas of the transaction.
pub fn gas(&self) -> &U256 { &self.gas }
/// Get the action of the transaction (Create or Call).
pub fn action(&self) -> &Action { &self.action }
/// Get the value of the transaction.
pub fn value(&self) -> &U256 { &self.value }
/// Get the data of the transaction.
pub fn data(&self) -> &Bytes { &self.data }
/// Append object into RLP stream, optionally with or without the signature.
pub fn rlp_append_opt(&self, s: &mut RlpStream, with_seal: Seal) {
s.begin_list(6 + match with_seal { Seal::With => 3, _ => 0 });