docs: document everything, dedup existing docs

crates/interpreter/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 authors = ["Dragan Rakita <dragan0rakita@gmail.com>"]
-description = "REVM Interpreter"
+description = "EVM bytecode interpreter"
 edition = "2021"
 keywords = ["no_std", "ethereum", "evm", "revm", "interpreter"]
 license = "MIT"
@@ -10,7 +10,7 @@ version = "1.1.2"
 readme = "../../README.md"
 
 [dependencies]
-revm-primitives = { path = "../primitives", version="1.1.2", default-features = false }
+revm-primitives = { path = "../primitives", version = "1.1.2", default-features = false }
 
 #utility
 derive_more = "0.99"
@@ -48,10 +48,7 @@ optional_eip3607 = ["revm-primitives/optional_eip3607"]
 optional_gas_refund = ["revm-primitives/optional_gas_refund"]
 optional_no_base_fee = ["revm-primitives/optional_no_base_fee"]
 std = ["revm-primitives/std"]
-serde = [
-    "dep:serde",
-    "revm-primitives/serde",
-]
+serde = ["dep:serde", "revm-primitives/serde"]
 arbitrary = [
     "std",
     "dep:arbitrary",

crates/interpreter/src/gas.rs

@@ -1,5 +1,7 @@
-pub mod calc;
-pub mod constants;
+//! EVM gas calculation utilities.
+
+mod calc;
+mod constants;
 
 pub use calc::*;
 pub use constants::*;

crates/interpreter/src/host.rs

@@ -10,48 +10,67 @@ mod dummy;
 
 /// EVM context host.
 pub trait Host {
+    /// Called before the interpreter executes an instruction.
     fn step(&mut self, interpreter: &mut Interpreter) -> InstructionResult;
+
+    /// Called after the interpreter executes an instruction.
     fn step_end(
         &mut self,
         interpreter: &mut Interpreter,
         ret: InstructionResult,
     ) -> InstructionResult;
 
+    /// Returns a mutable reference to the environment.
     fn env(&mut self) -> &mut Env;
 
-    /// load account. Returns (is_cold,is_new_account)
+    /// Load an account.
+    ///
+    /// Returns (is_cold, is_new_account)
     fn load_account(&mut self, address: B160) -> Option<(bool, bool)>;
-    /// Get environmental block hash.
+
+    /// Get the block hash of the given block `number`.
     fn block_hash(&mut self, number: U256) -> Option<B256>;
-    /// Get balance of address and if account is cold loaded.
+
+    /// Get balance of `address` and if the account is cold.
     fn balance(&mut self, address: B160) -> Option<(U256, bool)>;
-    /// Get code of address and if account is cold loaded.
+
+    /// Get code of `address` and if the account is cold.
     fn code(&mut self, address: B160) -> Option<(Bytecode, bool)>;
-    /// Get code hash of address and if account is cold loaded.
+
+    /// Get code hash of `address` and if the account is cold.
     fn code_hash(&mut self, address: B160) -> Option<(B256, bool)>;
-    /// Get storage value of address at index and if account is cold loaded.
+
+    /// Get storage value of `address` at `index` and if the account is cold.
     fn sload(&mut self, address: B160, index: U256) -> Option<(U256, bool)>;
+
     /// Set storage value of account address at index.
-    /// Returns (original, present, new, sis_cold)
+    ///
+    /// Returns (original, present, new, is_cold).
     fn sstore(
         &mut self,
         address: B160,
         index: U256,
         value: U256,
     ) -> Option<(U256, U256, U256, bool)>;
-    /// Get the transient storage value of address at index.
+
+    /// Get the transient storage value of `address` at `index`.
     fn tload(&mut self, address: B160, index: U256) -> U256;
-    /// Set the transient storage value of address at index.
+
+    /// Set the transient storage value of `address` at `index`.
     fn tstore(&mut self, address: B160, index: U256, value: U256);
-    /// Create a log owned by address with given topics and data.
+
+    /// Emit a log owned by `address` with given `topics` and `data`.
     fn log(&mut self, address: B160, topics: Vec<B256>, data: Bytes);
-    /// Mark an address to be deleted, with funds transferred to target.
-    fn selfdestruct(&mut self, address: B160, target: B160) -> Option<SelfDestructResult>;
+
+    /// Invoke a call operation.
+    fn call(&mut self, input: &mut CallInputs) -> (InstructionResult, Gas, Bytes);
+
     /// Invoke a create operation.
     fn create(
         &mut self,
         inputs: &mut CreateInputs,
     ) -> (InstructionResult, Option<B160>, Gas, Bytes);
-    /// Invoke a call operation.
-    fn call(&mut self, input: &mut CallInputs) -> (InstructionResult, Gas, Bytes);
+
+    /// Mark `address` to be deleted, with funds transferred to `target`.
+    fn selfdestruct(&mut self, address: B160, target: B160) -> Option<SelfDestructResult>;
 }

crates/interpreter/src/host/dummy.rs

@@ -5,6 +5,7 @@ use crate::{
 };
 use alloc::vec::Vec;
 
+/// A dummy [Host] implementation.
 pub struct DummyHost {
     pub env: Env,
     pub storage: HashMap<U256, U256>,

crates/interpreter/src/inner_models.rs

@@ -18,20 +18,26 @@ pub struct CallInputs {
     pub gas_limit: u64,
     /// The context of the call.
     pub context: CallContext,
-    /// Is static call
+    /// Whether this is a static call.
     pub is_static: bool,
 }
 
+/// Inputs for a create call.
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub struct CreateInputs {
+    /// Caller address of the EVM.
     pub caller: B160,
+    /// The create scheme.
     pub scheme: CreateScheme,
+    /// The value to transfer.
     pub value: U256,
+    /// The init code of the contract.
     #[cfg_attr(
         feature = "serde",
         serde(with = "crate::primitives::utilities::serde_hex_bytes")
     )]
     pub init_code: Bytes,
+    /// The gas limit of the call.
     pub gas_limit: u64,
 }
 
@@ -49,13 +55,13 @@ pub enum CallScheme {
     StaticCall,
 }
 
-/// CallContext of the runtime.
+/// Context of a runtime call.
 #[derive(Clone, Debug, PartialEq, Eq)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub struct CallContext {
     /// Execution address.
     pub address: B160,
-    /// Caller of the EVM.
+    /// Caller address of the EVM.
     pub caller: B160,
     /// The address the contract code was loaded from, if any.
     pub code_address: B160,
@@ -81,14 +87,15 @@ impl Default for CallContext {
 #[derive(Clone, Debug)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub struct Transfer {
-    /// Source address.
+    /// The source address.
     pub source: B160,
-    /// Target address.
+    /// The target address.
     pub target: B160,
-    /// Transfer value.
+    /// The transfer value.
     pub value: U256,
 }
 
+/// Result of a call that resulted in a self destruct.
 #[derive(Default)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub struct SelfDestructResult {

crates/interpreter/src/instructions.rs

@@ -1,5 +1,7 @@
+//! EVM opcode implementations.
+
 #[macro_use]
-pub mod macros;
+mod macros;
 
 pub mod arithmetic;
 pub mod bitwise;

crates/interpreter/src/instructions/macros.rs

@@ -52,9 +52,7 @@ macro_rules! gas_or_fail {
 
 macro_rules! memory_resize {
     ($interp:expr, $offset:expr, $len:expr) => {
-        if let Some(new_size) =
-            crate::interpreter::memory::next_multiple_of_32($offset.saturating_add($len))
-        {
+        if let Some(new_size) = revm_primitives::next_multiple_of_32($offset.saturating_add($len)) {
             #[cfg(feature = "memory_limit")]
             if new_size > ($interp.memory_limit as usize) {
                 $interp.instruction_result = InstructionResult::MemoryLimitOOG;

crates/interpreter/src/interpreter.rs

@@ -1,6 +1,6 @@
 pub mod analysis;
 mod contract;
-pub mod memory;
+mod memory;
 mod stack;
 
 use crate::primitives::{Bytes, Spec};
@@ -9,9 +9,7 @@ use crate::{alloc::boxed::Box, opcode::eval, Gas, Host, InstructionResult};
 pub use analysis::BytecodeLocked;
 pub use contract::Contract;
 pub use memory::Memory;
-pub use stack::{Stack, STACK_LIMIT};
-
-pub const CALL_STACK_LIMIT: u64 = 1024;
+pub use stack::Stack;
 
 /// EIP-170: Contract code size limit
 ///

crates/interpreter/src/interpreter/analysis.rs

@@ -58,6 +58,7 @@ fn analyze(code: &[u8]) -> JumpMap {
     JumpMap(Arc::new(jumps))
 }
 
+/// An analyzed bytecode.
 #[derive(Clone)]
 pub struct BytecodeLocked {
     bytecode: Bytes,

crates/interpreter/src/interpreter/contract.rs

@@ -2,6 +2,7 @@ use super::analysis::{to_analysed, BytecodeLocked};
 use crate::primitives::{Bytecode, Bytes, Env, TransactTo, B160, B256, U256};
 use crate::CallContext;
 
+/// EVM contract information.
 #[derive(Clone, Debug, Default)]
 pub struct Contract {
     /// Contracts data

crates/interpreter/src/interpreter/memory.rs

@@ -1,9 +1,5 @@
 use crate::{alloc::vec::Vec, primitives::U256};
-use core::{
-    cmp::min,
-    fmt,
-    ops::{BitAnd, Not},
-};
+use core::{cmp::min, fmt};
 
 /// A sequential memory. It uses Rust's `Vec` for internal
 /// representation.
@@ -183,17 +179,9 @@ impl Memory {
     }
 }
 
-/// Rounds up `x` to the closest multiple of 32. If `x % 32 == 0` then `x` is returned.
-#[inline]
-pub(crate) fn next_multiple_of_32(x: usize) -> Option<usize> {
-    let r = x.bitand(31).not().wrapping_add(1).bitand(31);
-    x.checked_add(r)
-}
-
 #[cfg(test)]
 mod tests {
-    use super::next_multiple_of_32;
-    use crate::Memory;
+    use super::*;
 
     #[test]
     fn test_copy() {
@@ -212,22 +200,4 @@ mod tests {
         let copied_data = memory.slice(5, 4);
         assert_eq!(copied_data, &[1, 2, 3, 4]);
     }
-
-    #[test]
-    fn test_next_multiple_of_32() {
-        // next_multiple_of_32 returns x when it is a multiple of 32
-        for i in 0..32 {
-            let x = i * 32;
-            assert_eq!(Some(x), next_multiple_of_32(x));
-        }
-
-        // next_multiple_of_32 rounds up to the nearest multiple of 32 when `x % 32 != 0`
-        for x in 0..1024 {
-            if x % 32 == 0 {
-                continue;
-            }
-            let next_multiple = x + 32 - (x % 32);
-            assert_eq!(Some(next_multiple), next_multiple_of_32(x));
-        }
-    }
 }

crates/interpreter/src/interpreter/stack.rs

@@ -1,13 +1,10 @@
 use crate::{
-    primitives::{B256, U256},
+    primitives::{B256, STACK_LIMIT, U256},
     InstructionResult,
 };
 use alloc::vec::Vec;
 use core::fmt;
 
-/// The EVM stack limit, in number of items.
-pub const STACK_LIMIT: usize = 1024;
-
 /// EVM stack.
 #[derive(Clone, Debug, Eq, PartialEq)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]

crates/interpreter/src/lib.rs

@@ -1,3 +1,7 @@
+//! # revm-interpreter
+//!
+//! EVM bytecode interpreter.
+
 #![cfg_attr(not(feature = "std"), no_std)]
 
 extern crate alloc;
@@ -7,23 +11,22 @@ mod macros;
 
 pub mod gas;
 mod host;
-pub mod inner_models;
-pub mod instruction_result;
+mod inner_models;
+mod instruction_result;
 pub mod instructions;
 mod interpreter;
 
 pub(crate) const USE_GAS: bool = !cfg!(feature = "no_gas_measuring");
 
 // Reexport primary types.
 pub use gas::Gas;
-pub use host::{DummyHost, Host};
+pub use host::*;
 pub use inner_models::*;
-pub use instruction_result::InstructionResult;
+pub use instruction_result::*;
 pub use instructions::{opcode, Instruction, OpCode, OPCODE_JUMPMAP};
 pub use interpreter::{
-    analysis, BytecodeLocked, Contract, Interpreter, Memory, Stack, CALL_STACK_LIMIT,
-    MAX_CODE_SIZE, MAX_INITCODE_SIZE,
+    analysis, BytecodeLocked, Contract, Interpreter, Memory, Stack, MAX_CODE_SIZE,
+    MAX_INITCODE_SIZE,
 };
-
-#[doc(inline)]
+#[doc(hidden)]
 pub use revm_primitives as primitives;

crates/precompile/Cargo.toml

@@ -1,16 +1,13 @@
 [package]
 authors = ["Dragan Rakita <dragan0rakita@gmail.com>"]
-description = "REVM Precompiles - Ethereum compatible precompiled contracts"
+description = "Implementations of EVM precompiled contracts"
 edition = "2021"
 keywords = ["no_std", "ethereum", "evm", "revm", "precompiles"]
 license = "MIT"
 name = "revm-precompile"
 repository = "https://github.com/bluealloy/revm"
 version = "2.0.3"
 
-# Don't need to run build script outside of this repo
-exclude = ["build.rs", "src/blob/kzg_settings/*.txt"]
-
 [dependencies]
 revm-primitives = { path = "../primitives", version = "1.1.2", default-features = false }
 bn = { package = "substrate-bn", version = "0.6", default-features = false }
@@ -29,9 +26,6 @@ c-kzg = { git = "https://github.com/ethereum/c-kzg-4844", default-features = fal
 [dev-dependencies]
 hex = "0.4"
 
-[build-dependencies]
-hex = "0.4"
-
 [features]
 default = ["secp256k1", "std"]
 # Used to disable kzg lib as i couldn't make it compile for wasm target