Add full monorepo: virtual-banker, backend, frontend, docs, scripts, deployment
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
defiQUG
229
docs/CCIP_TOKEN_POOL_ARCHITECTURE.md
Normal file
229
docs/CCIP_TOKEN_POOL_ARCHITECTURE.md
Normal file
@@ -0,0 +1,229 @@
|
||||
# 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
|
||||
|
||||
Reference in New Issue
Block a user