book workflow (bluealloy#537)

* book workflow

* mdbook lint

* mdbook build optional

* Update introduction.md

* interpreter

primitives + precompiles

mdbook test, doctests

* fmt + CI

* clippy + book

.github/workflows/book.yml

@@ -0,0 +1,127 @@
+name: book
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  merge_group:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    name: test
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Install mdbook
+        run: |
+          mkdir mdbook
+          curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.14/mdbook-v0.4.14-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook
+          echo `pwd`/mdbook >> $GITHUB_PATH
+
+      - name: Install mdbook-template
+        run: |
+          mkdir mdbook-template
+          curl -sSL https://github.com/sgoudham/mdbook-template/releases/latest/download/mdbook-template-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook-template
+          echo `pwd`/mdbook-template >> $GITHUB_PATH
+
+      - name: Run tests
+        run: mdbook test
+
+  lint:
+    runs-on: ubuntu-latest
+    name: lint
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Install mdbook-linkcheck
+        run: |
+          mkdir mdbook-linkcheck
+          curl -sSL -o mdbook-linkcheck.zip https://github.com/Michael-F-Bryan/mdbook-linkcheck/releases/latest/download/mdbook-linkcheck.x86_64-unknown-linux-gnu.zip
+          unzip mdbook-linkcheck.zip -d ./mdbook-linkcheck
+          chmod +x `pwd`/mdbook-linkcheck/mdbook-linkcheck
+          echo `pwd`/mdbook-linkcheck >> $GITHUB_PATH
+
+      - name: Run linkcheck
+        run: mdbook-linkcheck --standalone
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Install toolchain
+        uses: dtolnay/rust-toolchain@nightly
+      - uses: Swatinem/rust-cache@v2
+        with:
+          cache-on-failure: true
+
+      - name: Install mdbook
+        run: |
+          mkdir mdbook
+          curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.14/mdbook-v0.4.14-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook
+          echo `pwd`/mdbook >> $GITHUB_PATH
+
+      - name: Install mdbook-template
+        run: |
+          mkdir mdbook-template
+          curl -sSL https://github.com/sgoudham/mdbook-template/releases/latest/download/mdbook-template-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook-template
+          echo `pwd`/mdbook-template >> $GITHUB_PATH
+
+      - name: Build book
+        run: mdbook build
+
+      - name: Build docs
+        run: RUSTDOCFLAGS="--enable-index-page -Zunstable-options" cargo +nightly doc --all --no-deps
+
+      - name: Move docs to book folder
+        run: |
+          mkdir -p target/book/docs
+          mv target/doc target/book/docs
+
+      - name: Archive artifact
+        shell: sh
+        run: |
+          chmod -c -R +rX "target/book" |
+          while read line; do
+             echo "::warning title=Invalid file permissions automatically fixed::$line"
+          done
+          tar \
+            --dereference --hard-dereference \
+            --directory "target/book" \
+            -cvf "$RUNNER_TEMP/artifact.tar" \
+            --exclude=.git \
+            --exclude=.github \
+            .
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: github-pages
+          path: ${{ runner.temp }}/artifact.tar
+          retention-days: 1
+          if-no-files-found: error
+
+  deploy:
+    # Only deploy if a push to main
+    if: github.ref_name == 'main' && github.event_name == 'push'
+    runs-on: ubuntu-latest
+    needs: [test, lint, build]
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

README.md

@@ -65,6 +65,14 @@ cargo run -p revm --features ethersdb --example fork_ref_transact
 (If you want to add your project to the list, ping me or open the PR)
 
 
+# Documentation
+
+To serve the mdbook documentation, ensure you have mdbook installed (if not install it with cargo) and then run:
+
+```shell
+mdbook serve documentation
+```
+
 # Contact
 
 There is public telegram group: https://t.me/+Ig4WDWOzikA3MzA0

book.toml

@@ -1,6 +1,11 @@
 [book]
-authors = ["Colin, Waylon Jepsen"]
+authors = ["Colin Roberts, Waylon Jepsen"]
 language = "en"
 multilingual = false
 src = "documentation/src"
 title = "Rust EVM"
+
+
+[output.linkcheck]
+optional = true
+follow-web-links = true

crates/primitives/src/result.rs

@@ -39,7 +39,7 @@ pub enum ExecutionResult {
 impl ExecutionResult {
     /// Returns if transaction execution is successful.
     /// 1 indicates success, 0 indicates revert.
-    /// https://eips.ethereum.org/EIPS/eip-658
+    /// <https://eips.ethereum.org/EIPS/eip-658>
     pub fn is_success(&self) -> bool {
         matches!(self, Self::Success { .. })
     }

crates/primitives/src/specification.rs

@@ -1,7 +1,7 @@
 #![allow(non_camel_case_types)]
 
 /// SpecId and their activation block
-/// Information was obtained from: https://github.com/ethereum/execution-specs
+/// Information was obtained from: <https://github.com/ethereum/execution-specs>
 #[repr(u8)]
 #[derive(Debug, Copy, Clone, Eq, PartialEq, Hash, Ord, PartialOrd, enumn::N)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]

crates/primitives/src/utilities.rs

@@ -11,7 +11,7 @@ pub fn keccak256(input: &[u8]) -> B256 {
     B256(Keccak256::digest(input)[..].try_into().unwrap())
 }
 
-/// Returns the address for the legacy `CREATE` scheme: [`CreateScheme::Create`]
+/// Returns the address for the legacy `CREATE` scheme: [`crate::env::CreateScheme::Create`]
 pub fn create_address(caller: B160, nonce: u64) -> B160 {
     let mut stream = rlp::RlpStream::new_list(2);
     stream.append(&caller.0.as_ref());
@@ -20,7 +20,7 @@ pub fn create_address(caller: B160, nonce: u64) -> B160 {
     B160(out[12..].try_into().unwrap())
 }
 
-/// Returns the address for the `CREATE2` scheme: [`CreateScheme::Create2`]
+/// Returns the address for the `CREATE2` scheme: [`crate::env::CreateScheme::Create2`]
 pub fn create2_address(caller: B160, code_hash: B256, salt: U256) -> B160 {
     let mut hasher = Keccak256::new();
     hasher.update([0xff]);

crates/revm/src/evm.rs

@@ -25,6 +25,18 @@ use revm_precompile::Precompiles;
 /// want to update anything on it. It enabled `transact_ref` and `inspect_ref` functions
 /// * Database+DatabaseCommit allow directly committing changes of transaction. it enabled `transact_commit`
 /// and `inspect_commit`
+///
+/// /// # Example
+///
+/// ```
+/// # use revm::EVM;        // Assuming this struct is in 'your_crate_name'
+/// # struct SomeDatabase;  // Mocking a database type for the purpose of this example
+/// # struct Env;           // Assuming the type Env is defined somewhere
+///
+/// let evm: EVM<SomeDatabase> = EVM::new();
+/// assert!(evm.db.is_none());
+/// ```
+///
 #[derive(Clone)]
 pub struct EVM<DB> {
     pub env: Env,

crates/revm/src/inspector/tracer_eip3155.rs

@@ -1,4 +1,4 @@
-//! Inspector that support tracing of EIP-3155 https://eips.ethereum.org/EIPS/eip-3155
+//! Inspector that support tracing of EIP-3155 <https://eips.ethereum.org/EIPS/eip-3155>
 
 use crate::inspectors::GasInspector;
 use crate::interpreter::{CallInputs, CreateInputs, Gas, InstructionResult};

documentation/src/SUMMARY.md

@@ -12,7 +12,6 @@
   - [inner_models](./crates/interpreter/inner_models.md)
   - [instruction_result](./crates/interpreter/instruction_result.md)
   - [instructions](./crates/interpreter/instructions.md)
-- [Examples](./examples.md)
 - [Primitives](./crates/primitives.md)
   - [database](./crates/primitives/database.md)
   - [result](./crates/primitives/result.md)
@@ -32,3 +31,4 @@
   - [Identity function](./crates/precompile/identity.md)
   - [Modular Exponentiation](./crates/precompile/modexp.md)
   - [Secp256k1](./crates/precompile/secp256k1.md)
+  - [Point Evaluation](./crates/precompile/point_evaluation.md)

documentation/src/crates/interpreter.md

@@ -5,11 +5,11 @@ 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 `Host` trait, and any types or functions that the host machine (the machine running the EVM).
-- [inner_models](./interpreter/inner_models.md): Based on the name, this module could contain the inner data structures or models used in the EVM implementation.
-- [instruction_result](./interpreter/instruction_result.md): This module likely contains definitions related to the result of instruction execution.
-- [instructions](./interpreter/instructions.md): This module is expected to include the definitions of the EVM opcodes (instructions).
-- [interpreter](./interpreter/interpreter.md): This module would contain the Interpreter struct and related functionality for executing EVM instructions.
+- [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:
 
@@ -18,9 +18,8 @@ External Crates:
 
 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 used. It's set to false if the `no_gas_measuring` feature is enabled.
 
-Re-exported Types:
-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.
-Re-exported Crate:
-revm_primitives: This crate is re-exported, likely providing primitive types or functionality used in the EVM implementation.
+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.

documentation/src/crates/interpreter/gas.md

@@ -2,33 +2,18 @@
 
 The `gas.rs` module in this Rust EVM implementation manages the concept of "gas" within the Ethereum network. In Ethereum, "gas" signifies the computational effort needed to execute operations, whether a simple transfer of ether or the execution of a smart contract function. Each operation carries a gas cost, and transactions must specify the maximum amount of gas they are willing to consume.
 
-## `Gas` Struct
-
-The `Gas` struct represents the gas state for a particular operation or transaction. The struct is defined as follows:
-
-```rust
-#[derive(Clone, Copy, Debug)]
-pub struct Gas {
-    /// Gas Limit
-    limit: u64,
-    /// used+memory gas.
-    all_used_gas: u64,
-    /// Used gas without memory
-    used: u64,
-    /// Used gas for memory expansion
-    memory: u64,
-    /// Refunded gas. This gas is used only at the end of execution.
-    refunded: i64,
-}
-```
-
-### Fields in `Gas` Struct
-
-- `limit`: The maximum amount of gas allowed for the operation or transaction.
-- `all_used_gas`: The total gas used, inclusive of memory expansion costs.
-- `used`: The gas used, excluding memory expansion costs.
-- `memory`: The gas used for memory expansion.
-- `refunded`: The gas refunded. Certain operations in Ethereum allow for gas refunds, up to half the gas used by a transaction.
+## Data Structures
+- `Gas` Struct
+
+    The `Gas` struct represents the gas state for a particular operation or transaction. The struct is defined as follows:
+
+    ### Fields in `Gas` Struct
+
+    - `limit`: The maximum amount of gas allowed for the operation or transaction.
+    - `all_used_gas`: The total gas used, inclusive of memory expansion costs.
+    - `used`: The gas used, excluding memory expansion costs.
+    - `memory`: The gas used for memory expansion.
+    - `refunded`: The gas refunded. Certain operations in Ethereum allow for gas refunds, up to half the gas used by a transaction.
 
 ## Methods of the `Gas` Struct
 
@@ -42,6 +27,3 @@ The `Gas` struct also includes several methods to manage the gas state. Here's a
 - `record_memory`: This method works similarly to `record_cost`, but specifically for memory expansion gas. It only updates the state if the new memory gas usage is greater than the current usage.
 - `gas_refund`: Increases the refunded gas by a specified amount.
 
-## Importance of the `Gas` Struct
-
-These features of the `Gas` struct allow for effective management and tracking of the gas cost associated with executing EVM operations. This is a key part of ensuring that smart contracts and transactions adhere to the resource constraints of the Ethereum network, since overconsumption of resources could potentially lead to network congestion.

documentation/src/crates/interpreter/host.md

@@ -2,23 +2,8 @@
 
 The `host.rs` module in this Rust EVM implementation defines a crucial trait `Host`. The `Host` trait outlines an interface for the interaction of the EVM interpreter with its environment (or "host"), encompassing essential operations such as account and storage access, creating logs, and invoking transactions.
 
-## `Host` Trait
 
-The `Host` trait provides the definition for all the methods that any EVM host must implement. It's a crucial bridge between the EVM and its environment, allowing the EVM to interact with blockchain state.
-
-```rust
-pub trait Host {
-    fn step(&mut self, interpreter: &mut Interpreter) -> InstructionResult;
-    fn step_end(
-        &mut self,
-        interpreter: &mut Interpreter,
-        ret: InstructionResult,
-    ) -> InstructionResult;
-    // ... (other methods omitted for brevity)
-}
-```
-
-## Key Methods of the `Host` Trait
+## Trait Methods
 
 - `step` & `step_end`: These methods manage the execution of EVM opcodes. The `step` method is invoked before executing an opcode, while `step_end` is invoked after. These methods can modify the EVM state or halt execution based on certain conditions.
 
@@ -38,6 +23,5 @@ pub trait Host {
 
 - `create` & `call`: These methods handle the creation of new smart contracts and the invocation of smart contract functions, respectively.
 
-## Importance of the `Host` Trait
 
 The `Host` trait provides a standard interface that any host environment for the EVM must implement. This abstraction allows the EVM code to interact with the state of the Ethereum network in a generic way, thereby enhancing modularity and interoperability. Different implementations of the `Host` trait can be used to simulate different environments for testing or for connecting to different Ethereum-like networks.