{"id":21526889,"url":"https://github.com/lambdaclass/ethrex","last_synced_at":"2025-05-15T23:08:45.840Z","repository":{"id":242086395,"uuid":"808266543","full_name":"lambdaclass/ethrex","owner":"lambdaclass","description":"ethrex: Ethereum Rust Execution L1 and L2 client.","archived":false,"fork":false,"pushed_at":"2025-05-12T14:39:50.000Z","size":62684,"stargazers_count":352,"open_issues_count":367,"forks_count":56,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-05-12T14:39:54.421Z","etag":null,"topics":["blockchain","distributed-systems","ethereum","execution-layer","p2p","rollup","rollups","rust","zero-knowledge"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lambdaclass.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-05-30T18:00:35.000Z","updated_at":"2025-05-12T10:25:06.000Z","dependencies_parsed_at":"2024-07-22T15:32:09.955Z","dependency_job_id":"0f1a2db0-647c-4584-9cfa-0041b184a0a7","html_url":"https://github.com/lambdaclass/ethrex","commit_stats":null,"previous_names":["lambdaclass/ethereum_rust","lambdaclass/ethrex","lambdaclass/lambda_ethereum_rust"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambdaclass%2Fethrex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambdaclass%2Fethrex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambdaclass%2Fethrex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lambdaclass%2Fethrex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lambdaclass","download_url":"https://codeload.github.com/lambdaclass/ethrex/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254436949,"owners_count":22070947,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain","distributed-systems","ethereum","execution-layer","p2p","rollup","rollups","rust","zero-knowledge"],"created_at":"2024-11-24T01:47:01.515Z","updated_at":"2025-05-15T23:08:40.077Z","avatar_url":"https://github.com/lambdaclass.png","language":"Rust","readme":"# ethrex\n\nEthereum Rust Execution L1 and L2 client.\n\n[![Telegram Chat][tg-badge]][tg-url]\n[![license](https://img.shields.io/github/license/lambdaclass/ethrex)](/LICENSE)\n\n[tg-badge]: https://img.shields.io/endpoint?url=https%3A%2F%2Ftg.sumanjay.workers.dev%2Fethrex_client%2F\u0026logo=telegram\u0026label=chat\u0026color=neon\n[tg-url]: https://t.me/ethrex_client\n\n# L1 and L2 support\n\nThis client supports running in two different modes:\n\n- As a regular Ethereum execution client\n- As a ZK-Rollup, where block execution is proven and the proof sent to an L1 network for verification, thus inheriting the L1's security.\n\nWe call the first one ethrex L1 and the second one ethrex L2.\n\n## Philosophy\n\nMany long-established clients accumulate bloat over time. This often occurs due to the need to support legacy features for existing users or through attempts to implement overly ambitious software. The result is often complex, difficult-to-maintain, and error-prone systems.\n\nIn contrast, our philosophy is rooted in simplicity. We strive to write minimal code, prioritize clarity, and embrace simplicity in design. We believe this approach is the best way to build a client that is both fast and resilient. By adhering to these principles, we will be able to iterate fast and explore next-generation features early, either from the Ethereum roadmap or from innovations from the L2s.\n\nRead more about our engineering philosophy [here](https://blog.lambdaclass.com/lambdas-engineering-philosophy/)\n\n## Design Principles\n\n- Ensure effortless setup and execution across all target environments.\n- Be vertically integrated. Have the minimal amount of dependencies.\n- Be structured in a way that makes it easy to build on top of it, i.e rollups, vms, etc.\n- Have a simple type system. Avoid having generics leaking all over the codebase.\n- Have few abstractions. Do not generalize until you absolutely need it. Repeating code two or three times can be fine.\n- Prioritize code readability and maintainability over premature optimizations.\n- Avoid concurrency split all over the codebase. Concurrency adds complexity. Only use where strictly necessary.\n\n# ethrex L1\n\n## Quick Start (L1 localnet)\n\n### Prerequisites\n- [Kurtosis](https://docs.kurtosis.com/install/#ii-install-the-cli)\n- [Rust](#rust)\n- [Docker](https://docs.docker.com/engine/install/)\n```shell\nmake localnet\n```\n\nThis make target will:\n1. Build our node inside a docker image.\n2. Fetch our fork [ethereum package](https://github.com/ethpandaops/ethereum-package), a private testnet on which multiple ethereum clients can interact.\n3. Start the localnet with kurtosis.\n\nIf everything went well, you should be faced with our client's logs (ctrl-c to leave)\n\nTo stop everything, simply run:\n```shell\nmake stop-localnet\n```\n\n## Dev Setup\n### Build\n\n#### Rust\nTo build the node, you will need the rust toolchain. To do so, use `rustup` following [this link](https://www.rust-lang.org/tools/install)\n\n### Database\nCurrently, the database is `libmdbx`, it will be set up\nwhen you start the client. The location of the db's files will depend on your OS:\n- Mac: `~/Library/Application Support/ethrex`\n- Linux: `~/.config/ethrex`\n\nYou can delete the db with:\n```bash\ncargo run --bin ethrex -- removedb\n```\n### Dev Mode\nIn order to run `ethrex` without a Consensus Client and with the `InMemory` engine, to start from scratch each time we fire it up, the following make target can be used:\n\n```bash\nmake dev\n```\n\n- RPC endpoint: localhost:8545\n- Genesis file: ./test_data/genesis-l1.json\n\n### Test\n\nFor testing, we're using three kinds of tests.\n\n#### Ethereum Foundation Tests\n\nThese are the official execution spec tests, you can execute them with:\n\n```bash\nmake test\n```\n\nThis will download the test cases from the [official execution spec tests repo](https://github.com/ethereum/execution-spec-tests/) and run them with our glue code\nunder `cmd/ef_tests/tests`.\n\n#### Crate Specific Tests\n\nThe second kind are each crate's tests, you can run them like this:\n\n```bash\nmake test CRATE=\u003ccrate\u003e\n```\nFor example:\n```bash\nmake test CRATE=\"ethrex-blockchain\"\n```\n\n#### Load tests\n\nMore information in the [load test documentation](cmd/load_test/README.md).\n\n#### Hive Tests\n\nFinally, we have End-to-End tests with hive.\nHive is a system which simply sends RPC commands to our node,\nand expects a certain response. You can read more about it [here](https://github.com/ethereum/hive/blob/master/docs/overview.md).\n\n##### Prereqs\nWe need to have go installed for the first time we run hive, an easy way to do this is adding the asdf go plugin:\n\n```shell\nasdf plugin add golang https://github.com/asdf-community/asdf-golang.git\n\n# If you need to se GOROOT please follow: https://github.com/asdf-community/asdf-golang?tab=readme-ov-file#goroot\n```\n\nAnd uncommenting the golang line in the asdf `.tool-versions` file:\n```\nrust 1.82.0\ngolang 1.23.2\n```\n\n##### Running Simulations\nHive tests are categorized by \"simulations', and test instances can be filtered with a regex:\n```bash\nmake run-hive-debug SIMULATION=\u003csimulation\u003e TEST_PATTERN=\u003ctest-regex\u003e\n```\nThis is an example of a Hive simulation called `ethereum/rpc-compat`, which will specificaly\nrun chain id and transaction by hash rpc tests:\n```bash\nmake run-hive SIMULATION=ethereum/rpc-compat TEST_PATTERN=\"/eth_chainId|eth_getTransactionByHash\"\n```\nIf you want debug output from hive, use the run-hive-debug instead:\n```bash\nmake run-hive-debug SIMULATION=ethereum/rpc-compat TEST_PATTERN=\"*\"\n```\nThis example runs **every** test under rpc, with debug output\n\n##### Assertoor\n\nWe run some assertoot checks on our CI, to execute them locally you can run the following:\n```bash\nmake localnet-assertoor-tx\n# or\nmake localnet-assertoor-blob\n```\n\nThose are two different set of assertoor checks the details are as follows:\n\n*assertoor-tx*\n- [eoa-transaction-test](https://raw.githubusercontent.com/ethpandaops/assertoor/refs/heads/master/playbooks/stable/eoa-transactions-test.yaml)\n\n*assertoor-blob*\n- [blob-transaction-test](https://raw.githubusercontent.com/ethpandaops/assertoor/refs/heads/master/playbooks/stable/blob-transactions-test.yaml)\n- _Custom_ [el-stability-check](https://raw.githubusercontent.com/lambdaclass/ethrex/refs/heads/main/.github/config/assertoor/el-stability-check.yaml)\n\nFor reference on each individual check see the [assertoor-wiki](https://github.com/ethpandaops/assertoor/wiki#supported-tasks-in-assertoor)\n\n### Run\n\nExample run:\n```bash\ncargo run --bin ethrex -- --network test_data/genesis-kurtosis.json\n```\n\nThe `network` argument is mandatory, as it defines the parameters of the chain.\nFor more information about the different cli arguments check out the next section.\n\n### CLI Commands\n\n\u003c!-- BEGIN_CLI_HELP --\u003e\n```\nethrex Execution client\n\nUsage: ethrex [OPTIONS] [COMMAND]\n\nCommands:\n  removedb  Remove the database\n  import    Import blocks to the database\n  help      Print this message or the help of the given subcommand(s)\n\nOptions:\n  -h, --help\n          Print help (see a summary with '-h')\n\n  -V, --version\n          Print version\n\nNode options:\n      --network \u003cGENESIS_FILE_PATH\u003e\n          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.\n\n      --datadir \u003cDATABASE_DIRECTORY\u003e\n          If the datadir is the word `memory`, ethrex will use the `InMemory Engine`.\n\n          [default: ethrex]\n\n      --force\n          Delete the database without confirmation.\n\n      --metrics.addr \u003cADDRESS\u003e\n          [default: 0.0.0.0]\n\n      --metrics.port \u003cPROMETHEUS_METRICS_PORT\u003e\n          [default: 9090]\n\n      --dev\n          If set it will be considered as `true`. The Binary has to be built with the `dev` feature enabled.\n\n      --evm \u003cEVM_BACKEND\u003e\n          Has to be `levm` or `revm`\n\n          [default: revm]\n\n      --log.level \u003cLOG_LEVEL\u003e\n          Possible values: info, debug, trace, warn, error\n\n          [default: INFO]\n\nP2P options:\n      --bootnodes \u003cBOOTNODE_LIST\u003e...\n          Comma separated enode URLs for P2P discovery bootstrap.\n\n      --syncmode \u003cSYNC_MODE\u003e\n          Can be either \"full\" or \"snap\" with \"full\" as default value.\n\n          [default: full]\n\n      --p2p.enabled\n\n\n      --p2p.addr \u003cADDRESS\u003e\n          [default: 0.0.0.0]\n\n      --p2p.port \u003cPORT\u003e\n          [default: 30303]\n\n      --discovery.addr \u003cADDRESS\u003e\n          UDP address for P2P discovery.\n\n          [default: 0.0.0.0]\n\n      --discovery.port \u003cPORT\u003e\n          UDP port for P2P discovery.\n\n          [default: 30303]\n\nRPC options:\n      --http.addr \u003cADDRESS\u003e\n          Listening address for the http rpc server.\n\n          [default: localhost]\n\n      --http.port \u003cPORT\u003e\n          Listening port for the http rpc server.\n\n          [default: 8545]\n\n      --authrpc.addr \u003cADDRESS\u003e\n          Listening address for the authenticated rpc server.\n\n          [default: localhost]\n\n      --authrpc.port \u003cPORT\u003e\n          Listening port for the authenticated rpc server.\n\n          [default: 8551]\n\n      --authrpc.jwtsecret \u003cJWTSECRET_PATH\u003e\n          Receives the jwt secret used for authenticated rpc requests.\n\n          [default: jwt.hex]\n```\n\u003c!-- END_CLI_HELP --\u003e\n\n# ethrex L2\n\nIn this mode, the ethrex code is repurposed to run a rollup that settles on Ethereum as the L1.\n\nThe main differences between this mode and regular ethrex are:\n\n- There is no consensus, the node is turned into a sequencer that proposes blocks for the network.\n- Block execution is proven using a RISC-V zkVM and its proofs are sent to L1 for verification.\n- A set of Solidity contracts to be deployed to the L1 are included as part of network initialization.\n- Two new types of transactions are included: deposits (native token mints) and withdrawals.\n\nAt a high level, the following new parts are added to the node:\n\n- A `proposer` component, in charge of continually creating new blocks from the mempool transactions. This replaces the regular flow that an Ethereum L1 node has, where new blocks come from the consensus layer through the `forkChoiceUpdate` -\u003e `getPayload` -\u003e `NewPayload` Engine API flow in communication with the consensus layer.\n- A `prover` subsystem, which itself consists of two parts:\n  - A `proverClient` that takes new blocks from the node, proves them, then sends the proof back to the node to send to the L1. This is a separate binary running outside the node, as proving has very different (and higher) hardware requirements than the sequencer.\n  - A `proverServer` component inside the node that communicates with the prover, sending witness data for proving and receiving proofs for settlement on L1.\n- L1 contracts with functions to commit to new state and then verify the state transition function, only advancing the state of the L2 if the proof verifies. It also has functionality to process deposits and withdrawals to/from the L2.\n- The EVM is lightly modified with new features to process deposits and withdrawals accordingly.\n\n## Prerequisites\n\n- [Rust (explained in L1 requirements section above)](#build)\n- [Docker](https://docs.docker.com/engine/install/) (with [Docker Compose](https://docs.docker.com/compose/install/))\n- [The Solidity Compiler](https://docs.soliditylang.org/en/latest/installing-solidity.html) (solc)\n\n## How to run\n\n### Initialize the network\n\n\u003e [!IMPORTANT]\n\u003e Before this step:\n\u003e\n\u003e 1. Make sure you are inside the `crates/l2` directory.\n\u003e 2. Make sure the Docker daemon is running.\n\u003e 3. Make sure you have created a `sequencer_config.toml` file following the `sequencer_config_example.toml` file.\n\n```\nmake init\n```\n\nThis will setup a local Ethereum network as the L1, deploy all the needed contracts on it, then start an ethrex L2 node pointing to it.\n\n### Restarting the network\n\n\u003e [!WARNING]\n\u003e This command will cleanup your running L1 and L2 nodes.\n\n```\nmake restart\n```\n\n## Local L1 Rich Wallets\n\nMost of them are [here](https://github.com/ethpandaops/ethereum-package/blob/main/src/prelaunch_data_generator/genesis_constants/genesis_constants.star), but there's an extra one:\n\n```\n{\n    \"address\": \"0x3d1e15a1a55578f7c920884a9943b3b35d0d885b\",\n    \"private_key\": \"0x385c546456b6a603a1cfcaa9ec9494ba4832da08dd6bcf4de9a71e4a01b74924\"\n}\n```\n\n## ethrex L2 Docs\n\n- [ethrex L2 Docs](./crates/l2/docs/README.md)\n- [ethrex L2 CLI Docs](./cmd/ethrex_l2/README.md)\n\n\n## 📚 References and acknowledgements\n\nThe following links, repos, companies and projects have been important in the development of this repo, we have learned a lot from them and want to thank and acknowledge them.\n\n- [Ethereum](https://ethereum.org/en/)\n- [ZKsync](https://zksync.io/)\n- [Starkware](https://starkware.co/)\n- [Polygon](https://polygon.technology/)\n- [Optimism](https://www.optimism.io/)\n- [Arbitrum](https://arbitrum.io/)\n- [Geth](https://github.com/ethereum/go-ethereum)\n- [Taiko](https://taiko.xyz/)\n- [RISC Zero](https://risczero.com/)\n- [SP1](https://github.com/succinctlabs/sp1)\n- [Aleo](https://aleo.org/)\n- [Neptune](https://neptune.cash/)\n- [Mina](https://minaprotocol.com/)\n- [Nethermind](https://www.nethermind.io/)\n- [Commonware](https://commonware.xyz/)\n\nIf we forgot to include anyone, please file an issue so we can add you. We always strive to reference the inspirations and code we use, but as an organization with multiple people, mistakes can happen, and someone might forget to include a reference.\n\n# Security\n\nWe take security seriously. If you discover a vulnerability in this project, please report it responsibly.\n\n- You can report vulnerabilities directly via the **[GitHub \"Report a Vulnerability\" feature](../../security/advisories/new)**.\n- Alternatively, send an email to **[security@lambdaclass.com](mailto:security@lambdaclass.com)**.\n\nFor more details, please refer to our [Security Policy](./.github/SECURITY.md).\n","funding_links":[],"categories":["Blockchains","Execution","Rust"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flambdaclass%2Fethrex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flambdaclass%2Fethrex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flambdaclass%2Fethrex/lists"}