311 lines
7.2 KiB
Markdown
311 lines
7.2 KiB
Markdown
# 🔗 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)
|