# ethereum/solidity architecture

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

- Interactive diagram: https://gitdiagram.com/ethereum/solidity
- Repository: https://github.com/ethereum/solidity

## Overview

##### Project Type and Purpose
- This is a large, modular compiler for the Solidity smart‐contract language.
- It includes a command‐line interface (solc), a language server (LSP), a formal verification engine, and various code‐generation backends (Yul IR, EVM bytecode).

##### High‐Level Architectural Components
a. Front-End
- CLI / Standard-JSON interface (solc/main.cpp, solc/CommandLineInterface.cpp)
- Scanner & Parser (liblangutil/Scanner, liblangutil/ParserBase, libsolidity/parsing/Parser)
- Abstract Syntax Tree (libsolidity/ast)
b. Middle-End (Semantic Analysis & IR Generation)
- Name & Type Resolution, Contract-Level Checks, Control-Flow Analysis (libsolidity/analysis/*)
- Intermediate Representation Generator (Yul‐IR via libsolidity/codegen/ir and libyul)
- Optimiser passes (libyul/optimiser/*)
c. Back-End (Code Generation & Linking)
- Yul→EVM codegen (libyul/backends/evm)
- Assembly optimisation & bytecode emitter (libevmasm)
- Linker (Part of libevmasm/LinkerObject)
d. Formal Verification
- SMT‐based solvers adapter (libsmtutil)
- Model checking & predicate encoding (libsolidity/formal)
e. Language Server
- LSP transport and handlers (libsolidity/lsp/*)
- Hooks into parsing & semantic analysis for hover, definition, rename
f. Build & CI Orchestration
- CMake modules (cmake/*, CMakeLists.txt)
- Continuous integration scripts (​.circleci/​*, scripts/ci/*)
g. Testing & Examples
- Unit and end-to-end tests (test/*, test/cmdlineTests, test/lib* )
- Documentation and examples (docs/*)

##### Component Interactions
- The CLI frontend invokes the parser → AST → semantic analysis → IR generator → optimizer pipeline → codegen → bytecode output.
- The LSP server sits alongside the CLI, calling into parser & analysis modules and communicating over JSON-RPC.
- The formal subsystem can be invoked from the CLI (model checker) and interacts with external SMT backends via libsmtutil.
- CMake defines build targets for each library and executable; CI scripts drive builds, tests, documentation.

##### Architectural Patterns & Principles
- Pipeline / modular stages (front-end, mid-end, back-end).
- Clear layering: language utilities (liblangutil) → AST & analysis (libsolidity) → IR & optimisation (libyul) → codegen (libevmasm).
- Adapter pattern for external SMT solvers (libsmtutil).
- Plugin-style codegen backends (Yul, strict assembly, EVM).
- Separation of concerns: LSP protocols isolated from core compiler logic.

##### Essential Details
- Major modules by name (liblangutil, libsolidity/analysis, libyul/optimiser, libevmasm).
- Integration points (CLI calling into each library).
- Build and CI orchestrating compilation, testing, documentation generation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Front-End Layer
    subgraph "Front-End"
        direction TB
        CLI(("solc CLI")):::frontend
        Scanner["Scanner"]:::frontend
        Parser["Parser"]:::frontend
        AST["AST"]:::frontend
    end

    %% Mid-End Layer
    subgraph "Mid-End"
        direction TB
        Analysis["Semantic Analysis"]:::mid
        IRGen["IR Generator"]:::mid
        Optimiser["Optimiser Passes"]:::mid
    end

    %% Back-End Layer
    subgraph "Back-End"
        direction TB
        Codegen["Yul→EVM Codegen"]:::backend
        Assembler["Assembly & Bytecode Emitter"]:::backend
        Linker["Linker"]:::backend
        Bytecode["Bytecode Output"]:::backend
    end

    %% Formal Verification
    subgraph "Formal Verification"
        direction TB
        FormalEngine["Model Checker"]:::formal
        SMTUtil["SMT Adapter"]:::formal
        Z3(("Z3")):::external
        CVC5(("CVC5")):::external
    end

    %% Language Server
    LSP(("LSP Server")):::frontend

    %% Build & CI Orchestration
    BuildCI(("Build & CI")):::infra

    %% Data Flow
    CLI --> Scanner --> Parser --> AST --> Analysis --> IRGen --> Optimiser --> Codegen --> Assembler --> Linker --> Bytecode

    %% LSP interactions
    LSP --> Parser
    LSP --> Analysis

    %% Formal interactions
    FormalEngine --> Analysis
    FormalEngine --> SMTUtil --> Z3
    SMTUtil --> CVC5

    %% Build & CI orchestration
    BuildCI --> CLI
    BuildCI --> LSP
    BuildCI --> Analysis
    BuildCI --> IRGen
    BuildCI --> Codegen
    BuildCI --> FormalEngine
    BuildCI --> TestSuite[(Tests & Examples)]:::infra

    %% Click Events
    click CLI "https://github.com/ethereum/solidity/blob/develop/solc/main.cpp"
    click CLI "https://github.com/ethereum/solidity/blob/develop/solc/CommandLineInterface.cpp"
    click CLI "https://github.com/ethereum/solidity/blob/develop/solc/CommandLineParser.cpp"
    click Scanner "https://github.com/ethereum/solidity/blob/develop/liblangutil/Scanner.cpp"
    click Parser "https://github.com/ethereum/solidity/blob/develop/liblangutil/ParserBase.cpp"
    click Parser "https://github.com/ethereum/solidity/blob/develop/libsolidity/parsing/Parser.cpp"
    click AST "https://github.com/ethereum/solidity/blob/develop/libsolidity/ast/AST.cpp"
    click Analysis "https://github.com/ethereum/solidity/blob/develop/libsolidity/analysis/NameAndTypeResolver.cpp"
    click IRGen "https://github.com/ethereum/solidity/blob/develop/libsolidity/codegen/ir/IRGenerator.cpp"
    click Optimiser "https://github.com/ethereum/solidity/blob/develop/libyul/optimiser/ASTWalker.cpp"
    click Codegen "https://github.com/ethereum/solidity/blob/develop/libyul/backends/evm/AsmCodeGen.cpp"
    click Assembler "https://github.com/ethereum/solidity/blob/develop/libevmasm/Assembly.cpp"
    click Linker "https://github.com/ethereum/solidity/blob/develop/libevmasm/LinkerObject.cpp"
    click FormalEngine "https://github.com/ethereum/solidity/blob/develop/libsolidity/formal/ModelChecker.cpp"
    click SMTUtil "https://github.com/ethereum/solidity/blob/develop/libsmtutil/SMTLib2Interface.cpp"
    click LSP "https://github.com/ethereum/solidity/blob/develop/libsolidity/lsp/LanguageServer.cpp"
    click BuildCI "https://github.com/ethereum/solidity/blob/develop/CMakeLists.txt"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef mid fill:#E6F4EA,stroke:#22863a,color:#22863a;
    classDef backend fill:#FFF5E5,stroke:#d9941c,color:#d9941c;
    classDef formal fill:#F3E8FF,stroke:#6f42c1,color:#6f42c1;
    classDef infra fill:#F0F0F0,stroke:#6a737d,color:#6a737d;
    classDef external fill:#FFFFFF,stroke:#444444,stroke-dasharray: 2 2,color:#444444;
```
