# flashbots/simple-arbitrage architecture

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

- Interactive diagram: https://gitdiagram.com/flashbots/simple-arbitrage
- Repository: https://github.com/flashbots/simple-arbitrage

## Overview

##### Project Type and Purpose
- This is a backend‐only, command-line Ethereum “searcher” bot written in TypeScript.
- Its goal is to discover on-chain arbitrage opportunities (mainly on UniswapV2 ETH pairs), rate them, and submit atomic bundles via the Flashbots relay to miners.
- It also includes a small Solidity contract (`BundleExecutor.sol`) that it uses to execute swaps on-chain in one atomic transaction.

##### File Structure Analysis
Top-level files:
- contracts/ – contains the `BundleExecutor.sol` contract.
- src/ – core TypeScript modules:
– `Arbitrage.ts` – logic to scan and evaluate opportunities
– `EthMarket.ts` – abstraction over an Ethereum‐based market/pair
– `UniswappyV2EthPair.ts` – UniswapV2 ETH‐pair pricing and swap calls
– `abi.ts` & `addresses.ts` – ABIs and on-chain addresses
– `index.ts` – entry point, reads env vars, kicks off the loop
– `utils.ts` – helper functions (e.g., BigNumber math)
- test/ – Jasmine unit tests for core modules
- Config files: `tsconfig.json`, `package.json`, ESLint, GitHub Actions workflow.

##### Key Components
a. Bot Application (Node.js/TypeScript)
- Modules: Arbitrage Scanner, Market Adapter (UniswapV2), Transaction Builder, Flashbots Client, Healthcheck Client
b. External RPC Services
- Ethereum RPC Endpoint (e.g., Infura, Alchemy)
- Flashbots Relay RPC
- (Optional) Healthcheck URL
c. On-chain Components
- Deployed `BundleExecutor` contract
- UniswapV2 Pair Contracts / WETH Token Contract
d. Storage/State
- In-memory state in bot (e.g., latest block, best opportunity)
- No persistent database

##### Interactions and Data Flow
1. Bot polls Ethereum RPC → fetches reserves & block state
2. Bot calls `UniswappyV2EthPair` → computes prices, potential profit
3. `Arbitrage` module → selects best opportunity
4. Bot builds transaction bundle targeting `BundleExecutor` → includes swap calls
5. Bot signs bundle with searcher private key + Flashbots relay signing key
6. Bot submits bundle to Flashbots Relay RPC
7. Flashbots → miner(s) → atomic execution on-chain
8. On success → Bot hits HEALTHCHECK_URL

##### Architectural Patterns & Design Principles
- Separation of concerns:
- Market abstraction (Uniswap) vs. opportunity logic vs. bundling logic.
- Stateless/functional modules: makes testing easy (see test/*.ts).
- Single loop (poll → evaluate → submit) reminiscent of an event-driven microservice.

##### Essential Elements
- “BundleExecutor” deployed contract and UniswapV2 pair contracts on Ethereum mainnet
- Error paths or healthcheck triggers if submission succeeds/fails

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Bot Application Container
    subgraph "Bot Application" 
        direction TB
        Orchestrator["Index.ts\n(Loop Orchestration)"]:::bot
        Scanner["Arbitrage.ts\n(Opportunity Discovery)"]:::bot
        MarketAdapter["EthMarket.ts\n(Market Abstraction)"]:::bot
        UniswapAdapter["UniswappyV2EthPair.ts\n(UniswapV2 Adapter)"]:::bot
        Builder["Transaction Builder\n&amp; Flashbots Client"]:::bot
        Healthcheck["Healthcheck Client"]:::bot
        ABI["ABI Definitions\n(abi.ts)"]:::bot
        Addrs["On-chain Addresses\n(addresses.ts)"]:::bot
        Utils["Utility Helpers\n(utils.ts)"]:::bot
        State[(In-Memory State)]:::storage

        Orchestrator -->|calls| Scanner
        Scanner -->|uses| MarketAdapter
        MarketAdapter -->|calls| UniswapAdapter
        Orchestrator -->|references| ABI
        Orchestrator -->|references| Addrs
        Orchestrator -->|calls| Utils
        Orchestrator -->|builds bundle| Builder
        Orchestrator -->|updates| State
        Builder -->|on success/fail| Healthcheck
    end

    %% External Services
    subgraph "External RPC Services" 
        direction TB
        EthRPC["Ethereum RPC Endpoint\n(eth_call)"]:::external
        Flashbots["Flashbots Relay\n(eth_sendBundle)"]:::external
        HealthURL["Healthcheck URL\n(HTTP ping)"]:::external
    end

    %% On-chain Contracts
    subgraph "On-Chain Components"
        direction TB
        BundleExecutor["BundleExecutor.sol\n(Deployed Executor)"]:::contract
        UniswapPair["UniswapV2 Pair / WETH\n(Deployed Contracts)"]:::contract
    end

    %% Tests
    subgraph "Unit Tests" 
        direction TB
        TestArb["Arbitrage.test.ts"]:::test
        TestUni["UniswappyV2EthPair.test.ts"]:::test
    end

    %% Data Flows
    Scanner -->|eth_call| EthRPC
    MarketAdapter -->|eth_call| EthRPC
    Builder -->|eth_sendBundle| Flashbots
    Flashbots -->|executes atomic tx| BundleExecutor
    BundleExecutor -->|swaps on Uniswap| UniswapPair
    Builder -->|HTTP ping| HealthURL
    Healthcheck -.->|dashed ping| HealthURL

    %% Tests interactions (optional)
    TestArb -.-> Scanner
    TestUni -.-> UniswapAdapter

    %% Click Events
    click Orchestrator "https://github.com/flashbots/simple-arbitrage/blob/master/src/index.ts"
    click Builder "https://github.com/flashbots/simple-arbitrage/blob/master/src/index.ts"
    click Healthcheck "https://github.com/flashbots/simple-arbitrage/blob/master/src/index.ts"
    click Scanner "https://github.com/flashbots/simple-arbitrage/blob/master/src/Arbitrage.ts"
    click MarketAdapter "https://github.com/flashbots/simple-arbitrage/blob/master/src/EthMarket.ts"
    click UniswapAdapter "https://github.com/flashbots/simple-arbitrage/blob/master/src/UniswappyV2EthPair.ts"
    click ABI "https://github.com/flashbots/simple-arbitrage/blob/master/src/abi.ts"
    click Addrs "https://github.com/flashbots/simple-arbitrage/blob/master/src/addresses.ts"
    click Utils "https://github.com/flashbots/simple-arbitrage/blob/master/src/utils.ts"
    click BundleExecutor "https://github.com/flashbots/simple-arbitrage/blob/master/contracts/BundleExecutor.sol"
    click TestArb "https://github.com/flashbots/simple-arbitrage/blob/master/test/Arbitrage.test.ts"
    click TestUni "https://github.com/flashbots/simple-arbitrage/blob/master/test/UniswappyV2EthPair.test.ts"

    %% Styles
    classDef bot fill:#ccffcc,stroke:#2d572c,color:#000;
    classDef external fill:#cce5ff,stroke:#1a5eab,color:#000;
    classDef contract fill:#ffe5cc,stroke:#ab5e1a,color:#000;
    classDef storage fill:#e5ccff,stroke:#5e1aab,color:#000;
    classDef test fill:#f0f0f0,stroke:#555,color:#000;
```
