# solidquant/mev-templates architecture

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

- Interactive diagram: https://gitdiagram.com/solidquant/mev-templates
- Repository: https://github.com/solidquant/mev-templates

## Overview

##### Main Components
- Environment and Configuration: Include the .env and .env.example files which store key configurations (node endpoints, chain ID, Blocknative token, private keys, signing keys, bot contract address, etc.).
- On-Chain Smart Contracts: Represent the "contracts" directory. Inside this, you have subcomponents such as:
– The core contract(s) (for example, the arbitrage bot contract “V2ArbBot” referenced in the README).
– External libraries (forge-std and OpenZeppelin contracts) that support security, proxy patterns, token standards, and testing.
– Python: Contains modules like bundler.py, constants.py, simulator.py, multi.py, pools.py, streams.py, etc.
– Javascript: Contains similar modules (bundler.js, constants.js, simulator.js, multi.js, pools.js, strategy.js, etc.).
– Rust: Mirrors the functionality of the other two with files like bundler.rs, simulator.rs, constants.rs, multi.rs, pools.rs, strategy.rs, etc.
- Data Ingestion and Simulation Layer: Since all three templates include functionalities to:
– Retrieve historical blockchain events (e.g., “PairCreated” events).
– Execute multicall requests (getReserve calls for pools).
– Stream blockchain events (new headers and new pending transactions).
– Simulate arbitrage paths off-chain.
- Benchmarking and Testing: Highlight the benchmarking files (benchmarks.py, benchmarks.js, benchmarks.rs) and tests inside the contracts folder.

##### Out Relationships and Interactions
– The streaming of new headers, events, and pending transactions flowing into the “Streams” or “Multi” modules.
– Historical events being fetched and passed into the “Simulator” and “Strategy” modules.
– Data input from simulation and blockchain events.
– Construction of transaction bundles (with a component like “Bundler”) and subsequent signing.
– Outbound flow toward sending these bundles (to mempool or Flashbots service).
- Benchmarking flow: from the execution of the same strategy in Python, Javascript, and Rust to a “Benchmark Results” component, which then can flow into analysis and blog post output.

##### Architectural Patterns and Key Technologies
- Modularity: Emphasize that although there are three language implementations, they share a similar design pattern. This can be depicted as three parallel modules that have a similar inner structure.
- Asynchronous and event-driven programming: Indicate that streaming, event retrieval, and multicall requests are handled asynchronously.
- External integrations: Mark the connection to blockchain nodes for event streaming and Flashbots for bundle transmission.
- Smart Contract Standardization: Note the usage of recognizable libraries (cryptography, escrow, proxy patterns, token standards) from OpenZeppelin and forge-std, which enforce secure design principles.

## Diagram (Mermaid)

```mermaid
flowchart TD

  %% Configuration
  subgraph "Configuration"
    ConfTop[".env.example"]:::config
    ConfPython["Python .env.example"]:::config
    ConfJS["Javascript .env.example"]:::config
    ConfRust["Rust .env.example"]:::config
  end

  %% Smart Contracts & Libraries
  subgraph "Smart Contracts & Libraries"
    SC["Contracts"]:::chain
    ForgeStd["Forge-Std"]:::chain
    OpenZeppelin["OpenZeppelin"]:::chain
  end

  %% Python Bot Core
  subgraph "Python Bot Core"
    PyBundler["bundler.py"]:::offchain
    PyConstants["constants.py"]:::offchain
    PyMulti["multi.py"]:::offchain
    PyPaths["paths.py"]:::offchain
    PyPools["pools.py"]:::offchain
    PySimulator["simulator.py"]:::offchain
    PyStreams["streams.py"]:::offchain
    PyStrategy["dex_3hop_arb_ex.py"]:::offchain
    PyMain["main.py"]:::offchain
    PyRelay["relay.py"]:::offchain
    PyTracing["tracing.py"]:::offchain
    PyUtils["utils.py"]:::offchain
    PyBench["benchmarks.py"]:::benchmarking
  end

  %% Javascript Bot Core
  subgraph "Javascript Bot Core"
    JsBundler["bundler.js"]:::offchain
    JsConstants["constants.js"]:::offchain
    JsMulti["multi.js"]:::offchain
    JsPaths["paths.js"]:::offchain
    JsPools["pools.js"]:::offchain
    JsSimulator["simulator.js"]:::offchain
    JsStreams["streams.js"]:::offchain
    JsStrategy["strategy.js"]:::offchain
    JsUtils["utils.js"]:::offchain
    JsABI["ABI Directory"]:::offchain
    JsBench["benchmarks.js"]:::benchmarking
  end

  %% Rust Bot Core
  subgraph "Rust Bot Core"
    RsBundler["bundler.rs"]:::offchain
    RsConstants["constants.rs"]:::offchain
    RsMulti["multi.rs"]:::offchain
    RsPaths["paths.rs"]:::offchain
    RsPools["pools.rs"]:::offchain
    RsSimulator["simulator.rs"]:::offchain
    RsStreams["streams.rs"]:::offchain
    RsStrategy["strategy.rs"]:::offchain
    RsUtils["utils.rs"]:::offchain
    RsLib["lib.rs"]:::offchain
    RsMain["main.rs"]:::offchain
    RsABI["ABI Directory"]:::offchain
    RsBench["benchmarks.rs"]:::benchmarking
  end

  %% External Services
  subgraph "External Services"
    ETHNode["Ethereum/Polygon Node (HTTP&WS)"]:::external
    Flashbots["Flashbots/Mempool"]:::external
  end

  %% Benchmarking & Analysis
  subgraph "Benchmarking & Analysis"
    BenchResults["Benchmark Results"]:::benchmarking
  end

  %% Connections from Configuration to Bot Cores and Contracts
  ConfTop --> SC
  ConfPython --> PyBundler
  ConfJS --> JsBundler
  ConfRust --> RsBundler

  %% Smart Contracts internals
  SC --> ForgeStd
  SC --> OpenZeppelin

  %% External Data Flow into Off-Chain Modules (Python)
  ETHNode --- PySimulator
  ETHNode --- PyStreams

  %% External Data Flow into Off-Chain Modules (Javascript)
  ETHNode --- JsSimulator
  ETHNode --- JsStreams

  %% External Data Flow into Off-Chain Modules (Rust)
  ETHNode --- RsSimulator
  ETHNode --- RsStreams

  %% Python internal processing flow
  PySimulator --> PyStrategy
  PyStreams --> PyStrategy
  PyStrategy --> PyBundler
  PyBundler --> Flashbots
  PyStrategy --> SC

  %% Javascript internal processing flow
  JsSimulator --> JsStrategy
  JsStreams --> JsStrategy
  JsStrategy --> JsBundler
  JsBundler --> Flashbots
  JsStrategy --> SC

  %% Rust internal processing flow
  RsSimulator --> RsStrategy
  RsStreams --> RsStrategy
  RsStrategy --> RsBundler
  RsBundler --> Flashbots
  RsStrategy --> SC

  %% Benchmarking flows from each language
  PyBench --> BenchResults
  JsBench --> BenchResults
  RsBench --> BenchResults

  %% Styling Classes
  classDef config fill:#f9e79f,stroke:#333,stroke-width:2px;
  classDef chain fill:#aed6f1,stroke:#333,stroke-width:2px;
  classDef offchain fill:#d5f5e3,stroke:#333,stroke-width:2px;
  classDef external fill:#f5b7b1,stroke:#333,stroke-width:2px;
  classDef benchmarking fill:#e8daef,stroke:#333,stroke-width:2px;

  %% Click Events for Configuration
  click ConfTop "https://github.com/solidquant/mev-templates/blob/main/.env.example"
  click ConfPython "https://github.com/solidquant/mev-templates/blob/main/python/.env.example"
  click ConfJS "https://github.com/solidquant/mev-templates/blob/main/javascript/.env.example"
  click ConfRust "https://github.com/solidquant/mev-templates/blob/main/rust/.env.example"

  %% Click Events for Smart Contracts & Libraries
  click SC "https://github.com/solidquant/mev-templates/tree/main/contracts/"
  click ForgeStd "https://github.com/solidquant/mev-templates/tree/main/contracts/lib/forge-std"
  click OpenZeppelin "https://github.com/solidquant/mev-templates/tree/main/contracts/lib/openzeppelin-contracts"

  %% Click Events for Python Bot Core
  click PyBundler "https://github.com/solidquant/mev-templates/blob/main/python/bundler.py"
  click PyConstants "https://github.com/solidquant/mev-templates/blob/main/python/constants.py"
  click PyMulti "https://github.com/solidquant/mev-templates/blob/main/python/multi.py"
  click PyPaths "https://github.com/solidquant/mev-templates/blob/main/python/paths.py"
  click PyPools "https://github.com/solidquant/mev-templates/blob/main/python/pools.py"
  click PySimulator "https://github.com/solidquant/mev-templates/blob/main/python/simulator.py"
  click PyStreams "https://github.com/solidquant/mev-templates/blob/main/python/streams.py"
  click PyStrategy "https://github.com/solidquant/mev-templates/blob/main/python/strategy/dex_3hop_arb_ex.py"
  click PyMain "https://github.com/solidquant/mev-templates/blob/main/python/main.py"
  click PyRelay "https://github.com/solidquant/mev-templates/blob/main/python/relay.py"
  click PyTracing "https://github.com/solidquant/mev-templates/blob/main/python/tracing.py"
  click PyUtils "https://github.com/solidquant/mev-templates/blob/main/python/utils.py"
  click PyBench "https://github.com/solidquant/mev-templates/blob/main/python/benchmarks.py"

  %% Click Events for Javascript Bot Core
  click JsBundler "https://github.com/solidquant/mev-templates/blob/main/javascript/src/bundler.js"
  click JsConstants "https://github.com/solidquant/mev-templates/blob/main/javascript/src/constants.js"
  click JsMulti "https://github.com/solidquant/mev-templates/blob/main/javascript/src/multi.js"
  click JsPaths "https://github.com/solidquant/mev-templates/blob/main/javascript/src/paths.js"
  click JsPools "https://github.com/solidquant/mev-templates/blob/main/javascript/src/pools.js"
  click JsSimulator "https://github.com/solidquant/mev-templates/blob/main/javascript/src/simulator.js"
  click JsStreams "https://github.com/solidquant/mev-templates/blob/main/javascript/src/streams.js"
  click JsStrategy "https://github.com/solidquant/mev-templates/blob/main/javascript/src/strategy.js"
  click JsUtils "https://github.com/solidquant/mev-templates/blob/main/javascript/src/utils.js"
  click JsABI "https://github.com/solidquant/mev-templates/tree/main/javascript/abi/"
  click JsBench "https://github.com/solidquant/mev-templates/blob/main/javascript/benchmarks.js"

  %% Click Events for Rust Bot Core
  click RsBundler "https://github.com/solidquant/mev-templates/blob/main/rust/src/bundler.rs"
  click RsConstants "https://github.com/solidquant/mev-templates/blob/main/rust/src/constants.rs"
  click RsMulti "https://github.com/solidquant/mev-templates/blob/main/rust/src/multi.rs"
  click RsPaths "https://github.com/solidquant/mev-templates/blob/main/rust/src/paths.rs"
  click RsPools "https://github.com/solidquant/mev-templates/blob/main/rust/src/pools.rs"
  click RsSimulator "https://github.com/solidquant/mev-templates/blob/main/rust/src/simulator.rs"
  click RsStreams "https://github.com/solidquant/mev-templates/blob/main/rust/src/streams.rs"
  click RsStrategy "https://github.com/solidquant/mev-templates/blob/main/rust/src/strategy.rs"
  click RsUtils "https://github.com/solidquant/mev-templates/blob/main/rust/src/utils.rs"
  click RsLib "https://github.com/solidquant/mev-templates/blob/main/rust/src/lib.rs"
  click RsMain "https://github.com/solidquant/mev-templates/blob/main/rust/src/main.rs"
  click RsABI "https://github.com/solidquant/mev-templates/tree/main/rust/src/abi/"
  click RsBench "https://github.com/solidquant/mev-templates/blob/main/rust/benches/benchmarks.rs"
```
