Add some basic docs (#238)

rust-ethereum · Nov 24, 2023 · 23fbe73 · 23fbe73
1 parent 214be63
commit 23fbe73
Show file tree

Hide file tree

Showing 13 changed files with 80 additions and 39 deletions.
diff --git a/Cargo.toml b/Cargo.toml
@@ -61,6 +61,6 @@ with-serde = [
 members = [
 	"interpreter",
 	"jsontests",
-	"precompiles",
+	"precompile",
 	"tracer",
 ]
diff --git a/README.md b/README.md
@@ -1,49 +1,41 @@
-# SputnikVM: Rust Ethereum Virtual Machine Implementation
+# Rust EVM
 
-[![Build Status](https://github.com/rust-blockchain/evm/workflows/Rust/badge.svg)](https://github.com/rust-blockchain/evm/actions?query=workflow%3ARust)
+[![Build Status](https://github.com/rust-ethereum/evm/workflows/Rust/badge.svg)](https://github.com/rust-ethereum/evm/actions?query=workflow%3ARust)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE)
 
-| Name          | Description                                                     | Crates.io                                                                                                 | Documentation                                                                              |
-|---------------|:---------------------------------------------------------------:|:---------------------------------------------------------------------------------------------------------:|:------------------------------------------------------------------------------------------:|
-| evm           | Main library that re-exports most things.                        | [![crates.io](https://img.shields.io/crates/v/evm.svg)](https://crates.io/crates/evm)                     | [![Documentation](https://docs.rs/evm/badge.svg)](https://docs.rs/evm)                     |
-| evm-core      | Core library defining the basic execution rules.                | [![crates.io](https://img.shields.io/crates/v/evm-core.svg)](https://crates.io/crates/evm-core)           | [![Documentation](https://docs.rs/evm-core/badge.svg)](https://docs.rs/evm-core)           |
-| evm-gasometer | Integration of Ethereum gas rules.                              | [![crates.io](https://img.shields.io/crates/v/evm-gasometer.svg)](https://crates.io/crates/evm-gasometer) | [![Documentation](https://docs.rs/evm-gasometer/badge.svg)](https://docs.rs/evm-gasometer) |
-| evm-runtime   | Runtime defining interface for block, transaction, and storage. | [![crates.io](https://img.shields.io/crates/v/evm-runtime.svg)](https://crates.io/crates/evm-runtime)     | [![Documentation](https://docs.rs/evm-runtime/badge.svg)](https://docs.rs/evm-runtime)     |
+Rust EVM, also known as SputnikVM, is a flexible Ethereum Virtual Machine
+interpreter that can be easily customized.
+
+## Status
+
+The Rust EVM project has a long history dating back to the initial
+implementation in 2017 (when it was called SputnikVM). It has went through
+multiple rewrites over the years to accomodate for different requirements, when
+we successfully tested one integrating Geth to sync the mainnet.
+
+The current rewrite is used in production for the Frontier project (the
+Ethereum-compatibility layer for Polkadot). However, we have not yet fully
+tested it against Ethereum mainnet. If you have such requirements, PR for fixes
+are welcomed.
 
 ## Features
 
-* **Standalone** - can be launched as an independent process or integrated into other apps
-* **Universal** - supports different Ethereum chains, such as ETC, ETH or private ones
-* **Stateless** - only an execution environment connected to independent State storage
-* **Fast** - main focus is on performance
-* written in Rust, can be used as a binary, cargo crate or shared
-  library
+* **Standalone** - can be launched as an independent process or integrated into other apps.
+* **Flexible** - can be customized and extended to support additional opcodes,
+  additional precompiles, different gasometers or other more exotic use cases.
+* **Portable** - support `no_std`, and can be used in different environments
+  like in WebAssembly.
+* **Fast** - we of course try to be fast!
+* written in Rust, can be used as a binary, cargo crate or shared library.
 
 ## Dependencies
 
-Ensure you have at least `rustc 1.51.0 (2fd73fabe 2021-03-23)`. Rust 1.50.0 and
-before are not supported.
+Rust EVM requires at least `rustc 1.75`.
 
 ## Documentation
 
 * [Latest release documentation](https://docs.rs/evm)
 
-## Build from sources
-
-SputnikVM is written in Rust. If you are not familiar with Rust, please
-see the [starting documentation](https://www.rust-lang.org/learn).
-
-### Build
-
-To start working with SputnikVM you'll
-need to install [rustup](https://www.rustup.rs/), then you can do:
-
-```bash
-$ git clone [email protected]:rust-blockchain/evm.git
-$ cd evm
-$ cargo build --release --all
-```
-
 ## License
 
 Apache 2.0
diff --git a/jsontests/Cargo.toml b/jsontests/Cargo.toml
@@ -7,7 +7,7 @@ edition = "2021"
 
 [dependencies]
 evm = { path = ".." }
-precompiles = { path = "../precompiles" }
+evm-precompile = { path = "../precompile" }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 primitive-types = { version = "0.12", features = ["rlp", "serde"] }

diff --git a/jsontests/src/run.rs b/jsontests/src/run.rs
@@ -6,7 +6,7 @@ use evm::backend::in_memory::{
 use evm::standard::{Config, Etable, EtableResolver, Gasometer, Invoker, TransactArgs};
 use evm::utils::u256_to_h256;
 use evm::Capture;
-use precompiles::StandardPrecompileSet;
+use evm_precompile::StandardPrecompileSet;
 use primitive_types::U256;
 use std::collections::{BTreeMap, BTreeSet};
 

diff --git a/precompiles/Cargo.toml → precompile/Cargo.toml b/precompiles/Cargo.toml → precompile/Cargo.toml
@@ -1,5 +1,5 @@
 [package]
-name = "precompiles"
+name = "evm-precompile"
 version = "0.1.0"
 edition = "2021"
 license = "Apache-2.0"

diff --git a/precompiles/src/blake2/eip152.rs → precompile/src/blake2/eip152.rs b/precompiles/src/blake2/eip152.rs → precompile/src/blake2/eip152.rs
diff --git a/precompiles/src/blake2/mod.rs → precompile/src/blake2/mod.rs b/precompiles/src/blake2/mod.rs → precompile/src/blake2/mod.rs
diff --git a/precompiles/src/bn128.rs → precompile/src/bn128.rs b/precompiles/src/bn128.rs → precompile/src/bn128.rs
diff --git a/precompiles/src/lib.rs → precompile/src/lib.rs b/precompiles/src/lib.rs → precompile/src/lib.rs
diff --git a/precompiles/src/modexp.rs → precompile/src/modexp.rs b/precompiles/src/modexp.rs → precompile/src/modexp.rs
diff --git a/precompiles/src/simple.rs → precompile/src/simple.rs b/precompiles/src/simple.rs → precompile/src/simple.rs
diff --git a/src/lib.rs b/src/lib.rs
@@ -1,7 +1,54 @@
-//! Ethereum Virtual Machine implementation in Rust
+//! # Ethereum Virtual Machine in Rust
+//!
+//! Rust EVM is a flexible Ethereum Virtual Machine interpreter that can be
+//! easily customized.
+//!
+//! ## Basic usage
+//!
+//! The entrypoint of a normal EVM execution is through the [transact] function.
+//! The [transact] function implements a hybrid (stack-based, and then
+//! heap-based) call stack.
+//!
+//! To use the [transact] function, you will need to first implement a
+//! backend. This is anything that implements [RuntimeEnvironment],
+//! [RuntimeBaseBackend] and [RuntimeBackend] traits. You will also need to
+//! select a few other components to construct the `invoker` parameter needed
+//! for the function.
+//!
+//! * Select an [Invoker]. The invoker defines all details of the execution
+//!   environment except the external backend. [standard::SimpleInvoker] is
+//!   probably want you want if you are not extending EVM.
+//! * For the standard invoker, select a [standard::Config], which represents
+//!   different Ethereum hard forks.
+//! * Select the precompile set. You may want the `StandardPrecompileSet` in
+//!   `evm-precompile` crate.
+//! * Select a resolver. This defines how the interpreter machines are resolved
+//!   given a code address for call or an init code for create. You may want
+//!   [standard::EtableResolver], which accepts a precompile set.
+//!
+//! ## Debugging
+//!
+//! Rust EVM supports two different methods for debugging. You can either single
+//! stepping the execution, or you can trace the opcodes.
+//!
+//! ### Single stepping
+//!
+//! Single stepping allows you to examine the full machine internal state every
+//! time the interpreter finishes executing a single opcode. To do this, use the
+//! heap-only call stack [HeapTransact]. Parameters passed to [HeapTransact] are
+//! the same as [transact].
+//!
+//! ### Tracing
+//!
+//! The interpreter machine uses information from an [Etable] to decide how each
+//! opcode behaves. An [Etable] is fully customizable and a helper function is
+//! also provided [Etable::wrap].
+//!
+//! If you also want to trace inside gasometers, simply create a wrapper struct
+//! of the gasometer you use, and pass that into the invoker.
 
-// #![deny(warnings)]
-// #![forbid(unsafe_code, unused_variables)]
+#![deny(warnings)]
+#![forbid(unsafe_code, unused_variables)]
 #![cfg_attr(not(feature = "std"), no_std)]
 
 extern crate alloc;

diff --git a/src/standard/mod.rs b/src/standard/mod.rs
@@ -11,6 +11,8 @@ pub type Efn<H> = crate::Efn<crate::RuntimeState, H, crate::Opcode>;
 pub type Etable<H, F = Efn<H>> = crate::Etable<crate::RuntimeState, H, crate::Opcode, F>;
 pub type ColoredMachine<'etable, G, H, F = Efn<H>> =
 	crate::ColoredMachine<crate::RuntimeState, G, &'etable Etable<H, F>>;
+pub type SimpleInvoker<'config, 'resolver, H, R> =
+	Invoker<'config, 'resolver, crate::RuntimeState, Gasometer<'config>, H, R, crate::Opcode>;
 
 pub trait MergeableRuntimeState<M>:
 	AsRef<crate::RuntimeState> + AsMut<crate::RuntimeState>