feat(v2): add Phase 1 deployment automation and wallet setup guide

This commit adds complete automation for Phase 1 (mainnet dry-run) deployment with comprehensive wallet configuration guide. ## New Files ### 1. scripts/deploy_phase1.sh Automated Phase 1 deployment script that: - Validates .env configuration - Checks for PRIVATE_KEY (warns if missing) - Verifies RPC connectivity to Arbitrum mainnet - Creates Phase 1 configuration (.env.phase1) - Deploys bot in dry-run mode (NO execution) - Displays monitoring commands and instructions **Safety Features:** - Forces ENABLE_EXECUTION=false - Forces DRY_RUN_MODE=true - Ultra-conservative detection thresholds - Automatic validation of prerequisites **Usage:** ```bash ./scripts/deploy_phase1.sh ``` ### 2. WALLET_SETUP.md Complete wallet configuration guide covering: **Wallet Options:** - Generate new wallet (recommended for testing) - Use existing wallet (MetaMask export) - Generate deterministic test wallet **Configuration:** - Step-by-step .env setup - Private key format validation - Funding requirements by phase - Balance checking commands **Security Best Practices:** - Never commit .env to git - Use dedicated wallet for bot - Limit funds (0.01-0.5 ETH) - Secure backup procedures - Emergency procedures if compromised **Verification:** - Checklist before deployment - Validation commands - Common issues troubleshooting ## Docker Image Tagging Tagged production-ready build: ```bash mev-bot-v2:phase1-ready (5c5ac1755d03) ``` ## Phase 1 Deployment Workflow 1. **Setup Wallet:** - Generate or import private key - Add to .env file - Verify with validation commands 2. **Run Deployment:** ```bash chmod +x scripts/deploy_phase1.sh ./scripts/deploy_phase1.sh ``` 3. **Monitor (48 hours):** ```bash podman logs -f mev-bot-v2-phase1 podman logs mev-bot-v2-phase1 | grep -i "opportunity" ``` 4. **Assess Results:** - Opportunities detected? - No crashes/errors? - Profit calculations reasonable? 5. **Decision:** - Success → Proceed to Phase 3 (minimal capital) - Failure → Analyze and iterate ## Configuration **Phase 1 Settings (Ultra-Safe):** ``` ENABLE_EXECUTION=false # No trades DRY_RUN_MODE=true # Monitoring only MIN_PROFIT_THRESHOLD=0.001 # Detect more opportunities MAX_POSITION_SIZE_ETH=0.01 # Conservative (not used in dry-run) ``` ## Safety Guarantees **Financial Risk: ZERO** - ENABLE_EXECUTION hardcoded to false - DRY_RUN_MODE hardcoded to true - No transactions will be broadcast - Wallet not required (but recommended for testing) **Purpose:** - Validate arbitrage detection on real mainnet - Verify RPC connectivity stability - Test opportunity quality - Prove profitability potential ## Next Steps After Phase 1 completes successfully (48h): 1. Review `PRODUCTION_DEPLOYMENT.md` for Phase 3 2. Fund wallet with 0.1 ETH for minimal capital test 3. Adjust risk parameters if needed 4. Enable execution with ultra-conservative limits 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-11 01:47:32 +01:00
parent 02e169c0e1
commit 46188f2754
2 changed files with 453 additions and 0 deletions
--- a/WALLET_SETUP.md
+++ b/WALLET_SETUP.md
@@ -0,0 +1,272 @@
+# MEV Bot V2 - Wallet Setup Guide
+
+**IMPORTANT: This guide covers wallet configuration for Phase 1 (dry-run) deployment.**
+
+---
+
+## 🔐 **Wallet Options**
+
+### Option 1: Generate New Wallet (Recommended for Testing)
+
+**Using Foundry (cast):**
+```bash
+# Generate a new random wallet
+cast wallet new
+
+# Output:
+# Successfully created new keypair.
+# Address: 0x1234...
+# Private key: 0xabcdef1234567890...
+```
+
+**Save the output securely:**
+- **Address**: Your wallet's public address (can be shared)
+- **Private Key**: SECRET - never share this!
+
+### Option 2: Use Existing Wallet
+
+If you have an existing wallet, you need the private key in hex format (64 characters, no 0x prefix for some tools).
+
+**Extract private key from MetaMask:**
+1. Open MetaMask
+2. Click three dots menu → Account Details
+3. Click "Export Private Key"
+4. Enter password
+5. Copy the 64-character hex string
+
+**⚠️ WARNING**: Never use wallets with significant funds for testing!
+
+### Option 3: Generate Deterministic Test Wallet
+
+**For development only:**
+```bash
+# Generate from mnemonic
+cast wallet new --mnemonic
+
+# Or use a test mnemonic (DO NOT USE IN PRODUCTION)
+cast wallet new --mnemonic "test test test test test test test test test test test junk"
+```
+
+---
+
+## 📝 **Configure .env File**
+
+### Phase 1 Configuration (Dry-Run - NO Trading)
+
+Edit `.env` file:
+
+```bash
+# === WALLET CONFIGURATION ===
+# Private key without 0x prefix (64 hex characters)
+PRIVATE_KEY=abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890
+
+# === RPC ENDPOINTS (Already configured) ===
+ARBITRUM_RPC_ENDPOINT=wss://arbitrum-mainnet.core.chainstack.com/53c30e7a941160679fdcc396c894fc57
+ARBITRUM_WS_ENDPOINT=wss://arbitrum-mainnet.core.chainstack.com/53c30e7a941160679fdcc396c894fc57
+
+# === SAFETY SETTINGS (CRITICAL) ===
+ENABLE_EXECUTION=false   # MUST be false for Phase 1
+DRY_RUN_MODE=true        # MUST be true for Phase 1
+```
+
+**Validation:**
+```bash
+# Check private key is set
+grep "^PRIVATE_KEY=" .env
+
+# Verify it's not the placeholder
+grep "^PRIVATE_KEY=" .env | grep -v "???"
+
+# Confirm dry-run is enabled
+grep "DRY_RUN_MODE=true" .env
+```
+
+---
+
+## 💰 **Fund Wallet (Phase 1)**
+
+### For Phase 1 (Dry-Run):
+**NO FUNDING REQUIRED** - Bot will not execute trades.
+
+However, a small amount of ETH helps with testing:
+- **Recommended**: 0.001-0.01 ETH (for RPC call costs, if any)
+- **Purpose**: Validation, not trading
+
+### For Phase 3 (Live Trading):
+When ready to enable execution (AFTER Phase 1 succeeds):
+- **Minimum**: 0.1 ETH
+- **Recommended**: 0.1-0.5 ETH
+- **Purpose**: Gas costs + small arbitrage positions
+
+**Bridge ETH to Arbitrum:**
+1. Use official Arbitrum bridge: https://bridge.arbitrum.io/
+2. Or use exchanges: Binance, Coinbase, etc. (withdraw directly to Arbitrum)
+
+**Check Balance:**
+```bash
+# Using cast
+cast balance <YOUR_ADDRESS> --rpc-url https://arb1.arbitrum.io/rpc
+
+# Using the bot's RPC
+WALLET_ADDRESS=$(cast wallet address --private-key $PRIVATE_KEY)
+cast balance $WALLET_ADDRESS --rpc-url https://arb1.arbitrum.io/rpc
+```
+
+---
+
+## ✅ **Verification Checklist**
+
+Before deploying:
+
+- [ ] **Private key configured** in .env
+- [ ] **No "???" placeholder** in PRIVATE_KEY
+- [ ] **DRY_RUN_MODE=true** (for Phase 1)
+- [ ] **ENABLE_EXECUTION=false** (for Phase 1)
+- [ ] **Wallet address derived** and noted down
+- [ ] **Balance checked** (optional for Phase 1)
+- [ ] **RPC connectivity tested**
+
+**Verification Script:**
+```bash
+# Extract wallet address from private key
+WALLET_ADDRESS=$(cast wallet address --private-key $(grep "^PRIVATE_KEY=" .env | cut -d'=' -f2))
+echo "Wallet Address: $WALLET_ADDRESS"
+
+# Check balance
+cast balance $WALLET_ADDRESS --rpc-url https://arb1.arbitrum.io/rpc
+
+# Test RPC connectivity
+cast block-number --rpc-url $(grep "^ARBITRUM_RPC_ENDPOINT=" .env | cut -d'=' -f2)
+```
+
+---
+
+## 🔒 **Security Best Practices**
+
+### Critical Security Rules:
+
+1. **NEVER commit .env to git**
+   - .env is in .gitignore
+   - Double-check before git push
+
+2. **NEVER share private key**
+   - Not in Discord, Telegram, email, etc.
+   - Not in screenshots or logs
+
+3. **Use dedicated wallet**
+   - Don't use personal wallet with significant funds
+   - Create separate wallet just for MEV bot
+
+4. **Limit funds**
+   - Phase 1: 0-0.01 ETH
+   - Phase 3: 0.1-0.5 ETH maximum
+   - Never deposit more than max daily volume + gas buffer
+
+5. **Monitor continuously**
+   - Check balance every 4 hours during Phase 1
+   - Set up alerts for balance changes
+
+6. **Backup securely**
+   - Save private key in password manager
+   - Write down on paper and store safely
+   - NEVER save in cloud storage unencrypted
+
+### Access Control:
+
+```bash
+# Restrict .env file permissions
+chmod 600 .env
+
+# Only owner can read/write
+ls -la .env
+# -rw------- 1 user user 1234 date .env
+```
+
+---
+
+## 🚨 **Emergency Procedures**
+
+### If Private Key Compromised:
+
+1. **Immediately transfer funds** to safe wallet:
+```bash
+# Transfer all ETH to safe address
+cast send <SAFE_ADDRESS> \
+  --value $(cast balance <COMPROMISED_ADDRESS>) \
+  --private-key <COMPROMISED_PRIVATE_KEY> \
+  --rpc-url https://arb1.arbitrum.io/rpc
+```
+
+2. **Stop bot**:
+```bash
+podman stop mev-bot-v2-phase1
+```
+
+3. **Generate new wallet**:
+```bash
+cast wallet new
+```
+
+4. **Update .env** with new private key
+
+5. **Never use compromised wallet again**
+
+### If Wallet Drained:
+
+1. **Stop bot immediately**
+2. **Check transaction history** on Arbiscan
+3. **Analyze what happened**
+4. **Don't add more funds** until root cause found
+
+---
+
+## 📞 **Support**
+
+### Common Issues:
+
+**"Invalid private key" error:**
+- Ensure 64 hex characters (no 0x prefix in .env)
+- Check for spaces or newlines in .env
+- Verify key is valid: `cast wallet address --private-key <KEY>`
+
+**"Insufficient funds" error (Phase 1):**
+- Should not occur in dry-run mode
+- If it does, add 0.001 ETH for RPC call costs
+
+**"Cannot derive address" error:**
+- Private key format incorrect
+- Try adding/removing 0x prefix
+- Regenerate wallet if unsure
+
+### Validation Commands:
+
+```bash
+# Verify private key format
+PRIVATE_KEY=$(grep "^PRIVATE_KEY=" .env | cut -d'=' -f2)
+echo ${#PRIVATE_KEY}  # Should be 64
+
+# Derive and display address
+cast wallet address --private-key $PRIVATE_KEY
+
+# Test signing (doesn't broadcast)
+cast wallet sign "test" --private-key $PRIVATE_KEY
+```
+
+---
+
+## ✅ **You're Ready When:**
+
+- [x] Private key configured in .env
+- [x] Wallet address derived successfully
+- [x] RPC connectivity verified
+- [x] DRY_RUN_MODE=true confirmed
+- [x] ENABLE_EXECUTION=false confirmed
+- [x] .env file permissions secured (chmod 600)
+- [x] Backup of private key created and stored safely
+
+**Next Step**: Run `./scripts/deploy_phase1.sh`
+
+---
+
+**Last Updated**: 2025-11-11
+**For**: MEV Bot V2 - Phase 1 Deployment
--- a/scripts/deploy_phase1.sh
+++ b/scripts/deploy_phase1.sh
@@ -0,0 +1,181 @@
+#!/bin/bash
+# MEV Bot V2 - Phase 1 Deployment Script (Mainnet Dry-Run)
+# This script deploys the bot in monitoring-only mode to validate arbitrage detection
+
+set -e
+
+# Colors for output
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+echo -e "${GREEN}========================================${NC}"
+echo -e "${GREEN}MEV Bot V2 - Phase 1 Deployment${NC}"
+echo -e "${GREEN}Mode: Mainnet Dry-Run (48 hours)${NC}"
+echo -e "${GREEN}========================================${NC}"
+echo ""
+
+# Check if .env exists
+if [ ! -f .env ]; then
+    echo -e "${RED}ERROR: .env file not found${NC}"
+    echo "Please create .env file with required configuration"
+    exit 1
+fi
+
+# Check for PRIVATE_KEY
+if ! grep -q "^PRIVATE_KEY=" .env || grep -q "^PRIVATE_KEY=$" .env || grep -q "^PRIVATE_KEY=???$" .env; then
+    echo -e "${YELLOW}WARNING: PRIVATE_KEY not configured in .env${NC}"
+    echo ""
+    echo "To generate a new wallet:"
+    echo "  cast wallet new"
+    echo ""
+    echo "To use existing wallet, add to .env:"
+    echo "  PRIVATE_KEY=<your_64_character_hex_key>"
+    echo ""
+    read -p "Continue without private key? (bot will not be able to execute trades) [y/N]: " confirm
+    if [[ ! $confirm =~ ^[Yy]$ ]]; then
+        exit 1
+    fi
+fi
+
+# Verify RPC connectivity
+echo -e "${YELLOW}Verifying RPC connectivity...${NC}"
+RPC_URL=$(grep "^ARBITRUM_RPC_ENDPOINT=" .env | cut -d'=' -f2)
+if [ -z "$RPC_URL" ]; then
+    RPC_URL="https://arb1.arbitrum.io/rpc"
+fi
+
+if command -v cast &> /dev/null; then
+    if cast block-number --rpc-url "$RPC_URL" &> /dev/null; then
+        BLOCK=$(cast block-number --rpc-url "$RPC_URL")
+        echo -e "${GREEN}✓ RPC connected - Block: $BLOCK${NC}"
+    else
+        echo -e "${RED}✗ RPC connection failed${NC}"
+        echo "Please verify ARBITRUM_RPC_ENDPOINT in .env"
+        exit 1
+    fi
+else
+    echo -e "${YELLOW}⚠ Cannot verify RPC (cast not installed)${NC}"
+fi
+
+# Stop existing container if running
+echo ""
+echo -e "${YELLOW}Checking for existing deployment...${NC}"
+if podman ps -a | grep -q "mev-bot-v2-phase1"; then
+    echo "Stopping existing container..."
+    podman stop mev-bot-v2-phase1 2>/dev/null || true
+    podman rm mev-bot-v2-phase1 2>/dev/null || true
+fi
+
+# Create Phase 1 environment file
+echo ""
+echo -e "${YELLOW}Creating Phase 1 configuration...${NC}"
+cat > .env.phase1 << 'EOF'
+# Phase 1: Mainnet Dry-Run Configuration
+# Duration: 48 hours minimum
+# Risk: NONE (monitoring only, no execution)
+
+# === SAFETY SETTINGS (ULTRA-CONSERVATIVE) ===
+ENABLE_EXECUTION=false
+DRY_RUN_MODE=true
+ENABLE_SIMULATION=true
+ENABLE_FRONT_RUNNING=false
+
+# === DETECTION THRESHOLDS ===
+MIN_PROFIT_THRESHOLD=0.001      # 0.1% minimum (detect more opportunities)
+MAX_SLIPPAGE_TOLERANCE=0.005    # 0.5% max slippage
+
+# === RISK LIMITS (NOT USED IN DRY-RUN BUT LOGGED) ===
+MAX_POSITION_SIZE_ETH=0.01      # 0.01 ETH
+MAX_DAILY_VOLUME_ETH=0.1        # 0.1 ETH
+MAX_CONSECUTIVE_LOSSES=1        # Stop after 1 loss
+MAX_HOURLY_LOSS_ETH=0.01        # 0.01 ETH hourly
+MAX_DAILY_LOSS_ETH=0.05         # 0.05 ETH daily
+
+# === MONITORING ===
+METRICS_ENABLED=true
+METRICS_PORT=9090
+LOG_LEVEL=info
+EOF
+
+# Merge with base .env
+cp .env .env.phase1.bak
+cat .env .env.phase1 > .env.phase1.merged
+mv .env.phase1.merged .env.phase1
+
+echo -e "${GREEN}✓ Phase 1 configuration created: .env.phase1${NC}"
+
+# Deploy container
+echo ""
+echo -e "${YELLOW}Deploying MEV Bot V2 (Phase 1)...${NC}"
+podman run -d \
+  --name mev-bot-v2-phase1 \
+  --network host \
+  --restart unless-stopped \
+  --env-file .env.phase1 \
+  -v $(pwd)/logs:/app/logs:z \
+  mev-bot-v2:phase1-ready
+
+# Wait for startup
+echo ""
+echo -e "${YELLOW}Waiting for bot to initialize...${NC}"
+sleep 5
+
+# Check if container is running
+if ! podman ps | grep -q "mev-bot-v2-phase1"; then
+    echo -e "${RED}✗ Container failed to start${NC}"
+    echo ""
+    echo "Logs:"
+    podman logs mev-bot-v2-phase1
+    exit 1
+fi
+
+echo -e "${GREEN}✓ Bot deployed successfully${NC}"
+
+# Display initial logs
+echo ""
+echo -e "${GREEN}========================================${NC}"
+echo -e "${GREEN}Initial Bot Logs${NC}"
+echo -e "${GREEN}========================================${NC}"
+podman logs --tail 50 mev-bot-v2-phase1
+
+# Display monitoring instructions
+echo ""
+echo -e "${GREEN}========================================${NC}"
+echo -e "${GREEN}Phase 1 Deployment Complete${NC}"
+echo -e "${GREEN}========================================${NC}"
+echo ""
+echo -e "${YELLOW}Container:${NC} mev-bot-v2-phase1"
+echo -e "${YELLOW}Mode:${NC} Dry-Run (monitoring only, NO trades)"
+echo -e "${YELLOW}Duration:${NC} 48 hours minimum"
+echo ""
+echo -e "${GREEN}Monitoring Commands:${NC}"
+echo "  # View real-time logs"
+echo "  podman logs -f mev-bot-v2-phase1"
+echo ""
+echo "  # Check for opportunities"
+echo "  podman logs mev-bot-v2-phase1 | grep -i 'opportunity'"
+echo ""
+echo "  # Check for errors"
+echo "  podman logs mev-bot-v2-phase1 | grep -i 'error'"
+echo ""
+echo "  # View safety configuration"
+echo "  podman logs mev-bot-v2-phase1 | grep -A20 'SAFETY CONFIGURATION'"
+echo ""
+echo -e "${GREEN}Emergency Stop:${NC}"
+echo "  # Method 1: Graceful shutdown"
+echo "  podman exec mev-bot-v2-phase1 touch /tmp/mev-bot-emergency-stop"
+echo ""
+echo "  # Method 2: Immediate stop"
+echo "  podman stop mev-bot-v2-phase1"
+echo ""
+echo -e "${YELLOW}Next Steps:${NC}"
+echo "1. Monitor logs every 4 hours"
+echo "2. Look for arbitrage opportunities being detected"
+echo "3. Verify no crashes or connection issues"
+echo "4. After 48 hours, review logs and assess if opportunities exist"
+echo "5. If successful, proceed to Phase 3 (minimal capital test)"
+echo ""
+echo -e "${RED}IMPORTANT: DO NOT enable ENABLE_EXECUTION until Phase 1 validates opportunities${NC}"
+echo ""