mev-beta/docs/archive/PRODUCTION_DEPLOYMENT_GUIDE.md

# MEV Bot V2 - Production Deployment Safety Guide

**STATUS:** ⚠️ **PRE-PRODUCTION - NOT SAFE FOR LARGE CAPITAL YET**

---

## 🚨 CRITICAL: Read This First

**DO NOT deploy to production with significant capital until:**
1. ✅ All safety mechanisms are tested
2. ✅ Profit calculations validated with known scenarios
3. ✅ 24+ hours of dry-run monitoring completed
4. ✅ Emergency stop tested and working
5. ✅ Monitoring/alerting configured and tested

**Current Status:** Bot is in TESTING phase. Suitable for small-scale testing only.

---

## Safety-First Deployment Sequence

### Phase 1: Dry-Run Validation (Days 1-3)

**Objective:** Validate detection without risking capital

**Configuration:**
```bash
DRY_RUN_MODE=true
ENABLE_EXECUTION=false
ENABLE_SIMULATION=true
MIN_PROFIT_WEI=50000000000000000  # 0.05 ETH - conservative
```

**Actions:**
1. Deploy with `.env.production.safe` configuration
2. Monitor logs for 24+ hours continuously
3. Verify opportunities are detected correctly
4. Check profit calculations match expected values
5. Ensure no false positives

**Success Criteria:**
- ✅ Bot runs stable for 24+ hours
- ✅ No crashes or errors
- ✅ Profit calculations look reasonable
- ✅ Pool data updates correctly

**DO NOT PROCEED** if success criteria not met.

---

### Phase 2: Testnet Validation (Days 4-7)

**Objective:** Test execution logic without real money

**Configuration:**
```bash
# Use Arbitrum Sepolia/Goerli testnet
CHAIN_ID=421614  # Arbitrum Sepolia
RPC_URL=https://sepolia-rollup.arbitrum.io/rpc
ENABLE_EXECUTION=true
MAX_POSITION_SIZE=100000000000000000  # 0.1 ETH testnet funds
```

**Actions:**
1. Get testnet ETH from faucet
2. Deploy on testnet
3. Execute actual transactions
4. Monitor profit/loss carefully
5. Test circuit breaker triggers
6. Test emergency stop

**Success Criteria:**
- ✅ Transactions execute successfully
- ✅ Profit calculations accurate (compare pre/post trade)
- ✅ Circuit breaker stops trading after losses
- ✅ Emergency stop works immediately
- ✅ No unexpected behavior

**DO NOT PROCEED** to mainnet if any failures.

---

### Phase 3: Mainnet Micro-Testing (Days 8-14)

**Objective:** Validate on mainnet with minimal capital

**Configuration:**
```bash
# Mainnet with strict safety limits
CHAIN_ID=42161
RPC_URL=https://arb-mainnet.g.alchemy.com/v2/YOUR_KEY  # Archive RPC required!
ENABLE_EXECUTION=true
MAX_POSITION_SIZE=100000000000000000  # 0.1 ETH - TINY positions
MAX_DAILY_VOLUME=500000000000000000   # 0.5 ETH daily max
MAX_TRADES_PER_HOUR=5                 # Rate limit
```

**Capital Required:** 0.5-1 ETH (amount you're willing to lose)

**Actions:**
1. Fund wallet with SMALL amount only
2. Enable execution with strict limits
3. Monitor CONTINUOUSLY for first 24 hours
4. Track every trade manually
5. Calculate actual profit/loss
6. Verify gas costs match predictions

**Success Criteria:**
- ✅ Net profitable over 7 days (including gas)
- ✅ No unexpected losses
- ✅ Circuit breaker triggers appropriately
- ✅ Monitoring/alerts working

**IF UNPROFITABLE:** Stop immediately, debug issues

---

### Phase 4: Gradual Scale-Up (Weeks 3-8)

**Objective:** Slowly increase capital if consistently profitable

**Only if Phase 3 was net profitable:**

| Week | Max Position | Max Daily Volume | Notes |
|------|--------------|------------------|-------|
| 3 | 0.25 ETH | 1 ETH | Still testing |
| 4 | 0.5 ETH | 2 ETH | Monitor closely |
| 5 | 1 ETH | 5 ETH | If profitable, continue |
| 6 | 2 ETH | 10 ETH | Standard operation |
| 7-8 | 3-5 ETH | 20 ETH | Mature operation |

**Rules:**
- If ANY week is unprofitable, revert to previous week's limits
- Track ROI weekly - stop if declining
- Monitor gas costs - stop if eating profits

---

## 🛡️ Safety Mechanisms

### 1. Circuit Breaker

**Triggers:**
- 3 consecutive losing trades
- Hourly loss > 0.1 ETH
- Daily loss > 0.5 ETH

**Action:** Immediately stop trading for 1 hour cooldown

**Testing:**
```bash
# Manually trigger by creating test scenario
# Verify bot stops and doesn't restart automatically
```

### 2. Emergency Stop

**File-based kill switch:**
```bash
# Create this file to stop bot immediately
touch /tmp/mev-bot-emergency-stop

# Bot checks this file every 10 seconds
# Gracefully stops all operations
```

**Testing:**
```bash
# While bot running in testnet:
touch /tmp/mev-bot-emergency-stop
# Bot should log "Emergency stop detected" and exit within 10s
```

### 3. Position Size Limits

**Prevents large losses from single trade:**
- MAX_POSITION_SIZE enforced before execution
- MAX_DAILY_VOLUME enforced cumulatively
- Transactions rejected if limits exceeded

### 4. Slippage Protection

**Prevents sandwich attacks and price manipulation:**
- MAX_SLIPPAGE_BPS: 100 (1%) - very strict
- Simulation runs before every trade
- Trade rejected if simulated output < expected

### 5. Gas Price Limits

**Prevents overpaying during network congestion:**
- MAX_GAS_PRICE_GWEI: 50 gwei
- Transactions rejected if gas price higher
- Use GAS_PRICE_STRATEGY=safe for lower gas

---

## 📊 Monitoring Requirements

### Essential Metrics to Track

**1. Profitability Metrics**
- Gross profit per trade
- Net profit after gas
- ROI percentage
- Win rate (profitable trades / total trades)

**2. Execution Metrics**
- Trade execution latency
- Gas costs per trade
- Failed transactions
- Successful vs failed trade ratio

**3. Safety Metrics**
- Circuit breaker triggers
- Emergency stops
- Position size violations
- Daily volume tracking

**4. System Health**
- RPC connection status
- WebSocket connection status
- Pool cache size
- Memory/CPU usage

### Monitoring Tools

**Prometheus + Grafana** (included in repo):
```bash
docker-compose up -d prometheus grafana
# Access Grafana at http://localhost:3000
```

**Log Monitoring:**
```bash
# Tail logs in real-time
docker logs -f mev-bot-v2

# Filter for profits
docker logs mev-bot-v2 | grep "profit"

# Filter for errors
docker logs mev-bot-v2 | grep "ERROR\|WARN"
```

**Alerting** (recommended):
- Set up Slack/Discord/Telegram webhook
- Alert on circuit breaker triggers
- Alert on large losses (> 0.05 ETH)
- Alert on system errors

---

## 🔧 Production Infrastructure

### Required Infrastructure

**1. Archive RPC Provider** (CRITICAL)
- ❌ Public RPC insufficient
- ✅ Use: Alchemy, QuickNode, or Infura
- Cost: ~$200-500/month for archive access
- Required for pool discovery and state queries

**2. Private RPC (Recommended)**
- Reduces MEV risk on transaction submission
- Flashbots Protect or private mempool
- Cost: Free (Flashbots) or ~$100/month

**3. Dedicated Server**
- Minimum: 4 CPU cores, 8GB RAM
- Recommended: 8 CPU cores, 16GB RAM
- Low latency network connection to RPC
- Uptime: 99.9%+

**4. Monitoring Stack**
- Prometheus for metrics
- Grafana for visualization
- Alerting service (PagerDuty, Slack, etc.)

---

## ⚠️ Known Limitations & Risks

### Technical Limitations

1. **WebSocket Sequencer Connection**
   - Status: Not fully stable on Anvil fork
   - Impact: May miss some pending transactions
   - Mitigation: Test on live testnet/mainnet

2. **Pool Discovery**
   - Currently uses hardcoded pools for testing
   - Production needs archive RPC for discovery
   - May miss new pools initially

3. **Gas Estimation**
   - Estimates may be inaccurate under high load
   - May overpay or fail transactions
   - Needs more testing

4. **Profit Calculations**
   - Not validated against known scenarios yet
   - Risk of calculation errors
   - MUST test extensively before large capital

### Market Risks

1. **Competition**
   - Other MEV bots may front-run
   - Profits may be lower than expected
   - Need low latency connection

2. **Gas Price Volatility**
   - Network congestion can spike gas
   - May eat into profits
   - Circuit breaker helps limit damage

3. **Smart Contract Risks**
   - DEX contracts could have bugs
   - Pools could be manipulated
   - Use whitelisted pools only initially

4. **Slippage & Sandwich Attacks**
   - Larger trades more susceptible
   - Strict slippage limits help
   - Consider splitting large trades

---

## 📋 Pre-Deployment Checklist

### Infrastructure

- [ ] Archive RPC provider configured and tested
- [ ] Private RPC configured (optional but recommended)
- [ ] Server meets minimum specs
- [ ] Monitoring stack deployed (Prometheus + Grafana)
- [ ] Alerting configured and tested
- [ ] Backup wallet key secured (hardware wallet recommended)

### Configuration

- [ ] `.env.production.safe` reviewed and customized
- [ ] All safety limits set conservatively
- [ ] DRY_RUN_MODE=true initially
- [ ] ENABLE_EXECUTION=false initially
- [ ] Gas limits appropriate
- [ ] Slippage tolerance conservative

### Testing

- [ ] Dry-run completed (24+ hours)
- [ ] Profit calculations validated
- [ ] Circuit breaker tested
- [ ] Emergency stop tested
- [ ] Testnet deployment successful
- [ ] Manual trades verified profitable

### Monitoring

- [ ] Grafana dashboards configured
- [ ] Alerts set up for losses
- [ ] Alerts set up for circuit breaker
- [ ] Alerts set up for system errors
- [ ] Log rotation configured
- [ ] Backup/restore tested

### Safety

- [ ] Emergency stop file path configured
- [ ] Circuit breaker thresholds set
- [ ] Position limits conservative
- [ ] Daily volume limits set
- [ ] Gas price limits set
- [ ] Whitelist/blacklist configured (if needed)

---

## 🚀 Deployment Commands

### Step 1: Build Docker Image

```bash
docker build -t mev-bot-v2:production .
```

### Step 2: Configure Environment

```bash
# Copy safe configuration
cp .env.production.safe .env.production

# Edit with your keys and RPC endpoints
nano .env.production

# CRITICAL: Verify DRY_RUN_MODE=true for first deployment
grep DRY_RUN_MODE .env.production
```

### Step 3: Deploy with Docker

```bash
# Start in dry-run mode
docker run -d \
  --name mev-bot-v2-production \
  --restart unless-stopped \
  --env-file .env.production \
  -v $(pwd)/logs:/app/logs \
  -p 9090:9090 \
  mev-bot-v2:production

# Monitor logs in real-time
docker logs -f mev-bot-v2-production
```

### Step 4: Monitor & Validate

```bash
# Check status
docker ps | grep mev-bot

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

# Check for errors
docker logs mev-bot-v2-production | grep ERROR | tail -50

# Monitor circuit breaker status
docker logs mev-bot-v2-production | grep "circuit_breaker"
```

### Step 5: Emergency Stop (if needed)

```bash
# Method 1: File-based stop
docker exec mev-bot-v2-production touch /tmp/mev-bot-emergency-stop

# Method 2: Graceful stop
docker stop mev-bot-v2-production

# Method 3: Immediate stop
docker kill mev-bot-v2-production
```

---

## 📞 Support & Troubleshooting

### Common Issues

**Issue: Bot not finding opportunities**
- Check RPC connection is working
- Verify pool discovery running
- Check MIN_PROFIT_WEI isn't too high
- Review MIN_POOL_LIQUIDITY setting

**Issue: High gas costs eating profits**
- Lower MAX_GAS_PRICE_GWEI
- Use GAS_PRICE_STRATEGY=safe
- Increase MIN_PROFIT_WEI threshold

**Issue: Circuit breaker triggering frequently**
- Review trade profitability
- Check profit calculations
- Verify gas estimation accurate
- May need to adjust MIN_PROFIT_WEI higher

**Issue: Missing transactions**
- Check WebSocket connection stable
- Verify archive RPC working
- Review worker count settings
- Check buffer size adequate

### Logs to Check

```bash
# All errors
docker logs mev-bot-v2-production 2>&1 | grep "ERROR"

# Profitable trades
docker logs mev-bot-v2-production | grep "profit.*ETH"

# Circuit breaker events
docker logs mev-bot-v2-production | grep "circuit_breaker"

# RPC issues
docker logs mev-bot-v2-production | grep "RPC\|connection"
```

---

## ⚖️ Legal & Compliance

**DISCLAIMER:**
- MEV trading may be considered front-running in some jurisdictions
- Ensure compliance with local regulations
- This software is provided AS-IS with no warranties
- Use at your own risk
- Author not responsible for losses

**Recommendations:**
- Consult legal counsel before deployment
- Understand local securities/trading laws
- Consider tax implications of trading
- Maintain detailed trade records

---

## 📝 Post-Deployment Monitoring

### Daily Checks (First Week)

- [ ] Review all trades from last 24 hours
- [ ] Calculate net profit/loss (including gas)
- [ ] Check circuit breaker events
- [ ] Review error logs
- [ ] Verify RPC connection stable
- [ ] Check wallet balance

### Weekly Checks (Ongoing)

- [ ] Calculate weekly ROI
- [ ] Review most/least profitable pools
- [ ] Analyze gas cost trends
- [ ] Review system resource usage
- [ ] Update pool blacklist if needed
- [ ] Adjust parameters based on performance

### Monthly Reviews

- [ ] Comprehensive profit/loss analysis
- [ ] Compare to market conditions
- [ ] Review and update safety limits
- [ ] Update dependencies/security patches
- [ ] Backup configuration and logs
- [ ] Review and optimize strategies

---

## 🎯 Success Criteria

**Minimum viable production deployment:**
- ✅ Profitable for 7+ consecutive days
- ✅ ROI > 5% after gas costs
- ✅ Win rate > 60%
- ✅ No circuit breaker triggers from bugs
- ✅ Emergency stop tested and working
- ✅ Monitoring functional and alerting

**Ready for capital scale-up:**
- ✅ Profitable for 30+ days
- ✅ ROI > 10% monthly
- ✅ Win rate > 70%
- ✅ All safety mechanisms tested
- ✅ No unexpected losses
- ✅ Stable system performance

---

**Last Updated:** 2025-11-10
**Version:** 1.0.0-rc1
**Status:** Pre-Production