# herodotusdev/hdp-cairo architecture

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

- Interactive diagram: https://gitdiagram.com/herodotusdev/hdp-cairo
- Repository: https://github.com/herodotusdev/hdp-cairo

## Overview

##### Project Type & Purpose
- The README and file structure indicate a full-stack tool that integrates blockchain data ingestion (via RPC calls), computational processing in Cairo (including modules for dry-run simulation and sound execution), and output generation for zero-knowledge proofs.
- It also exposes a CLI (installed either via a script or built from source) to drive its operations. The numerous “crates” also confirm it was developed in Rust and organized into multiple interdependent modules.

##### Main Architectural Components
a. CLI Interface:
– Represented by the “crates/cli” which serves as the primary user interface, receiving commands to execute different operations (dry-run, sound-run, fetch-proofs).
b. Core Processing Modules:
– Dry-run Modules: Found in “crates/dry_run” and “crates/dry_hint_processor” (and their “sound_” counterparts) that simulate the execution of Cairo1 modules. They validate contract logic and generate intermediate traces.
– Hint Processing & Decoding: The “crates/hints” directory (with its decoders, verifiers, and utility modules) is used for translating on-chain data, processing hints, and verifying computations.
– Syscall Handler: The “crates/syscall_handler” abstracts external calls into a common processing interface, supporting different blockchain paradigms (EVM, Starknet).
– Data Types & Proof Structures: The “crates/types” package captures the underlying data models (accounts, transactions, proofs, keys) and facilitates interoperability.
– Indexer: “crates/indexer” and additional proof key modules help to aggregate and index blockchain data for further processing.
c. Contract Bootloader & Decoders:
– In the “src/contract_bootloader” and “src/decoders” directories, there are Cairo modules to bootstrap on-chain contracts and decode input data, which integrate closely with the execution engine.
d. External Data Sources:
– The system fetches on-chain data through RPC nodes (as mentioned in the README’s “fetch-proofs” command). Illustrate these RPC endpoints or blockchain nodes as external interfaces.
e. Utility & Testing Infrastructure:
– Several utilities (e.g., “src/utils”, “src/memorizers”, “src/verifiers”) support both data conversion and state validation.
– The “tests” directory provides integration and module tests that simulate actual on-chain conditions.
f. Infrastructure & Deployment:

##### Component Relationships & Data Flow
1. Execution modules (dry-run/sound-run) that perform simulation or actual computation.
2. Data fetchers that retrieve on-chain proof and RPC data.
3. Hint processors and decoders that transform raw blockchain data into processed execution traces.
4. The proof generation layer that uses the processed outputs and integrates with validity check modules, culminating in a zero-knowledge proof.

##### Architectural Patterns & Technologies
– Emphasize modularity: The code is split into multiple well-defined crates, each encapsulating a specific functionality (e.g., syscall handling, hint processing).
– Highlight layered design: Frontend (CLI) → Core Engine (simulation and processing modules) → Data Interfaces (RPC fetchers, decoders) → Proof Generation.
– Note key technologies: Rust’s Cargo workspace organization, Cairo1 for user-defined logic, Scarb as a build tool, and Docker/GitHub workflows for deployment and CI/CD.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interface Layer"
        CLI["CLI (User Interface for Commands)"]:::ui
    end

    subgraph "Core Processing Engine"
        subgraph "Module Execution"
            DrySim["Dry-run Simulation (Validation)"]:::core
            DryHint["Dry Hint Processor"]:::core
            SoundExec["Sound-run Execution (Live Execution)"]:::core
            SoundHint["Sound Hint Processor"]:::core
        end
        subgraph "Hint Processing & Decoding"
            Hints["Hint Processor & Decoders"]:::core
        end
        Syscall["Syscall Handler"]:::core
    end

    subgraph "Data & Proof Layer"
        Types["Data Models & Proof Structures"]:::data
        Indexer["Indexer (Blockchain Data Aggregator)"]:::data
        ContractBoot["Contract Bootloader & Decoders"]:::data
    end

    subgraph "External Interfaces"
        RPC["RPC/Blockchain Node"]:::external
        Fetcher["RPC Fetcher"]:::external
    end

    subgraph "Utility & Infrastructure"
        Utilities["Utilities & Tools"]:::infra
        Testing["Integration & Module Testing"]:::infra
        Deployment["CI/CD & Deployment (Docker, Workflows)"]:::infra
    end

    CLI -->|"executes"| DrySim
    CLI -->|"executes"| SoundExec

    DrySim -->|"triggers"| DryHint
    SoundExec -->|"triggers"| SoundHint

    DrySim -->|"calls"| Syscall
    SoundExec -->|"calls"| Syscall

    DryHint -->|"processes"| Hints
    SoundHint -->|"processes"| Hints

    RPC -->|"suppliesData"| Fetcher
    Fetcher -->|"feeds"| Hints

    Hints -->|"generatesOutput"| Types
    Types -->|"aggregatedBy"| Indexer
    Indexer -->|"feeds"| ContractBoot

    Utilities ---|"supports"| Hints
    Testing ---|"verifies"| Types
    Deployment ---|"orchestrates"| CLI

    click CLI "https://github.com/herodotusdev/hdp-cairo/blob/main/crates/cli/src/main.rs"
    click DrySim "https://github.com/herodotusdev/hdp-cairo/blob/main/crates/dry_run/src/main.rs"
    click DryHint "https://github.com/herodotusdev/hdp-cairo/blob/main/crates/dry_hint_processor/src/lib.rs"
    click SoundExec "https://github.com/herodotusdev/hdp-cairo/blob/main/crates/sound_run/src/main.rs"
    click SoundHint "https://github.com/herodotusdev/hdp-cairo/blob/main/crates/sound_hint_processor/src/lib.rs"
    click Hints "https://github.com/herodotusdev/hdp-cairo/blob/main/crates/hints/src/lib.rs"
    click Hints "https://github.com/herodotusdev/hdp-cairo/tree/main/src/decoders/"
    click Syscall "https://github.com/herodotusdev/hdp-cairo/blob/main/crates/syscall_handler/src/lib.rs"
    click Types "https://github.com/herodotusdev/hdp-cairo/blob/main/crates/types/src/lib.rs"
    click Indexer "https://github.com/herodotusdev/hdp-cairo/blob/main/crates/indexer/src/lib.rs"
    click ContractBoot "https://github.com/herodotusdev/hdp-cairo/blob/main/src/contract_bootloader/contract_bootloader.cairo"
    click Fetcher "https://github.com/herodotusdev/hdp-cairo/blob/main/crates/fetcher/src/main.rs"
    click Utilities "https://github.com/herodotusdev/hdp-cairo/tree/main/src/utils/"
    click Testing "https://github.com/herodotusdev/hdp-cairo/tree/main/tests/"
    click Deployment "https://github.com/herodotusdev/hdp-cairo/tree/main/.github/workflows/"

    classDef ui fill:#f9f,stroke:#333,stroke-width:2px;
    classDef core fill:#ff9,stroke:#333,stroke-width:2px;
    classDef external fill:#9f9,stroke:#333,stroke-width:2px;
    classDef data fill:#9ff,stroke:#333,stroke-width:2px;
    classDef infra fill:#f99,stroke:#333,stroke-width:2px;
```
