Referrals: guide leaderboard global totals + pagination

Summary

On /referrals, the Guide leaderboard card has two UX gaps:

  1. Summary stat mislabeled / wrong scope — the header shows "Codes registered (this page)" and the number is the sum of codes_registered_count for the current 20-row page only (computed client-side in ReferralLeaderboardSection). It should show "Codes registered (global)" with the network-wide total from the indexer (e.g. total rows in idx_referral_code_registered, or an equivalent authoritative aggregate), not a page-local sum.

  2. No pagination — the card loads a single fixed page (fetchReferralReferrerLeaderboard(20, 0)) and never exposes additional referrers. Users should be able to page through all guides via clickable page numbers at the bottom of the card.

Current behavior

  • Frontend: frontend/src/pages/referrals/ReferralLeaderboardSection.tsx
    • Fetches only limit=20&offset=0.
    • Summary totalCodesRegistered (and similarly totalBuys, totalCharmWad) are reduced from page items only.
    • Label reads "Codes registered (this page)" (line ~111).
  • Indexer: GET /v1/referrals/referrer-leaderboard already supports limit / offset and returns next_offset (indexer/src/api.rs); no total / global aggregate fields today (unlike GET /v1/timecurve/buys which exposes total).

Expected behavior

Global summary totals

  • Rename copy to "Codes registered (global)" (or product-approved equivalent).
  • Display the global count of onchain code registrations indexed on ReferralRegistry, independent of the visible page.
  • Consider whether "Recorded referral buys" and "Total guide CHARM" in the same summary strip should also be global (likely yes for consistency) rather than page-scoped sums.

Pagination

  • Add page controls at the bottom of the Guide leaderboard card (numbered pages preferred per product ask; prev/next acceptable if numbered pages are impractical).
  • Changing page updates offset on GET /v1/referrals/referrer-leaderboard and re-renders rows; rank values must remain the indexer’s dense competitive rank (not offset + row_index + 1) — see INV-INDEXER-170-REFERRAL-LB-TIE / #177 (closed).
  • Preserve "you" row highlighting when the connected wallet appears on the current page.
  • Loading / error states should not reset global summary totals awkwardly between page transitions.

Work to scope

  1. Indexer / API (if needed): Extend GET /v1/referrals/referrer-leaderboard (or add a small companion route) to return global aggregates for the summary strip — e.g. total_codes_registered, total_referred_buys, total_referrer_charm_wad, plus total referrer count for page math. Bump SCHEMA_VERSION per repo conventions if response shape changes.
  2. Frontend: Wire pagination state (limit, offset, derived page index from next_offset / total); update indexerApi types; fix summary labels and data source; add pagination UI + styles consistent with referrals / TimeCurve surfaces.
  3. Tests: Indexer integration for new aggregate fields; Vitest for API path/types; Playwright or component coverage on /referrals pagination + global summary label (extend frontend/e2e/referrals-surface.spec.ts as appropriate).
  4. Docs / QA: Update docs/product/referrals.md dashboard table and manual QA checklist if copy or invariants change.

Related

/cc @PlasticDigits/yieldomega