d-bis/237-combo
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
47f6f2de7ba11a46001d6c076f8de363b4a30e36
237-combo/docs/ENV_SETUP.md
defiQUG 47f6f2de7b Initial commit: add .gitignore and README
2026-02-09 21:51:30 -08:00

6.6 KiB
Raw Blame History

⚙️ 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

cp .env.example .env

2️⃣ Fill in Your RPC URLs

# 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

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
  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
  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
Alchemy Fast, good free tier alchemy.com
QuickNode Fast, global network quicknode.com
Ankr Good performance ankr.com

✅ Verification

🔍 Check Environment Variables

Run the environment checker:

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

# 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

  1. Use environment-specific files:

    • 📁 .env.local - Local development (gitignored)
    • 📁 .env.production - Production (gitignored)
    • 📁 .env.example - Template (committed)

  2. 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

# 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

pnpm run check:env

2. Run a Test Scenario

pnpm run strat:test

3. Run a Scenario with CLI

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

4. Try Fuzzing

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

📚 Related Documentation

Reference in New Issue View Git Blame Copy Permalink