|
1 | | -# revm |
| 1 | +### Revm |
2 | 2 |
|
3 | 3 | [][gh-ci] |
4 | 4 | [][mit-license] |
5 | 5 | [![Chat][tg-badge]][tg-url] |
6 | 6 |
|
| 7 | +Revm is a highly efficient and stable implementation of the Ethereum Virtual Machine (EVM) written in Rust. |
| 8 | + |
| 9 | + |
| 10 | + |
7 | 11 | [mit-license]: https://opensource.org/license/mit/ |
8 | 12 | [gh-ci]: https://github.com/bluealloy/revm/actions/workflows/ci.yml |
9 | 13 | [tg-url]: https://t.me/+Ig4WDWOzikA3MzA0 |
10 | 14 | [tg-badge]: https://img.shields.io/badge/chat-telegram-blue |
11 | 15 |
|
12 | | -**Rust Ethereum Virtual Machine** |
13 | | - |
14 | | - |
15 | | - |
16 | | -Revm is an EVM written in Rust that is focused on **speed** and **simplicity**. |
17 | | -It has a fast and flexible implementation with a simple interface and embedded Host. |
18 | | -It passes all `ethereum/tests` test suites. |
19 | | - |
20 | | -Here is a list of guiding principles that Revm follows. |
21 | | - |
22 | | -* **EVM compatibility and stability** - this goes without saying but it is nice to put it here. In the blockchain industry, stability is the most desired attribute of any system. |
23 | | -* **Speed** - is one of the most important things and most decisions are made to complement this. |
24 | | -* **Simplicity** - simplification of internals so that it can be easily understood and extended, and interface that can be easily used or integrated into other projects. |
25 | | -* **interfacing** - `[no_std]` so that it can be used as wasm lib and integrate with JavaScript and cpp binding if needed. |
26 | | - |
27 | | -# Project |
28 | | - |
29 | | -Structure: |
30 | | - |
31 | | -* crates |
32 | | - * revm -> main EVM library. |
33 | | - * revm-primitives -> Primitive data types. |
34 | | - * revm-interpreter -> Execution loop with instructions |
35 | | - * revm-precompile -> EVM precompiles |
36 | | -* bins: |
37 | | - * revme: cli binary, used for running state test jsons |
| 16 | +Known for its robustness, it stands as one of the most popular libraries and critical component of the Ethereum ecosystem. Revm plays a crucial role across various projects, being widely utilized by almost all tooling and block builders. It is integrated into Reth, multiple Layer 2 variants and other clients and serving as a standard for zkVMs. |
38 | 17 |
|
39 | | -This project tends to use the newest rust version, so if you're encountering a build error try running `rustup update` first. |
| 18 | +Revm offers two primary applications: firstly, it functions as an executor where users can set up block info and process mainnet transactions; secondly, it acts as a framework that facilitates the extension and support of different EVM variants such as revm-optimism. |
40 | 19 |
|
41 | | -There were some big efforts on optimization of revm: |
| 20 | +### How to use: |
42 | 21 |
|
43 | | -* Optimizing interpreter loop: https://github.com/bluealloy/revm/issues/7 |
44 | | -* Introducing Bytecode format (and better bytecode analysis): https://github.com/bluealloy/revm/issues/121 |
45 | | -* Unification of instruction signatures: https://github.com/bluealloy/revm/pull/283 |
| 22 | +Here is a straightforward example of using the Execution API: It allows us to create an Ethereum Virtual Machine (EVM) and execute transactions. Additionally, it can be utilized to generate traces with the inspector or more complex example of foundry cheatcodes. |
46 | 23 |
|
47 | | -# Building from source |
| 24 | +```rust,ignore |
| 25 | +let mut evm = Context::mainnet().with_block(block).build_mainnet(); |
| 26 | +let out = evm.transact(tx); |
48 | 27 |
|
49 | | -```shell |
50 | | -git clone https://github.com/bluealloy/revm.git |
51 | | -cd revm |
52 | | -cargo build --release |
| 28 | +// or you can use powerful inspection tool to trace it |
| 29 | +let mut evm = evm.with_inspector(tracer); |
| 30 | +let out = evm.inspect_with_tx(tx); |
53 | 31 | ``` |
54 | 32 |
|
55 | | -**_Note:_** `clang` is required for building revm with `c-kzg` or `secp256k1` feature flags as they depend on `C` libraries. If you don't have it installed, you can install it with `apt install clang`. |
| 33 | +The Evm Framework API is somewhat complex to use, but this document provides a detailed explanation. It enables users to extend logic, incorporate various context types, and offers built-in support for inspection. For a practical example, you can refer to the revm-optimism crate. |
56 | 34 |
|
57 | | -# Running eth tests |
| 35 | +### Users: |
58 | 36 |
|
59 | | -go to `cd bins/revme/` |
| 37 | +As previously noted, there are several groups of projects that utilize this technology: |
60 | 38 |
|
61 | | -Download eth tests from (this will take some time): `git clone https://github.com/ethereum/tests` |
| 39 | +* **Major block builders**. |
| 40 | +* **Clients**: [Reth](https://github.com/paradigmxyz/reth), [Helios](https://github.com/a16z/helios), [Trin](https://github.com/ethereum/trin),.. |
| 41 | +* **Tooling**: [Foundry](https://github.com/foundry-rs/foundry/), [Hardhat](https://github.com/NomicFoundation/hardhat),.. |
| 42 | +* **L2s**: [Optimism](https://github.com/bluealloy/revm/tree/main/crates/optimism), [Coinbase](https://www.base.org/), [Scroll](https://github.com/scroll-tech/revm),.. |
| 43 | +* **zkVM**: [Risc0](https://github.com/risc0/risc0-ethereum), [Succinct](https://github.com/succinctlabs/sp1-reth),.. |
62 | 44 |
|
63 | | -run tests with command: `cargo run --release -- statetest tests/GeneralStateTests/ tests/LegacyTests/Constantinople/GeneralStateTests` |
| 45 | +The full list of projects that use Revm is available in the awesome-revm section of the book. |
64 | 46 |
|
65 | | -`GeneralStateTests` contains all tests related to EVM. |
| 47 | +### How to, dev section |
66 | 48 |
|
67 | | -## Running benchmarks |
68 | | - |
69 | | -Benches can be found in [`crates/revm/benches`](./crates/revm/benches). |
70 | | - |
71 | | -Currently, available benches include the following. |
72 | | -- *analysis* |
73 | | -- *snailtracer* |
74 | | -- *transfer* |
75 | | - |
76 | | -To run the `snailtracer` bench, execute the `cargo bench` subcommand below. |
77 | | - |
78 | | -```shell |
79 | | -cargo bench --package revm --profile release -- snailtracer |
80 | | -``` |
81 | | - |
82 | | -Using [flamegraph][flamegraph], you can create a visualization breaking down the runtime of various |
83 | | -sections of the bench execution - a flame graph. Executing the `cargo flamegraph` subcommand requires |
84 | | -installing [flamegraph][flamegraph] by running `cargo install flamegraph`. |
85 | | - |
86 | | -```shell |
87 | | -cargo flamegraph --root --freq 4000 --min-width 0.001 --package revm --bench bench -- snailtracer |
88 | | -``` |
| 49 | +Note that book and code docs are still in WIP stage and they are being updated! |
89 | 50 |
|
90 | | -This command will produce a flamegraph image output to `flamegraph.svg`. |
91 | | -Flamegraph also requires sudo mode to run (hence the `--root` cli arg) and will prompt you for your password if not in sudo mode already. |
| 51 | +Part of the links point to the code documentation or the book. code docs are there to explain usage of particular part of the code where book is to get more of the overview on architecture or how components/projects fit toggether. |
92 | 52 |
|
93 | | -[flamegraph]: https://docs.rs/crate/flamegraph/0.1.6 |
| 53 | +* How to build and use revm can be found here. (code) |
| 54 | +* Architecture overview can be seen here. (book) |
| 55 | +* Structure of the project (list of crates) can be seen here. (book) |
| 56 | +* How to use Revm Framework can be found here. (book) |
| 57 | +* Release procedure and changelogs explanation. (book) |
| 58 | +* How to use revme (Revm binary with few commands) can be found here. (code) |
| 59 | +* How to run Ethereum test can be found here: (book) |
| 60 | +* How to run examples and benchmark with `samply` to check performance. (book) |
| 61 | +* If there is more explanations please open PR request for it. |
94 | 62 |
|
95 | | -## Running Examples |
| 63 | +### Community: |
| 64 | +For questions please open an github issue or join public telegram group: [https://t.me/+Ig4WDWOzikA3MzA0](https://t.me/+Ig4WDWOzikA3MzA0) |
96 | 65 |
|
97 | | -```shell |
98 | | -# Run database reference example |
99 | | -cargo run -p example-database-ref |
100 | | - |
101 | | -# Run contract deployment example |
102 | | -cargo run -p example-contract-deployment |
103 | | - |
104 | | -# Query Uniswap V2 pool reserves |
105 | | -cargo run -p example-uniswap-get-reserves |
106 | | - |
107 | | -# Execute USDC swap on Uniswap V2 |
108 | | -cargo run -p example-uniswap-v2-usdc-swap |
109 | | - |
110 | | -# Generate block traces |
111 | | -cargo run -p example-block-traces |
112 | | - |
113 | | -# Run database reference example |
114 | | -cargo run -p example-database-ref |
115 | | -``` |
116 | | - |
117 | | -All examples can be found in the `examples/` directory. Each example demonstrates different aspects of revm: |
118 | | -- `block_traces`: Generating execution traces for entire blocks |
119 | | -- `contract_deployment`: Deploying and interacting with smart contracts |
120 | | -- `database_ref`: Using database references for state access |
121 | | -- `uniswap_get_reserves`: Reading state from Uniswap contracts |
122 | | -- `uniswap_v2_usdc_swap`: Executing swaps on Uniswap V2 |
123 | | - |
124 | | -# Used by: |
125 | | - |
126 | | -* [Foundry](https://github.com/foundry-rs/foundry) is a blazing fast, portable and modular toolkit for Ethereum application development written in Rust. |
127 | | -* [Helios](https://github.com/a16z/helios) is a fully trustless, efficient, and portable Ethereum light client written in Rust. |
128 | | -* [Reth](https://github.com/paradigmxyz/reth) Modular, contributor-friendly and blazing-fast implementation of the Ethereum protocol |
129 | | -* [Arbiter](https://github.com/primitivefinance/arbiter) is a framework for stateful Ethereum smart-contract simulation |
130 | | -* [Zeth](https://github.com/risc0/zeth) is an open-source ZK block prover for Ethereum built on the RISC Zero zkVM. |
131 | | -* [VERBS](https://github.com/simtopia/verbs) an open-source Ethereum agent-based modelling and simulation library with a Python API. |
132 | | -* [Hardhat](https://github.com/NomicFoundation/hardhat) is a development environment to compile, deploy, test, and debug your Ethereum software. |
133 | | -* [Trin](https://github.com/ethereum/trin) is Portal Network client. An execution and consensus layer Ethereum light client written in Rust. Portal Network client's provide complete, provable, and distributed execution archival access. |
134 | | -* [Simular](https://github.com/simular-fi/simular/) is a Python smart-contract API with a fast, embedded, Ethereum Virtual Machine. |
135 | | -* [rbuilder](https://github.com/flashbots/rbuilder) is a state of the art Ethereum MEV-Boost block builder written in Rust and designed to work with Reth. |
136 | | -* [Tycho-simulation](https://github.com/propeller-heads/tycho-simulation) is a local simulation toolkit that lets you simulate any DEX pool in a revm environment without worrying about protocol internals. |
137 | | -* ... |
138 | | - |
139 | | -(If you want to add project to the list, ping me or open the PR) |
140 | | - |
141 | | -# Documentation |
142 | | - |
143 | | -The book can be found at github page here: https://bluealloy.github.io/revm/ |
144 | | - |
145 | | -The documentation (alas needs some love) can be found here: https://bluealloy.github.io/revm/docs/ |
146 | | - |
147 | | -To serve the mdbook documentation in a local environment, ensure you have mdbook installed (if not install it with cargo) and then run: |
148 | | - |
149 | | -```shell |
150 | | -mdbook serve documentation |
151 | | -``` |
| 66 | +### Licence |
| 67 | +Revm is licensed under MIT Licence. |
152 | 68 |
|
153 | | -# Contact |
| 69 | +Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in these crates by you, shall be licensed as above, without any additional terms or conditions. |
154 | 70 |
|
155 | | -There is public telegram group: https://t.me/+Ig4WDWOzikA3MzA0 |
| 71 | +### Security |
156 | 72 |
|
157 | | -Or if you want to contact me directly, here is my email : [email protected] and telegram: https://t.me/draganrakita |
| 73 | +For any security questions or findings, please reach out to me directly via email at [email protected] or contact me on Keybase under the username [draganrakita](https://keybase.io/draganrakita/). |
0 commit comments