# morph-l2/morph architecture

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

- Interactive diagram: https://gitdiagram.com/morph-l2/morph
- Repository: https://github.com/morph-l2/morph

## Overview

##### Project Type and Purpose
- Morph is a blockchain protocol implementation aimed at revolutionizing consumer blockchain use through its unique rollup and validity proof mechanisms.
- It focuses on enhancing Ethereum scalability (Layer 2) with components for on-chain smart contracts, off-chain transaction processing, orchestration nodes, validity proof generation (“prover”), and gas pricing/oracle services.

##### Analyzing the File Structure
- There are many top-level directories that map closely to main subsystems:
- “contracts”: Contains Solidity smart contracts, deployment scripts (Hardhat, Foundry, etc.), and testing data. These represent the on-chain layer including L1 and L2 gateways, staking, rollup contracts, and other protocols.
- “bindings”: Contains Go code to auto-generate bindings for the smart contracts. This module is a bridge between on-chain components and off-chain Go-based services.
- “node”: Contains several subdirectories (node/ops-morph, node/sequencer, node/sync, etc.). This is the core execution engine and networking layer that handles L1/L2 message processing, block production, and consensus.
- “tx-submitter”: Implements services that collect, group, and submit batches of transactions. It likely interacts with both on-chain contracts and the blockchain nodes.
- “prover”: A complex subsystem written in Rust (with some Go integration) where validity proofs are generated (including components such as “challenge”, “shadow-prove”, and test suites) to support the RVP concept.
- “gas-oracle” and “oracle”: These modules provide mechanisms for monitoring gas fees and handling governance or staking oracle functions.
- “ops”: Contains multiple docker configurations, deployment scripts, and testnet setups, which outline the operational and orchestration aspects.
- Additional files (like Makefiles, Dockerfiles, CI workflows, etc.) emphasize that the project’s build, testing, and continuous integration/deployment processes are highly automated.

##### Key Components
a. On-Chain Smart Contracts Layer:
– Represented by “contracts” where rollup contracts, gateway contracts (such as ERC20, ERC721, etc. deployed in bindings), and libraries are defined.
– Label these as “L1 Contracts” and “L2 Contracts” where applicable.
b. Binding Layer:
– The “bindings” directory contains code to generate language-specific interfaces that allow off-chain components to interact with the smart contracts.
– Represent it as an integration layer between on-chain contracts and backend services.
c. Node/Sequencer Component:
– Use the “node” directory to illustrate the blockchain node responsible for message processing, batch handling, and consensus (including subsections for key converter, tendermint integration, sync, and validator modules).
– Emphasize that these nodes are responsible for creating and processing the rollup blocks.
d. Prover System:
– Highlight the “prover” module, which is responsible for generating correctness proofs for batches of transactions.
– Show subcomponents (client, host, shadow-prove) that work together to produce and verify validity proofs.
e. Transaction Submission Service:
– From “tx-submitter”, show how transactions are batched and submitted into the system.
– Indicate its role in mediating between the off-chain processes and on-chain state changes.
f. Gas Oracle & External Oracles:
– The “gas-oracle” and “oracle” directories provide external price signals and staking/other governance data.
– Represent these as ancillary services that feed into other modules (for instance, affecting fee calculations or stake management).
g. Ops and Deployment:
– The “ops” directory represents the container orchestration, deployment setup (including Docker configurations and automated CI pipelines), and genesis management.
– It is crucial for understanding how all these components are deployed and integrated in various environments.

##### Relationships and Interactions
- A clear directional flow from the Prover system toward both the Node (or directly to Contracts) to deliver validity proofs.

##### Architectural Patterns and Design Principles
- The overall design is modular and decoupled. Each component (e.g., node, tx submitter, prover) works as an independent microservice or module with well-defined interfaces.
- There is a clear separation between on-chain and off-chain layers.
- The binding layer serves as the integration gateway between different programming languages/environments.
- The use of Docker and CI workflows indicates an emphasis on repeatable deployments and containerized orchestration.
- Multiple languages (Go, Rust, Solidity) require clear interface boundaries; this emphasizes service isolation and clear dependency management.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "On-Chain Layer"
        SC["Smart Contracts (L1 & L2)"]:::onchain
    end

    subgraph "Off-Chain Services"
        Bindings["Bindings/Integration Layer"]:::integration
        Node["Blockchain Node/Sequencer"]:::node
        TxSubmitter["Tx-Submitter"]:::service
        Prover["Prover System"]:::service
        GasOracle["Gas Oracle"]:::oracle
        ExternalOracle["External Oracle (Staking/Governance)"]:::oracle
    end

    Ops["Ops/Deployment"]:::ops

    TxSubmitter -->|"submitsTx"| Node
    Node -->|"forwardsMessages"| SC
    Bindings <-->|"interfaces"| SC
    Prover -->|"deliversProofs"| Node
    GasOracle -->|"feedsPricing"| TxSubmitter
    GasOracle -->|"feedsPricing"| Node
    ExternalOracle -->|"providesData"| Node

    Ops -.-> SC
    Ops -.-> Bindings
    Ops -.-> Node
    Ops -.-> TxSubmitter
    Ops -.-> Prover
    Ops -.-> GasOracle
    Ops -.-> ExternalOracle

    click SC "https://github.com/morph-l2/morph/tree/main/contracts/"
    click Bindings "https://github.com/morph-l2/morph/tree/main/bindings/"
    click Node "https://github.com/morph-l2/morph/tree/main/node/"
    click TxSubmitter "https://github.com/morph-l2/morph/tree/main/tx-submitter/"
    click Prover "https://github.com/morph-l2/morph/tree/main/prover/"
    click GasOracle "https://github.com/morph-l2/morph/tree/main/gas-oracle/"
    click ExternalOracle "https://github.com/morph-l2/morph/tree/main/oracle/"
    click Ops "https://github.com/morph-l2/morph/tree/main/ops/"

    classDef onchain fill:#f9f,stroke:#333,stroke-width:2px;
    classDef integration fill:#bbf,stroke:#333,stroke-width:2px;
    classDef node fill:#bfb,stroke:#333,stroke-width:2px;
    classDef service fill:#ff9,stroke:#333,stroke-width:2px;
    classDef oracle fill:#9cf,stroke:#333,stroke-width:2px;
    classDef ops fill:#f96,stroke:#333,stroke-width:2px;
```
