Add full monorepo: virtual-banker, backend, frontend, docs, scripts, deployment
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
defiQUG
138
docs/specs/ccip/ccip-event-schema.md
Normal file
138
docs/specs/ccip/ccip-event-schema.md
Normal file
@@ -0,0 +1,138 @@
|
||||
# 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`
|
||||
|
||||
110
docs/specs/ccip/ccip-observability.md
Normal file
110
docs/specs/ccip/ccip-observability.md
Normal file
@@ -0,0 +1,110 @@
|
||||
# CCIP Observability Dashboard Specification
|
||||
|
||||
## Overview
|
||||
|
||||
This document specifies the observability dashboards and analytics for CCIP message lifecycle visualization and monitoring.
|
||||
|
||||
## Dashboard Components
|
||||
|
||||
### Message Lifecycle Visualization
|
||||
|
||||
**Components**:
|
||||
- Timeline view showing source → CCIP → destination flow
|
||||
- Status indicators at each stage
|
||||
- Time metrics (send time, delivery time, execution time)
|
||||
- Transaction links (click to view source/destination transactions)
|
||||
|
||||
**Visualization**:
|
||||
```
|
||||
[Source Chain] → [CCIP DON] → [Destination Chain]
|
||||
✓ ✓ ✓
|
||||
Sent Delivered Executed
|
||||
00:00 00:02 00:05
|
||||
```
|
||||
|
||||
### Status Aggregation
|
||||
|
||||
**Metrics**:
|
||||
- Total messages by status
|
||||
- Success rate (% executed successfully)
|
||||
- Average execution time
|
||||
- Failed message count
|
||||
- Expired message count
|
||||
|
||||
**Time Series**:
|
||||
- Messages per hour/day
|
||||
- Success rate over time
|
||||
- Average execution time over time
|
||||
|
||||
### Failure Analysis
|
||||
|
||||
**Failure Categories**:
|
||||
- Execution failures (revert on destination)
|
||||
- Timeouts (expired messages)
|
||||
- Delivery failures (CCIP DON issues)
|
||||
- Invalid messages
|
||||
|
||||
**Analysis**:
|
||||
- Failure rate by category
|
||||
- Common failure reasons
|
||||
- Failure patterns (time, chain pairs, etc.)
|
||||
|
||||
### Performance Metrics
|
||||
|
||||
**Metrics**:
|
||||
- Average delivery time (source → CCIP)
|
||||
- Average execution time (CCIP → destination)
|
||||
- Total end-to-end time
|
||||
- P50, P95, P99 latencies
|
||||
|
||||
**Charts**:
|
||||
- Latency distribution
|
||||
- Latency trends over time
|
||||
- Latency by chain pair
|
||||
|
||||
## Cross-Chain Analytics
|
||||
|
||||
### Chain Pair Analysis
|
||||
|
||||
**Metrics per Chain Pair**:
|
||||
- Message volume
|
||||
- Success rate
|
||||
- Average latency
|
||||
- Popular routes
|
||||
|
||||
**Visualization**:
|
||||
- Network graph showing chain connections
|
||||
- Edge weights showing message volume
|
||||
- Color coding for success rates
|
||||
|
||||
### Token Flow Analysis
|
||||
|
||||
**Tracking**:
|
||||
- Token transfers via CCIP
|
||||
- Volume by token
|
||||
- Volume by chain pair
|
||||
- Cumulative volume over time
|
||||
|
||||
## Real-Time Monitoring
|
||||
|
||||
### Live Message Stream
|
||||
|
||||
**Features**:
|
||||
- Real-time updates of new messages
|
||||
- Status change notifications
|
||||
- Alert on failures
|
||||
- Filter by chain, status, etc.
|
||||
|
||||
### Alerts
|
||||
|
||||
**Alert Conditions**:
|
||||
- High failure rate (> 5%)
|
||||
- Message timeout (> 30 minutes)
|
||||
- Unusual message volume spike
|
||||
- Chain connectivity issues
|
||||
|
||||
## References
|
||||
|
||||
- CCIP Tracking: See `ccip-tracking.md`
|
||||
- Observability: See `../observability/`
|
||||
|
||||
203
docs/specs/ccip/ccip-tracking.md
Normal file
203
docs/specs/ccip/ccip-tracking.md
Normal file
@@ -0,0 +1,203 @@
|
||||
# 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
|
||||
|
||||
```mermaid
|
||||
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**:
|
||||
```sql
|
||||
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**:
|
||||
```json
|
||||
{
|
||||
"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`
|
||||
|
||||
Reference in New Issue
Block a user