chore(docs): minor improvements, create separate page for Host trait

documentation/src/SUMMARY.md

@@ -4,6 +4,7 @@
 - [Revm](./crates/revm.md)
   - [evm](./crates/revm/evm.md)
   - [evm_impl](./crates/revm/evm_impl.md)
+  - [The Host Trait](./crates/revm/host_trait.md)
   - [inspector](./crates/revm/inspector.md)
   - [journaled_state](./crates/revm/journaled_state.md)
 - [Interpreter](./crates/interpreter.md)

documentation/src/crates/interpreter.md

@@ -5,21 +5,21 @@ The `interpreter` crate is concerned with the execution of the EVM opcodes and s
 Modules:
 
 - [gas](./interpreter/gas.md): This module deals with handling the gas mechanics in the EVM, such as calculating gas costs for operations.
-- [host](./interpreter/host.md): This module defines the evm context `Host` trait.
+- [host](./interpreter/host.md): This module defines the EVM context `Host` trait.
 - [inner_models](./interpreter/inner_models.md): This module contains the inner data structures used in the EVM implementation.
 - [instruction_result](./interpreter/instruction_result.md): This module contains definitions related to the result of instruction execution.
 - [instructions](./interpreter/instructions.md): This module includes the definitions of the EVM opcodes (instructions).
 
 
 External Crates:
 
-- alloc: The alloc crate is used to provide the ability to allocate memory on the heap. It's a part of Rust's standard library that can be used in environments without a full host OS.
-- core: The core crate is the dependency-free foundation of the Rust standard library. It includes fundamental types, macros, and traits.
+- [alloc](https://doc.rust-lang.org/alloc/): The alloc crate is used to provide the ability to allocate memory on the heap. It's a part of Rust's standard library that can be used in environments without a full host OS.
+- [core](https://doc.rust-lang.org/core/): The core crate is the dependency-free foundation of the Rust standard library. It includes fundamental types, macros, and traits.
 
 Constants:
 
-- `USE_GAS`: This constant determines whether gas measurement should be used. It's set to false if the `no_gas_measuring` feature is enabled.
+- `USE_GAS`: This constant determines whether gas measurement should be enabled. It's set to false if the `no_gas_measuring` feature is enabled.
 
 Re-exports:
 - Several types and functions are re-exported for easier access by users of this library, such as `Gas`, `Host`, `InstructionResult`, `OpCode`, `Interpreter`, `Memory`, `Stack`, and others. This allows users to import these items directly from the library root instead of from their individual modules.
-- revm_primitives: This crate is re-exported, providing primitive types or functionality used in the EVM implementation.
+- `revm_primitives`: This crate is re-exported, providing primitive types or functionality used in the EVM implementation.

documentation/src/crates/precompile.md

@@ -1,12 +1,12 @@
 # Precompile
 
-The `precompile` crate contains the implementation of the Ethereum precompile opcodes in the evm. Precompiles are a shortcut to execute a function implemented by the EVM itself, rather than an actual contract. Precompiled contracts are essentially predefined smart contracts on Ethereum, residing at hardcoded addresses and used for computationally heavy operations that are cheaper when implemented this way. There are 6 precompiles implemented in REVM, and they are: `blake2`, `bn128` curve, `identity`, `secp256k1`, `modexp`, and `sha256` and `ripemd160` has functions.
+The `precompile` crate contains the implementation of the Ethereum precompile opcodes in the EVM. Precompiles are a shortcut to execute a function implemented by the EVM itself, rather than an actual contract. Precompiled contracts are essentially predefined smart contracts on Ethereum, residing at hardcoded addresses and used for computationally heavy operations that are cheaper when implemented this way. There are 6 precompiles implemented in REVM, and they are: `blake2`, `bn128` curve, `identity`, `secp256k1`, `modexp`, and `sha256` and `ripemd160` hash functions.
 
 Modules:
 
 - [blake2](./precompile/blake2.md): This module implements the `BLAKE2` compression function, as specified in EIP-152.
 - [bn128](./precompile/bn128.md): This module contains the implementations of precompiled contracts for addition, scalar multiplication, and optimal ate pairing check on the alt_bn128 elliptic curve.
-- [hash](./precompile/hash.md): This module includes the implementations for the SHA256 and RIPEMD160 hash function precompiles.
+- [hash](./precompile/hash.md): This module includes the implementations for the `SHA256` and `RIPEMD160` hash function precompiles.
 - [identity](./precompile/identity.md): This module implements the Identity precompile, which returns the input data unchanged.
 - [modexp](./precompile/modexp.md): This module implements the big integer modular exponentiation precompile.
 - [secp256k1](./precompile/secp256k1.md): This module implements the ECDSA public key recovery precompile, based on the secp256k1 curve.
@@ -29,8 +29,8 @@ Functions:
 
 External Crates:
 
-- alloc: The alloc crate provides types for heap allocation, and is used here for the `Vec` type.
-- core: The core crate provides fundamental Rust types, macros, and traits, and is used here for `fmt::Result`.
+- [alloc](https://doc.rust-lang.org/alloc/): The alloc crate provides types for heap allocation, and is used here for the `Vec` type.
+- [core](https://doc.rust-lang.org/core/): The core crate provides fundamental Rust types, macros, and traits, and is used here for `fmt::Result`.
 
 Re-exported Crates and Types:
 

documentation/src/crates/revm/evm_impl.md

@@ -1,6 +1,8 @@
 # EVM Implementation
 
-This module implements the Ethereum Virtual Machine (EVM), a stack-based virtual machine that executes Ethereum smart contracts.
+This module implements the Ethereum Virtual Machine (EVM), a stack-based virtual machine that executes Ethereum smart contracts. The following methods are exposed through the `EVMImpl` struct.
+
+## Methods
 
 - `run_interpreter`
 
@@ -30,63 +32,4 @@ This module implements the Ethereum Virtual Machine (EVM), a stack-based virtual
 
     - `inputs`: A mutable reference to a `CallInputs` instance, which contains all the necessary information for the contract call.
 
-    The method returns a tuple containing the result of the call (as an `InstructionResult`), the remaining gas (as a `Gas` instance), and any output data from the call (as a `Bytes` instance).
-
-## Host Implementation
-
-The `Host` trait provides an interface that allows the EVM to interact with the external world. It contains methods to access environmental information, manipulate account balances, and interact with contract code and storage.
-
-The `EVMImpl` struct implements this `Host` trait.
-
-- `step` & `step_end`
-
-    These methods are used to control the interpreter's execution. They move the interpreter forward one step, allowing the user to inspect the state of the interpreter after each individual operation.
-    These control the execution of the interpreter, allowing step-by-step execution and inspection.
-
-- `env`
-
-    This method returns a mutable reference to the environment information that the EVM uses for its execution. The `Env` struct contains details about the current block, such as the timestamp, block number, difficulty, and gas limit.
-
-- `block_hash`
-
-    This method retrieves the hash of a block given its number. It's typically used within smart contracts for actions like random number generation.
-
-- `load_account`
-
-    This method loads the account associated with a given address and returns information about the account's existence and if it's a contract.
-
-- `balance`
-
-    This method retrieves the balance of an Ethereum account given its address. It returns a tuple containing the balance and a boolean indicating whether the account was "cold" (accessed for the first time in the current transaction).
-
--  `code`
-
-    This method retrieves the bytecode of a given address. It returns a tuple containing the bytecode and a boolean indicating whether the account was "cold".
-
--  `code_hash`
-
-    This method retrieves the code_hash at a given address. It returns a tuple containing the hash and a boolean indicating whether the account was "cold".
-
-- `sload` & `sstore`
-
-    These methods interact with the contract storage. The `sload` method retrieves a value from contract storage, while `sstore` sets a value in contract storage.
-
-- `tload` & `tstore`
-
-    As defined in [EIP1153](https://eips.ethereum.org/EIPS/eip-1153), for transiant storage reads and writes. 
-
-- `log`
-
-    This method is used to create log entries, which are a way for contracts to produce output that external observers (like dapps or the frontend of a blockchain explorer) can listen for and react to.
-
--  `selfdestruct`
-
-    The selfdestruct method attempts to terminate the specified address, transferring its remaining balance to a given target address. If the INSPECT constant is true, the self-destruction event is observed or logged via an inspector. The method returns an Option<SelfDestructResult>, encapsulating the outcome of the operation: Some(SelfDestructResult) on success and None if an error occurs, with the error being stored internally for later reference.
-
-- `create`
-
-    The create method initiates the creation of a contract with the provided CreateInputs. If the INSPECT constant is true, the creation process is observed or logged using an inspector, both at the start and end of the creation. The method returns a tuple consisting of the operation's result (InstructionResult), the optional address (Option<B160>) of the newly created contract, the amount of gas consumed (Gas), and the output data (Bytes). If the inspector intervenes and determines the instruction shouldn't continue, an early return occurs with the observed outcomes.
-
-- `call`
-
-    The call method manages a contract invocation using the provided CallInputs. If the INSPECT constant is active, the call event is observed or logged via an inspector before execution. The method yields a tuple representing the outcome of the call: the result status (InstructionResult), the consumed gas (Gas), and the output data (Bytes). If the inspector suggests early termination, the method returns immediately with the observed results. Otherwise, the main call execution is processed, and the outcomes, either raw or observed, are returned accordingly.
+    The method returns a tuple containing the result of the call (as an `InstructionResult`), the remaining gas (as a `Gas` instance), and any output data from the call (as a `Bytes` instance).

documentation/src/crates/revm/host_trait.md

@@ -0,0 +1,57 @@
+# Host Implementation
+
+The `Host` trait provides an interface that allows the EVM to interact with the external world. It contains methods to access environmental information, manipulate account balances, and interact with contract code and storage.
+
+The [`EVMImpl`](./evm_impl.md) struct implements this `Host` trait.
+
+- `step` & `step_end`
+
+    These methods are used to control the interpreter's execution. They move the interpreter forward one step, allowing the user to inspect the state of the interpreter after each individual operation. These control the execution of the interpreter, allowing step-by-step execution and inspection.
+
+- `env`
+
+    This method returns a mutable reference to the environment information that the EVM uses for its execution. The `Env` struct contains details about the current block, such as the timestamp, block number, difficulty, and gas limit.
+
+- `block_hash`
+
+    This method retrieves the hash of a block given its number. It's typically used within smart contracts for actions like random number generation.
+
+- `load_account`
+
+    This method loads the account associated with a given address and returns information about the account's existence and if it's a contract.
+
+- `balance`
+
+    This method retrieves the balance of an Ethereum account given its address. It returns a tuple containing the balance and a boolean indicating whether the account was "cold" (accessed for the first time in the current transaction).
+
+-  `code`
+
+    This method retrieves the bytecode of a given address. It returns a tuple containing the bytecode and a boolean indicating whether the account was "cold".
+
+-  `code_hash`
+
+    This method retrieves the code_hash at a given address. It returns a tuple containing the hash and a boolean indicating whether the account was "cold".
+
+- `sload` & `sstore`
+
+    These methods interact with the contract storage. The `sload` method retrieves a value from contract storage, while `sstore` sets a value in contract storage.
+
+- `tload` & `tstore`
+
+    As defined in [EIP1153](https://eips.ethereum.org/EIPS/eip-1153), for transiant storage reads and writes. 
+
+- `log`
+
+    This method is used to create log entries, which are a way for contracts to produce output that external observers (like dapps or the frontend of a blockchain explorer) can listen for and react to.
+
+-  `selfdestruct`
+
+    The selfdestruct method attempts to terminate the specified address, transferring its remaining balance to a given target address. If the INSPECT constant is true, the self-destruction event is observed or logged via an inspector. The method returns an Option<SelfDestructResult>, encapsulating the outcome of the operation: Some(SelfDestructResult) on success and None if an error occurs, with the error being stored internally for later reference.
+
+- `create`
+
+    The create method initiates the creation of a contract with the provided CreateInputs. If the INSPECT constant is true, the creation process is observed or logged using an inspector, both at the start and end of the creation. The method returns a tuple consisting of the operation's result (InstructionResult), the optional address (Option<B160>) of the newly created contract, the amount of gas consumed (Gas), and the output data (Bytes). If the inspector intervenes and determines the instruction shouldn't continue, an early return occurs with the observed outcomes.
+
+- `call`
+
+    The call method manages a contract invocation using the provided CallInputs. If the INSPECT constant is active, the call event is observed or logged via an inspector before execution. The method yields a tuple representing the outcome of the call: the result status (InstructionResult), the consumed gas (Gas), and the output data (Bytes). If the inspector suggests early termination, the method returns immediately with the observed results. Otherwise, the main call execution is processed, and the outcomes, either raw or observed, are returned accordingly.

documentation/src/crates/revm/journaled_state.md

@@ -1,21 +1,8 @@
 # Journaled State
 
-The `journaled_state` module of the `revm` crate provides a state management
-implementation for Ethereum-style accounts. It includes support for
-various actions such as self-destruction of accounts, initial account loading, account state
-modification, and logging. It also contains several important utility functions such as
-`is_precompile`.
-This module is built around the `JournaledState` structure, which encapsulates the entire
-state of the blockchain. `JournaledState` uses an internal state representation (a HashMap)
-that tracks all accounts. Each account is represented by the `Account` structure, which includes
-fields like balance, nonce, and code hash.
-For state-changing operations, the module keeps track of all the changes within a "journal" for
-easy reversion and commitment to the database. This feature is particularly useful for handling
-reversion of state changes in case of transaction failures or other exceptions.
-The module interacts with a database through the `Database` trait, which abstracts the
-operations for fetching and storing data. This design allows for a pluggable backend
-where different implementations of the `Database` trait can be used to persist the state
-in various ways (for instance, in-memory or disk-based databases).
+The `journaled_state` module of the `revm` crate provides a state management implementation for Ethereum-style accounts. It includes support for various actions such as self-destruction of accounts, initial account loading, account state modification, and logging. It also contains several important utility functions such as `is_precompile`.
+
+This module is built around the `JournaledState` structure, which encapsulates the entire state of the blockchain. `JournaledState` uses an internal state representation (a `HashMap`) that tracks all accounts. Each account is represented by the `Account` structure, which includes fields like balance, nonce, and code hash. For state-changing operations, the module keeps track of all the changes within a "journal" for easy reversion and commitment to the database. This feature is particularly useful for handling reversion of state changes in case of transaction failures or other exceptions. The module interacts with a database through the `Database` trait, which abstracts the operations for fetching and storing data. This design allows for a pluggable backend where different implementations of the `Database` trait can be used to persist the state in various ways (for instance, in-memory or disk-based databases).
 
 ## Data Structures
 

documentation/src/introduction.md

@@ -1,10 +1,10 @@
 # Introduction
 
-`revm` is an Ethereum Virtual Machine (EVM) written in Rust that is focused on speed and simplicity. This documentation is very much a work in progress and a community effort. If you would like to contribute and improve these docs please make a pr to the [github repo](https://github.com/bluealloy/revm/tree/main). Importantly Revm is just the execution environment for ethereum, there is no networking or consensus related work in this repository.
+`revm` is an Ethereum Virtual Machine (EVM) written in Rust that is focused on speed and simplicity. This documentation is very much a work in progress and a community effort. If you would like to contribute and improve these docs please make a pr to the [github repo](https://github.com/bluealloy/revm/tree/main). Most importantly, Revm is just the execution environment for ethereum; there is no networking or consensus related work in this repository.
 
 ## Crates
 
-The project has 4 main crates that are used to build the revm. The crates are:
+The project has 4 main crates that are used to build revm. These are:
 
 - `revm`: The main EVM library.
 - `primitives`: Primitive data types.