smom-dbis-138/docs/relay/ARCHITECTURE.md

CCIP Relay Architecture

Overview

The custom CCIP relay mechanism enables cross-chain message delivery from Chain 138 to Ethereum Mainnet by implementing an off-chain relay service that monitors events and delivers messages to destination chain contracts.

System Architecture

┌─────────────────┐
│   Chain 138     │
│                 │
│  CCIP Router    │───MessageSent Event───┐
│  (0xd49B5...)   │                       │
│                 │                       │
│  WETH9 Bridge   │                       │
│  (0xBBb4a...)   │                       │
│                 │                       │
│  [User sends    │                       │
│   20k WETH9]    │                       │
└─────────────────┘                       │
                                          │
                                          ▼
                              ┌───────────────────────┐
                              │  Relay Service        │
                              │  (Off-chain)          │
                              │                       │
                              │  - Event Monitoring   │
                              │  - Message Queue      │
                              │  - Token Mapping      │
                              │  - Message Relay      │
                              └───────────────────────┘
                                          │
                                          │ HTTP/WebSocket
                                          │ Transaction
                                          │
                                          ▼
┌──────────────────────────────────────────────────────┐
│           Ethereum Mainnet                           │
│                                                       │
│  ┌──────────────────┐      ┌──────────────────┐    │
│  │ Relay Router     │─────▶│ Relay Bridge     │    │
│  │ (Access Control) │      │ (Token Transfer) │    │
│  │                  │      │                  │    │
│  │ - Authorize      │      │ - Receives       │    │
│  │   bridges        │      │   messages       │    │
│  │ - Grant relayer  │      │ - Transfers      │    │
│  │   roles          │      │   WETH9 to       │    │
│  └──────────────────┘      │   recipients     │    │
│                            └──────────────────┘    │
│                                     │                │
│                                     ▼                │
│                            ┌──────────────────┐    │
│                            │   WETH9 Token    │    │
│                            │   Transfer       │    │
│                            └──────────────────┘    │
│                                     │                │
│                                     ▼                │
│                            ┌──────────────────┐    │
│                            │   Recipient      │    │
│                            │   Receives 20k   │    │
│                            │   WETH9          │    │
│                            └──────────────────┘    │
└──────────────────────────────────────────────────────┘

Components

1. Source Chain (Chain 138)

CCIP Router (0xd49B579DfC5912fA7CAa76893302c6e58f231431)

• Emits MessageSent events when messages are sent
• Stores message metadata
• Collects fees
• Note: This is a custom router that simulates CCIP - it only emits events and does not actually relay messages cross-chain

WETH9 Bridge (0xBBb4a9202716eAAB3644120001cC46096913a3C8)

• Locks WETH9 tokens from users
• Creates CCIP messages
• Sends messages via router

WETH9 Token (0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2)

• Wrapped Ether token on Chain 138

2. Relay Service (Off-chain)

Event Monitor

• Listens for MessageSent events from router
• Polls for historical events as fallback
• Filters messages for target destination chain (Ethereum Mainnet, chain selector: 5009297550715157269)

Message Queue

• Queues detected messages
• Manages retry logic
• Tracks processed/failed messages
• Prevents duplicate processing

Token Address Mapping

• Maps source chain token addresses to destination chain addresses
• Ensures bridge receives correct token addresses
• Currently maps WETH9 Chain 138 → WETH9 Mainnet (same address in this case)

Message Relay

• Constructs Any2EVMMessage format with mapped token addresses
• Calls relayMessage on destination relay router
• Handles errors and retries
• Monitors transaction status

3. Destination Chain (Ethereum Mainnet)

Relay Router (0xAd9A228CcEB4cbB612cD165FFB72fE090ff10Afb)

• Receives relayed messages from off-chain service
• Authorizes bridge contracts (only authorized bridges can receive messages)
• Grants relayer roles (only authorized relayers can call relayMessage)
• Forwards messages to authorized bridges using interface calls for proper ABI encoding
• Emits MessageRelayed events

Relay Bridge (0xF9A32F37099c582D28b4dE7Fca6eaC1e5259f939)

• Receives messages from relay router
• Validates message format
• Implements replay protection (tracks processed messageIds)
• Transfers WETH9 tokens to recipients
• CRITICAL: Must be funded with WETH9 tokens to complete transfers
• Emits CrossChainTransferCompleted events

WETH9 Token (0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2)

• Wrapped Ether token on Ethereum Mainnet
• Bridge must hold sufficient balance for transfers

Message Flow

1. User initiates transfer on Chain 138

   • User calls sendCrossChain() on bridge
   • Bridge locks 20,000 WETH9 from user
   • Bridge creates CCIP message with:
     • Receiver: Destination bridge address
     • Data: (recipient, amount, sender, nonce)
     • TokenAmounts: [{token: WETH9, amount: 20000e18, amountType: 0}]
   • Bridge calls router's ccipSend()
   • Router emits MessageSent event

2. Relay service detects event

   • Service monitors router for MessageSent events
   • Filters for Ethereum Mainnet destination (chain selector: 5009297550715157269)
   • Adds message to queue
   • Logs message detection

3. Message queued for relay

   • Message stored in queue with metadata
   • Retry count initialized (starts at 0)
   • Status: pending
   • Queue size tracked

4. Relay service processes message

   • Service constructs Any2EVMMessage:
     • messageId: From event
     • sourceChainSelector: 138 (chain ID)
     • sender: Encoded as bytes
     • data: Original message data
     • tokenAmounts: Token addresses mapped to destination chain
   • Service calls relayMessage(bridge, message) on Relay Router (Mainnet)
   • Transaction sent with relayer's private key
   • Gas limit: 1,000,000

5. Relay Router validates and forwards

   • Checks relayer has RELAYER_ROLE (AccessControl)
   • Verifies bridge is authorized
   • Calls bridge's ccipReceive(message) using interface call
   • Interface call ensures proper ABI encoding for complex structs

6. Relay Bridge processes message

   • Validates messageId (replay protection - checks processedTransfers)
   • Marks message as processed
   • Validates token amounts (length > 0, token == WETH9, amount > 0)
   • Decodes recipient from message data
   • Transfers WETH9 to recipient (requires bridge has sufficient balance)
   • Emits CrossChainTransferCompleted event

7. Recipient receives tokens

   • WETH9 balance increased
   • Transfer complete

Security Considerations

Access Control

• Relayer Role: Only addresses with RELAYER_ROLE can call relayMessage on router
• Bridge Authorization: Only pre-authorized bridges can receive messages
• Admin Controls: Admin can add/remove bridges and relayers via AccessControl

Replay Protection

• Message IDs tracked in bridge contract (processedTransfers mapping)
• Each messageId can only be processed once
• Prevents duplicate token transfers
• Bridge checks processedTransfers[messageId] before processing

Message Validation

• Bridge validates token address matches WETH9 on destination chain
• Bridge validates amount > 0
• Bridge validates recipient != address(0)
• Bridge validates tokenAmounts array has elements

Token Address Mapping

• Source chain token addresses are mapped to destination chain addresses
• Prevents invalid token transfers
• Currently maps WETH9 Chain 138 → WETH9 Mainnet

Operational Security

• Private keys should be secured (hardware wallet or key management)
• Service should run in secure environment
• Monitor for failed relays and retry appropriately
• Implement rate limiting (future improvement)

Critical Operational Requirement

Bridge Funding: The relay bridge MUST be funded with WETH9 tokens before it can complete any transfers. This is the most common reason for failed relays.

Error Handling

Relay Service Errors

• Network errors: Retry with exponential backoff
• Transaction failures: Log error, retry up to MAX_RETRIES (default: 3)
• Gas estimation failures: Use fixed gas limit (1,000,000)
• Message encoding errors: Log error, skip message

Contract Errors

• Unauthorized relayer: Grant RELAYER_ROLE in router
• Bridge not authorized: Authorize bridge in router
• Duplicate message: Message already processed (expected - skip)
• Insufficient WETH9: Fund bridge with WETH9 tokens (CRITICAL)
• Invalid token: Token address mismatch - check token mapping
• Invalid amount: Amount is zero - invalid message

Monitoring

Key Metrics

• Messages detected per hour
• Messages relayed successfully
• Failed relay attempts
• Average relay time (from detection to completion)
• Bridge WETH9 balance
• Gas costs per relay
• Queue size

Alerts

• Bridge WETH9 balance below threshold (CRITICAL)
• High failure rate (> 5%)
• Service downtime
• Unprocessed messages in queue
• Relayer ETH balance low

Logging

• All events logged to relay-service.log
• Error logs include full error details
• Transaction hashes logged for tracking
• Message IDs logged for debugging

Scalability

Current Limitations

• Single relay instance
• Sequential message processing
• No message batching
• Manual bridge funding

Future Improvements

• Multiple relay instances (high availability)
• Parallel message processing
• Message batching to reduce gas costs
• Priority queue for time-sensitive messages
• Automatic bridge funding mechanism
• Distributed relay network

Current Deployment Status

Contracts Deployed

• ✅ Relay Router: 0xAd9A228CcEB4cbB612cD165FFB72fE090ff10Afb
• ✅ Relay Bridge: 0xF9A32F37099c582D28b4dE7Fca6eaC1e5259f939
• ✅ Router configured (bridge authorized, relayer role granted)
• ✅ Service running and monitoring

Operational Status

• ✅ Service: Running
• ✅ Monitoring: Active
• ⚠️ Bridge Funding: REQUIRED (must have WETH9 tokens)

Known Issues

• None (all technical issues resolved)
• Bridge funding is operational requirement, not a bug

Related Documentation

• Service README
• Deployment Guide
• Investigation Report