# Environment Variables Reference

Complete reference for all environment variables needed for the trustless bridge deployment.

## Required Variables (Must Be Set)

### Deployment Account
```bash
PRIVATE_KEY=0x...  # Deployer private key (NEVER commit to git)
```

### RPC Endpoints
```bash
ETHEREUM_MAINNET_RPC=https://eth.llamarpc.com  # Ethereum Mainnet RPC URL
RPC_URL_138=http://chain138.example.com:8545    # ChainID 138 RPC URL
```

### Etherscan Verification
```bash
ETHERSCAN_API_KEY=your_etherscan_api_key  # For contract verification
```

## Contract Addresses (Populated During Deployment)

### Core Bridge Contracts (ChainID 138)
```bash
LOCKBOX_138=0x...  # Lockbox contract address on ChainID 138
```

### Core Bridge Contracts (Ethereum Mainnet)
```bash
BOND_MANAGER=0x...              # BondManager contract address
CHALLENGE_MANAGER=0x...         # ChallengeManager contract address
LIQUIDITY_POOL=0x...            # LiquidityPoolETH contract address
INBOX_ETH=0x...                 # InboxETH contract address
SWAP_ROUTER=0x...               # Basic SwapRouter contract address
BRIDGE_SWAP_COORDINATOR=0x...   # BridgeSwapCoordinator contract address
```

### Enhanced Routing
```bash
ENHANCED_SWAP_ROUTER=0x...  # EnhancedSwapRouter contract address
```

### Integration Contracts
```bash
STABLECOIN_PEG_MANAGER=0x...      # StablecoinPegManager contract address
COMMODITY_PEG_MANAGER=0x...       # CommodityPegManager contract address
ISO_CURRENCY_MANAGER=0x...        # ISOCurrencyManager contract address
BRIDGE_RESERVE_COORDINATOR=0x...  # BridgeReserveCoordinator contract address
```

### Reserve System
```bash
RESERVE_SYSTEM=0x...  # ReserveSystem contract address (ChainID 138)
XAU_ADDRESS=0x...    # XAU token address (if tokenized)
```

## Optional Configuration Variables

### Bridge Configuration
```bash
BOND_MULTIPLIER_BPS=11000              # 110% (default)
MIN_BOND=1000000000000000000           # 1 ETH (default)
CHALLENGE_WINDOW_SECONDS=1800           # 30 minutes (default)
LP_FEE_BPS=5                           # 0.05% (default)
MIN_LIQUIDITY_RATIO_BPS=11000          # 110% (default)
```

### Peg Configuration
```bash
USD_PEG_THRESHOLD_BPS=50                # 0.5% (default)
ETH_PEG_THRESHOLD_BPS=10                # 0.1% (default)
COMMODITY_PEG_THRESHOLD_BPS=100        # 1.0% (default)
MIN_RESERVE_RATIO_BPS=11000             # 110% (default)
```

### Liquidity Configuration
```bash
LIQUIDITY_AMOUNT=100                    # ETH amount for initial liquidity (default: 100)
RESERVE_AMOUNT=100000                   # USDT amount for reserves (default: 100000)
```

## Token Addresses (Ethereum Mainnet)

These are standard addresses and typically don't need to be changed:

```bash
WETH=0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2
USDT=0xdAC17F958D2ee523a2206206994597C13D831ec7
USDC=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
DAI=0x6B175474E89094C44Da98b954EedeAC495271d0F
```

## DEX Protocol Addresses (Ethereum Mainnet)

These are standard addresses and typically don't need to be changed:

```bash
UNISWAP_V3_ROUTER=0xE592427A0AEce92De3Edee1F18E0157C05861564
CURVE_3POOL=0xbEbc44782C7dB0a1A60Cb6fe97d0b483032FF1C7
DODOEX_ROUTER=0xa356867fDCEa8e71AEaF87805808803806231FdC
BALANCER_VAULT=0xBA12222222228d8Ba445958a75a0704d566BF2C8
ONEINCH_ROUTER=0x1111111254EEB25477B68fb85Ed929f73A960582
```

`UNISWAP_V3_ROUTER` should point at the legacy SwapRouter on Ethereum mainnet because the trustless router contracts in this repo call `exactInputSingle` directly.

## Balancer Pool IDs (Configure After Deployment)

```bash
# BALANCER_WETH_USDT_POOL_ID=0x...
# BALANCER_WETH_USDC_POOL_ID=0x...
# Add more pool IDs as needed
```

## Dodoex PMM / Full Swappable (Chains 138, 651940)

For PMM coverage of all tokens and swap+bridge+swap flow:

```bash
# Per-chain DODO (set for each chain)
CHAIN_138_DODO_POOL_MANAGER=0x...
CHAIN_138_DODO_VENDING_MACHINE=0x...
CHAIN_651940_DODO_POOL_MANAGER=0x...
CHAIN_651940_DODO_VENDING_MACHINE=0x...

# Token coverage script (create-all-dodo-pools-from-token-api.sh)
TOKEN_AGGREGATION_API_URL=http://localhost:3000
CHAIN_ID=138
QUOTE_TOKEN_ADDRESS=0x...   # WETH or canonical stable per chain
DODO_PMM_INTEGRATION_ADDRESS=0x...
ENHANCED_SWAP_ROUTER_ADDRESS=0x...
UNIVERSAL_ASSET_REGISTRY_ADDRESS=0x...
RPC_URL=...
PRIVATE_KEY=0x...

# Quote service (swap+bridge+swap)
ENHANCED_SWAP_ROUTER_ADDRESS=0x...   # Source chain router
DESTINATION_RPC_URL=...
DESTINATION_SWAP_ROUTER_ADDRESS=0x...

# SwapBridgeSwapCoordinator (atomic swap then bridge)
SWAP_BRIDGE_SWAP_COORDINATOR=0x...
```

Run pool creation for all tokens: `scripts/create-all-dodo-pools-from-token-api.sh` (use `DRY_RUN=true` to preview). Ensure CCIP router and chain selectors are set for 138, 651940, and target chains; LINK funded for bridge contracts.

## Service Configuration

### Market Reporting Service
```bash
MARKET_REPORTING_API_KEY=your_api_key_here  # API key for market reporting service
```

### Service Ports (Optional - defaults provided)
```bash
# Liquidity Engine Service
LIQUIDITY_ENGINE_PORT=3000

# Market Reporting Service
MARKET_REPORTING_PORT=3001

# Bridge Reserve Service
BRIDGE_RESERVE_PORT=3002

# ISO Currency Service
ISO_CURRENCY_PORT=3003
```

## Phase-by-Phase Requirements

### Phase 1: Environment Setup
**Required:**
- `PRIVATE_KEY`
- `ETHEREUM_MAINNET_RPC`
- `RPC_URL_138`
- `ETHERSCAN_API_KEY`

### Phase 2: Deploy Core Contracts
**Required:**
- All Phase 1 variables

**Populated After:**
- `LOCKBOX_138` (ChainID 138)
- `BOND_MANAGER`
- `CHALLENGE_MANAGER`
- `LIQUIDITY_POOL`
- `INBOX_ETH`
- `SWAP_ROUTER`
- `BRIDGE_SWAP_COORDINATOR`

### Phase 3: Deploy Enhanced Router
**Required:**
- All Phase 1 variables
- `BRIDGE_SWAP_COORDINATOR` (from Phase 2)

**Populated After:**
- `ENHANCED_SWAP_ROUTER`

### Phase 4: Deploy Integration Contracts
**Required:**
- All Phase 1 variables
- `BRIDGE_SWAP_COORDINATOR` (from Phase 2)
- `RESERVE_SYSTEM` (must be set if deploying)

**Populated After:**
- `STABLECOIN_PEG_MANAGER`
- `COMMODITY_PEG_MANAGER`
- `ISO_CURRENCY_MANAGER`
- `BRIDGE_RESERVE_COORDINATOR`

### Phase 5: Initialize System
**Required:**
- All Phase 1 variables
- `ENHANCED_SWAP_ROUTER` (from Phase 3)
- `BRIDGE_SWAP_COORDINATOR` (from Phase 2)

### Phase 6: Provide Liquidity
**Required:**
- All Phase 1 variables
- `LIQUIDITY_POOL` (from Phase 2)
- `RESERVE_SYSTEM` (must be set)

**Optional:**
- `LIQUIDITY_AMOUNT` (default: 100)
- `RESERVE_AMOUNT` (default: 100000)

### Phase 7: Configure Access Control
**Required:**
- All Phase 1 variables
- `ENHANCED_SWAP_ROUTER` (from Phase 3)
- `BRIDGE_SWAP_COORDINATOR` (from Phase 2)

### Phase 8: Deploy Backend Services
**Required:**
- All Phase 1 variables
- Contract addresses from previous phases

**Service-Specific:**
- `MARKET_REPORTING_API_KEY` (for Market Reporting Service)

### Phase 9: Deploy Frontend
**Required:**
- Contract addresses from previous phases (for frontend configuration)

### Phase 10: Verification
**Required:**
- All contract addresses from previous phases

## Validation Checklist

Before starting deployment, ensure:

- [ ] `PRIVATE_KEY` is set and valid
- [ ] `ETHEREUM_MAINNET_RPC` is accessible
- [ ] `RPC_URL_138` is accessible (or will be)
- [ ] `ETHERSCAN_API_KEY` is valid
- [ ] Deployer has sufficient ETH (5-10 ETH recommended)
- [ ] `RESERVE_SYSTEM` address is known (if deploying integration contracts)

## Security Notes

1. **Never commit `.env` file** to version control
2. **Use `.env.template`** as a reference
3. **Store private keys securely** - use hardware wallets for production
4. **Rotate API keys** regularly
5. **Use environment-specific values** for different networks (testnet vs mainnet)

## Example .env File

```bash
# Deployment Account
PRIVATE_KEY=0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

# RPC Endpoints
ETHEREUM_MAINNET_RPC=https://eth.llamarpc.com
RPC_URL_138=http://chain138.example.com:8545

# Etherscan Verification
ETHERSCAN_API_KEY=ABC123XYZ789

# Reserve System
RESERVE_SYSTEM=0x1111111111111111111111111111111111111111
XAU_ADDRESS=0x2222222222222222222222222222222222222222

# Contract Addresses (populated during deployment)
LOCKBOX_138=
BOND_MANAGER=
CHALLENGE_MANAGER=
LIQUIDITY_POOL=
INBOX_ETH=
SWAP_ROUTER=
BRIDGE_SWAP_COORDINATOR=
ENHANCED_SWAP_ROUTER=
STABLECOIN_PEG_MANAGER=
COMMODITY_PEG_MANAGER=
ISO_CURRENCY_MANAGER=
BRIDGE_RESERVE_COORDINATOR=

# Service Configuration
MARKET_REPORTING_API_KEY=your_api_key_here
```

## Troubleshooting

### Variable Not Found
- Check `.env` file exists
- Verify variable name spelling
- Ensure no extra spaces around `=`
- Check for comments (lines starting with `#`)

### Variable Not Set
- Run `phase1-env-setup.sh` to verify
- Check script output for missing variables
- Review this reference for required variables

### Contract Address Not Found
- Ensure previous phase completed successfully
- Check deployment output for addresses
- Verify addresses are saved to `.env`