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:

// 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:

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:

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:

YOURCHAIN_RPC_URL=https://rpc.yourchain.com

5️⃣ Update Foundry Config

Add RPC endpoint to foundry.toml:

[rpc_endpoints]
yourchain = "${YOURCHAIN_RPC_URL}"

---

📍 Getting Official Addresses

🏦 Aave v3

1. 📚 Check Aave Documentation
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
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
2. 🔍 Find your chain
3. 📋 Get Router address

🏛️ Compound III

1. 📚 Check Compound III Documentation
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
• 🔍 CoinGecko

---

✅ 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

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

2. Test RPC Connection

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

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

4. Run Examples

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

5. Run Tests

# 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
Uniswap Deployments	docs.uniswap.org
Protocolink Deployment Addresses	docs.protocolink.com
Compound III Documentation	docs.compound.finance

---

📚 Related Documentation

• 📖 Environment Setup Guide
• 🔐 Security Best Practices
• 🧪 Strategy Testing Guide