Skip to content

docs(levm): cleanup readme #4856

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Oct 16, 2025
Merged

docs(levm): cleanup readme #4856

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
84ec6a0
remove some docs and add info about testing
JereSalo Oct 13, 2025
ae3970c
update readme
JereSalo Oct 13, 2025
ba84bf2
improve docs a bit
JereSalo Oct 14, 2025
ecdc6a1
Update crates/vm/levm/README.md
JereSalo Oct 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
228 changes: 6 additions & 222 deletions crates/vm/levm/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,245 +6,29 @@ Implementation of a simple Ethereum Virtual Machine in Rust.

| Fork | Status |
| -------------- | ------ |
| Osaka | ✅ |
| Prague | ✅ |
| Cancun | ✅ |
| Shanghai | ✅ |
| Paris (Merge) | ✅ |

## Roadmap
## Docs

| Nº | Milestone | Status |
| --- | ------------------------------- | ------ |
| 1 | Support Merge->Cancun forks | ✅ |
| 2 | Integrate `ethrex L1` <> `levm` | 🏗️ |
| 3 | Support Pectra upgrade | 🏗️ |
| 4 | Integrate `ethrex L2` <> `levm` | ❌ |
| 5 | Performance | 🏗️ |
There is a large amount of docs in comments inside the code. For more information check out the [FAQ](../../../docs/vm/levm/faq.rs) and related documents.

### Milestone 1: Support Merge->Cancun forks
## Testing

This is having the minimum implementation so all the Ethereum Foundation tests from the fork Merge (Paris) to Cancun pass.

| Task Description | Status |
| --------------------------- | ------ |
| Make Cancun EF tests pass | ✅ |
| Make Shanghai EF tests pass | ✅ |
| Make Merge EF tests pass | ✅ |

### Milestone 2: Integrate `ethrex L1` <> `levm`

Once we support all the forks from Merge to Cancun, we will integrate `ethrex L1` with `levm`.

Nowadays `ethrex L1` uses `revm` as the backend VM. We will replace `revm` with `levm` and make sure all the tests pass.

| Task Description | Status |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| All the Hive tests that pass with `revm` also pass with `levm` | ✅ |
| We have an insurance that if `levm` some time diverges from `revm`'s behavior, we will know it. And in such case, switching to `revm` while we fix the issue is easy | ✅ |
| The feature flag `levm` is used as the default backend VM for `ethrex L1` | ❌ |
| We switch which EVM `ethrex` uses using a `--vm` CLI flag | ✅ |
| We have a `EVM` trait or similar to standardize the VM interface. This trait should be implemented by `levm` and `revm` | 🏗 |

### Milestone 3: Support Pectra upgrade

> [!NOTE]
> This milestone can be started after we finish milestone 1, and can be done in parallel with milestones 2, 3, and 5 (speaking in terms of the current priorities).

This is extending our current implementation so we support the [Pectra upgrade](https://eips.ethereum.org/EIPS/eip-7600).

There are a lot of EIPs schedule to include in this upgrade but for `levm` we'll only focus on:

- EIP-2537: Precompile for BLS12-381 curve operations
- EIP-7623: Increase calldata cost
- EIP-7691: Blob throughput increase
- EIP-7702: Set EOA account code
- EIP-7840: Add blob schedule to EL config files

| Task Description | Status |
| ------------------------- | ------ |
| Implement EIP-2537 | ✅ |
| Implement EIP-7623 | ✅ |
| Implement EIP-7691 | ✅️ |
| Implement EIP-7702 | ✅️ |
| Implement EIP-7840 | ✅️ |
| Make Prague EF tests pass | ✅️ |

### Milestone 4: Integrate `ethrex L2` <> `levm`

> [!NOTE]
> This milestone can be started after we finish milestone 2, and can be done in parallel with milestone 3. It is placed at this point in the roadmap because of the current priorities.

Once we support all the forks from Merge to Cancun and fully integrate `ethrex L1` with `levm`, we can start integrating with `ethrex L2`.

For this milestone we'll have to refactor the code to support custom builds of the VM. A user should be able to build an instance of the VM modifying or adding new behavior to the VM. We'll call this "hooks" and `ethrex L2` will plug custom hooks to the VM so it can support the current `ethrex L2`'s Privilege transactions and other features.

We'll also have to refactor (and probably re-write) some precompiles implementation to enable the RISC-V zkVM backend to successfully prove `levm`'s execution. We need to ensure that the crates used in LEVM are compatible with these. For instance, most of the precompiles will need to be rewritten using patched libraries instead of the ones they currently use.

| Task Description | Status |
| ------------------------------------------------------------------------- | ------ |
| This does not add breaking changes to the current implementation | ❌ |
| The feature flag `levm` is used as the default backend VM for `ethrex L2` | ❌ |
| The L2 integration test pass | ❌ |
| The prover tests pass | ❌ |

### Milestone 5: Performance

> [!NOTE]
> This milestone can be started after we finish milestone 1, and can be done in parallel with milestones 2, 3, and 4. It is placed at this point in the roadmap because of the current priorities.

This is improving the performance of the VM.

We'll run flamegraph or Samply over the VM to identify bottlenecks and improve the performance of the VM. We'll also extend the current benchmarks suite to include more complex contracts and compare the performance not only of `levm` with `revm` but also with other known EVM implementations (like `evmone`).

| Task Description | Status |
| ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| We have a GitHub workflow that posts the benchmark results comparison between the PR and the main branch in every PR that includes changes in `levm` | ✅ |
| We have a GitHub workflow that generates a flamegraph over `levm` and `revm` and post the results in GitHub Pages | ✅ |
| Add more benchmarks to the current suite | ✅ |
| Benchmark a mainnet's block execution | ✅ |
| We add a table in the README comparing the benchmark results between multiple EVM implementations similar to the one in GitHub Pages | 🏗️ |
| All the identified bottlenecks are fixed | 🏗️ |

## Ethereum Foundation Tests (EF Tests)

### Status

> [!NOTE]
> This is updated as of this README's last update. For the most up-to-date status, please run the tests locally.

**Total**: 18909/18909 (100.00%)

**Prague** 5201/5201 (100.00%)
**Cancun**: 7608/7608 (100.00%)
**Shanghai**: 3214/3214 (100.00%)
**Paris**: 2886/2886 (100.00%)


### How to run EF tests
We run `EEST`, `ethereum/tests` and `legacyTests` both in their [state](../../../tooling/ef_tests/state/README.md) and [blockchain](../../../tooling/ef_tests/blockchain/README.md) form. More info on each README.

For running state tests from the current directory use:
```
make download-evm-ef-tests run-evm-ef-tests QUIET=true
```

For more information on running EF state tests go [here](../../../tooling/ef_tests/state/README.md).

For running EF blockchain tests go [here](../../../tooling/ef_tests/blockchain/README.md).

## Benchmarks

### Status

> [!NOTE]
> This is updated as of this README's last update. For the most up-to-date status, please run the benchmarks locally.

| Benchmark | `levm` | `revm` | Difference |
| --------- | ------------------ | ----------------- | ---------------------------------------------- |
| Factorial | 910.7 ms ± 11.9 ms | 230.8 ms ± 3.1 ms | `revm` is 3.95 ± 0.07 times faster than `levm` |
| Fibonacci | 917.2 ms ± 13.3 ms | 206.5 ms ± 0.8 ms | `revm` is 4.44 ± 0.07 times faster than `levm` |
| Factorial Recursive | 15.815 s ± 0.033 s | 1.449 s ± 0.082 s | `revm` is 10.92 ± 0.62 times faster than `levm` |
| Many Hashes | 18.3 ms ± 0.1 ms | 8.6 ms ± 0.0 ms | `revm` is 2.14 ± 0.02 times faster than `levm` |
| Bubble Sort | 6.195 s ± 0.039 s | 3.197 s ± 0.017 s | `revm` is 1.94 ± 0.02 times faster than `levm` |
| ERC20 Approval | 2.058 s ± 0.008 s | 1.047 s ± 0.010 s | `revm` is 1.96 ± 0.02 times faster than `levm` |
| ERC20 Transfer | 546.6 ms ± 3.7 ms | 248.3 ms ± 4.2 ms | `revm` is 2.20 ± 0.04 times faster than `levm` |
| ERC20 Mint | 359.5 ms ± 2.7 ms | 141.4 ms ± 1.5 ms | `revm` is 2.54 ± 0.03 times faster than `levm` |

### How to run benchmarks locally

> [!IMPORTANT]
> You need to have `hyperfine` installed to run the benchmarks.

```
make revm-comparison
```

## LEVM as the backend VM for `ethrex`

This section covers how to run `ethrex`'s Hive tests using LEVM as the backend VM

### Status

> [!NOTE]
> This is updated as of this README's last update. For the most up-to-date status, please run the tests locally.

**Engine**
- **Cancun**: 114/226 (50.44%)
- **Paris**: 43/129 (33.33%)
- **Shanghai**: 26/35 (74.29%)
- **Auth**: 8/8 (100.00%)
- **Exchange Capabilities**: 5/5 (100.00%)

**P2P**
- **Discovery V4**: 15/15 (100.00%)
- **Eth capability**: 12/15 (80.00%)
- **Snap capability**: 6/6 (100.00%)

**RPC**
- **RPC API Compatibility**: 89/90 (98.89%)

**Sync**
- **Node Syncing**: 2/2 (100.00%)

**Total**: 320/531 (60.26%)

### How to run

> [!IMPORTANT]
> You need to have `go` installed to run the Hive tests.

```
make run-hive-debug-levm
```

## Useful Links

[Ethereum Yellowpaper](https://ethereum.github.io/yellowpaper/paper.pdf) - Formal definition of Ethereum protocol.
[The EVM Handbook](https://noxx3xxon.notion.site/The-EVM-Handbook-bb38e175cc404111a391907c4975426d) - General EVM Resources
[EVM Codes](https://www.evm.codes/) - Reference for opcode implementation
[EVM Playground](https://www.evm.codes/playground) - Useful for seeing opcodes in action
[EVM Deep Dives](https://noxx.substack.com/p/evm-deep-dives-the-path-to-shadowy) - Deep Dive into different aspects of the EVM

## Performance metrics

To run either flamegraph or samply on the EF tests you have to download the tests first:

```Shell
make download-state-tests
```

### To run Flamegraph on the Ethereum Foundation tests

First install Flamegraph

```Shell
cargo install flamegraph
```

Run the tests

```Shell
make flamegraph-run-ef-tests
```

This will create a folder inside `tooling/ef_tests/state/` named `levm_ef_test_perfgraphs` you can find the flamegraphs inside the folder `levm_ef_test_perfgraphs/flamegraph` open them with your preferred browser.

### To run Samply on the Ethereum Foundation tests

First install Samply

```Shell
cargo install --locked samply
```

Run the tests

```Shell
make samply-run-ef-tests
```

This will create a folder inside `tooling/ef_tests/state/` named `levm_ef_test_perfgraphs` you can find the flamegraphs inside the folder `levm_ef_test_perfgraphs/samply` run

```Shell
samply load <path-to-perf-file.json>
```

samply will open Firefox with the desired profile file.
Loading