P5-W2: Hyperliquid Analytics Pack — Gold datasets and dashboard endpoints

[user1303836]

Summary

Phase 5, Work Packet 2: Adds Gold-tier Hyperliquid analytics datasets and dashboard-ready endpoints, proving a Hyperliquid dashboard can consume Spectraplex outputs directly without raw chain parsing.

• Gold datasets: hl_pnl_summary (closed PnL + funding − fees) and hl_trade_history (open→close sequences with weighted avg entry price), materialized from Silver hl_fills and hl_funding
• Analytics endpoints: /v1/analytics/hl/trader and /v1/analytics/hl/market for dashboard-ready aggregations, behind auth
• Migration: 20260310300000_add_hl_analytics_gold.sql with IF NOT EXISTS guards and proper indexes
• Dataset registry: DatasetName::all() returns 11 datasets; QUERYABLE_DATASETS and EXPORTABLE_DATASETS each contain 10 entries including the two new ones
• Full backward compatibility with P5-W1 and P4-W5 confirmed

Key files

File	Purpose
adapters/src/hl_analytics.rs	Materialization logic, trader/market analytics, CSV export
core/src/materializer.rs	Dataset registration for hl_pnl_summary and hl_trade_history
adapters/src/v2_repo.rs	Repository queries for Gold HL analytics tables
api/src/main.rs	/v1/analytics/hl/trader and /v1/analytics/hl/market route handlers
migrations/20260310300000_add_hl_analytics_gold.sql	Gold analytics schema
README.md	New endpoints and datasets documented

Validation

• All 877 tests pass
• cargo fmt --all --check clean
• cargo clippy --workspace --all-targets -- -D warnings clean
• cargo build --release --workspace succeeds
• HlPnlSummary correctly computes net_pnl = closed_pnl + funding - fees
• HlTradeHistory groups fills into open→close sequences with weighted avg entry price
• TraderAnalytics and MarketAnalytics produce dashboard-ready aggregations
• CSV export tests validate well-formed header+data output

Test plan

• Verify all 877 tests pass (cargo test --workspace)
• Confirm fmt and clippy are clean
• Review materialization logic in hl_analytics.rs
• Review migration for correctness and index coverage
• Verify /v1/analytics/hl/trader and /v1/analytics/hl/market route correctly behind auth
• Confirm dataset registry counts (11 all, 10 queryable, 10 exportable)
• Confirm backward compatibility with P5-W1 wallet/tax/forensics endpoints

🤖 Generated with Claude Code

[user1303836]

Remote Review — P5-W2: Hyperliquid Analytics Pack

Reviewed the full diff against the eight review-focus items. Summary below.

PnL Computation ✅

net_pnl = total_closed_pnl + total_funding - total_fees is correctly implemented in compute_pnl_summary() (line 183 of hl_analytics.rs) and validated by pnl_summary_aggregates_fills_and_funding (50 + 7.5 − 3 = 54.5). Sign conventions are consistent with HL Silver data: closed_pnl is signed, funding is signed, fees are positive and subtracted.

Trade Grouping ✅

build_trade_history() groups fills by coin, sorts by fill_time, and tracks Open/Close sequences with weighted average entry price. Handles partial fills (multi-Open → single Close), standalone Close fills, and a clean fallback for fills without direction info. Open fills remaining at end of stream are silently dropped (correct — they're open positions, not completed trades).

Gold Layer Isolation ✅

All new code is purely additive:

• hl_analytics.rs is a standalone module
• New types in materializer.rs — no changes to existing types
• New repo methods in v2_repo.rs — additive query/export only
• New routes in api/src/main.rs — additive
• New migration creates new tables only
• No modifications to Silver ingestion, normalization, or shared infrastructure

Auth and Scoping ✅

Both analytics routes are inside the auth middleware layer. Tests test_hl_trader_analytics_requires_auth and test_hl_market_analytics_requires_auth confirm. Endpoints accept target_id, network, time_start, time_end filters matching the dataset-centric pattern.

No Wallet-Only Assumptions ✅

HlAnalyticsParams uses target_id as the primary scoping mechanism, consistent with the dataset-centric approach. wallet_address is a data field, not a scoping assumption. Analytics work for any Hyperliquid user target.

Migration Forward-Compatibility ✅

Both tables use CREATE TABLE IF NOT EXISTS, UUID PKs with gen_random_uuid(), REFERENCES dataset_versions(id), and appropriate indexes. Index coverage includes wallet+coin composite, network, and time columns (both ASC and DESC where appropriate).

CSV Export ✅

Column order matches struct field order. Both converters follow the existing pattern (manual format! + csv_escape for text, RFC3339 timestamps). Tests validate header+data output.

Backward Compatibility ✅

Three dedicated compat tests confirm wallet, P5-W1, and dataset endpoints remain routed. Queryable datasets: 8 → 10, Exportable datasets: 8 → 10. DatasetName enum: 9 → 11. All counts verified in tests.

Non-blocking Notes

1. CI pending at review time: Build (release) and Tests are still pending. Clippy and Formatting pass. These must complete green before merge.
2. Trader analytics multi-wallet edge: hl_trader_analytics_handler extracts wallet_address from the first returned record. Without a target_id filter, this could aggregate data across multiple wallets but label the result with only the first wallet's address. Not a bug if target_id is always passed in practice, but worth considering a validation or clear doc note.
3. Write path consistency: No insert/upsert methods for the new Gold tables — but this matches the P5-W1 pattern exactly (wallet_ledger and balance_history also only have query/export in v2_repo). The materialization trigger is a separate concern.

Verdict

Remote review pass is clear. No blocking issues found. The PR is well-structured, tests are thorough, the PnL formula is correct, and the implementation is purely additive with no Silver/shared pollution. Ready to merge once CI completes green.