mev-beta/docs/DEPLOYMENT_GUIDE.md

# Smart Contract Deployment Guide

This guide covers deploying the MEV Bot smart contracts to Arbitrum mainnet and testnet.

## 📋 Table of Contents

- [Prerequisites](#prerequisites)
- [Contract Overview](#contract-overview)
- [Deployment Process](#deployment-process)
- [Testnet Deployment](#testnet-deployment)
- [Mainnet Deployment](#mainnet-deployment)
- [Verification](#verification)
- [Post-Deployment](#post-deployment)
- [Troubleshooting](#troubleshooting)

---

## Prerequisites

### Required Tools

1. **Foundry** (Solidity development toolkit)
```bash
curl -L https://foundry.paradigm.xyz | bash
foundryup
```

2. **Deployer Wallet** with ETH on Arbitrum
   - Testnet: Get test ETH from [Arbitrum Goerli Faucet](https://faucet.triangleplatform.com/arbitrum/goerli)
   - Mainnet: Ensure sufficient ETH for gas (~0.01 ETH recommended)

3. **RPC Endpoint**
   - Free: https://arb1.arbitrum.io/rpc
   - Recommended: [Alchemy](https://www.alchemy.com/), [Chainstack](https://chainstack.com/), or [Infura](https://infura.io/)

4. **Arbiscan API Key** (optional, for verification)
   - Get from: https://arbiscan.io/myapikey

### Environment Setup

Create `.env.deployment` file:

```bash
# Deployer private key (NEVER commit this!)
DEPLOYER_PRIVATE_KEY="0x..."

# RPC endpoint
ARBITRUM_RPC_ENDPOINT="https://arb1.arbitrum.io/rpc"

# Arbiscan API key (for verification)
ARBISCAN_API_KEY="YOUR_API_KEY"
```

**⚠️ SECURITY WARNING:**
- **NEVER** commit private keys to git
- **NEVER** share your `.env.deployment` file
- Use a dedicated deployer wallet (not your main wallet)
- Test on testnet before mainnet deployment

---

## Contract Overview

### Contracts to Deploy

1. **ProductionArbitrageExecutor** (`contracts/ProductionArbitrageExecutor.sol`)
   - Main arbitrage execution contract
   - Handles flash swaps and multi-DEX arbitrage
   - Access controlled with role-based permissions
   - Emergency pause functionality

2. **FlashLoanReceiver** (`contracts/balancer/FlashLoanReceiver.sol`)
   - Balancer flash loan integration
   - Used for capital-efficient arbitrage
   - Flash loan callback handler

### Contract Addresses (Production)

Current deployed addresses (update after deployment):

```yaml
# Arbitrum Mainnet
ProductionArbitrageExecutor: 0xec2a16d5f8ac850d08c4c7f67efd50051e7cfc0b
FlashLoanReceiver: 0x5801ee5c2f6069e0f11cce7c0f27c2ef88e79a95
```

---

## Deployment Process

### Quick Start

1. **Install dependencies:**
```bash
forge install OpenZeppelin/openzeppelin-contracts --no-commit
```

2. **Load environment variables:**
```bash
source .env.deployment
```

3. **Deploy contracts:**
```bash
./scripts/deploy-contracts.sh
```

### Manual Deployment

If you prefer manual control:

#### 1. Compile Contracts
```bash
# Set Foundry to use contracts directory
export FOUNDRY_SRC="contracts"
export FOUNDRY_OUT="out"

# Compile
forge build
```

#### 2. Deploy ProductionArbitrageExecutor
```bash
forge create contracts/ProductionArbitrageExecutor.sol:ProductionArbitrageExecutor \
    --rpc-url "$ARBITRUM_RPC_ENDPOINT" \
    --private-key "$DEPLOYER_PRIVATE_KEY"
```

Save the deployed address!

#### 3. Deploy FlashLoanReceiver
```bash
forge create contracts/balancer/FlashLoanReceiver.sol:FlashLoanReceiver \
    --rpc-url "$ARBITRUM_RPC_ENDPOINT" \
    --private-key "$DEPLOYER_PRIVATE_KEY"
```

#### 4. Verify Contracts (optional)
```bash
# Verify ProductionArbitrageExecutor
./scripts/verify-contracts.sh <arbitrage_executor_address> ProductionArbitrageExecutor

# Verify FlashLoanReceiver
./scripts/verify-contracts.sh <flash_loan_receiver_address> FlashLoanReceiver
```

---

## Testnet Deployment

### Arbitrum Goerli Testnet

1. **Get test ETH:**
```bash
# Visit faucet
open https://faucet.triangleplatform.com/arbitrum/goerli

# Or use bridge from Goerli L1
open https://bridge.arbitrum.io/?l2ChainId=421613
```

2. **Set testnet RPC:**
```bash
export ARBITRUM_RPC_ENDPOINT="https://goerli-rollup.arbitrum.io/rpc"
export NETWORK="arbitrum-goerli"
```

3. **Deploy:**
```bash
./scripts/deploy-contracts.sh
```

4. **Test the deployment:**
```bash
# Check contract is deployed
cast code <contract_address> --rpc-url "$ARBITRUM_RPC_ENDPOINT"

# Should return bytecode (not 0x)
```

---

## Mainnet Deployment

### Pre-Deployment Checklist

- [ ] Contracts audited or thoroughly reviewed
- [ ] Tested on testnet successfully
- [ ] Deployer wallet has sufficient ETH (~0.01 ETH)
- [ ] Environment variables configured correctly
- [ ] `.env.deployment` file secure and not committed
- [ ] Backup of all deployment scripts

### Deployment Steps

1. **Final review:**
```bash
# Review contracts
cat contracts/ProductionArbitrageExecutor.sol
cat contracts/balancer/FlashLoanReceiver.sol

# Check gas estimation
forge estimate --rpc-url "$ARBITRUM_RPC_ENDPOINT" \
    contracts/ProductionArbitrageExecutor.sol:ProductionArbitrageExecutor
```

2. **Set mainnet RPC:**
```bash
export ARBITRUM_RPC_ENDPOINT="https://arb1.arbitrum.io/rpc"
export NETWORK="arbitrum"
export VERIFY="true"  # Enable contract verification
```

3. **Deploy contracts:**
```bash
./scripts/deploy-contracts.sh
```

The script will:
- ✅ Validate environment
- ✅ Compile contracts
- ✅ Deploy both contracts
- ✅ Verify on Arbiscan (if enabled)
- ✅ Update configuration files
- ✅ Save deployment records

4. **Backup deployment data:**
```bash
# Save deployment logs and addresses
cp -r deployments deployments_backup_$(date +%Y%m%d_%H%M%S)
cp logs/deployment_*.log logs/deployment_backup_$(date +%Y%m%d_%H%M%S).log
```

---

## Verification

### Automatic Verification

Enable during deployment:
```bash
export VERIFY="true"
export ARBISCAN_API_KEY="YOUR_API_KEY"
./scripts/deploy-contracts.sh
```

### Manual Verification

If automatic verification fails:

```bash
# Verify ProductionArbitrageExecutor
./scripts/verify-contracts.sh <address> ProductionArbitrageExecutor

# Verify FlashLoanReceiver
./scripts/verify-contracts.sh <address> FlashLoanReceiver
```

### Verify Deployment

1. **Check on Arbiscan:**
```bash
# View contract
open "https://arbiscan.io/address/<contract_address>"
```

2. **Test contract calls:**
```bash
# Check contract owner
cast call <contract_address> "hasRole(bytes32,address)(bool)" \
    0x0000000000000000000000000000000000000000000000000000000000000000 \
    <your_deployer_address> \
    --rpc-url "$ARBITRUM_RPC_ENDPOINT"

# Should return: true
```

---

## Post-Deployment

### 1. Update Configuration Files

The deployment script automatically updates:
- `.env.production` - Contract addresses
- `config/arbitrum_production.yaml` - Production config

Verify updates:
```bash
grep CONTRACT_ARBITRAGE_EXECUTOR .env.production
grep arbitrage_contract_address config/arbitrum_production.yaml
```

### 2. Grant Contract Permissions

Grant necessary roles to the MEV bot:

```bash
# Get your bot wallet address
BOT_ADDRESS="0x..."  # From keystore

# Grant EXECUTOR_ROLE to bot
cast send <arbitrage_executor_address> \
    "grantRole(bytes32,address)" \
    $(cast keccak "EXECUTOR_ROLE") \
    "$BOT_ADDRESS" \
    --rpc-url "$ARBITRUM_RPC_ENDPOINT" \
    --private-key "$DEPLOYER_PRIVATE_KEY"
```

### 3. Test Contract Integration

```bash
# Run bot in test mode
LOG_LEVEL=debug timeout 60 ./bin/mev-beta start

# Check logs for contract initialization
grep "Flash swap executor initialized" logs/mev_bot.log
```

### 4. Fund Contracts (if needed)

Some strategies may require initial ETH or token balance:

```bash
# Send ETH to arbitrage executor
cast send <arbitrage_executor_address> \
    --value 0.1ether \
    --rpc-url "$ARBITRUM_RPC_ENDPOINT" \
    --private-key "$DEPLOYER_PRIVATE_KEY"
```

### 5. Set Up Monitoring

Monitor contract activity:
```bash
# Watch for events
cast logs --address <contract_address> \
    --rpc-url "$ARBITRUM_RPC_ENDPOINT" \
    --from-block latest \
    --follow
```

---

## Troubleshooting

### Deployment Fails with "insufficient funds"

**Problem:** Deployer wallet has insufficient ETH

**Solution:**
```bash
# Check balance
cast balance <deployer_address> --rpc-url "$ARBITRUM_RPC_ENDPOINT"

# Send more ETH to deployer wallet
```

### Verification Fails

**Problem:** Contract verification on Arbiscan fails

**Solution:**
```bash
# Retry with specific compiler version
forge verify-contract \
    --chain-id 42161 \
    --compiler-version "v0.8.19+commit.7dd6d404" \
    --num-of-optimizations 200 \
    --etherscan-api-key "$ARBISCAN_API_KEY" \
    <contract_address> \
    contracts/ProductionArbitrageExecutor.sol:ProductionArbitrageExecutor
```

### Contract Compilation Errors

**Problem:** Missing dependencies or Solidity version mismatch

**Solution:**
```bash
# Reinstall dependencies
rm -rf lib
forge install OpenZeppelin/openzeppelin-contracts --no-commit

# Check Solidity version
forge --version

# Update Foundry
foundryup
```

### RPC Connection Issues

**Problem:** Cannot connect to RPC endpoint

**Solution:**
```bash
# Test RPC connection
cast client --rpc-url "$ARBITRUM_RPC_ENDPOINT"

# Try alternative RPC
export ARBITRUM_RPC_ENDPOINT="https://arbitrum.llamarpc.com"
```

### Gas Estimation Errors

**Problem:** Transaction gas estimation fails

**Solution:**
```bash
# Get current gas price
cast gas-price --rpc-url "$ARBITRUM_RPC_ENDPOINT"

# Manually set gas limit
forge create ... --gas-limit 5000000
```

---

## Deployment Checklist

### Pre-Deployment
- [ ] Foundry installed and updated
- [ ] Deployer wallet funded with ETH
- [ ] RPC endpoint configured and tested
- [ ] Environment variables set
- [ ] Contracts compiled successfully
- [ ] Testnet deployment tested
- [ ] Security review completed

### During Deployment
- [ ] Deployment script executed
- [ ] ProductionArbitrageExecutor deployed
- [ ] FlashLoanReceiver deployed
- [ ] Deployment addresses saved
- [ ] Configuration files updated
- [ ] Contracts verified on Arbiscan

### Post-Deployment
- [ ] Contract addresses verified on Arbiscan
- [ ] Permissions granted to bot wallet
- [ ] Test transaction executed successfully
- [ ] Monitoring set up
- [ ] Deployment documentation updated
- [ ] Team notified of deployment
- [ ] Deployment backups created

---

## Additional Resources

### Documentation
- Foundry Book: https://book.getfoundry.sh/
- Arbitrum Docs: https://docs.arbitrum.io/
- Arbiscan: https://arbiscan.io/

### Support
- Foundry Discord: https://discord.gg/foundry
- Arbitrum Discord: https://discord.gg/arbitrum

### Security
- OpenZeppelin Contracts: https://docs.openzeppelin.com/contracts/
- Smart Contract Security Best Practices: https://consensys.github.io/smart-contract-best-practices/

---

## Deployment Records

All deployments are logged in:
- `deployments/` - Deployment JSONs
- `logs/deployment_*.log` - Detailed logs

Example deployment record:
```json
{
  "network": "arbitrum",
  "timestamp": "2025-10-27T16:00:00Z",
  "contracts": {
    "ProductionArbitrageExecutor": {
      "address": "0x...",
      "verified": true
    },
    "FlashLoanReceiver": {
      "address": "0x...",
      "verified": true
    }
  }
}
```

---

**Need Help?** Check the [Troubleshooting](#troubleshooting) section or review deployment logs in `logs/deployment_*.log`.