feat: InspectEvm fn renames, inspector docs, book cleanup (#2275)

* feat: InspectEvm fn renames, inspector docs, book cleanup

* nits, docs and typos

* fix doc

Author: rakita

.github/workflows/book.yml

@@ -34,7 +34,7 @@ jobs:
       - name: Run tests
         run: |
           cp README.md book/src/README.md
-          sed -i -e 's|../../README.md|README.md|g' book/src/SUMMARY.md
+          sed -i -e 's|../../README.md|./README.md|g' book/src/SUMMARY.md
           mdbook test
 
   lint:
@@ -81,7 +81,10 @@ jobs:
           echo `pwd`/mdbook-template >> $GITHUB_PATH
 
       - name: Build book
-        run: mdbook build book
+        run: |
+          cp README.md book/src/README.md
+          sed -i -e 's|../../README.md|./README.md|g' book/src/SUMMARY.md
+          mdbook build book
 
       - name: Build docs
         run: RUSTDOCFLAGS="--enable-index-page -Zunstable-options" cargo doc --all --no-deps

bins/revme/src/cmd/statetest/runner.rs

@@ -426,7 +426,7 @@ pub fn execute_test_suite(
                         );
 
                     let timer = Instant::now();
-                    let res = evm.inspect_commit_previous();
+                    let res = evm.inspect_replay_commit();
                     *elapsed.lock().unwrap() += timer.elapsed();
 
                     let spec = cfg.spec();
@@ -498,7 +498,7 @@ pub fn execute_test_suite(
                         TracerEip3155::buffered(stderr()).without_summary(),
                     );
 
-                let _ = evm.inspect_commit_previous();
+                let _ = evm.inspect_replay_commit();
 
                 println!("\nExecution result: {exec_result:#?}");
                 println!("\nExpected exception: {:?}", test.expect_exception);

book/src/SUMMARY.md

@@ -2,8 +2,8 @@
 
 - [Introduction](./../../README.md)
 - [Awesome Revm](./awesome.md)
-- [Dev section](./dev.md)
 - [Architecture](./architecture.md)
+- [Dev section](./dev.md)
 - [Revme](./revme.md)
 - [Release procedure](./release_procedure.md)
 - [Contact](./contact.md)

book/src/architecture.md

@@ -1,4 +1,4 @@
-# Architecture
+# Architecture and API
 
 REVM is a flexible implementation of the Ethereum Virtual Machine (EVM). It follows the rules of the Ethereum mainnet and stays up to date with changes through hardforks as defined in the official [Ethereum 
 execution specs](https://github.com/ethereum/execution-specs).
@@ -7,26 +7,45 @@ You can use REVM in two main ways:
 1. Run regular Ethereum transactions using a Execution API
 2. Create your own custom version of the EVM (for Layer 2 solutions or other chains) using EVM framework
 
-The main `revm` library combines all the different crates into one package and reexports them. You can see overview revm crates in [crates folder](https://github.com/bluealloy/revm/tree/main/crates) and overview of examples in [examples folder](https://github.com/bluealloy/revm/tree/main/examples).
+To see usage examples you can check the [examples folder](https://github.com/bluealloy/revm/tree/ main/examples). Other than documentation, examples are main resource to see and learn about Revm.
 
-REVM works in no_std environments which means it can be used in zero-knowledge virtual machines (zkVMs). It also has very few external dependencies, which you can read more about in the [dev section](./dev.md).
+The main `revm` library combines all crates into one package and reexports them, standalone library are useful if there is need to import functionality with smaller scope. You can see overview of revm crates in [crates folder](https://github.com/bluealloy/revm/tree/main/crates).
+
+REVM works in `no_std` environments which means it can be used in zero-knowledge virtual machines (zkVMs) and it is the standard library in that use case. It also has very few external dependencies.
 
 # Execution API
 
-REVM provides four ways to execute transactions through traits (interfaces).
+`Evm` the main structure for executing mainnet ethereum transaction is build with a `Context` and a builder, code for it looks like this:
+
+```rust,ignore
+let mut evm = Context::mainnet().with_block(block).build_mainnet();
+let out = evm.transact(tx);
+```
+
+`Evm` struct contains:
+* `Context` - Environment and evm state.
+* `Instructions` - EVM opcode implementations
+* `Precompiles` - Built-in contract implementations
+* `Inspector` - Used for tracing.
 
-The State system builds on the `Database` trait and handles:
-- Getting data from external storage
-- Managing the EVM's output
-- Caching changes when running multiple transactions
+And `Context` contains data used in execution:
+* Environment data, the data that is known before execution starts are `Transaction`, `Block`, `Cfg`.
+* `Journal` is place where internal state is stored. Internal state is returned after execution ends.
+   * And `Database` is a interface that allows fetching external data that is needed in runtime. That data are account, storage and bytecode. When loaded they are stored in `Journal` 
 
-You can implement one of three database interfaces depending on what you need:
+REVM provides four ways to execute transactions through traits (API):
 
-- `Database`: Uses a mutable reference (`&mut self`). This is useful when you want to update a cache or track statistics while getting data. Enables basic transaction functions like `transact` and `inspect`.
+* `transact(tx)` and `replay()` are function of `ExecuteEvm` trait that allow execution transactions. They return the status of execution with reason, changed state and in of case of failed execution a error.
+* `transact_commit(tx)` and `replay_commit()` are part of `ExecuteCommitEvm` that internally commits the state diff to the database and returns status of execution. Database is requires to support `DatabaseCommit` trait.
+* `inspect()`, `inspect_replay(tx)` and few others are part of `InspectEvm` trait that allow execution with inspection. This is how tracers are called.
+* `inspect_commit()`,`inspect_replay_commit(tx)` that are part of `InspectCommitEvm` trait that extends `InspectEvm` to allow committing state diff after tracing.
 
-- `DatabaseRef`: Uses a regular reference (`&self`). Good for when you only need to read data without making changes. Enables reference-based functions like `transact_ref`.
+For inspection API to be enabled `Evm` needs to be create with inspector.
 
-- `Database + DatabaseCommit`: Adds the ability to save transaction changes directly. Enables commit functions like `transact_commit`.
+```rust,ignore
+let mut evm = Context::mainnet().with_block(block).build_mainnet().with_inspector(inspector);
+let _ = evm.inspect_with_tx(tx);
+```
 
 # EVM Framework
 
@@ -38,16 +57,12 @@ Each trait needed to build custom EVM has detailed documentation explaining how
 
 In summary, REVM is built around several key traits that enable customizable EVM functionality. The core traits include:
 
-* **EvmTr**: The core EVM trait that provides access to the main EVM components:
-  - Context - Environment and state access
-  - Instructions - EVM opcode implementations
-  - Precompiles - Built-in contract implementations
-  - Inspector - Used for tracing, only enabled with `InspectorEvmTr` trait.
-* **ContextTr**: Accessed through EvmTr, defines the execution environment including Tx/Block/Journal/Db:
+* **EvmTr**: The core EVM trait that provides access to `Context`, `Instruction`, `Precompiles`:
+* **ContextTr**: Accessed through EvmTr, defines the execution environment including Tx/Block/Journal/Db.
 * **Handler**: Implements the core execution logic, taking an EvmTr implementation. The default implementation follows Ethereum consensus.
 
 And traits that provide support for inspection and tracing:
 
-* **InspectorEvmTr**: Extends EvmTr to enable inspection mode execution with an associated Inspector type
-* **InspectorHandler**: Extends Handler with inspection-enabled execution paths that make Inspector callbacks
+* **InspectorEvmTr**: Extends EvmTr to enable inspection mode execution with an associated `Inspector` type
+* **InspectorHandler**: Extends Handler with inspection-enabled execution paths that make `Inspector` callbacks
 * **Inspector**: User-implementable trait for EVM inspection/tracing

book/src/awesome.md

@@ -17,6 +17,7 @@ A curated list of excellent Revm-related resources. Feel free to contribute to t
 - [**Reth:**](https://github.com/paradigmxyz/reth) A modular, contributor-friendly, and ultra-fast implementation of the Ethereum protocol.
 - [**Helios**](https://github.com/a16z/helios) is a trustless, efficient, and portable multichain light client written in Rust.
 - [**Trin**](https://github.com/ethereum/trin) is a Rust implementation of a Portal Network client.
+- 
 
 #### EVM Variants
 - [**Optimism**](https://github.com/bluealloy/revm/tree/main/crates/optimism) is a ethereum L2 network.

book/src/dev.md

@@ -9,29 +9,4 @@ cargo build --release
 
 **_Note:_** This project tends to use the newest rust version, so if you're encountering a build error try running rustup update first.
 
-**_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`.
-
-# External core dependencies
-
-REVM relies on several key external dependencies to provide its core functionality:
-
-* The `alloy-primitives` crate provides essential native types including:
-  - `ruint` U256 big number type
-  - Address, Bytes, and B256 types
-  - `hashbrown` implementations of HashMap/HashSet with custom hashing algorithms
-* For broad compatibility, REVM is `no_std` compliant and uses the `alloc` crate for heap allocation needs.
-* Precompile functionality requires several cryptography and math libraries:
-  - `c-kzg`: Implements Polynomial Commitments API for EIP-4844 (C implementation with Rust bindings)
-  - `modexp`: Handles big integer modular exponentiation
-  - `secp256k1`: Provides ECDSA public key recovery based on secp256k1 curves
-  - `k256`: Serves as a no_std compatible fallback for secp256k1
-* Transaction environment AccessList and AuthorizationList come from:
-  - `alloy-eip7702`
-  - `alloy-eip2930`
-* Optional serialization support through feature-flagged:
-  - `serde`
-  - `serde-json` 
-* Various utility crates enhance development:
-  - `auto_impl`
-  - `derive_more`
-  - Specialized libraries like `nnum` for specific use cases
+**_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`.

book/src/testing.md

@@ -1,7 +1,7 @@
 use super::Journal;
 use database_interface::EmptyDB;
 
-/// A clonable version of JournaledState that uses EmptyDB.
+/// A cloneable version of JournaledState that uses EmptyDB.
 /// Used to clone the journaled state and for initialization of new journaled state.
 pub type JournalInit = Journal<EmptyDB>;
 

crates/context/src/journaled_state/init.rs

@@ -16,38 +16,47 @@ impl Default for GasInspector {
 }
 
 impl GasInspector {
+    /// Returns the remaining gas.
+    #[inline]
     pub fn gas_remaining(&self) -> u64 {
         self.gas_remaining
     }
 
+    /// Returns the last gas cost.
+    #[inline]
     pub fn last_gas_cost(&self) -> u64 {
         self.last_gas_cost
     }
 
+    /// Create a new gas inspector.
     pub fn new() -> Self {
         Self {
             gas_remaining: 0,
             last_gas_cost: 0,
         }
     }
 
+    /// Sets remaining gas to gas limit.
     #[inline]
     pub fn initialize_interp(&mut self, gas: &Gas) {
         self.gas_remaining = gas.limit();
     }
 
+    /// Sets the remaining gas.
     #[inline]
     pub fn step(&mut self, gas: &Gas) {
         self.gas_remaining = gas.remaining();
     }
 
+    /// calculate last gas cost and remaining gas.
     #[inline]
     pub fn step_end(&mut self, gas: &mut Gas) {
         let remaining = gas.remaining();
         self.last_gas_cost = self.gas_remaining.saturating_sub(remaining);
         self.gas_remaining = remaining;
     }
 
+    /// Spend all gas if call failed.
     #[inline]
     pub fn call_end(&mut self, outcome: &mut CallOutcome) {
         if outcome.result.result.is_error() {
@@ -56,6 +65,7 @@ impl GasInspector {
         }
     }
 
+    /// Spend all gas if create failed.
     #[inline]
     pub fn create_end(&mut self, outcome: &mut CreateOutcome) {
         if outcome.result.result.is_error() {