docs: document everything, dedup existing docs (#741)

* docs: document everything, dedup existing docs

* stuff

* Move const where they are used

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: Address) -> 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: Address) -> 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: Address) -> 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: Address) -> 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: Address, 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: Address,
         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: Address, 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: Address, 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: Address, topics: Vec<B256>, data: Bytes);
-    /// Mark an address to be deleted, with funds transferred to target.
-    fn selfdestruct(&mut self, address: Address, target: Address) -> 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<Address>, 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: Address, target: Address) -> 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

@@ -14,16 +14,22 @@ 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: Address,
+    /// The create scheme.
     pub scheme: CreateScheme,
+    /// The value to transfer.
     pub value: U256,
+    /// The init code of the contract.
     pub init_code: Bytes,
+    /// The gas limit of the call.
     pub gas_limit: u64,
 }
 
@@ -41,13 +47,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: Address,
-    /// Caller of the EVM.
+    /// Caller address of the EVM.
     pub caller: Address,
     /// The address the contract code was loaded from, if any.
     pub code_address: Address,
@@ -73,14 +79,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: Address,
-    /// Target address.
+    /// The target address.
     pub target: Address,
-    /// 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

@@ -53,7 +53,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))
+            crate::interpreter::next_multiple_of_32($offset.saturating_add($len))
         {
             #[cfg(feature = "memory_limit")]
             if new_size > ($interp.memory_limit as usize) {

crates/interpreter/src/interpreter.rs

@@ -1,17 +1,15 @@
 pub mod analysis;
 mod contract;
-pub mod memory;
+mod memory;
 mod stack;
 
 use crate::primitives::{Bytes, Spec};
 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 memory::{next_multiple_of_32, Memory};
+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::{Address, Bytecode, Bytes, Env, TransactTo, B256, U256};
 use crate::CallContext;
 
+/// EVM contract information.
 #[derive(Clone, Debug, Default)]
 pub struct Contract {
     /// Contracts data

crates/interpreter/src/interpreter/memory.rs

@@ -186,15 +186,14 @@ 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> {
+pub 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() {

crates/interpreter/src/interpreter/stack.rs

@@ -5,7 +5,7 @@ use crate::{
 use alloc::vec::Vec;
 use core::fmt;
 
-/// The EVM stack limit, in number of items.
+/// EVM interpreter stack limit.
 pub const STACK_LIMIT: usize = 1024;
 
 /// EVM stack.

crates/interpreter/src/lib.rs

@@ -1,3 +1,7 @@
+//! # revm-interpreter
+//!
+//! REVM Interpreter.
+
 #![cfg_attr(not(feature = "std"), no_std)]
 #![warn(unused_crate_dependencies)]
 
@@ -8,8 +12,8 @@ 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;
 
@@ -19,12 +23,11 @@ pub(crate) const USE_GAS: bool = !cfg!(feature = "no_gas_measuring");
 pub use gas::Gas;
 pub use host::{DummyHost, 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

@@ -8,9 +8,6 @@ name = "revm-precompile"
 repository = "https://github.com/bluealloy/revm"
 version = "2.2.0"
 
-# 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.3.0", default-features = false }
 bn = { package = "substrate-bn", version = "0.6", default-features = false }
@@ -44,7 +41,6 @@ std = [
 
 optimism = ["revm-primitives/optimism"]
 
-
 # This library may not work on all no_std platforms as they depend on C libraries.
 
 # Enables the KZG point evaluation precompile.

crates/precompile/src/lib.rs

@@ -1,4 +1,8 @@
-#![no_std]
+//! # revm-precompile
+//!
+//! Implementations of EVM precompiled contracts.
+
+#![cfg_attr(not(feature = "std"), no_std)]
 #![warn(unused_crate_dependencies)]
 
 #[macro_use]
@@ -16,12 +20,12 @@ mod secp256k1;
 use alloc::{boxed::Box, vec::Vec};
 use core::fmt;
 use once_cell::race::OnceBox;
-pub use primitives::{
+#[doc(hidden)]
+pub use revm_primitives as primitives;
+pub use revm_primitives::{
     precompile::{PrecompileError as Error, *},
     Bytes, HashMap,
 };
-#[doc(inline)]
-pub use revm_primitives as primitives;
 
 pub type Address = [u8; 20];
 pub type B256 = [u8; 32];

crates/precompile/src/secp256k1.rs

@@ -1,4 +1,6 @@
 use crate::{Error, Precompile, PrecompileAddress, PrecompileResult, StandardPrecompileFn};
+use alloc::vec::Vec;
+use core::cmp::min;
 
 pub const ECRECOVER: PrecompileAddress = PrecompileAddress(
     crate::u64_to_address(1),
@@ -61,9 +63,6 @@ mod secp256k1 {
 }
 
 fn ec_recover_run(i: &[u8], target_gas: u64) -> PrecompileResult {
-    use alloc::vec::Vec;
-    use core::cmp::min;
-
     const ECRECOVER_BASE: u64 = 3_000;
 
     if ECRECOVER_BASE > target_gas {

crates/primitives/Cargo.toml

@@ -9,6 +9,9 @@ repository = "https://github.com/bluealloy/revm"
 version = "1.3.0"
 readme = "../../README.md"
 
+# Don't need to run build script outside of this repo
+exclude = ["build.rs", "src/kzg/*.txt"]
+
 [dependencies]
 alloy-primitives = { version = "0.4", default-features = false, features = [
     "rlp",

crates/primitives/src/constants.rs

@@ -1,10 +1,5 @@
 use crate::Address;
 
-/// Interpreter stack limit
-pub const STACK_LIMIT: u64 = 1024;
-/// EVM call stack limit
-pub const CALL_STACK_LIMIT: u64 = 1024;
-
 /// EIP-170: Contract code size limit
 /// By default limit is 0x6000 (~25kb)
 pub const MAX_CODE_SIZE: usize = 0x6000;

crates/primitives/src/db.rs

@@ -34,8 +34,10 @@ impl<F: DatabaseRef> From<F> for WrapDatabaseRef<F> {
     }
 }
 
+/// EVM database commit interface.
 #[auto_impl(&mut, Box)]
 pub trait DatabaseCommit {
+    /// Commit changes to the database.
     fn commit(&mut self, changes: Map<Address, Account>);
 }
 

crates/primitives/src/env.rs

@@ -67,7 +67,7 @@ pub struct BlobExcessGasAndPrice {
 }
 
 impl BlobExcessGasAndPrice {
-    /// Takes excess blob gas and calculated blob fee with [`calc_blob_fee`]
+    /// Creates a new instance by calculating the blob gas price with [`calc_blob_gasprice`].
     pub fn new(excess_blob_gas: u64) -> Self {
         let blob_gasprice = calc_blob_gasprice(excess_blob_gas);
         Self {