230 lines
5.2 KiB
Markdown
230 lines
5.2 KiB
Markdown
# CCIP Token Pool Architecture Documentation
|
|
|
|
**Date**: 2025-01-12
|
|
**Network**: ChainID 138
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
This document describes the architecture of token pools in the CCIP system and how tokens are managed for cross-chain bridging.
|
|
|
|
---
|
|
|
|
## Token Pool Concept
|
|
|
|
### Purpose
|
|
|
|
Token pools manage the liquidity and accounting for tokens being bridged across chains. They ensure that:
|
|
- Tokens are properly accounted for on source and destination chains
|
|
- Rate limits are enforced
|
|
- Token mechanisms (lock & release, burn & mint) are implemented
|
|
|
|
---
|
|
|
|
## Pool Types
|
|
|
|
### Lock & Release Pools
|
|
|
|
**Mechanism**: Tokens are locked on source chain and released on destination chain.
|
|
|
|
**Process**:
|
|
1. User sends tokens to pool on source chain
|
|
2. Tokens are locked in pool
|
|
3. CCIP message sent to destination
|
|
4. Pool on destination chain releases tokens to receiver
|
|
|
|
### Burn & Mint Pools
|
|
|
|
**Mechanism**: Tokens are burned on source chain and minted on destination chain.
|
|
|
|
**Process**:
|
|
1. User sends tokens to pool on source chain
|
|
2. Tokens are burned
|
|
3. CCIP message sent to destination
|
|
4. Pool on destination chain mints tokens to receiver
|
|
|
|
---
|
|
|
|
## Pool Configuration
|
|
|
|
### Remote Chain Configuration
|
|
|
|
Pools must know about remote chains (destination chains) to:
|
|
- Track token flow per chain
|
|
- Enforce rate limits per chain
|
|
- Account for tokens correctly
|
|
|
|
### Rate Limits
|
|
|
|
Pools enforce rate limits:
|
|
- **Outbound**: Maximum tokens that can be sent to a destination chain
|
|
- **Inbound**: Maximum tokens that can be received from a source chain
|
|
- **Per-Lane**: Limits specific to each source-destination pair
|
|
|
|
### Permissions
|
|
|
|
Pools require permissions for:
|
|
- **Minting**: If using burn & mint mechanism
|
|
- **Burning**: If using burn & mint mechanism
|
|
- **Transferring**: For lock & release mechanism
|
|
|
|
---
|
|
|
|
## TokenAdminRegistry
|
|
|
|
### Purpose
|
|
|
|
The TokenAdminRegistry maintains the mapping between tokens and their pools.
|
|
|
|
### Functions
|
|
|
|
**`getPool(address token)`**
|
|
- Returns the pool address for a given token
|
|
- Used by OffRamp to find the correct pool
|
|
|
|
**`registerToken(address token, address pool)`** (admin only)
|
|
- Registers a token with its pool
|
|
- Required for CCIP to route tokens correctly
|
|
|
|
---
|
|
|
|
## Pool Addresses
|
|
|
|
### Current Status: ⚠️ Unknown
|
|
|
|
Pool addresses for WETH9 and WETH10 are not yet identified. They may be:
|
|
1. Embedded in bridge contracts
|
|
2. Separate contracts managed by TokenAdminRegistry
|
|
3. Part of the CCIP infrastructure
|
|
|
|
### Finding Pool Addresses
|
|
|
|
**Method 1: TokenAdminRegistry**
|
|
```bash
|
|
./scripts/verify-token-admin-registry.sh
|
|
```
|
|
|
|
**Method 2: Bridge Contract Analysis**
|
|
- Analyze bridge contract code
|
|
- Check bridge contract storage
|
|
- Review deployment transactions
|
|
|
|
**Method 3: CCIP Documentation**
|
|
- Check Chainlink documentation
|
|
- Review CCIP deployment records
|
|
- Contact Chainlink support
|
|
|
|
---
|
|
|
|
## Pool Operations
|
|
|
|
### Outbound Flow (Source Chain)
|
|
|
|
1. **User Initiates Transfer**
|
|
- User approves bridge to spend tokens
|
|
- User calls bridge `sendCrossChain()`
|
|
|
|
2. **Bridge Processes**
|
|
- Bridge transfers tokens to pool (or burns)
|
|
- Bridge calls CCIP Router
|
|
|
|
3. **Pool Handles Tokens**
|
|
- Pool locks/burns tokens
|
|
- Pool tracks outbound amount
|
|
- Pool enforces rate limits
|
|
|
|
4. **CCIP Message Sent**
|
|
- Router sends message to oracle network
|
|
- Message includes token amount and pool info
|
|
|
|
### Inbound Flow (Destination Chain)
|
|
|
|
1. **CCIP Message Received**
|
|
- OffRamp receives message
|
|
- OffRamp queries TokenAdminRegistry for pool
|
|
|
|
2. **Pool Processes**
|
|
- Pool verifies message
|
|
- Pool checks rate limits
|
|
- Pool releases/mints tokens
|
|
|
|
3. **Tokens Delivered**
|
|
- Pool transfers tokens to receiver
|
|
- Pool tracks inbound amount
|
|
|
|
---
|
|
|
|
## Rate Limit Architecture
|
|
|
|
### Rate Limit Structure
|
|
|
|
```
|
|
Pool
|
|
├── Outbound Rate Limits
|
|
│ ├── Per Chain Selector
|
|
│ │ ├── Limit Amount
|
|
│ │ ├── Time Window
|
|
│ │ └── Current Usage
|
|
│ └── Global Outbound Limit
|
|
└── Inbound Rate Limits
|
|
├── Per Chain Selector
|
|
│ ├── Limit Amount
|
|
│ ├── Time Window
|
|
│ └── Current Usage
|
|
└── Global Inbound Limit
|
|
```
|
|
|
|
### Rate Limit Enforcement
|
|
|
|
1. **Check Limits**: Before processing, check if limit allows operation
|
|
2. **Update Usage**: After processing, update usage counter
|
|
3. **Reset Windows**: Periodically reset time windows
|
|
4. **Alert**: Alert when approaching limits
|
|
|
|
---
|
|
|
|
## Pool Liquidity Management
|
|
|
|
### Liquidity Requirements
|
|
|
|
Pools need adequate liquidity for:
|
|
- **Lock & Release**: Tokens locked must match tokens released
|
|
- **Burn & Mint**: Minting capability must be available
|
|
|
|
### Liquidity Monitoring
|
|
|
|
1. **Balance Tracking**: Monitor pool balances
|
|
2. **Flow Tracking**: Track inbound and outbound flows
|
|
3. **Rebalancing**: Rebalance liquidity as needed
|
|
4. **Alerts**: Alert on low liquidity
|
|
|
|
---
|
|
|
|
## Verification
|
|
|
|
### Verify Pool Configuration
|
|
|
|
```bash
|
|
./scripts/verify-token-pool-config.sh <pool_address>
|
|
```
|
|
|
|
### Verify Token Registration
|
|
|
|
```bash
|
|
./scripts/verify-token-admin-registry.sh
|
|
```
|
|
|
|
---
|
|
|
|
## Related Documentation
|
|
|
|
- [CCIP Rate Limits](./CCIP_RATE_LIMITS.md) (Tasks 33, 46)
|
|
- [Token Mechanism Documentation](./TOKEN_MECHANISM_DOCUMENTATION.md) (Task 39)
|
|
- [CCIP Configuration Status](./CCIP_CONFIGURATION_STATUS.md)
|
|
|
|
---
|
|
|
|
**Last Updated**: 2025-01-12
|
|
|