diff --git a/README.md b/README.md index 31f48dc..864fb53 100644 --- a/README.md +++ b/README.md @@ -12,10 +12,20 @@ Add the dependency, as usual: [dependencies] ewasm-api = "0.8" ``` + +In your project, include the prelude: ```rust -extern crate ewasm_api; +use ewasm_api::prelude::*; ``` +Other modules are available as well, outside of the prelude. Refer to the documentation for more info. + +`ewasm-rust-api` builds with various feature sets: +- `default`: Builds with `wee_alloc` as the global allocator and with the Rust standard library. +- `qimalloc`: Builds with [qimalloc](https://github.com/wasmx/qimalloc) as the global allocator. +- `debug`: Exposes the debugging interface. +- `experimental`: Exposes the experimental bignum system library API. + Further documentation is available [here](https://docs.rs/ewasm_api/). ## Author(s) diff --git a/src/bignum.rs b/src/bignum.rs index 6a8ab5a..6b6170c 100644 --- a/src/bignum.rs +++ b/src/bignum.rs @@ -1,7 +1,8 @@ //! The bignum system library. +use crate::types::Uint256; -use super::*; - +/// The low-level interface to the system library. Use the wrapper functions unless you know what +/// you're doing. pub mod native { extern "C" { pub fn bignum_mul256(a: *const u32, b: *const u32, ret: *const u32); @@ -9,6 +10,7 @@ pub mod native { } } +/// Unsigned 256-bit multiplication. pub fn mul256(a: &Uint256, b: &Uint256) -> Uint256 { let mut ret = Uint256::default(); @@ -23,6 +25,7 @@ pub fn mul256(a: &Uint256, b: &Uint256) -> Uint256 { ret } +/// Unsigned 256-bit multiplication modulo n. pub fn umulmod256(a: &Uint256, b: &Uint256, modulo: &Uint256) -> Uint256 { let mut ret = Uint256::default(); diff --git a/src/convert.rs b/src/convert.rs index 4c49458..02c770c 100644 --- a/src/convert.rs +++ b/src/convert.rs @@ -1,3 +1,6 @@ +//! Basic type conversion traits. Unlike the native standard library, `U: From` does not yet +//! imply `T: Into`. + use super::*; pub trait From: Sized { diff --git a/src/debug.rs b/src/debug.rs index d3ab305..ae2e659 100644 --- a/src/debug.rs +++ b/src/debug.rs @@ -1,8 +1,9 @@ //! The native debug interface exposed to the ewasm contract. These functions are for testing //! purposes only. On a live VM, any bytecode trying to import these symbols will be rejected. -use crate::types::*; +use crate::types::StorageKey; +/// The native interface for debugging functions. mod native { extern "C" { pub fn debug_print32(value: u32); @@ -14,26 +15,32 @@ mod native { } } +/// Prints an unsigned 32-bit int. pub fn print32(value: u32) { unsafe { native::debug_print32(value) } } +/// Prints an unsigned 64-bit int. pub fn print64(value: u64) { unsafe { native::debug_print64(value) } } +/// Prints the contents of a slice. pub fn print_mem(slice: &[u8]) { unsafe { native::debug_printMem(slice.as_ptr() as *const u32, slice.len() as u32) } } +/// Prints the contents of a slice in hexadecimal format. pub fn print_mem_hex(slice: &[u8]) { unsafe { native::debug_printMemHex(slice.as_ptr() as *const u32, slice.len() as u32) } } +/// Prints the value of a storage key. pub fn print_storage(key: &StorageKey) { unsafe { native::debug_printStorage(key.bytes.as_ptr() as *const u32) } } +/// Prints the value of a storage key in hexadecimal format. pub fn print_storage_hex(key: &StorageKey) { unsafe { native::debug_printStorageHex(key.bytes.as_ptr() as *const u32) } } diff --git a/src/lib.rs b/src/lib.rs index fd188e7..08cb9fc 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,24 +1,31 @@ -/// ewasm_api is a library used to interface with Ethereum's EEI in Ewasm, a set of enhancements to -/// the Ethereum smart contract platform. -/// ewasm_api exposes both a set of unsafe "native" functions representing the actual EEI -/// functions, and a set of safe wrappers around them. It is recommended not to use the native -/// functions as they do not perform bounds-checking. -/// -/// To use ewasm_api, simply include it as a dependency in your project. -/// -/// # Examples -/// ```ignore -/// extern crate ewasm_api; -/// -/// use ewasm_api::{Hash, block_hash, finish_data}; -/// -/// #[cfg(target_arch = "wasm32")] -/// #[no_mangle] -/// pub extern "C" fn main() { -/// let a: Hash = block_hash(1); -/// finish_data(&a.bytes); -/// } -/// ``` +//! ewasm_api is a library used to interface with Ethereum's EEI in [Ewasm](https://github.com/ewasm/design), a set of enhancements to +//! the Ethereum smart contract platform. +//! ewasm_api exposes both a set of unsafe "native" functions representing the actual EEI +//! functions, and a set of safe wrappers around them. It is recommended not to use the native +//! functions as they do not perform bounds-checking. +//! +//! To use ewasm_api, simply include it as a dependency in your project. +//! ewasm_api can be built with various feature sets: +//! - `default`: Builds with `wee_alloc` as the global allocator and with the Rust standard +//! library. +//! - `qimalloc`: Builds with [qimalloc](https://github.com/wasmx/qimalloc) as the global +//! allocator. +//! - `debug`: Exposes the debugging interface. +//! - `experimental`: Exposes the experimental bignum system library API. +//! +//! # Examples +//! ```ignore +//! extern crate ewasm_api; +//! +//! use ewasm_api::{Hash, block_hash, finish_data}; +//! +//! #[cfg(target_arch = "wasm32")] +//! #[no_mangle] +//! pub extern "C" fn main() { +//! let a: Hash = block_hash(1); +//! finish_data(&a.bytes); +//! } +//! ``` #[macro_use] extern crate cfg_if; diff --git a/src/native.rs b/src/native.rs index caebb16..172c328 100644 --- a/src/native.rs +++ b/src/native.rs @@ -1,5 +1,6 @@ -/// The native host interface exposed to the ewasm contract. Do not use these functions unless, for -/// some reason, the safe wrapper is not flexible enough. +//! The low-level bindings for the Ethereum Environment Interface (EEI). There is a safe set of wrappers for these functions, so use +//! those unless you are certain you know what you're doing. + extern "C" { pub fn ethereum_useGas(amount: u64); pub fn ethereum_getGasLeft() -> u64; diff --git a/src/types.rs b/src/types.rs index 8fb581d..c22a57a 100644 --- a/src/types.rs +++ b/src/types.rs @@ -1,3 +1,5 @@ +//! High-level types commonly used in Ethereum contracts. + /// A little-endian unsigned 128-bit integer. #[derive(Default, Copy, Clone, Debug, PartialEq, Eq)] pub struct Uint128 { @@ -22,25 +24,25 @@ pub struct Bytes32 { pub bytes: [u8; 32], } -/// Type representing a value in wei. +/// Type definition representing a value in wei. pub type EtherValue = Uint128; -/// Type representing an address. +/// Type definition representing an address. pub type Address = Bytes20; -/// Type representing a storage key. +/// Type definition representing a storage key. pub type StorageKey = Bytes32; -/// Type representing a storage value. +/// Type definition representing a storage value. pub type StorageValue = Bytes32; -/// Type representing a log topic. +/// Type definition representing a log topic. pub type LogTopic = Bytes32; -/// Type representing a Keccak-256 or SHA-256 hash. +/// Type definition representing a Keccak-256 or SHA-256 hash. pub type Hash = Bytes32; -/// Type representing a block's difficulty. +/// Type definition representing a block's difficulty. pub type Difficulty = Uint256; macro_rules! from_primitive_impl { diff --git a/src/utils.rs b/src/utils.rs index 6f444f3..6b3076c 100644 --- a/src/utils.rs +++ b/src/utils.rs @@ -1,3 +1,7 @@ +//! General utility functions. + +/// Allocate an owned buffer using the global allocator. +/// Only enabled with `std`. #[cfg(feature = "std")] pub fn unsafe_alloc_buffer(len: usize) -> Vec { let mut ret: Vec = Vec::with_capacity(len);