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

Referrals page: design review — leaderboards, wallet codes, CHARM earnings + CL8Y/USDM/ETH #94

New issue
Closed
opened 2026-04-30 03:24:54 +00:00 by PlasticDigits · 10 comments
PlasticDigits commented 2026-04-30 03:24:54 +00:00 (Migrated from gitlab.com)

Summary

Request a product + UX design pass for /referrals beyond the current register / share-link surface (docs/product/referrals.md, verification GitLab #64, launch F-11 GitLab #91).

Goals

  1. Referral leaderboards

    • Define what is ranked (e.g. referral CHARM accrued, referee count, gross volume attributed to a code — align with onchain truth and indexer capabilities).
    • Full visual design: layout, time ranges, empty states, loading, mobile.

  2. Connected wallet(s) — referral codes

    • Clear UX when one or more wallets are connected (if the app supports multi-account): show each connected address\u2019s registered code (from chain / ReferralRegistry), or explicit \u201cnot registered\u201d state + CTA.
    • Tie to per-wallet cache docs: yieldomega.myrefcode.v1.<wallet> vs authoritative reads.

  3. CHARM the connected user has earned (referral program)

    • Surface the user\u2019s referral-related CHARM weight (and/or total sale CHARM where product-defined) as documented in Reward math (refEach, charmWeight effects).
    • Show the notional value of that CHARM in CL8Y, USDM, and ETH (pricing source + disclaimers: spot/oracle vs ICharmPrice / sale context — spell out in design).

Deliverables

  • Wireframes or high-fidelity mockups for desktop + mobile.
  • Copy deck for headers, tooltips, and empty/error states.
  • Notes on data sources (indexer queries vs direct RPC) and what must stay authoritative onchain per repo guardrails.

Acceptance (for implementation follow-up)

  • Leaderboard spec matches measurable onchain/indexer fields (no fake metrics).
  • Connected-wallet section lists codes per address with correct registered/unregistered flows.
  • Earnings block shows CHARM quantity and equivalent CL8Y / USDM / ETH with clear methodology.
  • Coordinated with E2E / visual invariants (docs/testing/invariants-and-business-logic.md — referrals) once UI ships.

Labels

Please add appropriate labels (e.g. frontend, design, product, TimeCurve) if they exist in the project.

/cc @PlasticDigits/yieldomega

## Summary Request a **product + UX design pass** for [`/referrals`](frontend/src/pages/ReferralsPage.tsx) beyond the current register / share-link surface ([docs/product/referrals.md](docs/product/referrals.md), verification [GitLab #64](https://gitlab.com/PlasticDigits/yieldomega/-/issues/64), launch F-11 [GitLab #91](https://gitlab.com/PlasticDigits/yieldomega/-/issues/91)). ## Goals 1. **Referral leaderboards** - Define what is ranked (e.g. referral CHARM accrued, referee count, gross volume attributed to a code — align with **onchain truth** and indexer capabilities). - Full visual design: layout, time ranges, empty states, loading, mobile. 2. **Connected wallet(s) — referral codes** - Clear UX when **one or more** wallets are connected (if the app supports multi-account): show **each connected address\u2019s** registered code (from chain / `ReferralRegistry`), or explicit \u201cnot registered\u201d state + CTA. - Tie to per-wallet cache docs: [`yieldomega.myrefcode.v1.<wallet>`](docs/product/referrals.md#referral-browser-storage-keys) vs authoritative reads. 3. **CHARM the connected user has earned (referral program)** - Surface the user\u2019s **referral-related CHARM weight** (and/or total sale CHARM where product-defined) as documented in [Reward math](docs/product/referrals.md#reward-math-timecurve-canonical) (`refEach`, `charmWeight` effects). - Show the **notional value** of that CHARM in **CL8Y**, **USDM**, and **ETH** (pricing source + disclaimers: spot/oracle vs `ICharmPrice` / sale context — spell out in design). ## Deliverables - Wireframes or high-fidelity mockups for desktop + mobile. - Copy deck for headers, tooltips, and empty/error states. - Notes on **data sources** (indexer queries vs direct RPC) and what must stay **authoritative onchain** per repo guardrails. ## Acceptance (for implementation follow-up) - [ ] Leaderboard spec matches measurable onchain/indexer fields (no fake metrics). - [ ] Connected-wallet section lists codes per address with correct registered/unregistered flows. - [ ] Earnings block shows CHARM quantity and equivalent CL8Y / USDM / ETH with clear methodology. - [ ] Coordinated with E2E / visual invariants ([`docs/testing/invariants-and-business-logic.md` — referrals](docs/testing/invariants-and-business-logic.md#referrals-page-visual-issue-64)) once UI ships. ## Labels Please add appropriate labels (e.g. `frontend`, `design`, `product`, `TimeCurve`) if they exist in the project. /cc @PlasticDigits/yieldomega
PlasticDigits commented 2026-04-30 04:01:47 +00:00 (Migrated from gitlab.com)

mentioned in commit 2f10a49e4c

mentioned in commit 2f10a49e4cbab17ddea903b5e73c6341168d63cb
PlasticDigits commented 2026-04-30 04:05:03 +00:00 (Migrated from gitlab.com)

Implementation landed on main (GitLab #94)

Summary: Referrals page now ships indexer-backed referrer leaderboard, per-wallet indexed CHARM summary (referrer vs referee splits from ReferralApplied), connected-wallet registration panel, and illustrative CL8Y / USDM / ETH notionals using currentPricePerCharmWad + the same static fallback multipliers as other pay-mode labels. Bot swarm registers a shared code from Anvil HD index 27 (default swarmyo) and sets YIELDOMEGA_REFERRAL_CODE so buys hit buy(charmWad, codeHash, false) when YIELDOMEGA_SWARM_REFERRALS is not 0.

Docs / cross-links: docs/product/referrals.md (dashboard §), docs/testing/invariants-and-business-logic.md (#94 anchor), docs/indexer/design.md, skills/README.md, skills/verify-yo-referrals-surface/SKILL.md, .cursor/skills/yieldomega-guardrails/SKILL.md item 15.

@brouie — please verify on a stack with indexer + referral buys.

Checklist for verification

  • GET /v1/referrals/referrer-leaderboard?limit=20 returns ranked rows; sums match Postgres SUM(referrer_amount) per referrer.
  • GET /v1/referrals/wallet-charm-summary?wallet=0x… returns string wei totals; referrer vs referee counts match row filters.
  • /referrals shows hero + cutouts + Connected wallet / Referral program CHARM / Referrer leaderboard sections; leaderboard empty state when indexer off is readable.
  • Connect wallet: earnings panel loads when VITE_INDEXER_URL points at a live indexer; CL8Y line appears when currentPricePerCharmWad reads succeed.
  • bash scripts/start-local-anvil-stack.sh with SKIP_ANVIL_RICH_STATE=1 (swarm on): swarm logs show referral registration; indexer eventually lists ReferralApplied rows; leaderboard populates.
  • YIELDOMEGA_SWARM_REFERRALS=0 skips registrar funding + YIELDOMEGA_REFERRAL_CODE injection (bots buy without code).

Issue left open per request.

## Implementation landed on `main` (GitLab #94) **Summary:** Referrals page now ships **indexer-backed referrer leaderboard**, **per-wallet indexed CHARM summary** (referrer vs referee splits from `ReferralApplied`), **connected-wallet registration panel**, and **illustrative CL8Y / USDM / ETH notionals** using `currentPricePerCharmWad` + the same static fallback multipliers as other pay-mode labels. **Bot swarm** registers a shared code from Anvil HD index **27** (default `swarmyo`) and sets `YIELDOMEGA_REFERRAL_CODE` so buys hit `buy(charmWad, codeHash, false)` when `YIELDOMEGA_SWARM_REFERRALS` is not `0`. **Docs / cross-links:** `docs/product/referrals.md` (dashboard §), `docs/testing/invariants-and-business-logic.md` (#94 anchor), `docs/indexer/design.md`, `skills/README.md`, `skills/verify-yo-referrals-surface/SKILL.md`, `.cursor/skills/yieldomega-guardrails/SKILL.md` item 15. @brouie — please verify on a stack with indexer + referral buys. ### Checklist for verification - [ ] `GET /v1/referrals/referrer-leaderboard?limit=20` returns ranked rows; sums match Postgres `SUM(referrer_amount)` per referrer. - [ ] `GET /v1/referrals/wallet-charm-summary?wallet=0x…` returns string wei totals; referrer vs referee counts match row filters. - [ ] `/referrals` shows hero + cutouts + **Connected wallet** / **Referral program CHARM** / **Referrer leaderboard** sections; leaderboard empty state when indexer off is readable. - [ ] Connect wallet: earnings panel loads when `VITE_INDEXER_URL` points at a live indexer; CL8Y line appears when `currentPricePerCharmWad` reads succeed. - [ ] `bash scripts/start-local-anvil-stack.sh` with `SKIP_ANVIL_RICH_STATE=1` (swarm on): swarm logs show referral registration; indexer eventually lists `ReferralApplied` rows; leaderboard populates. - [ ] `YIELDOMEGA_SWARM_REFERRALS=0` skips registrar funding + `YIELDOMEGA_REFERRAL_CODE` injection (bots buy without code). Issue left **open** per request.
PlasticDigits commented 2026-04-30 04:21:49 +00:00 (Migrated from gitlab.com)

mentioned in commit 7b7210f214

mentioned in commit 7b7210f214ac856cdf8ecb716ba53096d57e1908
PlasticDigits commented 2026-04-30 05:25:10 +00:00 (Migrated from gitlab.com)

mentioned in issue #100

mentioned in issue #100
Brouie commented 2026-04-30 09:05:40 +00:00 (Migrated from gitlab.com)

Verified #94 referrals leaderboard + earnings on dd1c59a HEAD today. Items 1-5 PASS, Item 6 deferred. Closing as primary surface verified.

Stack state

Boot via: SKIP_ANVIL_RICH_STATE=1 START_BOT_SWARM=1 bash scripts/start-local-anvil-stack.sh (default referrals on, indexer schema v1.9.0 with new /v1/referrals/* Rust routes).

Item 1 — /v1/referrals/referrer-leaderboard ranked rows: PASS

Endpoint returns ranked rows with string wei totals.
Top referrer: 0x87bdce72c06c21cd96219bd8521bdf1f42c78b5e (HD-27 / swarmyo registrar)

  • referred_buy_count: 21 → 40 over session
  • total_referrer_charm_wad: 4611011563700613660 (≈4.61 CHARM)
    Cross-check: address matches the swarm referrals: registered 'swarmyo' for 0x87BdCE72... log line, and referred_buy_count advances with each indexer cycle.

Item 2 — /v1/referrals/wallet-charm-summary?wallet=0x...: PASS

Endpoint returns string wei totals matching leaderboard:
{ wallet, referrer_charm_wad: "4611011563700613660", referee_charm_wad: "0", referred_buy_count: "21", referee_buy_count: "0" }
Referrer counts match leaderboard row exactly.

Item 3 — /referrals page sections render: PASS

Hero + cutouts + Connected wallet + Referral program CHARM (indexed) + Referrer leaderboard sections all render. Three-step "Claim a code / Share a live route / Track CHARM" walk-through shown above the dashboard.

Item 4 — Connected wallet earnings panel: PASS

With deployer 0xf39Fd6...2266 connected on Chain 31337, the earnings panel loads cleanly (zero state — wallet hasn't been a referrer/referee). On-chain reward parameters render below ("Per-side referral bonus: 5.00% of charmWad to buyer + same to referrer"). Burn-per-registration figure renders from on-chain read.

Item 5 — Swarm registers + indexer ingests ReferralApplied: PASS

Stack log evidence:
registerCode('swarmyo') tx=8878ad5ea027467390c6645d9dbd2dfed9fff47e1a4a6fa3d90b830cf20596b5 status=1
swarm referrals: registered 'swarmyo' for 0x87BdCE72c06C21cd96219BD8521bDF1F42C78b5e
Indexer subsequently lists 21 → 40 ReferralApplied rows on the leaderboard. Empty-state copy verified by SIGSTOP indexer mid-session — page shows "Loading referral totals…" and "Loading leaderboard…" gracefully without errors, "Indexer: connecting…" pill appears, on-chain sections (Active address, Reward parameters, Canonical fee sinks) stay live (correct — not indexer-dependent). Recovery on SIGCONT clean.

Item 6 — YIELDOMEGA_SWARM_REFERRALS=0 skip path: DEFERRED

Tried to exercise this in-session but hit a swarm runner config issue when invoking swarm_runner.run_swarm() directly outside the start-local-anvil-stack.sh wrapper. The standalone path needs additional env scaffolding the wrapper script provides. Will follow up by setting the env on the wrapper script itself in a separate boot.

Closure

Indexer-backed leaderboard + per-wallet summary + frontend page + connected-wallet panel + swarm registration round-trip all verified end-to-end on a 40+ ReferralApplied row dataset. Closing.

cc @PlasticDigits

Verified #94 referrals leaderboard + earnings on `dd1c59a` HEAD today. Items 1-5 PASS, Item 6 deferred. Closing as primary surface verified. ## Stack state Boot via: `SKIP_ANVIL_RICH_STATE=1 START_BOT_SWARM=1 bash scripts/start-local-anvil-stack.sh` (default referrals on, indexer schema v1.9.0 with new `/v1/referrals/*` Rust routes). ## Item 1 — `/v1/referrals/referrer-leaderboard` ranked rows: PASS Endpoint returns ranked rows with string wei totals. Top referrer: `0x87bdce72c06c21cd96219bd8521bdf1f42c78b5e` (HD-27 / `swarmyo` registrar) - `referred_buy_count`: 21 → 40 over session - `total_referrer_charm_wad`: 4611011563700613660 (≈4.61 CHARM) Cross-check: address matches the `swarm referrals: registered 'swarmyo' for 0x87BdCE72...` log line, and `referred_buy_count` advances with each indexer cycle. ## Item 2 — `/v1/referrals/wallet-charm-summary?wallet=0x...`: PASS Endpoint returns string wei totals matching leaderboard: `{ wallet, referrer_charm_wad: "4611011563700613660", referee_charm_wad: "0", referred_buy_count: "21", referee_buy_count: "0" }` Referrer counts match leaderboard row exactly. ## Item 3 — `/referrals` page sections render: PASS Hero + cutouts + Connected wallet + Referral program CHARM (indexed) + Referrer leaderboard sections all render. Three-step "Claim a code / Share a live route / Track CHARM" walk-through shown above the dashboard. ## Item 4 — Connected wallet earnings panel: PASS With deployer 0xf39Fd6...2266 connected on Chain 31337, the earnings panel loads cleanly (zero state — wallet hasn't been a referrer/referee). On-chain reward parameters render below ("Per-side referral bonus: 5.00% of charmWad to buyer + same to referrer"). Burn-per-registration figure renders from on-chain read. ## Item 5 — Swarm registers + indexer ingests ReferralApplied: PASS Stack log evidence: `registerCode('swarmyo') tx=8878ad5ea027467390c6645d9dbd2dfed9fff47e1a4a6fa3d90b830cf20596b5 status=1` `swarm referrals: registered 'swarmyo' for 0x87BdCE72c06C21cd96219BD8521bDF1F42C78b5e` Indexer subsequently lists 21 → 40 ReferralApplied rows on the leaderboard. Empty-state copy verified by SIGSTOP indexer mid-session — page shows "Loading referral totals…" and "Loading leaderboard…" gracefully without errors, "Indexer: connecting…" pill appears, on-chain sections (Active address, Reward parameters, Canonical fee sinks) stay live (correct — not indexer-dependent). Recovery on SIGCONT clean. ## Item 6 — `YIELDOMEGA_SWARM_REFERRALS=0` skip path: DEFERRED Tried to exercise this in-session but hit a swarm runner config issue when invoking `swarm_runner.run_swarm()` directly outside the start-local-anvil-stack.sh wrapper. The standalone path needs additional env scaffolding the wrapper script provides. Will follow up by setting the env on the wrapper script itself in a separate boot. ## Closure Indexer-backed leaderboard + per-wallet summary + frontend page + connected-wallet panel + swarm registration round-trip all verified end-to-end on a 40+ ReferralApplied row dataset. Closing. cc @PlasticDigits
Brouie (Migrated from gitlab.com) closed this issue 2026-04-30 09:05:43 +00:00
PlasticDigits commented 2026-04-30 09:24:44 +00:00 (Migrated from gitlab.com)

mentioned in issue #102

mentioned in issue #102
PlasticDigits commented 2026-04-30 09:24:44 +00:00 (Migrated from gitlab.com)

marked this issue as related to #102

marked this issue as related to #102
PlasticDigits commented 2026-05-06 12:42:34 +00:00 (Migrated from gitlab.com)

mentioned in issue #165

mentioned in issue #165
PlasticDigits commented 2026-05-13 15:58:57 +00:00 (Migrated from gitlab.com)

mentioned in issue #204

mentioned in issue #204
PlasticDigits commented 2026-05-20 04:42:29 +00:00 (Migrated from gitlab.com)

mentioned in issue #225

mentioned in issue #225
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#94
No description provided.