# nethermindeth/juno architecture

> Architecture diagram of the GitHub repository nethermindeth/juno, 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/nethermindeth/juno
- Repository: https://github.com/nethermindeth/juno

## Overview

##### Overall Project Type and Purpose
- This is a full-node implementation for Starknet written in Golang (with some Rust components for performance-sensitive parts). It aims to synchronize and verify Starknet state (including blocks, transactions, classes, and state updates), expose JSON-RPC endpoints for clients, interface with Ethereum for state verification, and provide P2P capabilities for a decentralized network.
- The README and file tree indicate that Juno includes extensive support for various JSON-RPC APIs, synchronization protocols (via feeder and gateway), snapshot support, and even modes ranging from light client to sequencer.

##### Main Components
- User Interface / Entry Point:
- Command-line interface through cmd/juno. This is where the node is bootstrapped.
- Core Blockchain Module:
- Modules under “core” implement blockchain data structures (blocks, transactions, state updates, Merkle Patricia trie) and cryptographic primitives. Also include core packages for addresses, classes, and the history store.
- Virtual Machine (VM) and Execution:
- The vm module (with Rust components) executes transactions, simulates Cairo contracts, and verifies state transitions.
- Data Storage Layer:
- The db directory illustrates a local storage solution (with support for Pebble DB and remote DB adapters). Snapshots and persistent state storage are crucial here.
- Network and Synchronization:
- The p2p module supports peer-to-peer interactions (gossip, synchronization, keypair management, and peer discovery).
- The “clients/feeder” and “clients/gateway” directories show components that connect with the Starknet network – synchronizing blocks, transactions, and events.
- The “l1” folder indicates integration with Ethereum nodes for state verification (verifying state from layer 1).
- API & RPC Exposure:
- The jsonrpc and rpc directories include the implementation of JSON-RPC endpoints (supporting multiple versions) along with GRPC integrations under the grpc directory.
- Adapter and Integration Modules:
- Adapters (e.g., core2p2p, p2p2core, sn2core, vm2core) are used to translate between different layers and protocols.
- The “starknet” folder handles Starknet-specific logic (including classes, state updates, transactions, and compilers) and integrates with the CairoVM.
- Additional Services:
- Migration, plugin, feed, and upgrader directories indicate additional services for database migrations, plugin functionality, and state feed handling.
- The “sync” module is responsible for event listener functionality and keeping the node in sync with the network.
- External Dependencies:
- Integration with Ethereum nodes (configured via startup flags) and external snapshot sources is clearly outlined.

##### Relationships and Data Flow
- The synchronization logic (located in the clients/feeder, l1, and sync modules) pulls blocks, state updates, and events from the network (via the feeder gateway and Ethereum nodes).
- Once received, these events and blocks are validated by the Core module (core, blockchain, and crypto).
- The VM (vm, often using Rust integration) receives transactions and executes/simulates them for validation.
- The validated state is then persisted in the database (db with Pebble, etc.) and made available for query.
- The exposed APIs (JSON-RPC in jsonrpc and rpc, plus optional GRPC) interface with external clients, while the P2P module communicates with other nodes for decentralized consensus.
- Adapters translate data between these layers, ensuring protocol compatibility (e.g., core2p2p, p2p2core).

##### Architectural Patterns and Design Principles
- Modularization and Separation of Concerns: Each major subsystem (core, vm, network, API, storage) is organized in its own directory.
- Adapter Pattern: Multiple adapters provide a clear separation between protocols and internal representations.
- Layered Architecture: The system clearly separates internal blockchain state management from external interactions (RPC, P2P, L1 connectivity).
- Testability: A robust testing suite for each module suggests the importance of reliability and healthy unit/integration testing practices.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Node Initialization Layer"
        CLI["Node Initialization / CLI"]:::cli
    end

    subgraph "Core Engine"
        CORE["Core Engine\n(Blockchain, Validation, Crypto)"]:::core
    end

    subgraph "Virtual Machine Layer"
        VM["Virtual Machine (VM)"]:::vm
    end

    subgraph "Network & Synchronization"
        P2P["P2P Module"]:::network
        FEEDER["Feeder Clients"]:::network
        GATEWAY["Gateway Clients"]:::network
        L1["Ethereum L1 Integration"]:::network
    end

    subgraph "API Layer"
        JSONRPC["JSON-RPC Endpoints"]:::api
        RPC["Additional RPC Endpoints"]:::api
        GRPC["GRPC Endpoints"]:::api
    end

    subgraph "Database / Storage"
        DB["Database / Storage\n(Pebble, Remote)"]:::db
    end

    subgraph "Adapters"
        ADAPTERS["Adapters\n(core2p2p, p2p2core, sn2core, vm2core)"]:::adapter
    end

    subgraph "Additional Services"
        MIGRATION["Migration"]:::services
        PLUGIN["Plugin System"]:::services
        FEED["State Feed Handling"]:::services
        SYNC["Synchronization Service"]:::services
    end

    %% Relationships
    CLI -->|"bootstrap"| CORE
    P2P -->|"Block/TxData"| CORE
    FEEDER -->|"Block/TxData"| CORE
    GATEWAY -->|"Block/TxData"| CORE
    L1 -->|"StateVerification"| CORE
    CORE -->|"ExecuteTransactions"| VM
    VM -->|"UpdateState"| CORE
    CORE -->|"PersistState"| DB
    CORE -->|"ExposeData"| JSONRPC
    CORE -->|"ExposeData"| RPC
    CORE -->|"ExposeData"| GRPC
    CORE -- "ProtocolTranslation" --> ADAPTERS
    ADAPTERS -- "InterfaceBridging" --> P2P
    ADAPTERS -- "InterfaceBridging" --> VM
    MIGRATION -->|"ManageDB"| DB
    FEED -->|"FeedUpdates"| CORE
    SYNC -->|"EventListening"| CORE
    PLUGIN -->|"ExtendFunctions"| CORE

    %% Styling
    classDef cli fill:#f9c,stroke:#333,stroke-width:2px;
    classDef core fill:#bbf,stroke:#333,stroke-width:2px;
    classDef vm fill:#bfb,stroke:#333,stroke-width:2px;
    classDef network fill:#ff9,stroke:#333,stroke-width:2px;
    classDef api fill:#f9f,stroke:#333,stroke-width:2px;
    classDef db fill:#fdd,stroke:#333,stroke-width:2px;
    classDef adapter fill:#dfd,stroke:#333,stroke-width:2px;
    classDef services fill:#ffd,stroke:#333,stroke-width:2px;

    %% Click Events
    click CLI "https://github.com/nethermindeth/juno/blob/main/cmd/juno/juno.go"
    click CORE "https://github.com/nethermindeth/juno/tree/main/core/"
    click VM "https://github.com/nethermindeth/juno/tree/main/vm/"
    click P2P "https://github.com/nethermindeth/juno/tree/main/p2p/"
    click FEEDER "https://github.com/nethermindeth/juno/tree/main/clients/feeder/"
    click GATEWAY "https://github.com/nethermindeth/juno/tree/main/clients/gateway/"
    click L1 "https://github.com/nethermindeth/juno/tree/main/l1/"
    click JSONRPC "https://github.com/nethermindeth/juno/tree/main/jsonrpc/"
    click RPC "https://github.com/nethermindeth/juno/tree/main/rpc/"
    click GRPC "https://github.com/nethermindeth/juno/tree/main/grpc/"
    click DB "https://github.com/nethermindeth/juno/tree/main/db/"
    click ADAPTERS "https://github.com/nethermindeth/juno/tree/main/adapters/"
    click MIGRATION "https://github.com/nethermindeth/juno/tree/main/migration/"
    click PLUGIN "https://github.com/nethermindeth/juno/tree/main/plugin/"
    click FEED "https://github.com/nethermindeth/juno/tree/main/feed/"
    click SYNC "https://github.com/nethermindeth/juno/tree/main/sync/"
```
