# 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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "event": "MessageExecutionFailed",
  "messageId": "0x...",
  "reason": "execution reverted",
  // ... other fields
}
```

## Message Metadata Schema

### Stored Message Structure

```json
{
  "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`