explorer-monorepo/docs/CCIP_FEE_STRUCTURE.md

# CCIP Fee Structure Documentation

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

---

## Overview

This document describes the fee structure and payment mechanism for CCIP (Cross-Chain Interoperability Protocol) transactions.

---

## Fee Configuration

### Fee Token
- **Token Address**: `0x514910771AF9Ca656af840dff83E8264EcF986CA` (LINK)
- **Network**: ChainID 138
- **Purpose**: Payment token for CCIP fees

### Fee Structure

#### Base Fee
- **Amount**: 1000000000000000 wei (0.001 LINK)
- **Purpose**: Base fee for all CCIP messages
- **Applies To**: All cross-chain messages

#### Data Fee Per Byte
- **Amount**: 100000000 wei (0.0000001 LINK per byte)
- **Purpose**: Fee for message data size
- **Calculation**: `dataFee = dataSize * dataFeePerByte`

#### Total Fee Calculation
```
totalFee = baseFee + (dataSize * dataFeePerByte)
```

---

## Fee Payment Mechanism

### Payment Method
Fees are paid in **LINK tokens** (not native ETH).

### Fee Payment Process

1. **User Initiates Transfer**:
   - User calls bridge contract
   - Bridge contract calculates fee
   - Bridge contract checks LINK balance

2. **Fee Payment**:
   - Bridge contract transfers LINK to Router
   - Router processes payment
   - Message is sent

3. **Fee Verification**:
   - Router verifies fee payment
   - Message is queued for processing
   - Oracle network processes message

---

## Fee Calculation

### Current Status: ⚠️ Failing

Fee calculation in scripts is currently failing. This may be due to:
1. Router contract not exposing `getFee()` function
2. Fee calculation requiring different parameters
3. Fee calculation handled by separate contract

### Verification

**Script**: `scripts/verify-fee-calculation.sh`

**Usage**:
```bash
./scripts/verify-fee-calculation.sh [amount_eth] [destination_selector]
```

**Example**:
```bash
./scripts/verify-fee-calculation.sh 0.001 5009297550715157269
```

---

## LINK Token Requirements

### LINK Token Balance

Bridge contracts need LINK tokens to pay fees:
- **Minimum Balance**: Enough to cover expected fees
- **Recommended**: Buffer for multiple transactions

### Checking LINK Balance

```bash
cast call 0x514910771AF9Ca656af840dff83E8264EcF986CA \
  "balanceOf(address)" \
  <bridge_address> \
  --rpc-url <rpc_url>
```

### Acquiring LINK Tokens

1. **Purchase**: Buy LINK tokens on exchange
2. **Transfer**: Send LINK to bridge contract
3. **Faucet**: Use testnet faucet (if available)

---

## Fee Estimation

### Estimating Fees

For a typical cross-chain transfer:
- **Base Fee**: 0.001 LINK
- **Data Fee**: ~0.0001 LINK (depends on message size)
- **Total**: ~0.0011 LINK per transfer

### Factors Affecting Fees

1. **Message Size**: Larger messages = higher fees
2. **Destination Chain**: Different chains may have different fees
3. **Network Conditions**: Fees may vary with network load

---

## Fee Optimization

### Strategies

1. **Batch Transfers**: Combine multiple transfers to reduce per-transfer fees
2. **Optimize Message Size**: Minimize data in messages
3. **Monitor Fees**: Track fee trends and optimize timing

### Cost Analysis

- **Per Transfer**: ~0.001 LINK
- **Monthly (100 transfers)**: ~0.1 LINK
- **Annual (1000 transfers)**: ~1 LINK

---

## Troubleshooting

### Fee Calculation Failing

**Symptoms**:
- Scripts cannot calculate fees
- `getFee()` returns 0 or fails

**Solutions**:
1. Verify Router contract address
2. Check function availability
3. Verify LINK token configuration

### Insufficient LINK Balance

**Symptoms**:
- Transactions failing with insufficient balance
- Fee payment errors

**Solutions**:
1. Check LINK balance
2. Transfer LINK to bridge contract
3. Verify LINK token address

---

## Related Documentation

- [CCIP Router Configuration](./CCIP_ROUTER_CONFIGURATION.md)
- [CCIP Configuration Status](./CCIP_CONFIGURATION_STATUS.md)
- [Complete Task Catalog](./CCIP_COMPLETE_TASK_CATALOG.md)

---

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