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

Final docs

Browse Source
This commit is contained in:
arkpar 2016-02-03 16:43:48 +01:00
parent fe97809649
commit 42d5c09131
17 changed files with 75 additions and 189 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
ethcore/src/client.rs
View File

@ -15,6 +15,7 @@ use service::NetSyncMessage;
use env_info::LastHashes;
use verification::*;
use block::*;
pub use blockchain::TreeRoute;
/// General block status
#[derive(Debug, Eq, PartialEq)]
@ -50,8 +51,6 @@ impl fmt::Display for BlockChainInfo {
}
}
/// TODO [arkpar] Please document me
pub type TreeRoute = ::blockchain::TreeRoute;
/// Blockchain database client. Owns and manages a blockchain and a block queue.
pub trait BlockChainClient : Sync + Send {

11
ethcore/src/ethereum/denominations.rs
View File

@ -1,22 +1,21 @@
use util::*;
#[inline]
/// TODO [debris] Please document me
/// 1 Ether in Wei
pub fn ether() -> U256 { U256::exp10(18) }
#[inline]
/// TODO [debris] Please document me
/// 1 Finney in Wei
pub fn finney() -> U256 { U256::exp10(15) }
#[inline]
/// TODO [debris] Please document me
/// 1 Szabo in Wei
pub fn szabo() -> U256 { U256::exp10(12) }
#[inline]
/// TODO [debris] Please document me
/// 1 Shannon in Wei
pub fn shannon() -> U256 { U256::exp10(9) }
#[inline]
/// TODO [debris] Please document me
/// 1 Wei in Wei
pub fn wei() -> U256 { U256::exp10(0) }

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

@ -21,7 +21,7 @@ pub struct Ethash {
}
impl Ethash {
/// TODO [arkpar] Please document me
/// Create a new boxed instance of Ethash engine
pub fn new_boxed(spec: Spec) -> Box<Engine> {
Box::new(Ethash {
spec: spec,

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

@ -2,7 +2,6 @@
pub mod ext;
pub mod evm;
/// TODO [Tomusdrw] Please document me
pub mod interpreter;
#[macro_use]
pub mod factory;

34
ethcore/src/extras.rs
View File

@ -7,21 +7,21 @@ use rocksdb::{DB, Writable};
/// Represents index of extra data in database
#[derive(Copy, Debug, Hash, Eq, PartialEq, Clone)]
pub enum ExtrasIndex {
/// TODO [debris] Please document me
/// Block details index
BlockDetails = 0,
/// TODO [debris] Please document me
/// Block hash index
BlockHash = 1,
/// TODO [debris] Please document me
/// Transaction address index
TransactionAddress = 2,
/// TODO [debris] Please document me
/// Block log blooms index
BlockLogBlooms = 3,
/// TODO [debris] Please document me
/// Block blooms index
BlocksBlooms = 4
}
/// trait used to write Extras data to db
pub trait ExtrasWritable {
/// TODO [debris] Please document me
/// Write extra data to db
fn put_extras<K, T>(&self, hash: &K, value: &T) where
T: ExtrasIndexable + Encodable,
K: ExtrasSliceConvertable;
@ -29,12 +29,12 @@ pub trait ExtrasWritable {
/// trait used to read Extras data from db
pub trait ExtrasReadable {
/// TODO [debris] Please document me
/// Read extra data from db
fn get_extras<K, T>(&self, hash: &K) -> Option<T> where
T: ExtrasIndexable + Decodable,
K: ExtrasSliceConvertable;
/// TODO [debris] Please document me
/// Check if extra data exists in the db
fn extras_exists<K, T>(&self, hash: &K) -> bool where
T: ExtrasIndexable,
K: ExtrasSliceConvertable;
@ -98,7 +98,7 @@ impl ExtrasSliceConvertable for BlockNumber {
/// Types implementing this trait can be indexed in extras database
pub trait ExtrasIndexable {
/// TODO [debris] Please document me
/// Returns this data index
fn extras_index() -> ExtrasIndex;
}
@ -111,13 +111,13 @@ impl ExtrasIndexable for H256 {
/// Familial details concerning a block
#[derive(Debug, Clone)]
pub struct BlockDetails {
/// TODO [debris] Please document me
/// Block number
pub number: BlockNumber,
/// TODO [debris] Please document me
/// Total difficulty of the block and all its parents
pub total_difficulty: U256,
/// TODO [debris] Please document me
/// Parent block hash
pub parent: H256,
/// TODO [debris] Please document me
/// List of children block hashes
pub children: Vec<H256>
}
@ -159,7 +159,7 @@ impl Encodable for BlockDetails {
/// Log blooms of certain block
#[derive(Clone)]
pub struct BlockLogBlooms {
/// TODO [debris] Please document me
/// List of log blooms for the block
pub blooms: Vec<H2048>
}
@ -193,7 +193,7 @@ impl Encodable for BlockLogBlooms {
/// Neighboring log blooms on certain level
pub struct BlocksBlooms {
/// TODO [debris] Please document me
/// List of block blooms.
pub blooms: [H2048; 16]
}
@ -241,9 +241,9 @@ impl Encodable for BlocksBlooms {
/// Represents address of certain transaction within block
#[derive(Clone)]
pub struct TransactionAddress {
/// TODO [debris] Please document me
/// Block hash
pub block_hash: H256,
/// TODO [debris] Please document me
/// Transaction index within the block
pub index: u64
}

2
ethcore/src/service.rs
View File

@ -15,7 +15,7 @@ pub enum SyncMessage {
BlockVerified,
}
/// TODO [arkpar] Please document me
/// IO Message type used for Network service
pub type NetSyncMessage = NetworkIoMessage<SyncMessage>;
/// Client service setup. Creates and registers client and network services with the IO subsystem.

104
sync/src/service.rs
View File

@ -1,104 +0,0 @@
use util::*;
use sync::*;
use spec::Spec;
use error::*;
use std::env;
use client::Client;
/// Message type for external and internal events
#[derive(Clone)]
pub enum SyncMessage {
/// New block has been imported into the blockchain
NewChainBlock(Bytes), //TODO: use Cow
/// A block is ready
BlockVerified,
}
/// TODO [arkpar] Please document me
pub type NetSyncMessage = NetworkIoMessage<SyncMessage>;
/// Client service setup. Creates and registers client and network services with the IO subsystem.
pub struct ClientService {
net_service: NetworkService<SyncMessage>,
client: Arc<Client>,
sync: Arc<EthSync>,
}
impl ClientService {
/// Start the service in a separate thread.
pub fn start(spec: Spec, net_config: NetworkConfiguration) -> Result<ClientService, Error> {
let mut net_service = try!(NetworkService::start(net_config));
info!("Starting {}", net_service.host_info());
info!("Configured for {} using {} engine", spec.name, spec.engine_name);
let mut dir = env::home_dir().unwrap();
dir.push(".parity");
dir.push(H64::from(spec.genesis_header().hash()).hex());
let client = try!(Client::new(spec, &dir, net_service.io().channel()));
let sync = EthSync::register(&mut net_service, client.clone());
let client_io = Arc::new(ClientIoHandler {
client: client.clone()
});
try!(net_service.io().register_handler(client_io));
Ok(ClientService {
net_service: net_service,
client: client,
sync: sync,
})
}
/// Get the network service.
pub fn add_node(&mut self, _enode: &str) {
unimplemented!();
}
/// TODO [arkpar] Please document me
pub fn io(&mut self) -> &mut IoService<NetSyncMessage> {
self.net_service.io()
}
/// TODO [arkpar] Please document me
pub fn client(&self) -> Arc<Client> {
self.client.clone()
}
/// Get shared sync handler
pub fn sync(&self) -> Arc<EthSync> {
self.sync.clone()
}
}
/// IO interface for the Client handler
struct ClientIoHandler {
client: Arc<Client>
}
const CLIENT_TICK_TIMER: TimerToken = 0;
const CLIENT_TICK_MS: u64 = 5000;
impl IoHandler<NetSyncMessage> for ClientIoHandler {
fn initialize(&self, io: &IoContext<NetSyncMessage>) {
io.register_timer(CLIENT_TICK_TIMER, CLIENT_TICK_MS).expect("Error registering client timer");
}
fn timeout(&self, _io: &IoContext<NetSyncMessage>, timer: TimerToken) {
if timer == CLIENT_TICK_TIMER {
self.client.tick();
}
}
#[allow(match_ref_pats)]
#[allow(single_match)]
fn message(&self, io: &IoContext<NetSyncMessage>, net_message: &NetSyncMessage) {
if let &UserMessage(ref message) = net_message {
match message {
&SyncMessage::BlockVerified => {
self.client.import_verified_blocks(&io.channel());
},
_ => {}, // ignore other messages
}
}
}
}

6
util/src/bytes.rs
View File

@ -111,11 +111,11 @@ impl ToPretty for Bytes {
}
}
/// TODO [debris] Please document me
/// A byte collection reference that can either be a slice or a vector
pub enum BytesRef<'a> {
/// TODO [debris] Please document me
/// This is a reference to a vector
Flexible(&'a mut Bytes),
/// TODO [debris] Please document me
/// This is a reference to a slice
Fixed(&'a mut [u8])
}

4
util/src/chainfilter.rs
View File

@ -49,9 +49,9 @@ use sha3::*;
/// index. Their `BloomIndex` can be created from block number and given level.
#[derive(Eq, PartialEq, Hash, Clone, Debug)]
pub struct BloomIndex {
/// TODO [debris] Please document me
/// Bloom level
pub level: u8,
/// TODO [debris] Please document me
/// Filter Index
pub index: usize,
}

30
util/src/crypto.rs
View File

@ -39,17 +39,17 @@ impl Signature {
}
#[derive(Debug)]
/// TODO [arkpar] Please document me
/// Crypto error
pub enum CryptoError {
/// TODO [arkpar] Please document me
/// Invalid secret key
InvalidSecret,
/// TODO [arkpar] Please document me
/// Invalid public key
InvalidPublic,
/// TODO [arkpar] Please document me
/// Invalid EC signature
InvalidSignature,
/// TODO [arkpar] Please document me
/// Invalid AES message
InvalidMessage,
/// TODO [arkpar] Please document me
/// IO Error
Io(::std::io::Error),
}
@ -134,7 +134,7 @@ impl KeyPair {
pub fn sign(&self, message: &H256) -> Result<Signature, CryptoError> { ec::sign(&self.secret, message) }
}
/// TODO [arkpar] Please document me
/// EC functions
pub mod ec {
use hash::*;
use uint::*;
@ -211,12 +211,12 @@ pub mod ec {
}
}
/// TODO [arkpar] Please document me
/// ECDH functions
pub mod ecdh {
use crypto::*;
use crypto::{self};
/// TODO [arkpar] Please document me
/// Agree on a shared secret
pub fn agree(secret: &Secret, public: &Public, ) -> Result<Secret, CryptoError> {
use secp256k1::*;
let context = &crypto::SECP256K1;
@ -232,13 +232,13 @@ pub mod ecdh {
}
}
/// TODO [arkpar] Please document me
/// ECIES function
pub mod ecies {
use hash::*;
use bytes::*;
use crypto::*;
/// TODO [arkpar] Please document me
/// Encrypt a message with a public key
pub fn encrypt(public: &Public, plain: &[u8]) -> Result<Bytes, CryptoError> {
use ::rcrypto::digest::Digest;
use ::rcrypto::sha2::Sha256;
@ -274,7 +274,7 @@ pub mod ecies {
Ok(msg)
}
/// TODO [arkpar] Please document me
/// Decrypt a message with a secret key
pub fn decrypt(secret: &Secret, encrypted: &[u8]) -> Result<Bytes, CryptoError> {
use ::rcrypto::digest::Digest;
use ::rcrypto::sha2::Sha256;
@ -340,20 +340,20 @@ pub mod ecies {
}
}
/// TODO [arkpar] Please document me
/// AES encryption
pub mod aes {
use ::rcrypto::blockmodes::*;
use ::rcrypto::aessafe::*;
use ::rcrypto::symmetriccipher::*;
use ::rcrypto::buffer::*;
/// TODO [arkpar] Please document me
/// Encrypt a message
pub fn encrypt(k: &[u8], iv: &[u8], plain: &[u8], dest: &mut [u8]) {
let mut encryptor = CtrMode::new(AesSafe128Encryptor::new(k), iv.to_vec());
encryptor.encrypt(&mut RefReadBuffer::new(plain), &mut RefWriteBuffer::new(dest), true).expect("Invalid length or padding");
}
/// TODO [arkpar] Please document me
/// Decrypt a message
pub fn decrypt(k: &[u8], iv: &[u8], encrypted: &[u8], dest: &mut [u8]) {
let mut encryptor = CtrMode::new(AesSafe128Encryptor::new(k), iv.to_vec());
encryptor.decrypt(&mut RefReadBuffer::new(encrypted), &mut RefWriteBuffer::new(dest), true).expect("Invalid length or padding");

11
util/src/io/mod.rs
View File

@ -42,9 +42,9 @@ mod worker;
use mio::{EventLoop, Token};
#[derive(Debug)]
/// TODO [arkpar] Please document me
/// IO Error
pub enum IoError {
/// TODO [arkpar] Please document me
/// Low level error from mio crate
Mio(::std::io::Error),
}
@ -78,19 +78,12 @@ pub trait IoHandler<Message>: Send + Sync where Message: Send + Sync + Clone + '
fn deregister_stream(&self, _stream: StreamToken, _event_loop: &mut EventLoop<IoManager<Message>>) {}
}
/// TODO [arkpar] Please document me
pub use io::service::TimerToken;
/// TODO [arkpar] Please document me
pub use io::service::StreamToken;
/// TODO [arkpar] Please document me
pub use io::service::IoContext;
/// TODO [arkpar] Please document me
pub use io::service::IoService;
/// TODO [arkpar] Please document me
pub use io::service::IoChannel;
/// TODO [arkpar] Please document me
pub use io::service::IoManager;
/// TODO [arkpar] Please document me
pub use io::service::TOKENS_PER_HANDLER;
#[cfg(test)]

6
util/src/rlp/bytes.rs
View File

@ -140,9 +140,9 @@ impl <T>ToBytes for T where T: FixedHash {
/// Error returned when FromBytes conversation goes wrong
#[derive(Debug, PartialEq, Eq)]
pub enum FromBytesError {
/// TODO [debris] Please document me
/// Expected more RLP data
DataIsTooShort,
/// TODO [debris] Please document me
/// Extra bytes after the end of the last item
DataIsTooLong,
/// Integer-representation is non-canonically prefixed with zero byte(s).
ZeroPrefixedInt,
@ -165,7 +165,7 @@ pub type FromBytesResult<T> = Result<T, FromBytesError>;
///
/// TODO: check size of bytes before conversation and return appropriate error
pub trait FromBytes: Sized {
/// TODO [debris] Please document me
/// Create a value from bytes
fn from_bytes(bytes: &[u8]) -> FromBytesResult<Self>;
}

4
util/src/rlp/rlpin.rs
View File

@ -103,12 +103,12 @@ impl <'a, 'view> Rlp<'a> where 'a: 'view {
res.unwrap_or_else(|_| panic!())
}
/// TODO [debris] Please document me
/// Decode into an object
pub fn as_val<T>(&self) -> T where T: RlpDecodable {
Self::view_as_val(self)
}
/// TODO [debris] Please document me
/// Decode list item at given index into an object
pub fn val_at<T>(&self, index: usize) -> T where T: RlpDecodable {
Self::view_as_val(&self.at(index))
}

30
util/src/rlp/rlptraits.rs
View File

@ -31,17 +31,17 @@ pub trait RlpDecodable: Sized {
fn decode<D>(decoder: &D) -> Result<Self, DecoderError> where D: Decoder;
}
/// TODO [debris] Please document me
/// A view into RLP encoded data
pub trait View<'a, 'view>: Sized {
/// TODO [debris] Please document me
/// RLP prototype type
type Prototype;
/// TODO [debris] Please document me
/// Payload info type
type PayloadInfo;
/// TODO [debris] Please document me
/// Data type
type Data;
/// TODO [debris] Please document me
/// Item type
type Item;
/// TODO [debris] Please document me
/// Iterator type
type Iter;
/// Creates a new instance of `Rlp` reader
@ -65,10 +65,10 @@ pub trait View<'a, 'view>: Sized {
/// Get the prototype of the RLP.
fn prototype(&self) -> Self::Prototype;
/// TODO [debris] Please document me
/// Get payload info.
fn payload_info(&self) -> Self::PayloadInfo;
/// TODO [debris] Please document me
/// Get underlieing data.
fn data(&'view self) -> Self::Data;
/// Returns number of RLP items.
@ -205,18 +205,18 @@ pub trait View<'a, 'view>: Sized {
/// ```
fn iter(&'view self) -> Self::Iter;
/// TODO [debris] Please document me
/// Decode data into an object
fn as_val<T>(&self) -> Result<T, DecoderError> where T: RlpDecodable;
/// TODO [debris] Please document me
/// Decode data at given list index into an object
fn val_at<T>(&self, index: usize) -> Result<T, DecoderError> where T: RlpDecodable;
}
/// TODO [debris] Please document me
/// Raw RLP encoder
pub trait Encoder {
/// TODO [debris] Please document me
/// Write a value represented as bytes
fn emit_value<E: ByteEncodable>(&mut self, value: &E);
/// TODO [debris] Please document me
/// Write raw preencoded data to the output
fn emit_raw(&mut self, bytes: &[u8]) -> ();
}
@ -250,7 +250,7 @@ pub trait RlpEncodable {
fn rlp_append(&self, s: &mut RlpStream);
}
/// TODO [debris] Please document me
/// RLP encoding stream
pub trait Stream: Sized {
/// Initializes instance of empty `Stream`.
@ -341,7 +341,7 @@ pub trait Stream: Sized {
/// }
fn is_finished(&self) -> bool;
/// TODO [debris] Please document me
/// Get raw encoded bytes
fn as_raw(&self) -> &[u8];
/// Streams out encoded bytes.

12
util/src/rlp/untrusted_rlp.rs
View File

@ -21,21 +21,21 @@ impl OffsetCache {
}
#[derive(Debug)]
/// TODO [debris] Please document me
/// RLP prototype
pub enum Prototype {
/// TODO [debris] Please document me
/// Empty
Null,
/// TODO [debris] Please document me
/// Value
Data(usize),
/// TODO [debris] Please document me
/// List
List(usize),
}
/// Stores basic information about item
pub struct PayloadInfo {
/// TODO [debris] Please document me
/// Header length in bytes
pub header_len: usize,
/// TODO [debris] Please document me
/// Value length in bytes
pub value_len: usize,
}

2
util/src/squeeze.rs
View File

@ -36,7 +36,7 @@ use heapsize::HeapSizeOf;
/// Should be used to squeeze collections to certain size in bytes
pub trait Squeeze {
/// TODO [debris] Please document me
/// Try to reduce collection size to `size` bytes
fn squeeze(&mut self, size: usize);
}

2
util/src/vector.rs
View File

@ -13,7 +13,7 @@
/// }
/// ```
pub trait SharedPrefix <T> {
/// TODO [debris] Please document me
/// Get common prefix length
fn shared_prefix_len(&self, elem: &[T]) -> usize;
}