How Topaz Stats are computed

A snapshot job runs every 15 minutes on Vercel Cron (*/15 * * * *) and writes one row per table per run to a Postgres database. The job is idempotent for bribe events (deduped on (tx_hash, log_index)) and marks each run success, partial, or failed. The read API and dashboard only surface status='success' rows.

Dashboard pages read from the snapshot tables only — no live RPC/subgraph calls happen at page-render time. Lag of 1–2 blocks vs. chain head is normal.

Epochs are 7 days and align to Thursday 00:00 UTC.

• Voting opens 1 hour after epoch start
• Voting closes 1 hour before the next epoch starts
• The hour immediately after a new epoch is the distribute window (keepers only)

On every snapshot we cross-check the local epoch math against on-chain Voter.epochStart(now) and log a divergence if they disagree.

KPI causality is not guaranteed. A pool's TVL/volume/fee delta over an epoch has many causes — a foundation vote or bribe is one input among token prices, external incentives, market beta, and depositor behavior. Read classifications (scale, repeat, reduce, etc.) as effectiveness indicators, not causal proofs.

Insufficient data is the default. For the first 1–2 epochs of any pool the baseline window is too sparse to classify; you'll see insufficient_data until enough history accrues.

Bribe scan is incremental. The snapshot job indexes BribeVotingReward.NotifyReward logs in 50k-block chunks (up to 20 chunks per cron run) starting from the Voter contract's deploy block. Existing rows are re-priced in place on rescan, so a historical pricing improvement propagates without manual backfill.