code/yieldomega
Watch
4
0
Fork
You've already forked yieldomega
 0
Code Issues 1 Pull requests 1 Projects Releases Packages Wiki Activity

Referrals: guide leaderboard global totals + pagination #225

New issue
Closed
opened 2026-05-20 04:42:28 +00:00 by PlasticDigits · 6 comments
PlasticDigits commented 2026-05-20 04:42:28 +00:00 (Migrated from gitlab.com)

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.
  • 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

  • Registry union + per-row codes_registered_count: #204
  • Referrer leaderboard + earnings surface: #94
  • Dense rank semantics: #177

/cc @PlasticDigits/yieldomega

## 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`](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`](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](https://gitlab.com/PlasticDigits/yieldomega/-/issues/177). - 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`](frontend/e2e/referrals-surface.spec.ts) as appropriate). 4. **Docs / QA:** Update [`docs/product/referrals.md`](docs/product/referrals.md) dashboard table and manual QA checklist if copy or invariants change. ## Related - Registry union + per-row `codes_registered_count`: [#204](https://gitlab.com/PlasticDigits/yieldomega/-/issues/204) - Referrer leaderboard + earnings surface: [#94](https://gitlab.com/PlasticDigits/yieldomega/-/issues/94) - Dense rank semantics: [#177](https://gitlab.com/PlasticDigits/yieldomega/-/issues/177) /cc @PlasticDigits/yieldomega
PlasticDigits commented 2026-05-20 04:49:51 +00:00 (Migrated from gitlab.com)

mentioned in commit 0632942790

mentioned in commit 0632942790c7ab5e02ba009ed1c245e935217bb4
PlasticDigits commented 2026-05-20 04:49:56 +00:00 (Migrated from gitlab.com)

Implementation summary (merged to main @ 0632942)

Guide leaderboard on /referrals now uses network-wide indexer aggregates for the summary strip and supports numbered pagination through all guides.

Changes

Indexer (SCHEMA_VERSION → 1.25.0)

  • GET /v1/referrals/referrer-leaderboard now returns on every page:
    • total — distinct referrer union count (registry ∪ ReferralApplied)
    • total_codes_registered — full-table count on idx_referral_code_registered
    • total_referred_buys — full-table count on idx_timecurve_referral_applied
    • total_referrer_charm_wad — SUM(referrer_amount) on idx_timecurve_referral_applied

Frontend

  • Summary labels updated to “(global)”; values come from API fields (not page-local reduce sums).
  • Numbered page controls (ReferralLeaderboardPagination) at the bottom of the card; 20 rows/page.
  • Global totals stay visible while paging; row rank remains indexer dense competitive rank (#177).
  • Helpers: referralLeaderboardPagination.ts, ReferralLeaderboardPagination.tsx.

Tests

  • postgres_gitlab225_referrer_leaderboard_global_totals_and_pagination
  • Vitest: referralLeaderboardPagination.test.ts
  • Playwright: referrals-surface.spec.ts (mocked indexer + global label assertion)

Docs / invariants

  • INV-INDEXER-225-REFERRAL-LB-GLOBAL, INV-FRONTEND-225-REFERRAL-LB
  • Updated: docs/product/referrals.md, docs/indexer/design.md, docs/testing/invariants-and-business-logic.md, docs/testing/manual-qa-checklists.md#manual-qa-issue-225, skills/README.md, .cursor/skills/yieldomega-guardrails/SKILL.md

Verification checklist

  • Indexer reports x-schema-version: 1.25.0 (or later) on referrer-leaderboard responses.
  • GET /v1/referrals/referrer-leaderboard?limit=20&offset=0 returns total_* fields matching full-table counts (not sums of current items).
  • /referrals summary shows “Codes registered (global)”, “Recorded referral buys (global)”, “Total guide CHARM (global)”.
  • With >20 referrers indexed, numbered pagination appears; page 2 uses offset=20 and rank values are still dense competitive ranks (not 21, 22, …).
  • Connected wallet “you” highlight works when your address is on the current page.
  • Summary totals do not change when switching pages (only the row list updates).
  • Automated: cargo test postgres_gitlab225 · npm test -- referralLeaderboardPagination in frontend/.

/cc @nullvector_ux — please verify on staging/local stack when convenient. Leaving this issue open until sign-off.

## Implementation summary (merged to `main` @ `0632942`) Guide leaderboard on `/referrals` now uses **network-wide indexer aggregates** for the summary strip and supports **numbered pagination** through all guides. ### Changes **Indexer (`SCHEMA_VERSION` → 1.25.0)** - `GET /v1/referrals/referrer-leaderboard` now returns on every page: - `total` — distinct referrer union count (registry ∪ ReferralApplied) - `total_codes_registered` — full-table count on `idx_referral_code_registered` - `total_referred_buys` — full-table count on `idx_timecurve_referral_applied` - `total_referrer_charm_wad` — `SUM(referrer_amount)` on `idx_timecurve_referral_applied` **Frontend** - Summary labels updated to **“(global)”**; values come from API fields (not page-local `reduce` sums). - Numbered page controls (`ReferralLeaderboardPagination`) at the bottom of the card; 20 rows/page. - Global totals stay visible while paging; row `rank` remains indexer dense competitive rank ([#177](https://gitlab.com/PlasticDigits/yieldomega/-/issues/177)). - Helpers: `referralLeaderboardPagination.ts`, `ReferralLeaderboardPagination.tsx`. **Tests** - `postgres_gitlab225_referrer_leaderboard_global_totals_and_pagination` - Vitest: `referralLeaderboardPagination.test.ts` - Playwright: `referrals-surface.spec.ts` (mocked indexer + global label assertion) **Docs / invariants** - `INV-INDEXER-225-REFERRAL-LB-GLOBAL`, `INV-FRONTEND-225-REFERRAL-LB` - Updated: `docs/product/referrals.md`, `docs/indexer/design.md`, `docs/testing/invariants-and-business-logic.md`, `docs/testing/manual-qa-checklists.md#manual-qa-issue-225`, `skills/README.md`, `.cursor/skills/yieldomega-guardrails/SKILL.md` --- ### Verification checklist - [ ] Indexer reports **`x-schema-version: 1.25.0`** (or later) on referrer-leaderboard responses. - [ ] `GET /v1/referrals/referrer-leaderboard?limit=20&offset=0` returns **`total_*`** fields matching full-table counts (not sums of current `items`). - [ ] `/referrals` summary shows **“Codes registered (global)”**, **“Recorded referral buys (global)”**, **“Total guide CHARM (global)”**. - [ ] With **>20** referrers indexed, numbered pagination appears; page 2 uses `offset=20` and **`rank`** values are still dense competitive ranks (not `21, 22, …`). - [ ] Connected wallet **“you”** highlight works when your address is on the current page. - [ ] Summary totals do **not** change when switching pages (only the row list updates). - [ ] Automated: `cargo test postgres_gitlab225` · `npm test -- referralLeaderboardPagination` in `frontend/`. /cc @nullvector_ux — please verify on staging/local stack when convenient. Leaving this issue **open** until sign-off.
nullvector_ux commented 2026-05-20 07:21:45 +00:00 (Migrated from gitlab.com)

Verification checklist @PlasticDigits

  • (on local 1.25.0 and in online 1.24.0) Indexer reports x-schema-version: 1.25.0 (or later) on referrer-leaderboard responses.
  • GET /v1/referrals/referrer-leaderboard?limit=20&offset=0 returns total_* fields matching full-table counts (not sums of current items).
  • /referrals summary shows “Codes registered (global)”, “Recorded referral buys (global)”, “Total guide CHARM (global)”.
  • With >20 referrers indexed, numbered pagination appears; page 2 uses offset=20 and rank values are still dense competitive ranks (not 21, 22, …).
  • (in referrals it is only highlighted gold but there is no "YOU" as labeled same for prize podiume) Connected wallet “you” highlight works when your address is on the current page.
  • Summary totals do not change when switching pages (only the row list updates).
  • Automated: cargo test postgres_gitlab225 · npm test -- referralLeaderboardPagination in frontend/.
### Verification checklist @PlasticDigits * [x] (on local 1.25.0 and in online 1.24.0) Indexer reports **`x-schema-version: 1.25.0`** (or later) on referrer-leaderboard responses. * [x] `GET /v1/referrals/referrer-leaderboard?limit=20&offset=0` returns **`total_*`** fields matching full-table counts (not sums of current `items`). * [x] `/referrals` summary shows **“Codes registered (global)”**, **“Recorded referral buys (global)”**, **“Total guide CHARM (global)”**. * [ ] With **\>20** referrers indexed, numbered pagination appears; page 2 uses `offset=20` and **`rank`** values are still dense competitive ranks (not `21, 22, …`). * [x] (in referrals it is only highlighted gold but there is no "YOU" as labeled same for prize podiume) Connected wallet **“you”** highlight works when your address is on the current page. * [x] Summary totals do **not** change when switching pages (only the row list updates). * [x] Automated: `cargo test postgres_gitlab225` · `npm test -- referralLeaderboardPagination` in `frontend/`.
PlasticDigits commented 2026-05-21 05:42:47 +00:00 (Migrated from gitlab.com)

mentioned in issue #231

mentioned in issue #231
PlasticDigits (Migrated from gitlab.com) closed this issue 2026-05-21 12:01:19 +00:00
PlasticDigits commented 2026-05-21 12:01:20 +00:00 (Migrated from gitlab.com)

Ransk due to 0 charm tie, closing

Ransk due to 0 charm tie, closing
PlasticDigits commented 2026-05-21 13:21:02 +00:00 (Migrated from gitlab.com)

mentioned in issue #234

mentioned in issue #234
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
cac-design-issue-544
renovate/configure
No results found.
Labels
Clear labels   
agent:fix_bugfix

   
agent:fix_conflicts

   
agent:fix_security

   
agent:gap_analysis

   
agent:implement

   
agent:open_issues

   
agents

   
agent:security_audit

   
agent:verify
  
area
timecurve

  
arena

   
arena-v2

   
audit

   
block:feature_review

   
block:security

   
bug

   
contracts

   
design

   
devops

   
docs
Documentation

  
documentation

   
enhancement

   
epic
Epic / umbrella issue

  
feature

   
frontend

   
indexer

   
low priority
Low priority, investigate other issues first

  
megaeth

   
operations

   
ops
Deploy and operations

  
performance

   
QA

   
qa checklist

   
referrals

   
removal
Legacy removal

  
security

   
smart-contracts

   
tech-debt

   
testing

   
time-arena
TimeArena v2 revamp

  
timecurve

   
visual-qa
No labels
agent:fix_bugfix
agent:fix_conflicts
agent:fix_security
agent:gap_analysis
agent:implement
agent:open_issues
agents
agent:security_audit
agent:verify
area
timecurve
arena
arena-v2
audit
block:feature_review
block:security
bug
contracts
design
devops
docs
documentation
enhancement
epic
feature
frontend
indexer
low priority
megaeth
operations
ops
performance
QA
qa checklist
referrals
removal
security
smart-contracts
tech-debt
testing
time-arena
timecurve
visual-qa
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
code/yieldomega#225
No description provided.