Initial commit: add .gitignore and README
This commit is contained in:
defiQUG
261
docs/ENV_SETUP.md
Normal file
261
docs/ENV_SETUP.md
Normal file
@@ -0,0 +1,261 @@
|
||||
# ⚙️ 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)
|
||||
Reference in New Issue
Block a user