# kkrt-labs/keth architecture

> Architecture diagram of the GitHub repository kkrt-labs/keth, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kkrt-labs/keth
- Repository: https://github.com/kkrt-labs/keth

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Input Layer
    subgraph "Data Input Layer"
        pre["Pre-State Manager"]:::rust
    end

    %% Processing Core
    subgraph "Processing Core"
        tx["Transaction Executor"]:::core
        prover["Post-State Calculator/Prover Module"]:::core
    end

    %% Coordination/Orchestration
    subgraph "Coordination/Orchestration"
        py["Python Orchestration Layer"]:::python
    end

    %% External Dependencies
    subgraph "External Dependencies"
        ext1["Kakarot Core EVM"]:::external
        ext2["Starkware's Cairo"]:::external
        ext3["SHARP SDK"]:::external
    end

    %% CI/CD & Testing
    subgraph "CI/CD & Testing"
        ci1["CI Pipelines"]:::ci
        ci2["Solidity Integration Tests"]:::ci
    end

    %% Relationships
    pre -->|"provides_pre-state"| tx
    tx -->|"processes_transactions"| prover
    py -->|"orchestrates"| pre
    py -->|"orchestrates"| tx
    py -->|"orchestrates"| prover
    ext1 -.-> tx
    ext2 -.-> prover
    ext3 -.-> prover
    ci1 -.-> py
    ci2 -.-> py

    %% Click Events
    click pre "https://github.com/kkrt-labs/keth/blob/main/crates/atlantic/src/endpoints.rs"
    click tx "https://github.com/kkrt-labs/keth/blob/main/cairo/ethereum/cancun/transactions.cairo"
    click prover "https://github.com/kkrt-labs/keth/blob/main/crates/atlantic/src/prover.rs"
    click py "https://github.com/kkrt-labs/keth/tree/main/python/cairo-addons/src/cairo_addons"
    click ci1 "https://github.com/kkrt-labs/keth/tree/main/.github/workflows"
    click ci2 "https://github.com/kkrt-labs/keth/tree/main/solidity_contracts"

    %% Styles
    classDef rust fill:#f9c,stroke:#333,stroke-width:2px;
    classDef core fill:#cce,stroke:#333,stroke-width:2px;
    classDef python fill:#cfc,stroke:#333,stroke-width:2px;
    classDef external fill:#ffc,stroke:#333,stroke-width:2px;
    classDef ci fill:#fcc,stroke:#333,stroke-width:2px;

    class pre rust;
    class tx,prover core;
    class py python;
    class ext1,ext2,ext3 external;
    class ci1,ci2 ci;
```
