proxmox/docs/04-configuration/ACTIVITY_FEED_SPEC.md

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, heatmap-chains.ts (ALT vs B/SBS), 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"
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 or 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):

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
• Down: 0014_activity_events.down.sql

Run with your existing migration runner (e.g. golang-migrate, node-pg-migrate) against the explorer/backend DB.