# chainwayxyz/citrea architecture

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

- Interactive diagram: https://gitdiagram.com/chainwayxyz/citrea
- Repository: https://github.com/chainwayxyz/citrea

## Overview

##### Project type and purpose
- Citrea is a blockchain rollup system (“the first rollup that enhances Bitcoin blockspace with ZK”) built in Rust on a forked Sovereign‑SDK.
- It integrates with Bitcoin as its L1, provides an EVM‑compatible L2 execution shard, and uses zero‑knowledge proofs (via Risc0/SP1 circuits) plus optimistic verification (BitVM) on Bitcoin.

##### File structure
- Top‑level binaries (bin/citrea, bin/cli) act as entrypoints for the rollup node and its CLI.
- The crates/ directory contains standalone services & libraries:
– bitcoin-da: Data availability provider for Bitcoin blocks & headers
– sequencer: L2 block builder, commitment generator, mempool
– fullnode: L2 state sync, server RPC, metrics
– batch‑prover & light-client-prover: off‑chain ZK proof generators
– l2-block-rule-enforcer & soft-confirmation-rule-enforcer: enforce protocol rules
– citrea-stf + evm: state transition function & EVM execution engine
– common: shared RPC/server utilities, config, caching
– sovereign-sdk & rollup-interface/module‑system: core SDK abstractions & plugin framework
- guests/: Risc0 and SP1 guest circuits for ZK proof execution
- resources/: configuration, genesis, Docker, test data, dashboards
- docs/, Dockerfiles, CI workflows, Makefiles, and GitHub actions for build/test/deploy

##### README for architecture hints
- Citrea uses BTC as its native asset, no separate token.
- It leverages zero‑knowledge proofs for each transaction, optimistically verified on Bitcoin.
- Key components (sequencer, full node, prover services) are referenced in docs but not yet diagrammed.

##### Be detailed but concise
- Essential services and their interconnections.
- Avoid over‑splitting: group related crates under the same service.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    subgraph "External"
        BitcoinL1["Bitcoin L1 Network"]:::external
        ExtClients["External Clients (Web3 Wallets, Explorers)"]:::client
    end

    %% Core Services
    subgraph "Core Services"
        DAProvider["DA Provider Service"]:::service
        Sequencer["Sequencer Service"]:::service
        FullNode["Full Node Service"]:::service
        RuleEnforcer1["L2 Block Rule Enforcer"]:::service
        RuleEnforcer2["Soft Confirmation Rule Enforcer"]:::service
    end

    %% Prover Services
    subgraph "Prover Services"
        BatchProver["Batch Prover Service"]:::prover
        LightProver["Light Client Prover Service"]:::prover
        subgraph "Batch Prover Circuits"
            BPGuest["Risc0/SP1 Batch-Proof Circuit"]:::compute
        end
        subgraph "Light Client Circuits"
            LCGuest["Risc0/SP1 Light-Client-Proof Circuit"]:::compute
        end
    end

    %% Execution Engines
    subgraph "Execution Layer"
        STF["State Transition Function (STF)"]:::engine
        EVM["EVM Execution Engine"]:::engine
    end

    %% Storage & DB
    subgraph "Storage Layer"
        Storage["Sovereign‑SDK DB (RocksDB)"]:::storage
    end

    %% API & CLI
    subgraph "API & CLI"
        RPCUtil["JSON-RPC Utilities"]:::api
        SeqRPC["Sequencer RPC Server"]:::api
        NodeRPC["Full Node RPC Server"]:::api
        CLI["CLI Client"]:::client
        NodeBin["Rollup Node Binary"]:::client
    end

    %% Interconnections
    BitcoinL1 -->|"L1 blocks"| DAProvider
    DAProvider -->|"sync"| Sequencer
    DAProvider -->|"sync"| FullNode

    Sequencer -->|"writes L2 blocks"| Storage
    FullNode -->|"state snapshots & queries"| Storage

    Sequencer -->|"RPC Requests"| SeqRPC
    FullNode -->|"RPC Requests"| NodeRPC
    RPCUtil --> SeqRPC
    RPCUtil --> NodeRPC

    SeqRPC -->|"JSON-RPC"| CLI
    NodeRPC -->|"JSON-RPC"| CLI
    SeqRPC -->|"JSON-RPC"| ExtClients
    NodeRPC -->|"JSON-RPC"| ExtClients

    Sequencer -->|"publish L2 commitments"| BitcoinL1

    Sequencer -->|"events"| BatchProver
    Sequencer -->|"events"| LightProver

    BatchProver --> BPGuest
    BPGuest -->|"proofs"| Sequencer

    LightProver --> LCGuest
    LCGuest -->|"proofs"| Sequencer

    Sequencer -->|"L2 channel"| RuleEnforcer1
    Sequencer -->|"L2 channel"| RuleEnforcer2

    Sequencer -->|"execute tx"| STF
    Sequencer -->|"execute tx"| EVM
    FullNode -->|"execute tx"| STF
    FullNode -->|"execute tx"| EVM

    %% Click Events
    click DAProvider "https://github.com/chainwayxyz/citrea/tree/nightly/crates/bitcoin-da"
    click Sequencer "https://github.com/chainwayxyz/citrea/tree/nightly/crates/sequencer"
    click FullNode "https://github.com/chainwayxyz/citrea/tree/nightly/crates/fullnode"
    click BatchProver "https://github.com/chainwayxyz/citrea/tree/nightly/crates/batch-prover"
    click BPGuest "https://github.com/chainwayxyz/citrea/tree/nightly/guests/risc0/batch-proof"
    click LightProver "https://github.com/chainwayxyz/citrea/tree/nightly/crates/light-client-prover"
    click LCGuest "https://github.com/chainwayxyz/citrea/tree/nightly/guests/risc0/light-client-proof"
    click RuleEnforcer1 "https://github.com/chainwayxyz/citrea/tree/nightly/crates/l2-block-rule-enforcer"
    click RuleEnforcer2 "https://github.com/chainwayxyz/citrea/tree/nightly/crates/soft-confirmation-rule-enforcer"
    click STF "https://github.com/chainwayxyz/citrea/tree/nightly/crates/citrea-stf"
    click EVM "https://github.com/chainwayxyz/citrea/tree/nightly/crates/evm"
    click Storage "https://github.com/chainwayxyz/citrea/tree/nightly/crates/sovereign-sdk/full-node/db/sov-db"
    click Storage "https://github.com/chainwayxyz/citrea/tree/nightly/crates/sovereign-sdk/full-node/db/sov-schema-db"
    click RPCUtil "https://github.com/chainwayxyz/citrea/tree/nightly/crates/common/src/rpc"
    click SeqRPC "https://github.com/chainwayxyz/citrea/blob/nightly/crates/sequencer/src/rpc.rs"
    click NodeRPC "https://github.com/chainwayxyz/citrea/blob/nightly/crates/fullnode/src/rpc.rs"
    click CLI "https://github.com/chainwayxyz/citrea/tree/nightly/bin/cli"
    click NodeBin "https://github.com/chainwayxyz/citrea/tree/nightly/bin/citrea"

    %% Styles
    classDef external fill:#FFD700,stroke:#333,stroke-width:1px
    classDef service fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef prover fill:#FFA07A,stroke:#333,stroke-width:1px
    classDef compute fill:#FFB6C1,stroke:#333,stroke-width:1px
    classDef engine fill:#98FB98,stroke:#333,stroke-width:1px
    classDef storage fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef api fill:#BA55D3,stroke:#333,stroke-width:1px
    classDef client fill:#F0E68C,stroke:#333,stroke-width:1px
```
