# a16z/helios architecture

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

- Interactive diagram: https://gitdiagram.com/a16z/helios
- Repository: https://github.com/a16z/helios

## Overview

##### Project Type and Purpose
- Helios is a Rust-based, multichain light client. Its core mission is to convert an untrusted centralized RPC endpoint into a secure, locally trusted RPC interface. It supports multiple blockchain networks (Ethereum, OP Stack, and others) and is designed to be lightweight, efficient, and even compile to WebAssembly for embedding into wallets and dapps.
- The README clearly outlines features like fast syncing, support for multiple networks, and integration with both execution and consensus layers. This indicates a full-stack “client” behavior rather than just a backend tool.

##### Analyzing the File Structure
- The repository is split into several top-level directories each representing a specific aspect or “crate” of the overall system:
- cli: Contains the command-line interface which provides the entry point for running Helios.
- core: This crate encapsulates the main client logic, consensus interactions, execution modules, and error handling. It communicates with external RPC endpoints.
- common: Holds shared files and types (like execution mode, network specification, and other utilities) used across multiple crates.
- ethereum (and subdirectory ethereum/consensus-core): Contains Ethereum-specific implementations, consensus cores, configurations, and test data.
- opstack, linea: These directories provide support for additional networks (OP Stack chains, Linea) and follow a similar architectural style as the Ethereum-specific modules.
- benches, tests, examples: They handle benchmarking, testing, and illustrative examples of usage.
- verifiable-api: Provides both the client and server components for the verifiable API functionality.
- helios-ts: A TypeScript/WASM layer to allow integration into browser-based or frontend scenarios.
- heliosup: An installer script/tool for Helios.
- The directory structure also reflects a modular design that leverages Rust’s workspace approach where each functional part is encapsulated into its own Cargo package/crate.

##### Extracting Architecture Insights from the README
- The README details how Helios is used via CLI commands, with options to set both consensus and execution RPC endpoints, various network configurations, and checkpoint settings.
- Specific usage instructions for Ethereum and OP Stack, along with configurable options, highlight the separation between the core client functionality and network-specific adaptations.
- The provided examples and configuration file instructions further indicate that the system has a layered architecture comprising:
- Client-facing CLI interface
- Core engine performing consensus, execution state management, and RPC handling
- Network adapter modules (Ethereum, OP Stack, etc.) that encapsulate protocol-specific behavior
- External interfaces to a range of RPC endpoints

##### Summary
- Notes on each module regarding its technology stack (Rust, Cargo, WASM, etc.) and include details (like Ethereum’s RPC configuration) as annotations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interface"
        CLI["CLI Interface (cli)"]:::cli
    end

    subgraph "Business Logic"
        CORE["Core Engine (core)"]:::core
        UTIL["Shared Utilities (common)"]:::core
    end

    subgraph "Network Modules"
        ETH["Ethereum Adapter (ethereum)"]:::adapter
        OP["OP Stack Module (opstack)"]:::adapter
        LIN["Linea Module (linea)"]:::adapter
    end

    subgraph "External Interfaces"
        API["Verifiable API Layer (verifiable-api)"]:::verif
        RPC["External RPC Endpoints"]:::external
    end

    subgraph "Additional Tools"
        WASM["WASM Integration (helios-ts)"]:::integration
        INSTALL["Installer (heliosup)"]:::integration
    end

    CLI -->|"triggers"| CORE
    CORE -->|"uses"| UTIL
    CORE -->|"adaptsTo"| ETH
    CORE -->|"adaptsTo"| OP
    CORE -->|"adaptsTo"| LIN
    CORE -->|"communicatesWith"| API
    ETH -->|"calls"| RPC
    OP -->|"calls"| RPC
    LIN -->|"calls"| RPC
    WASM -->|"integratesWith"| CORE
    INSTALL -->|"installsVia"| CLI

    click CLI "https://github.com/a16z/helios/blob/master/cli/src/main.rs"
    click CORE "https://github.com/a16z/helios/tree/master/core/src"
    click UTIL "https://github.com/a16z/helios/tree/master/common/src"
    click ETH "https://github.com/a16z/helios/tree/master/ethereum/"
    click OP "https://github.com/a16z/helios/tree/master/opstack/"
    click LIN "https://github.com/a16z/helios/tree/master/linea/"
    click API "https://github.com/a16z/helios/tree/master/verifiable-api/"
    click WASM "https://github.com/a16z/helios/tree/master/helios-ts/"
    click INSTALL "https://github.com/a16z/helios/tree/master/heliosup/"

    classDef cli fill:#90ee90,stroke:#333,stroke-width:2px;
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef adapter fill:#ffcc99,stroke:#333,stroke-width:2px;
    classDef verif fill:#ffffcc,stroke:#333,stroke-width:2px;
    classDef integration fill:#dda0dd,stroke:#333,stroke-width:2px;
    classDef external fill:#ff9999,stroke:#333,stroke-width:2px;
```
