# ethereum-optimism/optimism architecture

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

## Overview

Based on our review of the complete file tree and the README, we see that this is a monorepo for an entire blockchain scaling solution called “Optimism” (the OP Stack). This is a full-stack decentralized system that combines multiple services – from on‐chain smart contracts and consensus clients (op‑node) to off‐chain batch submitters (op‑batcher), fault proof programs (op‑program), dispute game challengers (op‑challenger), output proposers (op‑proposer), preimage oracle services (op‑preimage), and various supporting utilities (op‑service, op‑wheel, a whole contracts package in “packages/contracts-bedrock”, etc.). In other words, this repository contains many discrete components each responsible for a piece of the layer‑2 system that collectively forms Optimism’s rollup architecture.

##### Main architectural layers and components
- Core protocol services that run as separate “op‑*” binaries:
– op‑node: The consensus (rollup) client that carries out the central state transitions and (likely) handles L1–L2 communication.
– op‑batcher: Collects transactions from L2 and forms batches that are submitted to the L1 chain.
– op‑proposer: Responsible for proposing L2 output updates that get posted to L1.
– op‑challenger: Handles dispute game challenges in cases where a faulty batch or malicious state is detected.
– op‑program: The fault proof program that is part of validating state transitions.
– op‑preimage: Provides oracle bindings for preimage functionality.
- Smart Contracts Layer:
– Found under “packages/contracts-bedrock”; these contracts form the on‑chain logic and include components such as bridges, validators, and messenger contracts.
- Support and Utility Layers:
– Services like “op‑service”, “op‑wheel” and other utility libraries.
– Engaged CI/CD, testing (op‑e2e), deployment tooling, and developer environments (kurtosis‑devnet, ops) serve as the bottom “infrastructure” layer.
- External Dependencies:
– The underlying Ethereum L1 network.
– Developer tooling and external services used for testing, auditing, or communication (such as GitHub Actions, CI pipelines, and docker configurations).

##### Relationships and interactions between these components
- How the L2 components – op‑node, op‑batcher, op‑proposer, and op‑challenger – interact with each other. For example, transactions submitted to op‑node are batched by op‑batcher; op‑proposer then takes state changes or proofs from op‑node and prepares an output proposal, while op‑challenger monitors for conflicts or fraud.
- Feedback paths and dispute resolution mechanism: for example, if op‑challenger detects a dispute, it triggers a challenge (possibly interacting with op‑program for fault proofs) and the outcome is enforced via smart contracts.
- How the op‑preimage service fits into the data availability or oracle lookups when verifying state or contract inputs.

##### Detail design patterns and technology choices
- Each “op‑…” component generally is written in Golang (as evidenced by the numerous Go source files) and is deployed as an independent microservice or binary.
- The system uses containerization (Dockerfiles, CI config in .github and .circleci folders) so you might represent container boundaries around each service.
- That the system is modular, with clear separation between the execution node, state batching, output proposal, and challenge mechanisms – a design that favors both robustness and upgradeability.
- The smart contracts are developed as on‑chain modules that are versioned separately (using semver tags with “op‑node/vX.X.X”, etc.) and interact with these off-chain services via established protocols and APIs.

##### Overall details
- Be detailed in capturing the flow from the L2 entry (transaction processing) to batch submission, output proposers and challenge responses.
- Don’t over-simplify: since the project is modular with many interacting parts, try to break down into at least three layers (off‑chain services, on‑chain contracts, and deployment/operations).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients and Networks
    Clients["Clients/Users"]:::client
    L1["Ethereum L1 Network"]:::external

    %% L2 Services Subgraph
    subgraph "L2 Services"
        opNode["op-node (Golang microservice)"]:::l2
        opBatcher["op-batcher (Golang microservice)"]:::l2
        opProposer["op-proposer (Golang microservice)"]:::l2
        opChallenger["op-challenger (Golang microservice)"]:::l2
        opProgram["op-program (Fault Proof Service)"]:::l2
        opPreimage["op-preimage (Oracle Service)"]:::l2
    end

    %% On-Chain Smart Contracts Subgraph
    subgraph "On-Chain Smart Contracts"
        contracts["Smart Contracts (contracts-bedrock)"]:::contracts
    end

    %% Support & Utilities Subgraph
    subgraph "Support & Utilities"
        opService["op-service (Utility Service)"]:::utility
        opWheel["op-wheel (Utility Library)"]:::utility
    end

    %% Infrastructure & Tooling Subgraph
    subgraph "Infrastructure & Tooling"
        cicd["CI/CD & Testing"]:::infra
        devnet["DevNet & Ops"]:::infra
    end

    %% Data Flow Connections
    Clients -->|"submitTx"| opNode

    opNode -->|"batchGrouping"| opBatcher
    opNode -->|"stateOutput"| opProposer
    opNode -->|"monitorEvents"| opChallenger
    opPreimage -->|"oracleLookup"| opNode

    opBatcher -->|"submitBatch"| contracts
    opProposer -->|"postOutput"| contracts
    opPreimage -->|"verifyInputs"| contracts

    opChallenger -->|"initiateProof"| opProgram
    opProgram -->|"enforceChallenge"| contracts

    contracts -->|"onChainValidation"| L1
    L1 -->|"disputeEvents"| opChallenger

    %% Support Connections
    opService -->|"supportFunctions"| opNode
    opWheel -->|"assistOperations"| opNode

    %% Infrastructure Connections
    cicd -->|"deployAndTest"| opNode
    cicd -->|"deployAndTest"| contracts
    devnet -->|"orchestrateServices"| opNode
    devnet -->|"orchestrateServices"| contracts

    %% Class Definitions for Colors and Styles
    classDef l2 fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef contracts fill:#A9DFBF,stroke:#145A32,stroke-width:2px;
    classDef utility fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef infra fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef external fill:#F5CBA7,stroke:#7D6608,stroke-width:2px;
    classDef client fill:#D5F5E3,stroke:#1E8449,stroke-width:2px;

    %% Click Events - mapping to project file paths
    click opNode "https://github.com/ethereum-optimism/optimism/tree/develop/op-node"
    click opBatcher "https://github.com/ethereum-optimism/optimism/tree/develop/op-batcher"
    click opProposer "https://github.com/ethereum-optimism/optimism/tree/develop/op-proposer"
    click opChallenger "https://github.com/ethereum-optimism/optimism/tree/develop/op-challenger"
    click opProgram "https://github.com/ethereum-optimism/optimism/tree/develop/op-program"
    click opPreimage "https://github.com/ethereum-optimism/optimism/tree/develop/op-preimage"
    click opService "https://github.com/ethereum-optimism/optimism/tree/develop/op-service"
    click opWheel "https://github.com/ethereum-optimism/optimism/tree/develop/op-wheel"
    click contracts "https://github.com/ethereum-optimism/optimism/tree/develop/packages/contracts-bedrock"
```
