explorer-monorepo/docs/specs/ccip/ccip-tracking.md

CCIP Message Tracking Specification

Overview

This document specifies how CCIP (Cross-Chain Interoperability Protocol) messages are tracked from source chain to destination chain, including status monitoring and execution receipt linking.

CCIP Message Lifecycle

sequenceDiagram
    participant Source as Source Chain
    participant CCIP as CCIP DON
    participant Dest as Destination Chain
    participant Indexer as Indexer
    
    Source->>Indexer: Emit CCIP MessageSent event
    Indexer->>Indexer: Index source tx + messageId
    CCIP->>Dest: Deliver message
    Dest->>Indexer: Emit CCIP MessageExecuted event
    Indexer->>Indexer: Link messageId to dest tx
    Indexer->>Indexer: Update message status

Message Ingestion

Source Chain Events

Event: MessageSent(address indexed sender, uint64 indexed destinationChainSelector, bytes receiver, bytes data, address feeToken, uint256 fee)

Data Extracted:

• messageId: Unique message identifier
• sender: Source address
• destinationChainSelector: Destination chain selector
• receiver: Destination receiver address
• data: Message payload
• feeToken: Fee token address
• fee: Fee amount
• transactionHash: Source transaction hash
• blockNumber: Source block number
• timestamp: Source transaction timestamp

Destination Chain Events

Event: MessageExecuted(bytes32 indexed messageId, uint64 indexed sourceChainSelector, bytes sender, bytes data)

Data Extracted:

• messageId: Message identifier (matches source)
• sourceChainSelector: Source chain selector
• sender: Source sender address
• data: Message payload
• transactionHash: Destination transaction hash
• blockNumber: Destination block number
• timestamp: Destination transaction timestamp
• status: Execution status (success/failure)

Message ID Normalization

Message ID Format

Source: Generated from transaction hash and event log index Format: keccak256(transactionHash, logIndex) or CCIP-provided messageId

Normalization Strategy

Goal: Ensure consistent messageId across source and destination

Method:

1. Extract messageId from source event
2. Store with source transaction
3. Match with destination event by messageId
4. Link source and destination transactions

Delivery Status Tracking

Status States

States:

• sent: Message sent on source chain
• delivered: Message delivered to CCIP DON
• executing: Message executing on destination chain
• executed: Message executed successfully
• failed: Message execution failed
• expired: Message expired (timeout)

Status Transitions

sent → delivered → executing → executed
                ↓
              failed
                ↓
             expired (if timeout)

Status Updates

Tracking:

• Monitor destination chain for execution events
• Poll CCIP router for message status (if API available)
• Track timeout periods
• Update status in database

Execution Receipt Linking

Receipt Storage

Database Schema:

CREATE TABLE ccip_messages (
    id UUID PRIMARY KEY,
    message_id VARCHAR(66) NOT NULL UNIQUE,
    source_chain_id INTEGER NOT NULL,
    source_tx_hash VARCHAR(66) NOT NULL,
    source_block_number BIGINT NOT NULL,
    destination_chain_id INTEGER NOT NULL,
    destination_tx_hash VARCHAR(66),
    destination_block_number BIGINT,
    status VARCHAR(20) NOT NULL,
    sent_at TIMESTAMP NOT NULL,
    executed_at TIMESTAMP,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

Linking Process

Steps:

1. Index source transaction with messageId
2. Wait for destination chain event
3. Match messageId from destination event
4. Link destination transaction to source
5. Update status to "executed" or "failed"

Retry Tracking

Retry Detection

Detection:

• Multiple execution attempts with same messageId
• Track retry count
• Store retry timestamps

Retry Data

Fields:

• retry_count: Number of retry attempts
• retry_timestamps: Array of retry attempt times
• last_retry_at: Last retry timestamp

API Endpoints

Get Message by ID

GET /api/v1/ccip/messages/{message_id}

Response:

{
  "message_id": "0x...",
  "source": {
    "chain_id": 138,
    "tx_hash": "0x...",
    "block_number": 12345,
    "sender": "0x...",
    "timestamp": "2024-01-01T00:00:00Z"
  },
  "destination": {
    "chain_id": 1,
    "tx_hash": "0x...",
    "block_number": 19000000,
    "receiver": "0x...",
    "timestamp": "2024-01-01T00:05:00Z"
  },
  "status": "executed",
  "sent_at": "2024-01-01T00:00:00Z",
  "executed_at": "2024-01-01T00:05:00Z"
}

Get Message by Transaction

GET /api/v1/ccip/transactions/{chain_id}/{tx_hash}/messages

Response: Array of CCIP messages for transaction

Search Messages

GET /api/v1/ccip/messages

Query Parameters:

• source_chain_id: Filter by source chain
• destination_chain_id: Filter by destination chain
• status: Filter by status
• sender: Filter by sender address
• receiver: Filter by receiver address

References

• CCIP Observability: See ccip-observability.md
• CCIP Event Schema: See ccip-event-schema.md
• Graph Database: See ../database/graph-schema.md