Initial commit: add .gitignore and README
This commit is contained in:
defiQUG
310
docs/CHAIN_CONFIG.md
Normal file
310
docs/CHAIN_CONFIG.md
Normal file
@@ -0,0 +1,310 @@
|
||||
# 🔗 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)
|
||||
Reference in New Issue
Block a user