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.
Additionally, you can set the LOG_FORMAT
environment variable to control the
output format of logs from the Rust components. Supported values are:
plain
(default): Human-readable, colored log output.json
: Structured JSON logging, useful to be stored.
Keth provides two main CLI tools for different use cases.
First, you'll need to compile the Cairo programs.
uv run compile_keth
The main Keth CLI for generating execution traces and proofs for Ethereum blocks using STWO.
-
trace
- Generate execution traces from Ethereum block data- Uses ZK-PI (Zero-Knowledge Prover Input) data to create block execution traces
- Supports different execution steps:
main
(run everything sequentially),init
,body
,teardown
,aggregator
. - Can output traces as prover inputs JSON, binary files, or Cairo PIE files
-
prove
- Generate STWO proofs from prover input files- Takes prover input information and generates cryptographic proofs
- Supports Cairo-compatible serialization format to verify the proof in a Cairo program
-
verify
- Verify generated proofs- Validates proof correctness using the Rust STWO verifier
-
e2e
- End-to-end pipeline (trace + prove + verify)- Runs the complete workflow without intermediate file I/O
- Optionally includes proof verification
- Has high RAM requirements, and is not recommended for regular sized blocks
-
generate-ar-inputs
- Generate all prover inputs / Cairo PIEs for an Applicative Recursion run.- Creates all necessary traces for recursive proving
- Automatically chunks body transactions for efficient processing
- Outputs a Cairo PIE file for each step.
# Generate a trace for block 22615247
uv run keth trace -b 22615247
# Run end-to-end pipeline with verification
uv run keth e2e -b 22615247 --verify
# Generate all AR Cairo PIEs for recursive proving
uv run keth generate-ar-inputs -b 22615247 --cairo-pie
A tool for running and proving arbitrary Cairo programs.
run-and-prove
- Execute Cairo programs and generate proofs- Runs compiled Cairo programs with specified entrypoints and arguments
- Generates execution traces and STWO proofs
- Optionally verifies the generated proof
uv run prove-cairo --compiled-program cairo/tests/programs/fibonacci.json --arguments 1,1,20000
To generate a proof for an Ethereum block, you'll need:
- Prover inputs (ZK-PI) for the given block, generated with Kakarot's ZK-PIG
- The compiled Keth program (
uv run compile_keth
)
- Block must be of Prague fork
- ZKPI data must be available as a JSON file
- Compiled Cairo program must exist at the specified path
# Generate proof for a specific block
uv run keth e2e -b <BLOCK_NUMBER>
# Or use the legacy prove-block script
uv run prove-block <BLOCK_NUMBER>
Run uv run keth --help
for detailed command options and parameters.
For development-specific information including testing, profiling, and contributing guidelines, see docs/development.md.
Coming soon 🏗️.
- Ethereum Foundation: We are grateful to the Ethereum Foundation for the python execution specs and tests.
Keth is a work in progress (WIP