refactor(levm): maintain cached state between executions in levm

.github/workflows/check_readme_cli.yaml

@@ -0,0 +1,66 @@
+name: Check README CLI Help
+
+on:
+  pull_request:
+    paths:
+      - 'cmd/ethrex/**'
+      - 'README.md'
+      - '.github/workflows/check_readme_cli.yml'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  check-cli-help:
+    name: Verify README CLI Help Consistency
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout sources
+        uses: actions/checkout@v4
+
+      - name: Set up Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache Rust dependencies
+        uses: Swatinem/rust-cache@v2
+
+      - name: Build ethrex binary
+        run: cargo build --bin ethrex
+
+      - name: Generate current CLI help
+        id: generate_help
+        run: cargo run --bin ethrex -- --help > current_help.txt
+
+      - name: Extract documented CLI help from README
+        id: extract_help
+        run: |
+          # Extract content between markers, remove markers, remove code block fences
+          sed -n '/<!-- BEGIN_CLI_HELP -->/,/<!-- END_CLI_HELP -->/p' README.md \
+            | sed '1d;$d' \
+            | sed '/^```/d' \
+            > documented_help.txt
+
+          # Check if extraction was successful (simple check: file not empty)
+          if [ ! -s documented_help.txt ]; then
+            echo "::error::Could not extract CLI help section from README.md. Check markers <!-- BEGIN_CLI_HELP --> and <!-- END_CLI_HELP -->."
+            exit 1
+          fi
+
+      - name: Compare current help with documented help
+        run: |
+          # Use diff with flags:
+          # -u: unified format (standard)
+          # -b: ignore changes in amount of whitespace
+          # -B: ignore changes whose lines are all blank
+          # This makes the check less sensitive to minor formatting differences.
+          if ! diff -ubB documented_help.txt current_help.txt; then
+            echo "::error::CLI help in README.md is out of date."
+            echo "Please run 'cargo run --bin ethrex -- --help', copy the output,"
+            echo "and update the section between <!-- BEGIN_CLI_HELP --> and <!-- END_CLI_HELP --> in README.md."
+            echo "(Ignoring differences in spacing and blank lines)."
+            exit 1
+          else
+            echo "README CLI help is up to date."
+          fi

.github/workflows/ci_bench_block_execution.yaml

@@ -4,6 +4,9 @@ on:
   pull_request:
     branches: ["**"]
 
+permissions:
+  pull-requests: write
+
 jobs:
   build-binaries:
     if: contains(github.event.pull_request.labels.*.name, 'performance')

.github/workflows/ci_bench_levm_in_pr.yaml

@@ -6,6 +6,9 @@ on:
     paths:
       - "crates/vm/levm/**"
 
+permissions:
+  pull-requests: write
+
 jobs:
   benchmark-pr:
     name: Benchmark for PR
@@ -159,4 +162,3 @@ jobs:
           issue-number: ${{ github.event.pull_request.number }}
           body-path: combined_result.md
           edit-mode: replace
-

.github/workflows/ci_levm.yaml

@@ -12,6 +12,9 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
   cancel-in-progress: true
 
+permissions:
+  pull-requests: write
+
 env:
   CARGO_TERM_COLOR: always
 

.github/workflows/ci_loc_pr.yaml

@@ -4,6 +4,9 @@ on:
   pull_request:
     branches: ["**"]
 
+permissions:
+  pull-requests: write
+
 jobs:
   report-loc-changes:
     name: Report PR Line Changes

README.md

@@ -181,8 +181,9 @@ For more information about the different cli arguments check out the next sectio
 
 ### CLI Commands
 
+<!-- BEGIN_CLI_HELP -->
 ```
-> cargo run --release --bin ethrex -- --help
+ethrex Execution client
 
 Usage: ethrex [OPTIONS] [COMMAND]
 
@@ -198,48 +199,20 @@ Options:
   -V, --version
           Print version
 
-RPC options:
-      --http.addr <ADDRESS>
-          Listening address for the http rpc server.
-
-          [default: localhost]
-
-      --http.port <PORT>
-          Listening port for the http rpc server.
-
-          [default: 8545]
-
-      --authrpc.addr <ADDRESS>
-          Listening address for the authenticated rpc server.
-
-          [default: localhost]
-
-      --authrpc.port <PORT>
-          Listening port for the authenticated rpc server.
-
-          [default: 8551]
-
-      --authrpc.jwtsecret <JWTSECRET_PATH>
-          Receives the jwt secret used for authenticated rpc requests.
-
-          [default: jwt.hex]
-
 Node options:
-      --log.level <LOG_LEVEL>
-          Possible values: info, debug, trace, warn, error
-
-          [default: INFO]
-
       --network <GENESIS_FILE_PATH>
-          Alternatively, the name of a known network can be provided instead to use its preset genesis file and include its preset bootnodes. The networks currently supported include holesky, sepolia and ephemery.
+          Alternatively, the name of a known network can be provided instead to use its preset genesis file and include its preset bootnodes. The networks currently supported include holesky, sepolia and hoodi.
 
       --datadir <DATABASE_DIRECTORY>
           If the datadir is the word `memory`, ethrex will use the `InMemory Engine`.
 
           [default: ethrex]
 
-      --metrics.port <PROMETHEUS_METRICS_PORT>
+      --metrics.addr <ADDRESS>
+          [default: 0.0.0.0]
 
+      --metrics.port <PROMETHEUS_METRICS_PORT>
+          [default: 9090]
 
       --dev
           If set it will be considered as `true`. The Binary has to be built with the `dev` feature enabled.
@@ -249,7 +222,20 @@ Node options:
 
           [default: revm]
 
+      --log.level <LOG_LEVEL>
+          Possible values: info, debug, trace, warn, error
+
+          [default: INFO]
+
 P2P options:
+      --bootnodes <BOOTNODE_LIST>...
+          Comma separated enode URLs for P2P discovery bootstrap.
+
+      --syncmode <SYNC_MODE>
+          Can be either "full" or "snap" with "full" as default value.
+
+          [default: full]
+
       --p2p.enabled
 
 
@@ -269,14 +255,33 @@ P2P options:
 
           [default: 30303]
 
-      --bootnodes <BOOTNODE_LIST>...
-          Comma separated enode URLs for P2P discovery bootstrap.
+RPC options:
+      --http.addr <ADDRESS>
+          Listening address for the http rpc server.
 
-      --syncmode <SYNC_MODE>
-          Can be either "full" or "snap" with "full" as default value.
+          [default: localhost]
 
-          [default: full]
+      --http.port <PORT>
+          Listening port for the http rpc server.
+
+          [default: 8545]
+
+      --authrpc.addr <ADDRESS>
+          Listening address for the authenticated rpc server.
+
+          [default: localhost]
+
+      --authrpc.port <PORT>
+          Listening port for the authenticated rpc server.
+
+          [default: 8551]
+
+      --authrpc.jwtsecret <JWTSECRET_PATH>
+          Receives the jwt secret used for authenticated rpc requests.
+
+          [default: jwt.hex]
 ```
+<!-- END_CLI_HELP -->
 
 # ethrex L2
 

cmd/ef_tests/state/report.rs

@@ -544,10 +544,11 @@ impl EFTestReportForkResult {
         transaction_report: ExecutionReport,
         reason: String,
         failed_vector: TestVector,
+        levm_cache: HashMap<Address, Account>,
     ) {
         self.failed_vectors.insert(
             failed_vector,
-            EFTestRunnerError::FailedToEnsurePostState(transaction_report, reason),
+            EFTestRunnerError::FailedToEnsurePostState(transaction_report, reason, levm_cache),
         );
     }
 

cmd/ef_tests/state/runner/levm_runner.rs

@@ -9,15 +9,14 @@ use ethrex_common::{
     H256, U256,
 };
 use ethrex_levm::{
-    db::CacheDB,
     errors::{ExecutionReport, TxValidationError, VMError},
-    vm::{EVMConfig, VM},
+    vm::{EVMConfig, GeneralizedDatabase, VM},
     Environment,
 };
 use ethrex_storage::AccountUpdate;
 use ethrex_vm::backends;
 use keccak_hash::keccak;
-use std::{collections::HashMap, sync::Arc};
+use std::collections::HashMap;
 
 pub fn run_ef_test(test: &EFTest) -> Result<EFTestReport, EFTestRunnerError> {
     // There are some tests that don't have a hash, unwrap will panic
@@ -47,11 +46,16 @@ pub fn run_ef_test(test: &EFTest) -> Result<EFTestReport, EFTestRunnerError> {
                 Err(EFTestRunnerError::ExecutionFailedUnexpectedly(error)) => {
                     ef_test_report_fork.register_unexpected_execution_failure(error, *vector);
                 }
-                Err(EFTestRunnerError::FailedToEnsurePostState(transaction_report, reason)) => {
+                Err(EFTestRunnerError::FailedToEnsurePostState(
+                    transaction_report,
+                    reason,
+                    levm_cache,
+                )) => {
                     ef_test_report_fork.register_post_state_validation_failure(
                         transaction_report,
                         reason,
                         *vector,
+                        levm_cache,
                     );
                 }
                 Err(EFTestRunnerError::VMExecutionMismatch(_)) => {
@@ -79,20 +83,20 @@ pub fn run_ef_test_tx(
     test: &EFTest,
     fork: &Fork,
 ) -> Result<(), EFTestRunnerError> {
-    let mut levm = prepare_vm_for_tx(vector, test, fork)?;
+    let mut db = utils::load_initial_state_levm(test);
+    let mut levm = prepare_vm_for_tx(vector, test, fork, &mut db)?;
     ensure_pre_state(&levm, test)?;
     let levm_execution_result = levm.execute();
-    ensure_post_state(&levm_execution_result, vector, test, fork)?;
+    ensure_post_state(&levm_execution_result, vector, test, fork, &mut db)?;
     Ok(())
 }
 
-pub fn prepare_vm_for_tx(
+pub fn prepare_vm_for_tx<'a>(
     vector: &TestVector,
     test: &EFTest,
     fork: &Fork,
-) -> Result<VM, EFTestRunnerError> {
-    let db = Arc::new(utils::load_initial_state_levm(test));
-
+    db: &'a mut GeneralizedDatabase,
+) -> Result<VM<'a>, EFTestRunnerError> {
     let tx = test
         .transactions
         .get(vector)
@@ -153,17 +157,21 @@ pub fn prepare_vm_for_tx(
         tx.value,
         tx.data.clone(),
         db,
-        CacheDB::default(),
         access_lists,
         authorization_list,
     )
     .map_err(|err| EFTestRunnerError::VMInitializationFailed(err.to_string()))
 }
 
 pub fn ensure_pre_state(evm: &VM, test: &EFTest) -> Result<(), EFTestRunnerError> {
-    let world_state = &evm.db;
+    let world_state = &evm.db.store;
     for (address, pre_value) in &test.pre.0 {
-        let account = world_state.get_account_info(*address);
+        let account = world_state.get_account_info(*address).map_err(|e| {
+            EFTestRunnerError::Internal(InternalError::Custom(format!(
+                "Failed to get account info when ensuring pre state: {}",
+                e
+            )))
+        })?;
         ensure_pre_state_condition(
             account.nonce == pre_value.nonce.as_u64(),
             format!(
@@ -179,8 +187,9 @@ pub fn ensure_pre_state(evm: &VM, test: &EFTest) -> Result<(), EFTestRunnerError
             ),
         )?;
         for (k, v) in &pre_value.storage {
-            let storage_slot =
-                world_state.get_storage_slot(*address, H256::from_slice(&k.to_big_endian()));
+            let storage_slot = world_state
+                .get_storage_slot(*address, H256::from_slice(&k.to_big_endian()))
+                .unwrap();
             ensure_pre_state_condition(
                 &storage_slot == v,
                 format!(
@@ -278,6 +287,7 @@ pub fn ensure_post_state(
     vector: &TestVector,
     test: &EFTest,
     fork: &Fork,
+    db: &mut GeneralizedDatabase,
 ) -> Result<(), EFTestRunnerError> {
     match levm_execution_result {
         Ok(execution_report) => {
@@ -304,22 +314,18 @@ pub fn ensure_post_state(
                     return Err(EFTestRunnerError::FailedToEnsurePostState(
                         execution_report.clone(),
                         error_reason,
+                        db.cache.clone(),
                     ));
                 }
                 // Execution result was successful and no exception was expected.
                 None => {
-                    let store_wrapper = utils::load_initial_state_levm(test);
-                    let levm_account_updates = backends::levm::LEVM::get_state_transitions(
-                        Arc::new(store_wrapper),
-                        *fork,
-                        &execution_report.new_state,
-                    )
-                    .map_err(|_| {
-                        InternalError::Custom(
-                            "Error at LEVM::get_state_transitions in ensure_post_state()"
-                                .to_owned(),
-                        )
-                    })?;
+                    let levm_account_updates =
+                        backends::levm::LEVM::get_state_transitions(db, *fork).map_err(|_| {
+                            InternalError::Custom(
+                                "Error at LEVM::get_state_transitions in ensure_post_state()"
+                                    .to_owned(),
+                            )
+                        })?;
                     let pos_state_root = post_state_root(&levm_account_updates, test);
                     let expected_post_state_root_hash =
                         test.post.vector_post_value(vector, *fork).hash;
@@ -330,6 +336,7 @@ pub fn ensure_post_state(
                         return Err(EFTestRunnerError::FailedToEnsurePostState(
                             execution_report.clone(),
                             error_reason,
+                            db.cache.clone(),
                         ));
                     }
                 }