mev-beta/WALLET_SETUP.md

# 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