feat: book structure (bluealloy#2082)

* book: wip

* wip book

* structure of the book

* ci book, note about wip book

* git ignore

* rm generated book

* fix book links

* ignore incomplete codes

* Change perm for readme.md

* fix

* test

* test

* chmod 777

* 777 folder

* 777 folder

* change mod of root folder

* move file for mdbook test

* base link

* base link

.github/workflows/book.yml

@@ -32,7 +32,10 @@ jobs:
           echo `pwd`/mdbook-template >> $GITHUB_PATH
 
       - name: Run tests
-        run: mdbook test
+        run: |
+          cp README.md book/src/README.md
+          sed -i -e 's|../../README.md|README.md|g' book/src/SUMMARY.md
+          mdbook test
 
   lint:
     runs-on: ubuntu-latest
@@ -78,26 +81,26 @@ jobs:
           echo `pwd`/mdbook-template >> $GITHUB_PATH
 
       - name: Build book
-        run: mdbook build documentation
+        run: mdbook build book
 
       - name: Build docs
         run: RUSTDOCFLAGS="--enable-index-page -Zunstable-options" cargo doc --all --no-deps
 
       - name: Move docs to book folder
         run: |
           mkdir -p target/book/docs
-          mv target/doc documentation/book/docs
+          mv target/doc book/book/docs
 
       - name: Archive artifact
         shell: sh
         run: |
-          chmod -c -R +rX "documentation/book" |
+          chmod -c -R +rX "book/book" |
           while read line; do
              echo "::warning title=Invalid file permissions automatically fixed::$line"
           done
           tar \
             --dereference --hard-dereference \
-            --directory "documentation/book" \
+            --directory "book/book" \
             -cvf "$RUNNER_TEMP/artifact.tar" \
             --exclude=.git \
             --exclude=.github \

.gitignore

@@ -10,7 +10,6 @@ pkg/
 bins/revme/temp_folder
 bins/revme/tests
 ethereumjs-util.js
-book
 
 # Generated by the block traces example
 traces
@@ -19,3 +18,8 @@ burntpix/svgs
 
 # Rust bug report
 rustc-ice-*
+
+# book output of README.md generated by `mdbook serve book`
+/book/book
+/book/cache.json
+/index.html

README.md

@@ -1,157 +1,73 @@
-# revm
+### Revm
 
 [![CI](https://github.com/bluealloy/revm/actions/workflows/ci.yml/badge.svg)][gh-ci]
 [![License](https://img.shields.io/badge/License-MIT-orange.svg)][mit-license]
 [![Chat][tg-badge]][tg-url]
 
+Revm is a highly efficient and stable implementation of the Ethereum Virtual Machine (EVM) written in Rust.
+
+![banner](https://raw.githubusercontent.com/bluealloy/revm/refs/heads/main/assets/logo/revm-banner.png)
+
 [mit-license]: https://opensource.org/license/mit/
 [gh-ci]: https://github.com/bluealloy/revm/actions/workflows/ci.yml
 [tg-url]: https://t.me/+Ig4WDWOzikA3MzA0
 [tg-badge]: https://img.shields.io/badge/chat-telegram-blue
 
-**Rust Ethereum Virtual Machine**
-
-![](./assets/logo/revm-banner.png)
-
-Revm is an EVM written in Rust that is focused on **speed** and **simplicity**.
-It has a fast and flexible implementation with a simple interface and embedded Host.
-It passes all `ethereum/tests` test suites.
-
-Here is a list of guiding principles that Revm follows.
-
-* **EVM compatibility and stability** - this goes without saying but it is nice to put it here. In the blockchain industry, stability is the most desired attribute of any system.
-* **Speed** - is one of the most important things and most decisions are made to complement this.
-* **Simplicity** - simplification of internals so that it can be easily understood and extended, and interface that can be easily used or integrated into other projects.
-* **interfacing** - `[no_std]` so that it can be used as wasm lib and integrate with JavaScript and cpp binding if needed.
-
-# Project
-
-Structure:
-
-* crates
-  * revm -> main EVM library.
-  * revm-primitives -> Primitive data types.
-  * revm-interpreter -> Execution loop with instructions
-  * revm-precompile -> EVM precompiles
-* bins:
-  * revme: cli binary, used for running state test jsons
+Known for its robustness, it stands as one of the most popular libraries and critical component of the Ethereum ecosystem. Revm plays a crucial role across various projects, being widely utilized by almost all tooling and block builders. It is integrated into Reth, multiple Layer 2 variants and other clients and serving as a standard for zkVMs.
 
-This project tends to use the newest rust version, so if you're encountering a build error try running `rustup update` first.
+Revm offers two primary applications: firstly, it functions as an executor where users can set up block info and process mainnet transactions; secondly, it acts as a framework that facilitates the extension and support of different EVM variants such as revm-optimism.
 
-There were some big efforts on optimization of revm:
+### How to use:
 
-* Optimizing interpreter loop: https://github.com/bluealloy/revm/issues/7
-* Introducing Bytecode format (and better bytecode analysis): https://github.com/bluealloy/revm/issues/121
-* Unification of instruction signatures: https://github.com/bluealloy/revm/pull/283
+Here is a straightforward example of using the Execution API: It allows us to create an Ethereum Virtual Machine (EVM) and execute transactions. Additionally, it can be utilized to generate traces with the inspector or more complex example of foundry cheatcodes.
 
-# Building from source
+```rust,ignore
+let mut evm = Context::mainnet().with_block(block).build_mainnet();
+let out = evm.transact(tx);
 
-```shell
-git clone https://github.com/bluealloy/revm.git
-cd revm
-cargo build --release
+// or you can use powerful inspection tool to trace it
+let mut evm = evm.with_inspector(tracer);
+let out = evm.inspect_with_tx(tx);
 ```
 
-**_Note:_** `clang` is required for building revm with `c-kzg` or `secp256k1` feature flags as they depend on `C` libraries. If you don't have it installed, you can install it with `apt install clang`.
+The Evm Framework API is somewhat complex to use, but this document provides a detailed explanation. It enables users to extend logic, incorporate various context types, and offers built-in support for inspection. For a practical example, you can refer to the revm-optimism crate.
 
-# Running eth tests
+### Users:
 
-go to `cd bins/revme/`
+As previously noted, there are several groups of projects that utilize this technology:
 
-Download eth tests from (this will take some time): `git clone https://github.com/ethereum/tests`
+* **Major block builders**.
+* **Clients**: [Reth](https://github.com/paradigmxyz/reth), [Helios](https://github.com/a16z/helios), [Trin](https://github.com/ethereum/trin),..
+* **Tooling**: [Foundry](https://github.com/foundry-rs/foundry/), [Hardhat](https://github.com/NomicFoundation/hardhat),..
+* **L2s**: [Optimism](https://github.com/bluealloy/revm/tree/main/crates/optimism), [Coinbase](https://www.base.org/), [Scroll](https://github.com/scroll-tech/revm),..
+* **zkVM**: [Risc0](https://github.com/risc0/risc0-ethereum), [Succinct](https://github.com/succinctlabs/sp1-reth),..
 
-run tests with command: `cargo run --release -- statetest tests/GeneralStateTests/ tests/LegacyTests/Constantinople/GeneralStateTests`
+The full list of projects that use Revm is available in the awesome-revm section of the book.
 
-`GeneralStateTests` contains all tests related to EVM.
+### How to, dev section
 
-## Running benchmarks
-
-Benches can be found in [`crates/revm/benches`](./crates/revm/benches).
-
-Currently, available benches include the following.
-- *analysis*
-- *snailtracer*
-- *transfer*
-
-To run the `snailtracer` bench, execute the `cargo bench` subcommand below.
-
-```shell
-cargo bench --package revm --profile release -- snailtracer
-```
-
-Using [flamegraph][flamegraph], you can create a visualization breaking down the runtime of various
-sections of the bench execution - a flame graph. Executing the `cargo flamegraph` subcommand requires
-installing [flamegraph][flamegraph] by running `cargo install flamegraph`.
-
-```shell
-cargo flamegraph --root --freq 4000 --min-width 0.001 --package revm --bench bench -- snailtracer
-```
+Note that book and code docs are still in WIP stage and they are being updated!
 
-This command will produce a flamegraph image output to `flamegraph.svg`.
-Flamegraph also requires sudo mode to run (hence the `--root` cli arg) and will prompt you for your password if not in sudo mode already.
+Part of the links point to the code documentation or the book. code docs are there to explain usage of particular part of the code where book is to get more of the overview on architecture or how components/projects fit toggether.
 
-[flamegraph]: https://docs.rs/crate/flamegraph/0.1.6
+* How to build and use revm can be found here. (code)
+* Architecture overview can be seen here. (book)
+* Structure of the project (list of crates) can be seen here. (book)
+* How to use Revm Framework can be found here. (book)
+* Release procedure and changelogs explanation. (book)
+* How to use revme (Revm binary with few commands) can be found here. (code)
+* How to run Ethereum test can be found here: (book)
+* How to run examples and benchmark with `samply` to check performance. (book)
+* If there is more explanations please open PR request for it.
 
-## Running Examples
+### Community:
+For questions please open an github issue or join public telegram group: [https://t.me/+Ig4WDWOzikA3MzA0](https://t.me/+Ig4WDWOzikA3MzA0)
 
-```shell
-# Run database reference example
-cargo run -p example-database-ref
-
-# Run contract deployment example
-cargo run -p example-contract-deployment
-
-# Query Uniswap V2 pool reserves
-cargo run -p example-uniswap-get-reserves
-
-# Execute USDC swap on Uniswap V2
-cargo run -p example-uniswap-v2-usdc-swap
-
-# Generate block traces 
-cargo run -p example-block-traces
-
-# Run database reference example
-cargo run -p example-database-ref
-```
-
-All examples can be found in the `examples/` directory. Each example demonstrates different aspects of revm:
-- `block_traces`: Generating execution traces for entire blocks
-- `contract_deployment`: Deploying and interacting with smart contracts
-- `database_ref`: Using database references for state access
-- `uniswap_get_reserves`: Reading state from Uniswap contracts
-- `uniswap_v2_usdc_swap`: Executing swaps on Uniswap V2
-
-# Used by:
-
-* [Foundry](https://github.com/foundry-rs/foundry) is a blazing fast, portable and modular toolkit for Ethereum application development written in Rust.
-* [Helios](https://github.com/a16z/helios) is a fully trustless, efficient, and portable Ethereum light client written in Rust.
-* [Reth](https://github.com/paradigmxyz/reth) Modular, contributor-friendly and blazing-fast implementation of the Ethereum protocol
-* [Arbiter](https://github.com/primitivefinance/arbiter) is a framework for stateful Ethereum smart-contract simulation
-* [Zeth](https://github.com/risc0/zeth) is an open-source ZK block prover for Ethereum built on the RISC Zero zkVM.
-* [VERBS](https://github.com/simtopia/verbs) an open-source Ethereum agent-based modelling and simulation library with a Python API.
-* [Hardhat](https://github.com/NomicFoundation/hardhat) is a development environment to compile, deploy, test, and debug your Ethereum software.
-* [Trin](https://github.com/ethereum/trin) is Portal Network client. An execution and consensus layer Ethereum light client written in Rust. Portal Network client's provide complete, provable, and distributed execution archival access.
-* [Simular](https://github.com/simular-fi/simular/) is a Python smart-contract API with a fast, embedded, Ethereum Virtual Machine.
-* [rbuilder](https://github.com/flashbots/rbuilder) is a state of the art Ethereum MEV-Boost block builder written in Rust and designed to work with Reth.
-* [Tycho-simulation](https://github.com/propeller-heads/tycho-simulation) is a local simulation toolkit that lets you simulate any DEX pool in a revm environment without worrying about protocol internals.
-* ...
-
-(If you want to add project to the list, ping me or open the PR)
-
-# Documentation
-
-The book can be found at github page here: https://bluealloy.github.io/revm/
-
-The documentation (alas needs some love) can be found here: https://bluealloy.github.io/revm/docs/
-
-To serve the mdbook documentation in a local environment, ensure you have mdbook installed (if not install it with cargo) and then run:
-
-```shell
-mdbook serve documentation
-```
+### Licence
+Revm is licensed under MIT Licence.
 
-# Contact
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in these crates by you, shall be licensed as above, without any additional terms or conditions.
 
-There is public telegram group: https://t.me/+Ig4WDWOzikA3MzA0
+### Security
 
-Or if you want to contact me directly, here is my email: dragan0rakita@gmail.com and telegram: https://t.me/draganrakita
+For any security questions or findings, please reach out to me directly via email at dragan0rakita@gmail.com or contact me on Keybase under the username [draganrakita](https://keybase.io/draganrakita/).

book.toml

@@ -1,9 +1,9 @@
 [book]
-authors = ["Colin Roberts, Waylon Jepsen", "Dragan Rakita"]
+authors = ["Dragan Rakita"]
 language = "en"
 multilingual = false
-src = "documentation/src"
-title = "Rust EVM"
+src = "book/src"
+title = "Revm - Rust Ethereum Virtual Machine"
 
 [output.linkcheck]
 optional = true

book/src/SUMMARY.md

@@ -0,0 +1,13 @@
+# Summary
+
+- [Introduction](./../../README.md)
+- [Awesome Revm](./awesome.md)
+- [Architecture](./architecture.md)
+  - [Dependencies](./architecture/dependencies.md)
+  - [Crates](./architecture/crates.md)
+- [Framework](./framework.md)
+- [Dev section](./dev.md)
+- [Examples](./examples.md)
+- [Release procedure](./release_procedure.md)
+- [Testing](./testing.md)
+- [Contact](./contact.md)

book/src/architecture.md

@@ -0,0 +1,55 @@
+# Architecture
+
+List of crates can be found in [Crates](./architecture/crates.md) section of the book.
+
+REVM as any EVM implement a list of [EIP's (Ethereum Improvement Protocol)](https://github.com/ethereum/EIPs) changes over time. Those changes are shipped in the form of hardforks. List of hardforks can be found here [Ethereum Hardforks]() and repository that contains all EIPs can be found here [EIPs](https://eips.ethereum.org/).
+
+### Main components/traits:
+
+Revm consist of few traits that implement functionality of the EVM. The main traits are:
+* **EvmTrait**: This trait allows as to access main EVM fields and to run interpreter. It defines **Context**, **Precompiles**, **Instructions**. Docs
+* **ContextTrait**: is gained from EvmTrait and consist of types needed for execution. It defines environment such as block and transaction, database for runtime fetching of accounts and storage, journal for status changes and revert handling and few more fields. Docs
+* **EthHandler**: is a trait that by default implements Ethereum logic, it takes EvmTrait as a input. Entry point is a `run` function. Docs
+* **Frame**: is a associate type of EthHandler and contains runtime data of the call and logic of executing the call, default impl is a type is EthFrame. Docs
+
+Inspection for tracing is extensing above traits with:
+* **InspectorEvmTrait** is derived from EvmTrait and allows running Evm in Inspection mode. It contains **Inspector** associate type. Docs
+* **EthInspectorHandler** is derived from EthHandler and allows running Evm in Inspection mode. Entry point is `inspect_run` function and it calls a alternative functions for execution loop that includes inspector calls. Docs
+* **Inspector** is a a user oriented trait that is used for inspection of the EVM. It is used for tracing. It is part of Evm struct and it is called from EthInspectorHandler and InspectorEvmTrait. Docs
+
+
+### Simplified code
+
+```rust,ignore
+pub trait EvmTrait {
+    type Context: ContextTrait;
+    ...
+    fn execute_interpreter(..);
+}
+
+pub trait EthHandler {
+    type Evm: EvmTrait;
+    type Frame: Frame;
+    ...
+    fn run(evm);
+}
+```
+
+### flow of execution
+Execution flow can be found here (TODO Move to codebase to EthHandler trait):
+* It starts with creation of new EVM instance
+  * Building of the Context
+  * Building of the EVM. Inspector/Precompiles are created.
+  * Adding of the Inspector if needed.
+* transact/inspect. Both inspection and transaction have same flow where the only difference is that inspection includes calls to the inspector.
+  * validation of transaction and doing balance gas limit check.
+  * pre execution loads all warm accounts and deducts the caller.
+  * Execution :
+    * Creates first frame with Interpreter or executes precompile.
+    * run the frame loop:
+      * Calls Evm to exec interpreter with the frame. Interpreter loops is called here
+      * Output of Interpreter loop is NextAction that can be a Return of Call.
+      * If Return, then the frame is popped and the return value is pushed to the parent frame. If it is new call, then a new frame is created and pushed to the call stack.
+      * If call stack is empty the execution loop is done.
+    * handles the result of execution.s
+  * Post execution deals with halt and revert handling redistribution of rewards and reimbursement of unspend gas.

book/src/architecture/crates.md

@@ -0,0 +1,39 @@
+
+Revm project is split in multiple crates, each crate is responsible for different part of the project. The main crates are:
+
+There is one binary crate `revme`. It is used for running Ethereum state tests json.
+
+### Library crates
+* revm:
+* primitives:
+* interpreter:
+* precompile:
+* database:
+* database/interface:
+* bytecode:
+* state:
+* specification:
+* context:
+* context/interface:
+* handler:
+
+### variants
+* optimism
+* inspector
+
+### utility
+* statetest-types:
+
+### examples
+* block_traces:
+* cheatcode_inspector:
+* contract_deployment:
+* database_components:
+* uniswap_get_reserves:
+* uniswap_v2_usdc_swap:
+* erc20_gas:
+
+
+# Dependency of library crates can be seen here
+
+TODO Add dependency graph here