237-combo/docs/CHAIN_CONFIG.md

# 🔗 Chain Configuration Guide

How to add and configure new chains in the DeFi Starter Kit.

---

## 📋 Overview

This guide walks you through adding a new blockchain network to the DeFi Starter Kit. You'll need to configure:

- 🔗 RPC endpoints
- 📍 Protocol contract addresses
- 💰 Token addresses
- 🔧 Viem chain configuration

---

## 🚀 Adding a New Chain

### 1️⃣ Create Chain Config File

Create a new file in `config/chains/` with your chain configuration:

```typescript
// config/chains/yourchain.ts
import type { ChainConfig } from '../types.js';

export const yourchain: ChainConfig = {
  chainId: 12345, // Your chain ID
  name: 'Your Chain',
  rpcUrl: process.env.YOURCHAIN_RPC_URL || 'https://rpc.yourchain.com',
  
  // Aave v3
  aave: {
    poolAddressesProvider: '0x...', // Aave PoolAddressesProvider
    pool: '0x...', // Aave Pool
  },

  // Uniswap
  uniswap: {
    swapRouter02: '0x...', // Uniswap SwapRouter02
    universalRouter: '0x...', // Uniswap Universal Router
    permit2: '0x000000000022D473030F116dDEE9F6B43aC78BA3', // Permit2 (same across chains)
    quoterV2: '0x...', // Uniswap QuoterV2
  },

  // Protocolink
  protocolink: {
    router: '0x...', // Protocolink Router
  },

  // Compound III
  compound3: {
    cometUsdc: '0x...', // Compound III Comet (if available)
  },

  // Common Tokens
  tokens: {
    WETH: '0x...',
    USDC: '0x...',
    USDT: '0x...',
    DAI: '0x...',
    WBTC: '0x...',
  },
};
```

### 2️⃣ Register Chain in Addresses

Add your chain to `config/addresses.ts`:

```typescript
import { yourchain } from './chains/yourchain.js';

export const chainConfigs: Record<number, ChainConfig> = {
  1: mainnet,
  8453: base,
  // ... other chains
  12345: yourchain, // Add your chain
};

// Re-export
export { yourchain };
```

### 3️⃣ Add Viem Chain

Add your chain to `src/utils/chain-config.ts`:

```typescript
import { yourChain } from 'viem/chains';

const viemChains = {
  1: mainnet,
  8453: base,
  // ... other chains
  12345: yourChain, // Add your chain
};
```

### 4️⃣ Update Environment Variables

Add RPC URL to `.env.example`:

```bash
YOURCHAIN_RPC_URL=https://rpc.yourchain.com
```

### 5️⃣ Update Foundry Config

Add RPC endpoint to `foundry.toml`:

```toml
[rpc_endpoints]
yourchain = "${YOURCHAIN_RPC_URL}"
```

---

## 📍 Getting Official Addresses

### 🏦 Aave v3

1. 📚 Check [Aave Documentation](https://docs.aave.com/developers/deployed-contracts/deployed-contracts)
2. 🔍 Find your chain in the deployed contracts list
3. 📋 Get `PoolAddressesProvider` address
4. 🔗 Use `PoolAddressesProvider.getPool()` to get Pool address

### 🔄 Uniswap v3

1. 📚 Check [Uniswap Deployments](https://docs.uniswap.org/contracts/v3/reference/deployments)
2. 🔍 Find your chain's deployment page
3. 📋 Get addresses for:
   - `SwapRouter02`
   - `UniversalRouter`
   - `Permit2` (same address across all chains: `0x000000000022D473030F116dDEE9F6B43aC78BA3`)
   - `QuoterV2`

### 🔗 Protocolink

1. 📚 Check [Protocolink Deployment Addresses](https://docs.protocolink.com/smart-contract/deployment-addresses)
2. 🔍 Find your chain
3. 📋 Get Router address

### 🏛️ Compound III

1. 📚 Check [Compound III Documentation](https://docs.compound.finance/)
2. 🔍 Find your chain's Comet addresses
3. 📋 Get Comet proxy address for your market

### 💰 Common Tokens

For each chain, you'll need addresses for:

| Token | Description |
|-------|-------------|
| WETH | Wrapped Ether |
| USDC | USD Coin |
| USDT | Tether USD |
| DAI | Dai Stablecoin |
| WBTC | Wrapped Bitcoin |

**Resources:**
- 🔍 [Token Lists](https://tokenlists.org/)
- 🔍 [CoinGecko](https://www.coingecko.com/)

---

## ✅ Verifying Addresses

Always verify addresses from multiple sources:

1. ✅ Official protocol documentation
2. ✅ Block explorer (verify contract code)
3. ✅ Protocol GitHub repositories
4. ✅ Community resources (Discord, forums)

---

## 🧪 Testing Your Configuration

After adding a new chain:

### 1. Test Chain Config Loading

```typescript
import { getChainConfig } from './config/addresses.js';
const config = getChainConfig(12345);
console.log(config);
```

### 2. Test RPC Connection

```typescript
import { createRpcClient } from './src/utils/chain-config.js';
const client = createRpcClient(12345);
const blockNumber = await client.getBlockNumber();
console.log('Block number:', blockNumber);
```

### 3. Test Address Resolution

```typescript
import { getAavePoolAddress } from './src/utils/addresses.js';
const poolAddress = getAavePoolAddress(12345);
console.log('Pool address:', poolAddress);
```

### 4. Run Examples

```bash
# Update example to use your chain ID
tsx examples/ts/aave-supply-borrow.ts
```

### 5. Run Tests

```bash
# Update test to use your chain
forge test --fork-url $YOURCHAIN_RPC_URL
```

---

## 🔧 Common Issues

### ❌ RPC URL Not Working

**Possible causes:**
- ❌ RPC URL is incorrect
- ❌ RPC provider doesn't support your chain
- ❌ Rate limits exceeded

**Solutions:**
- ✅ Verify RPC URL is correct
- ✅ Try alternative RPC providers
- ✅ Check rate limits

### ❌ Addresses Not Found

**Possible causes:**
- ❌ Protocol not deployed on your chain
- ❌ Addresses are incorrect (typos, wrong network)
- ❌ Some protocols may not be available on all chains

**Solutions:**
- ✅ Verify protocol is deployed on your chain
- ✅ Double-check addresses for typos
- ✅ Check protocol documentation for chain support

### ❌ Token Addresses Wrong

**Possible causes:**
- ❌ Token addresses are incorrect
- ❌ Token decimals differ
- ❌ Tokens don't exist on your chain

**Solutions:**
- ✅ Verify token addresses on block explorer
- ✅ Check token decimals
- ✅ Ensure tokens exist on your chain

---

## 📝 Chain-Specific Notes

### 🚀 Layer 2 Chains

| Consideration | Description |
|---------------|-------------|
| Gas costs | Typically lower than mainnet |
| Finality times | May differ from mainnet |
| Protocol features | Some protocols may have L2-specific features |

### 🧪 Testnets

| Consideration | Description |
|---------------|-------------|
| Addresses | Use testnet-specific addresses |
| Tokens | Testnet tokens have no real value |
| Protocol availability | Some protocols may not be available on testnets |

---

## 💡 Best Practices

1. ✅ **Always verify addresses** - Don't trust a single source
2. ✅ **Use environment variables** - Never hardcode RPC URLs
3. ✅ **Test thoroughly** - Test on testnet before mainnet
4. ✅ **Document changes** - Update documentation when adding chains
5. ✅ **Keep addresses updated** - Protocols may upgrade contracts

---

## 🔗 Resources

| Resource | Link |
|----------|------|
| Aave Deployed Contracts | [docs.aave.com](https://docs.aave.com/developers/deployed-contracts/deployed-contracts) |
| Uniswap Deployments | [docs.uniswap.org](https://docs.uniswap.org/contracts/v3/reference/deployments) |
| Protocolink Deployment Addresses | [docs.protocolink.com](https://docs.protocolink.com/smart-contract/deployment-addresses) |
| Compound III Documentation | [docs.compound.finance](https://docs.compound.finance/) |

---

## 📚 Related Documentation

- 📖 [Environment Setup Guide](./ENV_SETUP.md)
- 🔐 [Security Best Practices](./SECURITY.md)
- 🧪 [Strategy Testing Guide](./STRATEGY_TESTING.md)