237-combo/docs/ENV_SETUP.md

# ⚙️ Environment Setup Guide

This guide explains how to set up environment variables for the DeFi Strategy Testing Framework.

---

## 🚀 Quick Start

### 1️⃣ Copy the Example Environment File

```bash
cp .env.example .env
```

### 2️⃣ Fill in Your RPC URLs

```bash
# Edit .env file
MAINNET_RPC_URL=https://mainnet.infura.io/v3/YOUR_INFURA_KEY
BASE_RPC_URL=https://base-mainnet.infura.io/v3/YOUR_INFURA_KEY
# ... etc
```

### 3️⃣ Verify Your Setup

```bash
pnpm run check:env
```

---

## 📋 Required Environment Variables

### 🔗 RPC URLs

These are used to connect to blockchain networks for forking and testing:

| Variable | Description | Required |
|----------|-------------|----------|
| `MAINNET_RPC_URL` | Ethereum mainnet RPC endpoint | ✅ Yes |
| `BASE_RPC_URL` | Base network RPC endpoint | ⚠️ Optional |
| `ARBITRUM_RPC_URL` | Arbitrum One RPC endpoint | ⚠️ Optional |
| `OPTIMISM_RPC_URL` | Optimism network RPC endpoint | ⚠️ Optional |
| `POLYGON_RPC_URL` | Polygon network RPC endpoint | ⚠️ Optional |

### 🔐 Optional Environment Variables

| Variable | Description | When Needed |
|----------|-------------|-------------|
| `PRIVATE_KEY` | Private key for executing transactions | Mainnet/testnet execution only |
| `TEST_SCENARIO` | Override default test scenario path | Custom test scenarios |
| `TEST_NETWORK` | Override default test network | Multi-chain testing |

---

## 🔗 Getting RPC URLs

### 🆓 Free Options

#### 1. Public RPCs (Rate-Limited)

| Network | Public RPC URL |
|---------|----------------|
| Ethereum | `https://eth.llamarpc.com` |
| Base | `https://mainnet.base.org` |
| Arbitrum | `https://arb1.arbitrum.io/rpc` |
| Optimism | `https://mainnet.optimism.io` |
| Polygon | `https://polygon-rpc.com` |

#### 2. Infura (Free Tier)

1. 📝 Sign up at [infura.io](https://infura.io)
2. ➕ Create a project
3. 📋 Copy your project ID
4. 🔗 Use: `https://mainnet.infura.io/v3/YOUR_PROJECT_ID`

#### 3. Alchemy (Free Tier)

1. 📝 Sign up at [alchemy.com](https://alchemy.com)
2. ➕ Create an app
3. 📋 Copy your API key
4. 🔗 Use: `https://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY`

### 💰 Paid Options (Recommended for Production)

| Provider | Best For | Link |
|----------|----------|------|
| **Infura** | Reliable, well-known | [infura.io](https://infura.io) |
| **Alchemy** | Fast, good free tier | [alchemy.com](https://alchemy.com) |
| **QuickNode** | Fast, global network | [quicknode.com](https://quicknode.com) |
| **Ankr** | Good performance | [ankr.com](https://ankr.com) |

---

## ✅ Verification

### 🔍 Check Environment Variables

Run the environment checker:

```bash
pnpm run check:env
```

This will:
- ✅ Check that all RPC URLs are set
- ✅ Verify connections to each network
- ✅ Show current block numbers
- ✅ Report any issues

### 🧪 Test with a Scenario

```bash
# Set your RPC URL
export MAINNET_RPC_URL=https://your-rpc-url-here

# Run a test
pnpm run strat:test
```

---

## 🔧 Troubleshooting

### ❌ "RPC URL contains placeholder"

**Problem:** Your `.env` file still has placeholder values like `YOUR_KEY` or `YOUR_INFURA_KEY`.

**Solution:** Replace placeholders with actual RPC URLs in your `.env` file.

### ❌ "Connection failed" or "403 Forbidden"

**Problem:** Your RPC endpoint is rejecting requests.

**Possible Causes:**
1. ❌ Invalid API key
2. ⏱️ Rate limiting (free tier exceeded)
3. 🚫 IP restrictions
4. 🔒 Infura project set to "private key only" mode

**Solutions:**
1. ✅ Verify your API key is correct
2. ✅ Check your RPC provider dashboard for rate limits
3. ✅ Try a different RPC provider
4. ✅ For Infura: Enable "Public Requests" in project settings

### ❌ "Environment variable not set"

**Problem:** The script can't find the required environment variable.

**Solutions:**
1. ✅ Check that `.env` file exists in project root
2. ✅ Verify variable name is correct (case-sensitive)
3. ✅ Restart your terminal/IDE after creating `.env`
4. ✅ Use `pnpm run check:env` to verify

### ❌ Module Load Order Issues

**Problem:** Environment variables not being loaded before modules that use them.

**Solution:** The framework now loads `dotenv` FIRST in all entry points. If you still have issues:
1. ✅ Ensure `.env` file is in the project root
2. ✅ Check that `dotenv` package is installed
3. ✅ Verify scripts load dotenv before other imports

---

## 💡 Best Practices

### 🔐 Security

1. **Never commit `.env` files:**
   - ✅ `.env` is in `.gitignore`
   - ✅ Only commit `.env.example`

2. **Use different keys for different environments:**
   - 🧪 Development: Free tier or public RPCs
   - 🚀 Production: Paid RPC providers

3. **Rotate keys regularly:**
   - 🔄 Especially if keys are exposed
   - 📝 Update `.env` file with new keys

### 🗂️ Organization

4. **Use environment-specific files:**
   - 📁 `.env.local` - Local development (gitignored)
   - 📁 `.env.production` - Production (gitignored)
   - 📁 `.env.example` - Template (committed)

5. **Validate on startup:**
   - ✅ Use `pnpm run check:env` before running tests
   - ✅ Scripts will warn if RPC URLs are not configured

---

## 🔒 Security Notes

> ⚠️ **IMPORTANT**: 
> - ⛔ **Never commit `.env` files** - They may contain private keys
> - 🔑 **Don't share RPC keys** - They may have rate limits or costs
> - 🔄 **Use separate keys** for development and production
> - 🔐 **Rotate keys** if they're exposed or compromised

---

## 📝 Example .env File

```bash
# RPC Endpoints
MAINNET_RPC_URL=https://mainnet.infura.io/v3/your-infura-project-id
BASE_RPC_URL=https://base-mainnet.infura.io/v3/your-infura-project-id
ARBITRUM_RPC_URL=https://arbitrum-mainnet.infura.io/v3/your-infura-project-id
OPTIMISM_RPC_URL=https://optimism-mainnet.infura.io/v3/your-infura-project-id
POLYGON_RPC_URL=https://polygon-mainnet.infura.io/v3/your-infura-project-id

# Private Keys (only for mainnet execution, not fork testing)
# PRIVATE_KEY=0x...

# Test Configuration (optional)
# TEST_SCENARIO=scenarios/aave/leveraged-long.yml
# TEST_NETWORK=mainnet
```

---

## 🎯 Next Steps

After setting up your environment:

### 1. Verify Setup

```bash
pnpm run check:env
```

### 2. Run a Test Scenario

```bash
pnpm run strat:test
```

### 3. Run a Scenario with CLI

```bash
pnpm run strat run scenarios/aave/leveraged-long.yml
```

### 4. Try Fuzzing

```bash
pnpm run strat fuzz scenarios/aave/leveraged-long.yml --iters 10
```

---

## 📚 Related Documentation

- 📖 [Strategy Testing Guide](./STRATEGY_TESTING.md)
- 🔗 [Chain Configuration](./CHAIN_CONFIG.md)
- 🔐 [Security Best Practices](./SECURITY.md)