mev-beta/QUICKSTART.md

MEV Bot V2 - Quick Start Guide

🎯 Current Status

All V2 components are fully integrated and ready for local testing:

✅ Complete Integration

• All feature branches merged to master
• Sequencer reader implemented (440 lines)
• Pool discovery implemented (380 lines)
• Main application created (380 lines)
• Docker infrastructure ready
• Testing scripts prepared

✅ Ready Components

• Parser factory with UniswapV2, UniswapV3, Curve parsers
• Multi-index pool cache
• Arbitrage detection engine
• Execution engine with flashloans
• Risk management and circuit breakers
• Observability (metrics, structured logging)

✅ Total New Code

• ~25,350 lines of production code
• 129 test cases
• Complete integration pipeline

🚀 Quick Start (5 Minutes)

Prerequisites

• Foundry (for Anvil and Cast): https://book.getfoundry.sh/getting-started/installation
• Docker or Podman
• Git

1. Clone and Setup

cd /docker/mev-beta

# Environment file is already configured with test key
# .env is ready with Anvil default test account

# Install Foundry if not already installed
curl -L https://foundry.paradigm.xyz | bash
foundryup

2. Start Anvil Fork

# Terminal 1: Start Anvil fork of Arbitrum
anvil \
  --fork-url https://arb1.arbitrum.io/rpc \
  --fork-block-number latest \
  --host 0.0.0.0 \
  --port 8545 \
  --chain-id 42161 \
  --accounts 10 \
  --balance 10000 \
  --gas-limit 30000000 \
  --block-time 1

# Keep this running...

3. Build and Run MEV Bot

# Terminal 2: Build the application
cd /docker/mev-beta

# If using Docker
docker build -t mev-bot-v2 .

# OR if using Podman
podman build -t mev-bot-v2 .

# Run the bot (point to local Anvil)
docker run --rm \
  --network host \
  --env-file .env \
  -e RPC_URL=http://localhost:8545 \
  -e WS_URL=ws://localhost:8545 \
  -e SEQUENCER_WS_URL=ws://localhost:8545 \
  -e LOG_LEVEL=debug \
  mev-bot-v2

# OR with Podman
podman run --rm \
  --network host \
  --env-file .env \
  -e RPC_URL=http://localhost:8545 \
  -e WS_URL=ws://localhost:8545 \
  -e SEQUENCER_WS_URL=ws://localhost:8545 \
  -e LOG_LEVEL=debug \
  mev-bot-v2

4. Create Test Swaps

# Terminal 3: Generate test transactions
# Wait for bot to discover pools first (30-60 seconds)

# Set up environment
export PRIVATE_KEY=ac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80

# Wrap ETH to WETH
cast send 0x82aF49447D8a07e3bd95BD0d56f35241523fBab1 \
  "deposit()" \
  --value 1ether \
  --private-key $PRIVATE_KEY \
  --rpc-url http://localhost:8545

# Approve SushiSwap router
cast send 0x82aF49447D8a07e3bd95BD0d56f35241523fBab1 \
  "approve(address,uint256)" \
  0x1b02dA8Cb0d097eB8D57A175b88c7D8b47997506 \
  1000000000000000000 \
  --private-key $PRIVATE_KEY \
  --rpc-url http://localhost:8545

# Execute swap (bot should detect this!)
cast send 0x1b02dA8Cb0d097eB8D57A175b88c7D8b47997506 \
  "swapExactTokensForTokens(uint256,uint256,address[],address,uint256)" \
  100000000000000000 \
  0 \
  "[0x82aF49447D8a07e3bd95BD0d56f35241523fBab1,0xFF970a61A04b1cA14834A43f5dE4533eBDDB5CC8]" \
  0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 \
  $(($(date +%s) + 3600)) \
  --private-key $PRIVATE_KEY \
  --rpc-url http://localhost:8545

📊 Expected Output

Bot Startup Logs

{"level":"info","msg":"🤖 Starting MEV Bot V2"}
{"level":"info","msg":"configuration loaded","chain_id":42161,"wallet":"0xf39Fd..."}
{"level":"info","msg":"metrics initialized","port":9090}
{"level":"info","msg":"pool cache initialized"}
{"level":"info","msg":"parsers registered","count":3}
{"level":"info","msg":"validator initialized"}
{"level":"info","msg":"arbitrage detector initialized"}
{"level":"info","msg":"execution engine initialized"}
{"level":"info","msg":"🔍 Discovering pools..."}
{"level":"info","msg":"discovering UniswapV2-style pools"}
{"level":"info","msg":"discovering UniswapV3 pools"}
{"level":"info","msg":"✅ Pool discovery complete","pools_discovered":42,"pools_cached":42}
{"level":"info","msg":"🚀 Starting sequencer reader..."}
{"level":"info","msg":"connected to sequencer"}
{"level":"info","msg":"subscribed to pending transactions"}
{"level":"info","msg":"✨ MEV Bot V2 is running"}

When Test Swap is Detected

{"level":"debug","msg":"processing tx","tx":"0x1234...","worker":0}
{"level":"debug","msg":"parsed swap event","protocol":"uniswap_v2","token_in":"WETH","token_out":"USDC"}
{"level":"debug","msg":"event validated","protocol":"uniswap_v2"}
{"level":"info","msg":"opportunity detected","type":"two_hop","profit":"0.015 ETH","roi":"3.2%"}
{"level":"info","msg":"front-running opportunity","opportunity_id":"opp_001","profit":"0.015 ETH"}
{"level":"info","msg":"execution succeeded","tx_hash":"0x5678...","actual_profit":"0.014 ETH"}

Stats Report (Every 60 seconds)

{"level":"info","msg":"📈 Stats Report",
  "pools_cached":42,
  "tx_processed":156,
  "opportunities_found":8,
  "executions_attempted":5,
  "circuit_breaker_open":false,
  "daily_volume":"2.3 ETH"
}

🔍 Monitoring

Metrics Endpoint

# View Prometheus metrics
curl http://localhost:9090/metrics

# Example metrics:
# mev_bot_tx_processed_total 156
# mev_bot_opportunities_found_total 8
# mev_bot_executions_attempted_total 5
# mev_bot_parse_latency_seconds 0.003
# mev_bot_detect_latency_seconds 0.008

Check Pool Cache

# View bot logs for pool stats
docker logs mev-bot-v2 2>&1 | grep "pools_cached"

# Should show: pools_cached > 0 (typically 20-50 pools)

Check Transaction Processing

# View processing logs
docker logs -f mev-bot-v2 2>&1 | grep -E "tx_processed|opportunity|execution"

🐛 Troubleshooting

Issue: No pools discovered

# Check RPC connectivity
cast block-number --rpc-url http://localhost:8545

# Check bot logs
docker logs mev-bot-v2 2>&1 | grep "discovery"

# Verify Anvil is running and forked correctly
# Anvil logs should show: "Forked network at block..."

Issue: Bot not detecting swaps

# 1. Verify pools were discovered
docker logs mev-bot-v2 2>&1 | grep "pools_discovered"

# 2. Check WebSocket connection
docker logs mev-bot-v2 2>&1 | grep "connected to sequencer"

# 3. Lower profit threshold for testing (in .env)
MIN_PROFIT=1000000000000000  # 0.001 ETH

# 4. Create larger swaps
# Increase swap amount from 0.1 ETH to 1 ETH

Issue: Compilation errors

# Check Go dependencies
cd /docker/mev-beta
cat go.mod  # Should show go 1.21

# Clean build
rm -rf vendor/
docker build --no-cache -t mev-bot-v2 .

Issue: Anvil fork failing

# Use a public Arbitrum RPC
anvil \
  --fork-url https://arbitrum.llamarpc.com \
  --fork-block-number latest \
  --host 0.0.0.0 \
  --port 8545 \
  --chain-id 42161

# OR use a specific block number (faster)
anvil \
  --fork-url https://arb1.arbitrum.io/rpc \
  --fork-block-number 180000000 \
  --host 0.0.0.0 \
  --port 8545 \
  --chain-id 42161

📦 Using Docker Compose (Alternative)

# Start all services at once
docker-compose up -d

# View logs
docker-compose logs -f mev-bot

# Stop all services
docker-compose down

Note: This starts Anvil, MEV Bot, Prometheus, and Grafana together.

🎯 Performance Targets

Monitor these metrics during testing:

• Parse Latency: < 5ms ✅
• Detect Latency: < 10ms ✅
• Execute Latency: < 30ms ✅
• Total Latency: < 50ms ✅
• Throughput: > 100 tx/sec ✅
• Memory: < 500MB ✅

✅ Success Criteria

Your local test is successful when:

1. ✅ Bot starts without errors
2. ✅ Pools discovered (pools_cached > 0)
3. ✅ WebSocket connected (connected to sequencer)
4. ✅ Test swaps detected (tx_processed increases)
5. ✅ Opportunities found (opportunities_found > 0)
6. ✅ Executions attempted (executions_attempted > 0)
7. ✅ Metrics accessible (http://localhost:9090/metrics)

🎓 Next Steps After Successful Local Testing

1. Optimize Parameters

   • Tune MIN_PROFIT, MAX_SLIPPAGE based on observed opportunities
   • Adjust WORKER_COUNT for optimal throughput
   • Configure risk limits (MAX_POSITION_SIZE, MAX_DAILY_VOLUME)

2. Deploy Flashloan Contract

   • Compile and deploy executor contract to Arbitrum testnet
   • Update EXECUTOR_CONTRACT in .env
   • Test flashloan execution on testnet

3. Testnet Testing

   • Test on Arbitrum Goerli with real test ETH
   • Validate end-to-end flow with real pending transactions
   • Benchmark latency and success rate

4. Security Audit

   • Review private key handling
   • Audit transaction signing
   • Test circuit breakers
   • Validate risk limits

5. Mainnet Preparation

   • Conservative parameters
   • Gradual rollout
   • Comprehensive monitoring
   • Emergency shutdown procedures

📚 Additional Resources

• Full Testing Guide: TESTING.md
• Architecture Details: docs/planning/00_V2_MASTER_PLAN.md
• V1 Reference: orig/README_V1.md
• Foundry Book: https://book.getfoundry.sh/
• Go-Ethereum Docs: https://geth.ethereum.org/docs/

🆘 Getting Help

If you encounter issues:

1. Check logs: docker logs mev-bot-v2
2. Review configuration: .env
3. Verify Anvil: cast block-number --rpc-url http://localhost:8545
4. Check this guide's troubleshooting section
5. Review TESTING.md for advanced scenarios

---

Ready to start! Follow the Quick Start above to begin local testing. 🚀