Methodology

How Topaz Stats are computed

Source-of-truth notes for every number you see on this dashboard. Methodology version 0.1.0.

Data sources

Subgraph data — pool stats (TVL, volume, fees, custom/dynamic fee flags) come from the official Topaz Goldsky subgraphs:

  • v2 (Solidly): topaz-v2 v0.0.3
  • v3 (Slipstream): topaz-v3 v0.0.1

On-chain data — gauges, vote weights, foundation veNFT ownership, and bribe deposit events (BribeVotingReward.NotifyReward) are read directly from BSC RPC with viem multicall and incremental getLogs scans.

Pricing — TOPAZ → USD comes from DexScreener primary (highest-liquidity BSC pair), with the v3 subgraph (TOPAZ.derivedETH × Bundle.ethPriceUSD) as fallback.

Snapshot cadence

A snapshot job runs hourly on Vercel Cron (0 * * * *) 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.

Epoch timing

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.

Formulas

Fee APR

(fees_24h_usd × 365) / tvl_usd × 100

Vote share

foundation_vote_weight / total_gauge_vote_weight × 100

KPI ROI estimate

fees_delta_usd / bribe_cost_usd

Limitations

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 50k blocks at a time, starting from BSC block 50M. Backfill to chain head takes ~2 days from cold start.

Competitor comparison deferred. PancakeSwap V3 and Uniswap V3 (BNB) comparisons require paid TheGraph access and land in Phase 7.

Foundation wallet: 0xF407739E81574A3C9A3195bCb85eE694C94e540c · veNFT IDs 1, 2, 3, 4, 5, 6, 7, 8

Public API: /api/stats/config returns this metadata machine-readable.