Repository files navigation

Keth is an open-source, proving backend for the Ethereum Execution Layer builtwithKakarot Core EVM andStarkware's provable VM, Cairo.

Keth makes it possible to prove a given state transition asynchronously by:

• pulling pre-state,
• executing all required transactions,
• computing post-state

For instance, this can be run for a given block to prove the Ethereum protocol'sState Transition Function (STF).

The project usesuv to manage pythondependencies and run commands. To install uv:

curl -LsSf https://astral.sh/uv/install.sh| sh

Moreover, the project usesrust to manage rustdependencies.

Everything is managed by uv, seethe uv docs forthe full documentation.

Apart fromuv, you just need to copy the.env.example file to.env, makingsure to set theCAIRO_PATH environment variable to the path to the cairolibraries. To have cairo-ls working, you need tosource .env before evenopening your IDE. To avoid doing this manually, you can add the following toyour shell's rc file:

cd() {builtincd"$@"||returnif [-f"$PWD/.env" ];thenecho"Loading environment variables from$PWD/.env"source"$PWD/.env"fi}

This will automatically source the.env file when youcd into a directorycontaining it. You can also update this to load only when you enter the kethdirectory.

uv run pytest<optional pytest args>

Some tests require to compile solidity code, which requiresforge to beinstalled, andfoundry to be in the path, and to runforge build.

We adapted the testing framework from theEthereum Execution Specs to beable to run on Keth. These tests are located in thecairo/tests/ef_testsdirectory. For now, only the State Transition tests are implemented. You can runthem with:

uv run pytest cairo/tests/ef_tests/cancun/test_state_transition.py

To run thestate_transition function against a given Ethereum Mainnet block,you'll need first to generate the Prover Input (ZK-PI) for this block usingZK-PIG:

zkpig generate

This will generate the ZK-PI for the given block and save it in thedata/1/directory. Then, you'll need to run

uv run zkpi_to_eels data/1/preflight/

to convert the ZK-PI to the EELS format, actually generating data in thedata/1/eels directory.

Then, you can run the tests with:

uv run pytest cairo/tests/ethereum/cancun/test_fork.py -k"test_state_transition_eth_mainnet"

To generate a proof for an Ethereum block, use theprove_block.py script:

uv run prove-block<BLOCK_NUMBER>

usage: prove-block [-h] [--output-dir OUTPUT_DIR] [--data-dir DATA_DIR] [--compiled-program COMPILED_PROGRAM]                   block_number

Requirements:

• Block must be post-Cancun fork (block number ≥ 19426587)
• ZKPI data must be available as a JSON file
• Compiled Cairo program must exist at the specified path (you can runcairo-compile --proof_mode cairo/ethereum/cancun/main.cairo --cairo_path=cairo --no_debug_info --output build/main_compiled.jsonfor that)

The script will load the ZKPI data for the specified block, convert it to theformat required by Keth, run the proof generation process, and save proofartifacts to the output directory.

Any changes to the rust code requires a re-build and re-install of the pythonpackage, seethe uv docsfor more information.

The tl;dr is:

uv run --reinstall<command>

Forgetting the--reinstall flag will not re-build the python package andconsequentially not use any changes to the rust code.

Keth is a work in progress (WIP⚠️) and as such is not suitable for production.

Coming soon 🏗️.

• Ethereum Foundation: We are grateful to the Ethereum Foundation for the pythonexecution specs and tests.