smom-dbis-138/docs/ccip-integration/README.md

CCIP Integration: Chain-138 to Ethereum Mainnet

Overview

Production-grade CCIP integration that turns Chain-138 activity into verified, on-chain Ethereum transactions using Chainlink CCIP.

Architecture

Chain-138 (Source)                    Chainlink CCIP                    Ethereum Mainnet (Destination)
┌──────────────────┐                  ┌──────────────┐                  ┌──────────────────┐
│ CCIPTxReporter   │ ────ccipSend───> │ CCIP Router  │ ────ccipReceive─> │ CCIPLogger       │
│ (Sender)         │                  │ / Oracle     │                  │ (Receiver)       │
└──────────────────┘                  │ Network      │                  └──────────────────┘
         ▲                            └──────────────┘                           │
         │                                                                         │
         │                                                                         ▼
┌──────────────────┐                                                      ┌──────────────┐
│ Watcher/Relayer   │                                                      │ Events &     │
│ (Off-chain)       │                                                      │ State        │
└──────────────────┘                                                      └──────────────┘

Components

1. Smart Contracts

CCIPLogger (Ethereum Mainnet)

• Location: contracts/ccip-integration/CCIPLogger.sol
• Purpose: Receives and logs Chain-138 transactions via CCIP
• Features:
  • Replay protection (batch ID tracking)
  • Optional signature verification
  • Source chain validation
  • Event emission for indexing

CCIPTxReporter (Chain-138)

• Location: contracts/ccip-integration/CCIPTxReporter.sol
• Purpose: Reports Chain-138 transactions to Ethereum via CCIP
• Features:
  • Single transaction reporting
  • Batch reporting (cost optimization)
  • Fee estimation
  • Automatic refund of excess fees

2. Deployment Scripts

• CCIPLogger: scripts/ccip-deployment/deploy-ccip-logger.js
• CCIPTxReporter: scripts/ccip-deployment/deploy-ccip-reporter.js

3. Watcher/Relayer Service

• Location: watcher/
• Purpose: Off-chain service that watches Chain-138 and relays transactions
• Features:
  • WebSocket/HTTP subscription to Chain-138
  • Postgres outbox pattern for reliability
  • Batching for cost optimization
  • Retry logic with exponential backoff
  • Metrics and monitoring

Deployment Guide

Prerequisites

1. Install dependencies:

npm install
cd watcher && npm install

2. Configure .env:

# Ethereum Mainnet
ETHEREUM_MAINNET_RPC=https://mainnet.infura.io/v3/YOUR_KEY
ETHERSCAN_API_KEY=your_etherscan_key
CCIP_ETH_ROUTER=0x80226fc0Ee2b096224EeAc085Bb9a8cba1146f7D
ETH_MAINNET_SELECTOR=0x500147

# Chain-138
CHAIN138_RPC_URL=https://rpc.d-bis.org
CHAIN138_RPC_WS=wss://rpc.d-bis.org/ws
CCIP_CHAIN138_ROUTER=<chain-138-ccip-router-address>
CHAIN138_SELECTOR=0x000000000000008a

# Deployment
PRIVATE_KEY=your_deployer_private_key
AUTHORIZED_SIGNER=optional_signer_address

# Relayer
RELAYER_PRIVATE_KEY=relayer_private_key
BATCH_SIGNER_PRIVATE_KEY=batch_signer_private_key
DATABASE_URL=postgresql://user:pass@localhost:5432/ccip_relayer

Step 1: Deploy CCIPLogger to Ethereum Mainnet

npm run deploy:logger:mainnet

This will:

1. Deploy CCIPLogger contract
2. Display deployment address
3. Provide verification command

Step 2: Deploy CCIPTxReporter to Chain-138

npm run deploy:reporter:chain138

This will:

1. Deploy CCIPTxReporter contract
2. Configure it with CCIPLogger address
3. Display deployment address

Step 3: Verify Contracts

# Verify CCIPLogger on Etherscan
npx hardhat verify --network mainnet <CCIP_LOGGER_ADDRESS> <ROUTER> <SIGNER> <SELECTOR>

# Verify CCIPTxReporter (if explorer available)
npx hardhat verify --network chain138 <CCIP_REPORTER_ADDRESS> <ROUTER> <SELECTOR> <RECEIVER>

Step 4: Start Watcher/Relayer

cd watcher
npm run build
npm start

Configuration

CCIP Directory

Use the Chainlink CCIP Directory to get:

• Chain selectors for each network
• Router addresses
• Supported tokens

Chain Selectors

Update chain selectors in .env based on CCIP Directory:

• Ethereum Mainnet: Check CCIP Directory
• Chain-138: Check CCIP Directory or contact Chainlink support

Security Checklist

• Use multisig (Gnosis Safe) for contract ownership
• Store private keys in hardware KMS (AWS KMS, GCP KMS, YubiKey)
• Set authorizedSigner for batch verification
• Configure expectedSourceChainSelector correctly
• Implement rate limiting in watcher
• Set up monitoring and alerting
• Test on testnets before mainnet deployment
• Review gas limits and fee management
• Implement circuit breakers for error conditions

Monitoring

Metrics

The watcher exposes Prometheus metrics:

• ccip_batches_sent_total
• ccip_batches_success_total
• ccip_batches_failed_total
• ccip_tx_queue_size
• ccip_fee_estimate_gwei

Alerts

Set up alerts for:

• Failed batch deliveries
• Low LINK/ETH balance
• High queue size
• CCIP delivery latency

Testing

Local Testing with Chainlink Local

1. Start Chainlink Local:

docker run -p 6688:6688 chainlink/local:latest

2. Run integration tests:

npm test

Testnet Testing

1. Deploy to Sepolia (Ethereum testnet)
2. Deploy to Chain-138 testnet (if available)
3. Test full flow end-to-end

Cost Optimization

1. Batching: Group multiple transactions per CCIP message
2. Compression: Store only hashes on-chain, full data off-chain
3. Adaptive Batching: Adjust batch size based on mempool activity
4. Fee Management: Monitor and optimize CCIP fees

References

• Chainlink CCIP Documentation
• CCIP Directory
• CCIP Starter Kit
• Chainlink Local

Support

For issues or questions:

1. Check Chainlink CCIP documentation
2. Review contract code comments
3. Check watcher logs
4. Contact Chainlink support for CCIP-specific issues