# paritytech/revive architecture

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

- Interactive diagram: https://gitdiagram.com/paritytech/revive
- Repository: https://github.com/paritytech/revive

## Overview

##### Main Components
- Compiler Frontend – This includes the Solidity integration (“resolc” executable) that processes Solidity source input and converts it to an intermediate language (YUL) before further processing.
- LLVM Builder – Implemented in the “crates/llvm-builder” directory, this component handles the acquisition/building of a custom LLVM (v18.1.8) tailored for RISC-V targets with the necessary builtins and compiler-rt.
- LLVM Context – Found under “crates/llvm-context”, this crate deals with building the LLVM IR representation, optimization passes, debugging configuration, and target machine support.
- Code Generation and Linker – The “crates/linker” (and other related crates such as “crates/builtins”) manage linking, embedded builtins and code transformations.
- Runtime Components – The “crates/runner” and “crates/runtime-api” components are in charge of executing contracts and providing the runtime environment required on PolkaVM.
- Solidity JSON Interface – The “crates/solc-json-interface” crate provides tooling to compile and interface with Solidity’s JSON formats, bridging between Solidity source and YUL/LLVM.
- Additional Utilities, Testing, and Benchmarking – Directories like “crates/benchmarks”, “crates/integration”, and “crates/differential” aid with performance testing, integration tests, and verifying correctness.
- JavaScript/Wasm Frontend – The “js” directory contains build scripts, examples (both for Node.js and web), cross-compilation instructions, and end-to-end tests to allow a Wasm version of the compiler to run in browser or Node.js environments.

##### Relationships and Interactions
- The Solidity frontend (resolc) processes contract source files and hands off an intermediate representation to the compiler core.
- The LLVM Builder supports both local builds of LLVM and cross-compilation scenarios; it supplies the LLVM binaries (or points to them) used by the LLVM Context.
- The LLVM Context interacts closely with both the code generator and the optimization routines to produce target-specific IR.
- The Runner and Runtime API receive finalized compiled code and execute it within an environment that simulates high-level contract execution.
- Testing and benchmarking crates run against these components to verify correctness, performance, and integration.
- The JavaScript layer, through Wasm cross-compilation, wraps around the primary compiler components to provide a frontend that can run on different platforms (browser, Node.js).

##### Architectural Patterns and Design Principles
- Modular Design – The project is separated into numerous well-defined crates, each with a clear role (frontend, builder, context, runner, etc.) following a separation-of-concerns principle.
- Dependency and Data Flow – There is a logical sequence where source code is ingested, transformed through multiple intermediate representations, built via an external custom LLVM dependency, and finally executed or integrated through testing tools.
- Extensibility – With dedicated crates for the JSON interfaces, integration tests, and differential testing, the system is designed for extensibility and robust automated testing.

##### Technologies and Frameworks
- Rust and Cargo for building and managing the project’s workspace.
- LLVM (custom build of v18.1.8) as the core compilation backend.
- C++ toolchain and Emscripten used for building the LLVM components and the Wasm target.
- GitHub Actions (CI workflows in .github directory) managing continuous integration and release processes.
- Additional testing tools (like Geth for testing Ethereum compatibility in integration tests) to simulate runtime environments.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        CF["Compiler Frontend"]:::frontend
        SJI["Solidity JSON Interface"]:::frontend
    end

    %% Core Compiler Components
    subgraph "Core Compiler"
        LB["LLVM Builder"]:::compiler
        LC["LLVM Context"]:::compiler
        CL["Code Generation & Linker"]:::compiler
    end

    %% Runtime Environment
    subgraph "Runtime Environment"
        R["Runner"]:::runtime
        RA["Runtime API"]:::runtime
    end

    %% Testing and Utilities
    subgraph "Testing & Utilities"
        BM["Benchmarks"]:::testing
        IT["Integration Tests"]:::testing
        DT["Differential Tests"]:::testing
    end

    %% JavaScript/Wasm Integration
    subgraph "JS/Wasm Integration"
        JS["JS/Wasm Frontend"]:::js
    end

    %% CI/CD Workflow
    CCD["CI/CD Workflow"]:::cd

    %% Data Flow Connections
    CF -->|"generates_YUL"| LB
    LB -->|"provides_LLVM_config"| LC
    LC -->|"produces_LLVM_IR"| CL
    CL -->|"performs_codegen"| R
    R -->|"executes_contracts"| RA
    CF -->|"interfaces_with"| SJI

    %% Integration with JS/Wasm Frontend
    JS -->|"wraps_compiler"| CF
    JS -->|"triggers_build"| LB

    %% Testing Feedback
    BM -->|"feedback_to"| CF
    BM -->|"validates"| CL
    IT -->|"integration_test"| RA
    DT -->|"differential_test"| RA

    %% CI/CD Connections
    CCD -->|"automated_tests"| BM
    CCD -->|"automated_tests"| IT
    CCD -->|"automated_tests"| DT

    %% Styles
    classDef frontend fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef compiler fill:#87CEEB,stroke:#333,stroke-width:2px;
    classDef runtime fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef testing fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef js fill:#DDA0DD,stroke:#333,stroke-width:2px;
    classDef cd fill:#D3D3D3,stroke:#333,stroke-width:2px;

    %% Click Events
    click CF "https://github.com/paritytech/revive/blob/main/crates/solidity/src/resolc/main.rs"
    click SJI "https://github.com/paritytech/revive/tree/main/crates/solc-json-interface"
    click LB "https://github.com/paritytech/revive/tree/main/crates/llvm-builder"
    click LC "https://github.com/paritytech/revive/tree/main/crates/llvm-context"
    click CL "https://github.com/paritytech/revive/tree/main/crates/linker"
    click R "https://github.com/paritytech/revive/tree/main/crates/runner"
    click RA "https://github.com/paritytech/revive/tree/main/crates/runtime-api"
    click BM "https://github.com/paritytech/revive/tree/main/crates/benchmarks"
    click IT "https://github.com/paritytech/revive/tree/main/crates/integration"
    click DT "https://github.com/paritytech/revive/tree/main/crates/differential"
    click JS "https://github.com/paritytech/revive/tree/main/js"
```
