explorer-monorepo/docs/CCIP_TOKEN_POOL_ARCHITECTURE.md

# 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