How flashbots/simple-arbitrage works
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