book workflow (bluealloy#537)

* book workflow

* mdbook lint

* mdbook build optional

* Update introduction.md

* interpreter

primitives + precompiles

mdbook test, doctests

* fmt + CI

* clippy + book

Author: 0xJepsen

.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

@@ -37,7 +37,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

@@ -17,3 +17,32 @@ pub fn create_address(caller: Address, nonce: u64) -> Address {
 pub fn create2_address(caller: Address, code_hash: B256, salt: U256) -> Address {
     caller.create2(salt.to_be_bytes::<32>(), code_hash)
 }
+
+/// Serde functions to serde as [bytes::Bytes] hex string
+#[cfg(feature = "serde")]
+pub mod serde_hex_bytes {
+    use alloc::string::{String, ToString};
+    use serde::{Deserialize, Deserializer, Serializer};
+
+    pub fn serialize<S, T>(x: T, s: S) -> Result<S::Ok, S::Error>
+    where
+        S: Serializer,
+        T: AsRef<[u8]>,
+    {
+        s.serialize_str(&alloc::format!("0x{}", hex::encode(x.as_ref())))
+    }
+
+    pub fn deserialize<'de, D>(d: D) -> Result<bytes::Bytes, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        let value = String::deserialize(d)?;
+        if let Some(value) = value.strip_prefix("0x") {
+            hex::decode(value)
+        } else {
+            hex::decode(&value)
+        }
+        .map(Into::into)
+        .map_err(|e| serde::de::Error::custom(e.to_string()))
+    }
+}

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.