smom-dbis-138/docs/operations/integrations/CCIP_INTEGRATION.md

# CCIP Integration Guide

## Overview

Chainlink Cross-Chain Interoperability Protocol (CCIP) enables secure cross-chain communication for oracle data updates. This guide explains how to integrate CCIP with the DeFi Oracle Meta Mainnet.

## Architecture

```
┌─────────────────┐         ┌──────────────┐         ┌─────────────────┐
│  Source Chain   │────────▶│  CCIP Router │────────▶│  Target Chain   │
│  (ChainID 138)  │         │              │         │  (Other Chain)  │
└─────────────────┘         └──────────────┘         └─────────────────┘
       │                            │                          │
       │                            │                          │
       ▼                            ▼                          ▼
┌──────────────┐         ┌──────────────┐         ┌──────────────┐
│ CCIPSender   │         │ CCIP Router  │         │ CCIPReceiver │
│  Contract    │         │   Service    │         │   Contract   │
└──────────────┘         └──────────────┘         └──────────────┘
```

## Components

### 1. CCIP Router Interface

The `IRouterClient` interface defines the standard CCIP Router interface for sending and receiving cross-chain messages.

**Location**: `contracts/ccip/IRouterClient.sol`

### 2. CCIP Sender Contract

The `CCIPSender` contract sends oracle data to other chains via CCIP.

**Location**: `contracts/ccip/CCIPSender.sol`

**Key Functions**:
- `sendOracleUpdate()`: Sends oracle price update to target chain
- `calculateFee()`: Calculates CCIP message fee

### 3. CCIP Receiver Contract

The `CCIPReceiver` contract receives oracle data from other chains via CCIP.

**Location**: `contracts/ccip/CCIPReceiver.sol`

**Key Functions**:
- `ccipReceive()`: Handles incoming CCIP messages
- `updateOracle()`: Updates oracle aggregator with received data

## Integration Steps

### Step 1: Deploy CCIP Router

1. Deploy Chainlink CCIP Router on your chain
2. Get the router address
3. Configure router in your contracts

### Step 2: Deploy CCIP Contracts

```bash
# Deploy CCIPSender
forge script script/DeployCCIPSender.s.sol --rpc-url $RPC_URL --broadcast

# Deploy CCIPReceiver
forge script script/DeployCCIPReceiver.s.sol --rpc-url $RPC_URL --broadcast
```

### Step 3: Configure Contracts

1. Set CCIP Router address in sender and receiver contracts
2. Set target chain selector
3. Configure oracle aggregator address
4. Set transmitter role for receiver contract

### Step 4: Send Cross-Chain Messages

```solidity
// In your oracle update function
CCIPSender sender = CCIPSender(senderAddress);
uint256 fee = sender.calculateFee(targetChainSelector, messageData);
sender.sendOracleUpdate{value: fee}(targetChainSelector, receiverAddress, priceData);
```

### Step 5: Receive Cross-Chain Messages

The CCIP Router automatically calls `ccipReceive()` on the receiver contract when a message arrives.

## Message Format

CCIP messages contain encoded oracle data:

```solidity
struct OracleMessage {
    uint256 answer;      // Oracle price/answer
    uint256 roundId;     // Round ID
    uint256 timestamp;   // Timestamp
}
```

## Fee Calculation

CCIP fees are calculated based on:
- Message size
- Target chain
- Gas price on target chain

Use `calculateFee()` to get the required fee before sending.

## Security Considerations

1. **Replay Protection**: Messages are tracked by `messageId` to prevent replay attacks
2. **Access Control**: Only authorized transmitters can update oracles
3. **Message Validation**: Validate message format and source chain
4. **Fee Management**: Ensure sufficient LINK tokens for fees

## Monitoring

Monitor CCIP message flow:
- Message send success/failure rates
- Message delivery latency
- Fee consumption
- Error rates

See `monitoring/prometheus/alerts/ccip.yml` for alerting rules.

## Troubleshooting

### Message Not Received

1. Check CCIP Router is deployed and running
2. Verify target chain selector is correct
3. Check receiver contract address is correct
4. Verify sufficient LINK tokens for fees
5. Check message was sent successfully

### High Fees

1. Optimize message size
2. Consider batching multiple updates
3. Monitor gas prices on target chain

### Replay Protection Errors

1. Check `processedMessages` mapping
2. Verify message IDs are unique
3. Check for duplicate message sends

## References

- [Chainlink CCIP Documentation](https://docs.chain.link/ccip)
- [CCIP Router Setup Guide](docs/CCIP_ROUTER_SETUP.md)
- [CCIP Message Format](docs/CCIP_MESSAGE_FORMAT.md)
- [CCIP Fees](docs/CCIP_FEES.md)