How herodotusdev/hdp-cairo works
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.