How kkrt-labs/keth works
Project Type and Purpose
• Keth is a proving backend that leverages the Kakarot Core EVM and Starkware’s Cairo to prove Ethereum state transitions. It does this asynchronously—fetching a pre-state, executing transactions, and computing a post-state—for example, to prove the state transition function (STF) for a given block.
• The project is a multi-language, multi-component system that integrates Rust, Python, and Cairo code, with additional solidity contracts for testing or integration purposes.
File Structure
• Top-Level Organization:
• There are directories for Rust (Cargo.toml, crates/atlantic, crates/cairo-addons), indicating core logic written in Rust.
• Extensive Cairo code under the “cairo” directory that implements Ethereum-related functionality (e.g., state, transactions, VM execution, precompiled contracts).
• Python directories (python/cairo-addons, python/cairo-core, python/cairo-ec) indicating Python bindings or integration modules that likely serve as a wrapper around or extension to the core functionality.
• Solidity contracts (solidity_contracts/) which may be used for testing or prototyping parts of the Ethereum execution environment.
• CI/CD configurations, GitHub workflows, and testing directories spread across Rust, Python, and Cairo, indicating a strong emphasis on automated testing and integration.
• Directory Patterns:
• The separation into “crates”, “cairo”, and “python/…” strongly suggests a layered architecture where performance-critical logic is implemented in Rust and Cairo, with Python gluing things together using uv (a tool to manage dependencies and commands).
README for Additional Insights
• The README clarifies that Keth is designed as a proving backend that works by pulling a pre-state, processing transactions, and then computing the post-state proof.
• It highlights the async nature of the processing and points out the dependencies (Kakarot Core EVM and Cairo) as well as tooling (uv, rust toolchain, forge for solidity compilation).
• The project is identified as work in progress; hence, the architecture might be evolving but the core components are already visible from the file structure.
• Main Components:
• Pre-State Manager: A service or module responsible for fetching or reading the pre-state.
• Transaction Executor: The core component that applies transactions to the pre-state using the Cairo implementation of the Ethereum state transition logic. This involves both the Cairo/Ethereum execution components (under “cairo/ethereum”) as well as Rust modules (e.g., in crates/atlantic, crates/cairo-addons) that coordinate the execution.
• Post-State Calculator/Prover: Computes the post-state and generates a proof demonstrating the validity of the state transition. This is likely implemented in the Cairo code and integrated with the Rust libraries.
• Integration and Coordination Layer: Python modules that (using uv) help orchestrate runs, manage dependencies, and integrate testing, build pipelines, and deployment workflows.
• External Dependencies: External systems (like the Kakarot Core EVM, Starkware’s Cairo libraries, and SHARP SDK libraries) that are vital to the proof generation.
• Testing and Deployment: Include CI workflows (GitHub workflows, uv commands) and the solidity contracts (possibly simulating parts of the blockchain environment).
• Relationships and Interactions:
• Pre-State Manager feeds the Transaction Executor with necessary state data.
• The Transaction Executor processes transactions in an asynchronous pipeline and passes the transformed state to the Post-State Calculator.
• The Prover module encapsulates the Cairo VM executions and cryptographic operations needed for generating the proofs.
• The Python layer acts as an orchestrator that triggers Rust builds, runs tests, and ensures environment consistency (e.g., via uv commands).
• Source code from various libraries interacts; for instance, Rust crates may leverage the Cairo addons and then expose functionality to Python bindings.
• External configuration and build scripts (e.g., .env for environment setup, GitHub workflows) ensure a consistent development and CI/CD environment.
• Architectural Patterns & Design Principles:
• Layered Architecture: Separation of concerns between state fetching, transaction execution, and proof generation.
• Multi-Language Integration: Clear boundaries between performance-critical components (Rust and Cairo), orchestration (Python), and testing/integration (solidity contracts, CI scripts).
• Modular Design: Components are clearly separated into directories (crates for core libraries, cairo for VM logic, python for orchestration and bindings) which facilitates independent development and testing of each module.
• Relevant Technologies/Frameworks:
• Rust (cargo-managed) for high-performance back-end libraries.
• Cairo for implementing the Ethereum Execution Layer’s verification and state management.
• Python with uv for dependency management, testing, and integration workflows.
• Solidity for smart contract simulation/testing.
• CI/CD tools (GitHub Actions, uv, and Foundry for solidity) facilitating automated testing and builds.