P5-W3: Protocol / TVL Pack — Gold datasets, protocol activity and TVL analytics

[user1303836]

Summary

• Gold-tier datasets: Added protocol_events and pool_snapshots datasets materialized from Silver decoded_events and token_transfers
• Protocol analytics module: compute_protocol_events(), compute_pool_snapshots(), build_protocol_activity(), and build_tvl_analytics() functions in new adapters/src/protocol_analytics.rs
• API endpoints: /v1/analytics/protocol/activity and /v1/analytics/protocol/tvl behind auth
• Migration: protocol_events and pool_snapshots tables with appropriate indexes, IF NOT EXISTS guards, and foreign keys
• Dataset registry: QUERYABLE_DATASETS and EXPORTABLE_DATASETS extended to 12 entries each; DatasetName::all() returns 13 datasets (7 Silver + 6 Gold)
• Full backward compatibility with P5-W1 (Wallet/Tax/Forensics) and P5-W2 (Hyperliquid Analytics)

Validation

• All 915 tests pass (0 failures)
• cargo fmt and cargo clippy clean
• ProtocolEvent correctly classifies decoded events by type (swap/mint/burn/liquidity_added/liquidity_removed/transfer/other) with protocol_address mapping
• PoolSnapshot captures reserve state with optional TVL
• ProtocolActivity aggregation produces correct event counts, unique participants, and time ranges
• TvlAnalytics produces per-pool and aggregate TVL with latest-snapshot dedup
• Both analytics endpoints route correctly behind auth
• CSV export tests validate well-formed header+data for both datasets
• README updated with new endpoints and datasets

Test plan

• cargo fmt --all --check — clean
• cargo clippy --workspace --all-targets -- -D warnings — clean
• cargo test --workspace — 915 tests pass
• GHA CI passes on this PR
• Reviewer validates protocol event classification logic
• Reviewer validates TVL aggregation and dedup behavior

🤖 Generated with Claude Code

[user1303836]

Remote Review — P5-W3: Protocol / TVL Pack

Verdict: No blocking issues. Clear from PR-comment review perspective.

Review against focus areas

1. Gold dataset design ✅ — protocol_events adds meaningful protocol-level context over raw decoded_events: event type classification (swap/mint/burn/liquidity_added/liquidity_removed/transfer/other), protocol_address derivation from program_or_contract, and pool_address extraction. This is a genuine aggregation layer, not a copy.

2. Pool snapshot semantics ✅ — compute_pool_snapshots correctly derives a point-in-time snapshot from the latest decoded event, extracting reserve values from decoded fields. build_tvl_analytics correctly deduplicates by pool (latest snapshot per pool), producing true point-in-time state.

3. TVL calculation ✅ — tvl_usd is Option<BigDecimal> (nullable). build_tvl_analytics handles missing price data gracefully: when all pool TVLs are None, both protocol and total TVL resolve to None. Reserves are derived from reserve0/reserve1 or amount0/amount1 decoded fields with BigDecimal parsing. Tests cover single-pool, multi-pool, no-USD, empty, and latest-snapshot-dedup cases.

4. Additive-only ✅ — No existing Silver datasets, shared repository methods, or Gold datasets were modified. All changes to existing files are purely additive (new enum variants, new query methods, new route registrations, updated counts). Verified: v2_repo.rs adds new row_to_* converters and query methods without touching existing ones; materializer.rs adds new struct definitions and enum variants; api/src/main.rs adds new routes and handlers alongside existing ones.

5. Auth scoping ✅ — Both /v1/analytics/protocol/activity and /v1/analytics/protocol/tvl are registered inside the same require_auth middleware layer as all other /v1/* routes. Tests explicitly verify auth is required (test_protocol_activity_requires_auth, test_protocol_tvl_requires_auth).

6. Migration conventions ✅ — IF NOT EXISTS guards on all CREATE TABLE and CREATE INDEX statements. Proper FK references to decoded_events(id) and dataset_versions(id). Indexes on protocol_address, pool_address, network, timestamp (DESC), and event_type. tvl_usd NUMERIC is correctly nullable (no NOT NULL).

7. Backward compatibility ✅ — Explicit compatibility tests verify P5-W1 wallet endpoints and P5-W2 HL analytics endpoints still route. Dataset counts are additive (10→12 for both queryable and exportable). No existing route, handler, or query method was modified.

Non-blocking observations

• Redundant TVL aggregation branches: In build_tvl_analytics, the if tvls.iter().all(|t| t.is_some()) and else if tvls.iter().any(|t| t.is_some()) branches produce identical results (both sum the Some values). Could simplify to a single if tvls.iter().any(...) branch.
• Unused _token_transfers parameter: compute_pool_snapshots accepts token_transfers but doesn't use them. The comment documents this as a simplification for future enhancement — acceptable for this pack.
• No composite unique constraint on pool_snapshots: A UNIQUE(pool_address, snapshot_timestamp) or UNIQUE(pool_address, network, snapshot_timestamp) constraint could prevent duplicate snapshots at the DB level. Not blocking since dedup is handled in the application layer.
• Analytics endpoint uses export-capped query (100k): protocol_activity_handler calls export_protocol_events (capped at EXPORT_MAX_RECORDS). For very active protocols this could silently truncate data, producing incomplete aggregates. This follows the same pattern as P5-W2's analytics handlers, so it's a pre-existing architectural choice, not a regression.
• CI checks: Formatting and Clippy pass. Tests and Release Build are still in progress at time of review.

Summary

Clean implementation. Follows established patterns from P5-W1 and P5-W2. Proper Gold materialization with genuine protocol-level enrichment. TVL nullable handling is correct. Auth, migration, additive-only, and backward compatibility criteria all met. Ready to merge once CI completes green.