- Executive Summary
- Project Overview
- Architecture and Components
3.1. Environment & Configuration
3.2. Smart Contracts
3.3. Python Modules
3.3.1. APIConfig
3.3.2. MarketMonitor
3.3.3. TransactionCore
3.3.4. StrategyNet
3.3.5. NonceCore
3.3.6. SafetyNet
3.3.7. MainCore
3.3.8. ABI Registry & Logging
3.4. User Interface / Dashboard - Key Features and Statistics
4.1. Flashloan and Arbitrage Strategies
4.2. Market Monitoring & Machine Learning
4.3. Transaction Execution and Safety
4.4. Testing and Reliability - Project Dependencies and Ecosystem
- Future Enhancements and Considerations
- Installation, Configuration & Usage
7.1. Prerequisites
7.2. Installation Steps
7.3. Configuration
7.4. Usage
7.5. Contributing
7.6. License - Appendix: Charts and Diagrams
- Disclaimer
ON1Builder is a versatile Maximal Extractable Value (MEV) flashloan arbitrage bot operating on Ethereum's mainnet and testnets. It integrates:
- Smart‑contract flashloans via Aave V3
- Automated DEX routing on Uniswap and Sushiswap
- Real‑time market data aggregation through multiple free‑tier APIs
- Machine learning price predictions
- Asynchronous, modular Python core with robust nonce & safety management
- Web‑based dashboard for monitoring and control
This end‑to‑end platform empowers traders to deploy atomic arbitrage and sandwich strategies with maximum reliability and minimum configuration overhead.
-
Smart Contracts:
A Solidity contract ('SimpleFlashloan.sol') that manages flashloan execution, request logging, and fallback safety mechanisms. -
Configuration & Environment:
A robust environment system using a extensive .env file combined with JSON files (for ABI definitions and token mappings) to provide a centralized and validated configuration. -
Python Application Layer:
Multiple asynchronous modules handle market data fetching, transaction creation and execution, risk management, and a reinforcement‑learning mechanism for selecting optimal MEV strategies. -
User Interface:
A responsive HTML/CSS/JavaScript dashboard displays real‑time system status, performance metrics, and provides control actions (start/stop). -
Testing Suite:
A comprehensive set of tests (unit, integration, and end‑to‑end) ensures each module and function operates correctly.
-
.env File & Dependencies:
The project uses a .env file to set critical parameters such as gas limits, slippage tolerances, API keys, and network endpoints. The requirements.txt provides a list of all dependencies (e.g., Flask, Web3, scikit‑learn, Pandas). -
Configuration Module (configuration.py):
Responsible for loading and validating environment variables, resolving file paths (for ABI, tokens, etc.), and creating required directories for ML model storage and logs.
-
SimpleFlashloan.sol:
Implements Aave‑based flashloan functionality with:- fn_RequestFlashLoan: Iterates over a list of tokens to request a flashloan.
- executeOperation: Executes the flashloan logic and handles exceptions.
- Withdrawal Functions: Allows the owner to withdraw tokens or ETH.
-
ABI Files:
Various JSON files supply contract ABIs for ERC20 tokens and protocols like Uniswap, Sushiswap, and Aave.
- apiconfig.py:
Integrates with multiple market data APIs (Binance, CoinGecko, etc.) to fetch both real‑time and historical data. It manages rate‑limiting and caching to ensure data accuracy.
- marketmonitor.py:
Gathers market data continuously, uses a linear regression model to predict price movements, and automates model retraining based on new training data.
- transactioncore.py:
Builds, signs, and executes transactions. It supports modern transaction formats (EIP‑1559), simulates transactions to ensure profitability, and implements MEV strategies such as front‑run, back‑run, and sandwich attacks.
- strategynet.py:
Uses reinforcement learning to dynamically select between various MEV strategies based on historical performance metrics. It adjusts strategy weights using a reward function that factors in profit, execution time, and risk.
- noncecore.py:
Manages sequential nonce assignment with a caching mechanism to handle rapid transaction submissions.
- safetynet.py:
Validates transaction safety by evaluating gas prices, expected profits (using Decimal calculations), and by adjusting slippage tolerance based on network congestion.
- maincore.py:
Acts as the central orchestrator by initializing all components, maintaining the event loop, monitoring system health and memory, and handling graceful shutdowns.
- abiregistry.py:
Loads and validates smart contract ABIs, extracting function signatures for seamless contract interactions. - loggingconfig.py:
Provides a robust logging configuration with colorized output and optional spinner animations for improved readability and debugging.
- Dashboard (ui/index.html):
A modern web dashboard provides live metrics (transaction success rate, gas usage, account balance, etc.) and real-time logs via Socket.IO, allowing users to monitor and control the bot interactively.
| Strategy | Description | Key Parameters |
|---|---|---|
| Flashloan Execution | Requests and executes flashloans using Aave’s protocols | Flashloan amount, asset, referral codes |
| Front-run | Preempts high‑value pending transactions by accelerating gas usage | Gas price multiplier, risk thresholds, predicted price |
| Aggressive & Predictive FR | Uses risk scoring and ML forecasts to preemptively execute trades | Aggressive thresholds; predicted price increase (%) |
| Back-run & Price Dip BR | Executes trades following target transactions to profit on a price dip | Price dip threshold, volume metrics |
| Sandwich Attack | Combines flashloan, front‑run, and back‑run to capture sandwich profits | Integrated multi‑step execution with strict profit margins |
-
Live Data Aggregation:
Collects real‑time prices and volume metrics from multiple APIs with built‑in rate‑limiting and TTL caching. -
ML Model for Price Prediction:
A linear regression model uses historical price, market cap, and volume data (stored in CSV format) to forecast future price movements.
Example training data features:Timestamp Symbol Price (USD) Market Cap Volume (24h) Volatility Liquidity Ratio Price Momentum 1737308400 BTC 106124.00 2.10e+12 7.09e+10 0.045 0.88 0.60 1737308400 ETH 3386.52 4.08e+11 3.23e+10 0.038 0.82 0.65 -
Automatic Model Retraining:
The model is retrained every hour (configurable) when sufficient new data becomes available.
-
Dynamic Transaction Building:
Transactions are built for both legacy and EIP‑1559 types, with dynamic gas limit estimation and risk-adjusted gas pricing. -
Risk Management:
SafetyNet evaluates transactions in real‑time, checking for profitability (after gas costs and slippage) and rejecting transactions that do not meet specified thresholds. -
Nonce Management:
NonceCore ensures that nonces are accurately assigned and updated to prevent collisions in high-frequency transaction scenarios.
-
Comprehensive Test Suite:
More than 40 tests cover unit, integration, and end‑to‑end scenarios, ensuring high system reliability. -
Real‑Time Logging & Health Monitoring:
The system continuously monitors component health and memory usage, with logs streamed to the dashboard for live troubleshooting.
-
Ethereum Connectivity
-
Smart Contracts
-
Data & ML
scikit-learn,pandas,numpy
-
Web/API
- Flask, Flask‑SocketIO, Flask‑CORS
-
Testing
- Pytest, unittest
- Advanced ML: Upgrade to neural nets / time‑series models.
- Strategy Refinement: Add new signals (on‑chain, sentiment).
- Scaling: Parallelize MempoolMonitor & TransactionCore further.
- Security Audits: Third‑party review of smart contracts & core logic.
- Dashboard Analytics: Interactive charting with Plotly or Matplotlib.
- Multi‑Chain: Extend support to other EVM & non‑EVM chains.
🐱💻 Security Warning
Don’t even trust your cats. They're sneaky and can’t be trusted.If you paste your private key in plaintext, congrats — you just gave your wallet the same security as a sticky note on a park bench.
Keep it encrypted, offline, and far away from prying eyes (or “oops” deployments).
Remember: one leak, and your ETH becomes someone else’s exit liquidity.
Not your opsec, not your coins. 🔐😼
- OS: Linux (Ubuntu 20.04+), Windows 10/11, or macOS 12+
- Python: ≥ 3.12
- Hardware: ≥ 4 cores, 32 (min 16) GB RAM, NVMe SSD
- Clients: Geth & Prysm (IPC mode) (NOTE: Syncing requires minimum 1.3TB Storage and can take up to 24hours)
git clone https://github.com/John0n1/ON1Builder.git
cd ON1Builder
python3 -m venv venv
source venv/bin/activate # Linux/macOS
# .\venv\Scripts\activate # Windows
pip install --upgrade pip
pip install -r requirements.txtCopy and edit the example .env:
cp .env.example .env
nano .env# API Keys & Endpoints
ETHERSCAN_API_KEY=YOUR_ETHERSCAN_KEY
INFURA_PROJECT_ID=YOUR_INFURA_PROJECT_ID # Optional
COINGECKO_API_KEY=YOUR_COINGECKO_API_KEY
COINMARKETCAP_API_KEY=YOUR_CMC_API_KEY
CRYPTOCOMPARE_API_KEY=YOUR_CC_API_KEY
# Provider IPC/HTTP/WS
IPC_ENDPOINT=~/ON1Builder/geth.ipc
HTTP_ENDPOINT=http://127.0.0.1:8545
WEBSOCKET_ENDPOINT=wss://127.0.0.1:8545
# Wallet
WALLET_ADDRESS=0xYourEthereumAddress
WALLET_KEY=0xYourPrivateKey # Start clients
# geth and prysm should already be running as per Section 7.4.1/2
# In project root
source venv/bin/activate # or venv\Scripts\activate on Windows
python python/main.py- Monitors mempool for MEV opportunities.
- Logs streamed to dashboard at
http://localhost:5000.
Install and run Geth in IPC-only mode:
# Install Geth on Ubuntu
sudo apt update && sudo apt install -y software-properties-common
sudo add-apt-repository -y ppa:ethereum/ethereum
sudo apt update && sudo apt install -y geth
# Run with snap sync
geth \
--syncmode snap \
--mainnet \
--http=false \
--ipcpath /ON1Builder/geth.ipc \
--cache 12000 \
--maxpeers 80 Install Prysm and run in IPC mode (no JWT):
# Install Prysm
curl https://raw.githubusercontent.com/prysmaticlabs/prysm/master/prysm.sh \
--output prysm.sh && chmod +x prysm.sh
# Run beacon node, linking to Geth IPC
./prysm.sh beacon-chain \
--execution-endpoint=/ON1Builder/geth.ipc \
--mainnet \
--checkpoint-sync-url=https://beaconstate.info \
--genesis-beacon-api-url=https://beaconstate.info| Provider | Free Tier Highlights |
|---|---|
| Infura | 3 million credits/day, 1 API key |
| Coingecko | Free API key, (trial) |
| Etherscan | 100 k calls/day, 5 calls/s |
| CoinMarketCap | Free API key, (trial) |
| Cryptocompare | Free API key, (trial) |
- Open Remix and paste
SimpleFlashloan.sol(importing Aave V3’s base contract). - Compile with Solidity 0.8.10.
- Connect MetaMask (inject Web3) using a free RPC from one of your providers.
- Deploy to mainnet by providing the correct
PoolAddressesProvideraddress for AAVE V3.
See QuickNode’s tutorial for full Remix walkthrough and contract code.
- Fork & branch
- Adhere to PEP8 & add tests
- Submit a detailed PR
- (see
CONTRIBUTING)
- License: MIT (see
LICENSE)
Component Summary
| Component | Function | Location/Module |
|---|---|---|
| Environment Config | Load & validate .env |
configuration.py |
| Smart Contracts | Flashloan & DEX interactions | SimpleFlashloan.sol, abi/ |
| Market Monitor | Data ingestion & ML forecasting | marketmonitor.py |
| Transaction Engine | Tx building, signing & execution | transactioncore.py |
| Strategy Selector | RL‑based MEV strategy selection | strategynet.py |
| Nonce Manager | High‑throughput nonce tracking | noncecore.py |
| Risk Manager | Profit & safety checks | safetynet.py |
| Orchestrator | Main event loop & health checks | maincore.py |
| Dashboard UI | Live metrics & control | ui/index.html |
Data Flow Diagram
Table 2:Performance Metrics (Dynamic Values)
| Metric | Value | Unit |
|---|---|---|
| Transaction Success Rate | 95.6 | % |
| Average Execution Time | 1.35 | seconds |
| Profitability | 0.256 | ETH |
| Gas Usage | 21000 | units |
| Network Congestion | 45.2 | % |
| Slippage | 0.1 | fraction |
| Account Balance | 12.5 | ETH |
| Transactions Executed | 185 | count |
Disclaimer: Use at your own risk—MEV flashloans incur financial risk.