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

./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

./scripts/verify-token-pool-config.sh <pool_address>

Verify Token Registration

./scripts/verify-token-admin-registry.sh

---

Related Documentation

• CCIP Rate Limits (Tasks 33, 46)
• Token Mechanism Documentation (Task 39)
• CCIP Configuration Status

---

Last Updated: 2025-01-12