explorer-monorepo/docs/CCIP_RATE_LIMITS.md

# CCIP Rate Limits Documentation

**Date**: 2025-01-12  
**Network**: ChainID 138

---

## Overview

This document describes the rate limits configured for CCIP token pools and cross-chain transfers.

---

## Rate Limit Types

### Outbound Rate Limits
Controls the maximum amount of tokens that can be sent from the source chain to a destination chain within a time period.

### Inbound Rate Limits
Controls the maximum amount of tokens that can be received on the destination chain from the source chain within a time period.

### Per-Lane Rate Limits
Rate limits specific to each source-destination chain pair (lane).

---

## Current Configuration

### Status: ⚠️ Unknown

Rate limit configuration cannot be verified from scripts without admin access or contract verification.

### Verification Methods

1. **Query Pool Contracts**:
   ```bash
   cast call <pool_address> "getOutboundRateLimit()" --rpc-url <rpc_url>
   cast call <pool_address> "getInboundRateLimit()" --rpc-url <rpc_url>
   ```

2. **Check TokenAdminRegistry**:
   ```bash
   ./scripts/verify-token-admin-registry.sh
   ```

3. **Query Pool Configuration**:
   ```bash
   ./scripts/verify-token-pool-config.sh <pool_address>
   ```

---

## Rate Limit Configuration

### Recommended Settings

#### Outbound Rate Limits
- **Per Lane**: Based on expected volume
- **Time Window**: 24 hours
- **Purpose**: Prevent excessive outbound transfers

#### Inbound Rate Limits
- **Per Lane**: Based on expected volume
- **Time Window**: 24 hours
- **Purpose**: Prevent excessive inbound transfers

#### Global Limits
- **Total Outbound**: Sum of all lane limits
- **Total Inbound**: Sum of all lane limits
- **Purpose**: Overall system protection

---

## Rate Limit Update Procedures

### Prerequisites
1. Admin access to pool contracts
2. Understanding of current usage patterns
3. Risk assessment of proposed changes

### Update Steps

1. **Analyze Current Usage**:
   - Review historical transfer volumes
   - Identify peak usage periods
   - Calculate average and maximum rates

2. **Determine New Limits**:
   - Consider expected growth
   - Add safety margin
   - Balance usability and security

3. **Update Configuration**:
   ```solidity
   pool.setOutboundRateLimit(chainSelector, newLimit);
   pool.setInboundRateLimit(chainSelector, newLimit);
   ```

4. **Verify Changes**:
   ```bash
   ./scripts/verify-token-pool-config.sh <pool_address>
   ```

---

## Monitoring

### Rate Limit Usage

Monitor current usage vs limits:
- Current outbound usage
- Current inbound usage
- Time until limit reset
- Approaching limits alerts

### Alerts

Set up alerts for:
- Approaching rate limits (80% threshold)
- Rate limit reached
- Unusual rate limit activity

---

## Troubleshooting

### Rate Limit Reached

**Symptoms**:
- Transfers failing with rate limit error
- High rate limit usage

**Solutions**:
1. Wait for rate limit reset
2. Request rate limit increase (if needed)
3. Distribute transfers across time

### Rate Limit Too Low

**Symptoms**:
- Frequent rate limit errors
- Legitimate transfers blocked

**Solutions**:
1. Analyze usage patterns
2. Request rate limit increase
3. Update rate limit configuration

---

## Best Practices

1. **Set Appropriate Limits**:
   - Based on expected usage
   - Include safety margin
   - Review regularly

2. **Monitor Usage**:
   - Track rate limit usage
   - Set up alerts
   - Review trends

3. **Plan for Growth**:
   - Anticipate increased usage
   - Adjust limits proactively
   - Document changes

---

## Related Documentation

- [Token Pool Architecture](./CCIP_TOKEN_POOL_ARCHITECTURE.md) (Task 25)
- [CCIP Configuration Status](./CCIP_CONFIGURATION_STATUS.md)
- [Complete Task Catalog](./CCIP_COMPLETE_TASK_CATALOG.md)

---

**Last Updated**: 2025-01-12