262 lines
6.6 KiB
Markdown
262 lines
6.6 KiB
Markdown
# ⚙️ 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)
|