# 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.