port real hl harness to public tree + honest hip3 discovery wording

benchmarks/hyperliquid-hip3-deployers.yml

@@ -54,7 +54,7 @@ abstract: |
 
 methodology:
   - "Data source. A local hl node operated on OCB infrastructure tails the Hyperliquid mainnet and writes every block of fills to node_fills_by_block hourly YYYYMMDD HH on local disk. Each line is one JSON block, the events array carries one entry per fill, and every fill on a HIP-3 market includes the dex namespaced coin (xyz:AAPL) plus the deployerFee in USDC."
-  - "Attribution. A fill belongs to a HIP-3 dex when its coin carries a namespace prefix (xyz:AAPL belongs to xyz). Namespaces are unique on chain by construction, so no hand curated registry is needed; a new deployer appears on the leaderboard with its first observed fill. Core Hyperliquid markets carry no namespace and no deployer fee, they are excluded."
+  - "Attribution. A fill belongs to a HIP-3 dex when its coin carries a namespace prefix (xyz:AAPL belongs to xyz). Namespaces are unique on chain by construction, so no hand curated registry is needed; the harness starts tracking a new deployer with its first observed fill, and the namespace is added to this page on the next spec review. Core Hyperliquid markets carry no namespace and no deployer fee, they are excluded."
   - "Cadence. The Go harness re reads the current and previous hourly files every 30 seconds, parses appended lines, and updates per dex hourly buckets keyed by the UTC hour floor of the fill timestamp. Prometheus scrapes the metrics every 30 seconds via a Caddy reverse proxy with basic auth. End to end staleness from fill landing on chain to bench page render is typically under one minute."
   - "Headline calculation. For each dex over the last 24 rolling hours we sum the deployerFee USD values of every fill on its namespaced markets. The 7 day and 30 day figures sum the same field over the last 168 and 720 hourly buckets, so the metric is consistent across the three ranges."
   - "Volume companion. hl_hip3_deployer_volume_usd_24h, _7d and _30d are computed the same way on the px times sz product of every fill. They feed the Volume column and tab."
@@ -83,7 +83,7 @@ faq:
   - q: "Where does the data come from?"
     a: "A local hl node operated on OCB infrastructure tails the Hyperliquid mainnet. The node writes every block of fills to disk; a Go harness running on the same host reads these files continuously, attributes namespaced fills to their dex, and aggregates per hour. No third party API, no internal Mobula service."
   - q: "How are dexes identified?"
-    a: "By their on chain coin namespace. Every HIP-3 market trades under a prefix (xyz:AAPL, vntl:MAG7, km:US500) that is unique to its deployer. The set is discovered dynamically from the fill stream, so a brand new deployer appears on the leaderboard with its first fill. Namespaces not yet matched to a public brand are listed under the raw prefix."
+    a: "By their on chain coin namespace. Every HIP-3 market trades under a prefix (xyz:AAPL, vntl:MAG7, km:US500) that is unique to its deployer. The harness discovers the set dynamically from the fill stream and starts metering a brand new deployer with its first fill; the page lists each new namespace after a short spec review. Namespaces not yet matched to a public brand are listed under the raw prefix."
   - q: "Why is trade.xyz so far ahead?"
     a: "It operates the deepest tokenized equity and commodity catalog on Hyperliquid, more than 70 markets including the large cap US names, and captures the bulk of HIP-3 open interest. Deployer revenue is volume times fee policy, and xyz leads on both breadth and notional."
   - q: "What does the Effective fee bps column tell me?"

harnesses/hyperliquid-frontends/README.md

@@ -1,78 +1,31 @@
-# hyperliquid-frontends harness
+# hyperliquid-frontends-local
 
-OpenChainBench bench № 030 — quality benchmark of Hyperliquid frontends, ranked by **how much they extract from users**, not by raw volume share.
+Local harness that reads the hl-node L1 output directly from
+`/mnt/hyperliquid/data/node_fills_by_block/hourly/` instead of fetching the
+public daily CSV bucket. Produces the same per-builder metrics as the
+`hyperliquid-frontends` harness but at sub-minute freshness instead of 24-48h
+lag.
 
-## What it measures
+Deployed on the OVH SGP server where the hl-node runs. Exposes Prometheus
+metrics on `127.0.0.1:2113/metrics`, fronted by Caddy with basic auth on
+`:8088` for OCB Prom scraping.
 
-Three quality metrics per builder, refreshed hourly from the public daily fills dumps Hyperliquid publishes at `https://stats-data.hyperliquid.xyz/Mainnet/builder_fills/{address}/{YYYYMMDD}.csv.lz4`:
+Metrics emitted (all labeled by `slug`):
 
-| Metric | Definition |
-|---|---|
-| **Effective fee bps** | `sum(builder_fee) / sum(notional) × 10 000` — volume-weighted average over 24 h |
-| **$ per user** | `sum(builder_fee) / count(distinct user)` — raw efficiency per active trader |
-| **Fee discipline** | `stddev_over_time(effective_fee_bps[30d])` — computed in Prometheus, surfaces rotating-promo cycles |
+- `hl_frontend_volume_usd_24h_v2`
+- `hl_frontend_fees_usd_24h_v2`
+- `hl_frontend_users_24h_v2`
+- `hl_frontend_fills_total_24h_v2`
+- `hl_frontend_effective_fee_bps_v2`
+- `hl_frontend_local_last_tick_unix_v2` (heartbeat)
 
-Headline ranking = lowest effective fee = most aligned with traders.
-
-Why this framing: the Hyperliquid frontend wars already have a dozen volume-share dashboards (ASXN HyperScreener, Coinmarketman HyperTracker, Flowscan, Allium, Hyperdash, several Dune boards). What nobody publishes cleanly is the user-cost side. This bench is the user-cost side.
-
-## Builder registry
-
-`builders.json` is a hand-curated `[{slug, name, address, valid_from, notes}]` array. Addresses are cross-referenced against:
-- Flowscan `/builders` — live leaderboard
-- Hyperliquid governance forum disclosures
-- Each frontend's public announcement of their builder code
-
-**The committed file ships with placeholder `0x0000…` addresses.** They MUST be filled in before the harness can fetch anything useful. The harness will return `403` for every placeholder address (the Hyperliquid bucket returns 403 when the date file doesn't exist for that address).
-
-Workflow for adding / updating addresses:
-1. Pull the latest Flowscan builders list, cross-check with ASXN's published mapping
-2. Edit `builders.json`, bump `valid_from` to today
-3. PR with a Flowscan screenshot in the description so the registry change is auditable
-4. After merge, redeploy the harness on Railway
-
-## Prometheus metrics emitted
+Run flags:
 
 ```
-hl_frontend_effective_fee_bps{builder}                    gauge
-hl_frontend_fees_per_user_usd{builder}                    gauge
-hl_frontend_volume_usd_24h{builder}                       gauge
-hl_frontend_users_24h{builder}                            gauge
-hl_frontend_fills_total{builder}                          gauge
-hl_frontend_unattributed_share_pct                        gauge
-hl_frontend_registry_age_seconds                          gauge
-hl_frontend_csv_fetch_status_total{builder,code}          counter
+hl-frontends-local \
+  -data /mnt/hyperliquid/data/node_fills_by_block/hourly \
+  -builders builders.json \
+  -addr 127.0.0.1:2113 \
+  -window-hours 24 \
+  -tick 30s
 ```
-
-Bench page column mapping is documented in `benchmarks/hyperliquid-frontends.yml` — p50 / p90 / p99 are repurposed for effective fee / 30d stddev / $/user respectively since the unit is bps and there is no native percentile semantics.
-
-## Run locally
-
-```bash
-cd harnesses/hyperliquid-frontends
-go run ./cmd/script
-curl http://localhost:2112/metrics | grep hl_frontend_
-```
-
-## Deploy
-
-Standard OCB-miniapp shape — multi-stage Dockerfile, port 2112, scraped by the shared `openchainbench-monitoring` Prometheus via `hyperliquid-frontends.railway.internal:2112`.
-
-After deploy, add a scrape config entry:
-
-```yaml
-- job_name: 'hyperliquid-frontends'
-  static_configs:
-    - targets:
-        - 'hyperliquid-frontends.railway.internal:2112'
-      labels:
-        benchmark: hyperliquid-frontends
-  metrics_path: /metrics
-```
-
-## Known limits
-
-- **Daily granularity** — the CSV bucket only rolls at UTC midnight. Intra-day movement is invisible. A v1.1 upgrade would consume the WebSocket `userFills` stream filtered on the `b` field for realtime.
-- **Native HL UI excluded** — orders without a builder code are not attributable here. Covered by the separate `/benchmarks/aggregator-head-lag` bench.
-- **Wash trading** — fills are taken at face value. A frontend running wash flow shows up exactly as the chain records. Mitigation = the unique-user column flags anomalous low-user / high-volume signatures. A sybil-cluster heuristic ships in v1.1.
-- **Registry maintenance** — the builder address list is hand-curated. The `hl_frontend_unattributed_share_pct` metric makes the coverage gap visible; an alert fires when it crosses 2 %.