explorer-monorepo/docs/specs/ccip/ccip-event-schema.md

CCIP Event Schema Specification

Overview

This document specifies the event schemas for CCIP messages on source and destination chains.

Source Chain Events

MessageSent Event

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

Decoded Structure:

{
  "event": "MessageSent",
  "messageId": "0x...",  // Derived from tx hash + log index
  "sender": "0x...",
  "destinationChainSelector": "866240039685049171407962509760789466724431933144813155647626",
  "receiver": "0x...",
  "data": "0x...",
  "feeToken": "0x...",
  "fee": "1000000000000000000",
  "transactionHash": "0x...",
  "blockNumber": 12345,
  "logIndex": 5,
  "timestamp": "2024-01-01T00:00:00Z"
}

MessageSentWithTransfer Event (if applicable)

For token transfers via CCIP:

{
  "event": "MessageSentWithTransfer",
  "messageId": "0x...",
  "token": "0x...",
  "amount": "1000000000000000000",
  // ... other MessageSent fields
}

Destination Chain Events

MessageExecuted Event

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

Decoded Structure:

{
  "event": "MessageExecuted",
  "messageId": "0x...",
  "sourceChainSelector": "866240039685049171407962509760789466724431933144813155647626",
  "sender": "0x...",
  "data": "0x...",
  "transactionHash": "0x...",
  "blockNumber": 19000000,
  "logIndex": 10,
  "timestamp": "2024-01-01T00:05:00Z",
  "status": "success"  // or "failed" if execution reverted
}

MessageExecutionFailed Event (if applicable)

For failed executions:

{
  "event": "MessageExecutionFailed",
  "messageId": "0x...",
  "reason": "execution reverted",
  // ... other fields
}

Message Metadata Schema

Stored Message Structure

{
  "message_id": "0x...",
  "source": {
    "chain_id": 138,
    "tx_hash": "0x...",
    "block_number": 12345,
    "sender": "0x...",
    "receiver": "0x...",
    "destination_chain_selector": "866240039685049171407962509760789466724431933144813155647626",
    "data": "0x...",
    "fee_token": "0x...",
    "fee": "1000000000000000000",
    "timestamp": "2024-01-01T00:00:00Z"
  },
  "destination": {
    "chain_id": 1,
    "tx_hash": "0x...",
    "block_number": 19000000,
    "sender": "0x...",
    "receiver": "0x...",
    "status": "executed",
    "timestamp": "2024-01-01T00:05:00Z"
  },
  "status": "executed",
  "retry_count": 0,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:05:00Z"
}

Status Transition Model

State Machine

[Sent] → [Delivered] → [Executing] → [Executed]
              ↓
          [Failed]
              ↓
          [Expired] (if timeout)

Status Definitions

• sent: Message sent on source chain, event indexed
• delivered: Message delivered to CCIP DON (if detectable)
• executing: Message execution started on destination
• executed: Message executed successfully
• failed: Message execution failed/reverted
• expired: Message timeout exceeded

References

• CCIP Tracking: See ccip-tracking.md
• Database Schema: See ../database/postgres-schema.md