e4c9dda0fd
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
- Marked submodules ai-mcp-pmm-controller, explorer-monorepo, and smom-dbis-138 as dirty to reflect recent changes. - Updated documentation to clarify operator script usage, including dotenv loading and task execution instructions. - Enhanced the README and various index files to provide clearer navigation and task completion guidance. Made-with: Cursor
92 lines
4.3 KiB
Markdown
92 lines
4.3 KiB
Markdown
# Activity Feed — Event Schema and Ingestion
|
|
|
|
**Purpose:** Canonical event model and ingestion spec for the normalized activity feed: transfers, app events, and bridge stitching. Table: `activity_events` (migration 0014).
|
|
|
|
**References:** [indexer-architecture.md](../../explorer-monorepo/docs/specs/indexing/indexer-architecture.md), [heatmap-chains.ts](../../smom-dbis-138/services/token-aggregation/src/config/heatmap-chains.ts) (ALT vs B/SBS), [cross-chain-bridges.ts](../../smom-dbis-138/services/token-aggregation/src/config/cross-chain-bridges.ts) (`getRouteFromRegistry`).
|
|
|
|
---
|
|
|
|
## 1. Table: `activity_events`
|
|
|
|
| Column | Type | Description |
|
|
|--------|------|-------------|
|
|
| `id` | uuid | Primary key (default gen_random_uuid()) |
|
|
| `chain_id` | integer | 138 or 651940 (and others when indexed) |
|
|
| `transaction_hash` | varchar(66) | Tx hash |
|
|
| `log_index` | integer | Log index (0 for tx-level) |
|
|
| `block_number` | bigint | Block number |
|
|
| `block_timestamp` | timestamptz | Block time |
|
|
| `actor` | varchar(42) | Wallet that initiated the action |
|
|
| `subject` | varchar(42) | Optional: user/account/tokenId/resource |
|
|
| `event_type` | varchar(32) | TRANSFER, APP_ACTION, CLAIM, BRIDGE_OUT, BRIDGE_IN |
|
|
| `contract_address` | varchar(42) | Contract that emitted or was called |
|
|
| `data` | jsonb | Parsed event fields |
|
|
| `routing` | jsonb | `{ "path": "ALT" | "CCIP", "fromChain", "toChain", "bridgeTxHash"?: string }` |
|
|
| `created_at` | timestamptz | Insert time |
|
|
|
|
**Unique:** `(chain_id, transaction_hash, log_index)`.
|
|
|
|
---
|
|
|
|
## 2. Ingestion
|
|
|
|
### 2.1 Transfers
|
|
|
|
- **Source:** Existing `token_transfers` (and ERC-721/1155 logs when indexed).
|
|
- **Mapping:** For each row: insert into `activity_events` with `event_type = 'TRANSFER'`, `actor = from_address`, `subject = to_address` (or token id for NFT), `data = { from, to, value, tokenContract }`, `contract_address = token_contract`. `routing` = NULL for same-chain transfers.
|
|
- **Backfill:** One-time or periodic job: `INSERT INTO activity_events (...) SELECT ... FROM token_transfers WHERE NOT EXISTS (...)`.
|
|
|
|
### 2.2 App events
|
|
|
|
- **Source:** Application-lifecycle events (create, complete, settle, redeem, etc.) from your contracts.
|
|
- **Registry:** Maintain a mapping (event signature → `event_type` + parser). Example: `0x...` → `APP_ACTION`, parse `data` from log topics/data.
|
|
- **Insert:** Decode log; set `event_type`, `actor` (e.g. tx from), `subject` (e.g. orderId), `data` (decoded fields), `contract_address`.
|
|
|
|
### 2.3 Bridge stitching
|
|
|
|
- **Source:** Bridge contracts (AlltraAdapter, CCIP WETH9/WETH10); events such as lock/burn on source, mint/release on destination.
|
|
- **Routing:** Use [getRouteFromRegistry](../../smom-dbis-138/services/token-aggregation/src/config/cross-chain-bridges.ts) or [config/routing-registry.json](../../config/routing-registry.json): 138↔651940 → `path: "ALT"`, 138↔others → `path: "CCIP"`.
|
|
- **Insert:** For each bridge event, set `routing = { path: "ALT"|"CCIP", fromChain, toChain, bridgeTxHash }`. Optionally correlate "bridge out" and "bridge in" with a shared `data.correlationId` so the API can return one stitched feed item per cross-chain move.
|
|
|
|
---
|
|
|
|
## 3. Activity feed API
|
|
|
|
**Queries:**
|
|
|
|
- **By user:** `WHERE actor = $address OR subject = $address` (paginated).
|
|
- **By token/NFT:** `WHERE subject = $tokenId` or `WHERE contract_address = $token AND data->>'tokenId' = $tokenId` (paginated).
|
|
- **Global:** `WHERE event_type IN (...)` with pagination by `(block_timestamp DESC, id DESC)`.
|
|
|
|
**Pagination:** Cursor-based using `(block_timestamp, id)`; limit e.g. 50 per page.
|
|
|
|
**Example (by user):**
|
|
|
|
```sql
|
|
SELECT * FROM activity_events
|
|
WHERE actor = $1 OR subject = $1
|
|
ORDER BY block_timestamp DESC, id DESC
|
|
LIMIT 50 OFFSET $2;
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Event type enum (logical)
|
|
|
|
| event_type | Description |
|
|
|------------|-------------|
|
|
| TRANSFER | ERC-20/721/1155 transfer |
|
|
| APP_ACTION | App-lifecycle (create, complete, settle, etc.) |
|
|
| CLAIM | Claim/mint from drop or contract |
|
|
| BRIDGE_OUT | Lock/burn on source chain |
|
|
| BRIDGE_IN | Mint/release on destination chain |
|
|
|
|
---
|
|
|
|
## 5. Migration
|
|
|
|
- **Up:** [0014_activity_events.up.sql](../../explorer-monorepo/backend/database/migrations/0014_activity_events.up.sql)
|
|
- **Down:** `0014_activity_events.down.sql`
|
|
|
|
Run with your existing migration runner (e.g. golang-migrate, node-pg-migrate) against the explorer/backend DB.
|