# primev/mev-commit architecture

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

## Overview

##### Main Components
- mev-commit client – found in the “p2p” directory. This component handles peer-to-peer communications, protocol-level message handling (using protobuf definitions, gRPC endpoints, REST gateways, and API servers), and networking functions.
- mev-commit-oracle – located in the “oracle” directory. It contains an API server, a listener for Layer 1 events, and store/updater mechanisms, likely meant to interpret and validate on-chain data.
- mev-commit-bridge – contained in the “bridge” directory. It features subcomponents like an emulator, relayer, and a user CLI. These interact with “gateway” contracts and handle transfer logic and storage.
- mev-commit-geth – contained as an “external/geth” submodule. This is an altered version or integration with Ethereum’s Geth client, likely for interfacing directly with the Ethereum blockchain.
- Contracts – located in the “contracts” directory as well as “contracts-abi” and “x/contracts”. These house the smart contracts, Solidity code, ABIs, deployment scripts, and tests which are central to the on-chain part of the system.

##### Architectural and Organizational Patterns
- A modular design spread across multiple Go modules managed via a go.work file. Each primary system component exists in its own directory and is relatively independent in terms of business logic while interacting over well-defined APIs.
- Clear separation of concerns: networking (p2p), on-chain interaction (oracle, bridge, contracts), and external dependencies (geth submodule).
- Use of infrastructure automation (Nomad jobs, dockerfiles, ansible playbooks under “infrastructure”) and extensive tooling (instant-bridge, bidder-cli, dashboard, etc.) that support deployment and monitoring.
- Protobuf-generated code and multiple API definitions indicate the usage of RPC, gRPC, and HTTP/REST protocols to enable interactions between microservices.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Off-chain Components"
        Client["MEV-Commit Client (P2P)"]:::microservice
        Oracle["MEV-Commit Oracle"]:::microservice
        Bridge["MEV-Commit Bridge"]:::microservice
        Geth["MEV-Commit Geth Integration (External)"]:::external
    end

    subgraph "On-chain Components"
        SC["Smart Contracts"]:::blockchain
    end

    Client -->|"gRPC/REST"| Oracle
    Client -->|"gRPC/REST"| Bridge
    Oracle -->|"L1EventFeed"| SC
    Bridge -->|"ContractInteraction"| SC
    Geth -->|"JSON-RPC"| SC
    Oracle -->|"DataTrigger"| Bridge

    click Client "https://github.com/primev/mev-commit/tree/main/p2p/"
    click Oracle "https://github.com/primev/mev-commit/tree/main/oracle/"
    click Bridge "https://github.com/primev/mev-commit/tree/main/bridge/standard/"
    click Geth "https://github.com/primev/mev-commit/tree/main/external/geth/"
    click SC "https://github.com/primev/mev-commit/tree/main/contracts/"

    classDef microservice fill:#f9e79f,stroke:#e67e22,stroke-width:2px,stroke-dasharray: 5,5;
    classDef external fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef blockchain fill:#aed6f1,stroke:#2980b9,stroke-width:2px;
```
