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.

Additionally, you can set theLOG_FORMAT environment variable to control theoutput 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 blocksusing STWO.

• trace - Generate execution traces from Ethereum block data

  • Uses ZK-PI (Zero-Knowledge Prover Input) data to create block executiontraces
  • 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 aCairo 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 anApplicative 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 22615247uv run keth trace -b 22615247# Run end-to-end pipeline with verificationuv run keth e2e -b 22615247 --verify# Generate all AR Cairo PIEs for recursive provinguv 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:

1. Prover inputs (ZK-PI) for the given block, generated with Kakarot'sZK-PIG
2. 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 blockuv run keth e2e -b<BLOCK_NUMBER># Or use the legacy prove-block scriptuv run prove-block<BLOCK_NUMBER>

Runuv run keth --help for detailed command options and parameters.

For development-specific information including testing, profiling, andcontributing guidelines, seedocs/development.md.

Coming soon 🏗️.

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

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