Keth is an open-source, proving backend for the Ethereum Execution Layer built with Kakarot Core EVM and Starkware'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's State Transition Function (STF).

The project uses uv to manage python dependencies and run commands. To install uv:

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

Moreover, the project uses rust to manage rust dependencies.

Everything is managed by uv, see the uv docs for the full documentation.

Apart from uv, you just need to copy the .env.example file to .env, making sure to set the CAIRO_PATH environment variable to the path to the cairo libraries. To have cairo-ls working, you need to source .env before even opening your IDE. To avoid doing this manually, you can add the following to your shell's rc file:

cd() {
    builtin cd "$@" || return

    if [ -f "$PWD/.env" ]; then
        echo "Loading environment variables from $PWD/.env"
        source "$PWD/.env"
    fi
}

This will automatically source the .env file when you cd into a directory containing it. You can also update this to load only when you enter the keth directory.

uv run pytest <optional pytest args>

Some tests require to compile solidity code, which requires forge to be installed, and foundry to be in the path, and to run forge build.

We adapted the testing framework from the Ethereum Execution Specs to be able to run on Keth. These tests are located in the cairo/tests/ef_tests directory. For now, only the State Transition tests are implemented. You can run them with:

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

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

zkpig generate

This will generate the ZK-PI for the given block and save it in the data/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 the data/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"

Any changes to the rust code requires a re-build and re-install of the python package, see the uv docs for more information.

The tl;dr is:

uv run --reinstall <command>

Forgetting the --reinstall flag will not re-build the python package and consequentially 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 python execution specs and tests.