#576 - ux: Charts/Protocol 24h volume looks cumulative — disclose trailing window (not midnight reset) - code/cl8y-dex-terraclassic

PlasticDigits commented

2026-08-19 11:52:55 +00:00

(Migrated from gitlab.com)

Summary

Retail on Charts & Analytics (/charts at dex.cl8y.com) reads 24h Volume (USD) as a calendar-day counter that should hit $0 (e.g. at midnight). It does not. The indexer figure is a trailing 24-hour window (Utc::now() − 24h over swap_events). With ongoing mainnet activity the number is expected to stay above $0 and can trend up for days. The UI never says that.

This issue owns copy + progressive disclosure on Charts, Protocol, pair 24h stats, and related 24h volume labels so the existing rolling math is obvious. It does not change the window to UTC calendar days.

Related (do not treat as done here): #548 USD-only overview; #550 Protocol 24h/7d/30d; #565 pair Vol (USD); #243 / #333 rollups. Indexer rollups that fail to decay (token stats, idle traders, stale global_stats_24h if the aggregator dies) are a separate linked issue.

Current codebase

What `/charts` actually shows

ChartsPage.tsx loads GET /api/v1/overview and renders:

Box	Source	Label / tooltip today
24h Volume (USD)	`total_volume_24h_usd`	Label `24h Volume (USD)`; `title="24h volume in USD"`
24h Trades	`total_trades_24h`	Label only — no window hint
Pair Vol (USD)	`GET /api/v1/pairs/{addr}/stats` `volume_usd`	`title="24h volume in USD"`
Pair High/Low	`high_usd` / `low_usd`	Already says “last 24h” on High/Low titles

StatBox puts title on the card (<div title={title}>). Native hover only; no aria-describedby. Mobile (the screenshot surface) has no hover, so the tooltip never appears on phones.

Pair list SORT default is 24h volume (PAIR_SORT_OPTIONS). /pool column header is Vol sorted as volume_24h (PoolPairsTable.tsx) — no window text.

/protocol labels 24h volume, 7d volume, 30d volume with a lead that explains USD/oracle provenance, not trailing vs calendar. No title on those StatBoxes.

Indexer window (correct for this issue)

refresh_global_stats / get_global_stats_live:

Cutoff = Utc::now() - Duration::hours(24) (and 7d / 30d).
SUM(volume_usd) FILTER (WHERE block_timestamp >= cutoff).
Rollup table global_stats_24h, refresh ~5 min (volume_aggregator.rs), /overview cached 60s (overview.rs).
Pair stats get_24h_stats_for_pair uses the same now − 24h live filter.
Tests already assert old swaps are excluded (global_stats_rollup_excludes_swaps_older_than_24h). Idle DEX with zero 24h trades is allowed to show $0 (#548 C3).

There is no UTC midnight reset. A growing DEX with continuous swaps will not print $0 on Charts. That is intended.

Docs / glossary gap

docs/frontend.md § Charts overview documents USD formatting, not trailing vs calendar.
docs/indexer-invariants.md says “Overview global 24h stats” / rollup lag, not retail wording.
docs/design-system.md terminology glossary has no 24h volume row.
docs/user-incident-faq.md is incident controls only — wrong place for this FAQ.

Why this is needed

The report is a product-trust bug even when the math is right. “It never goes back to 0” is the expected shape of a trailing window on a live DEX. The UI currently looks like a broken cumulative counter.
Mobile cannot see the existing tooltip, and that tooltip does not mention a trailing window anyway (24h volume in USD).
Inconsistent chrome: pair High/Low already say “last 24h”; volume boxes do not. Protocol 24h/7d/30d look like calendar buckets.
Do not “fix” this by switching to calendar-day volume. That would disagree with CG/CMC 24h, pair stats, pair_volume_24h, and every existing test cutoff.

Constraints / guardrails

Keep trailing now − 24h (and 7d / 30d). No UTC-day, no “resets at 00:00”, no cron that zeros the rollup.
Copy (#489): labels ≤ ~5 words. No always-on lecture banner on /charts or /protocol. Progressive disclosure = native title / aria-label (and optional one-line glossary in docs). Do not paste indexer SQL into the UI.
Do not resurrect raw total_volume_24h. Charts stays USD-only (#548 C1). Idle → $0; unpriced + trades → —.
Do not imply settlement or a peg. USD is advisory (X5). Tooltip must not say “guaranteed USD” or “daily close”.
Do not leak VITE_INDEXER_URL or hostnames in titles (#215).
Static copy only in labels/titles — never interpolate overview JSON into title (XSS / layout).
Accessible on mobile: hover-only title is not enough. Prefer a visible short label change or an aria-label on the value that screen readers and (if needed) a tap-safe title on the label text. Do not add a permanent help paragraph.
Out of scope: ingest / volume_usd formula; rollup SQL decay (linked indexer issue); CG/CMC; trader lifetime Volume (USD) (#553); candle histogram.

Relevant files

Area	Path
Charts overview + pair stats	`frontend-dapp/src/pages/ChartsPage.tsx`
Charts tests	`frontend-dapp/src/pages/ChartsPage.test.tsx`
StatBox	`frontend-dapp/src/components/ui/StatBox.tsx`
Protocol stats	`frontend-dapp/src/components/protocol/ProtocolGlobalStats.tsx`, `frontend-dapp/src/pages/ProtocolPage.test.tsx`
Pool Vol header	`frontend-dapp/src/components/pool/PoolPairsTable.tsx`
Copy / format helpers	`frontend-dapp/src/utils/chartsOverviewStats.ts`
Docs	`docs/frontend.md` (§ Charts overview, Protocol), `docs/design-system.md` (glossary), `skills/AGENTS_FRONTEND_CHARTS_OVERVIEW.md`, `skills/AGENTS_FRONTEND_PROTOCOL_STATS.md`, `skills/AGENTS_FRONTEND_COPY_COGNITIVE_LOAD.md`
Indexer (read-only for this issue)	`indexer/src/db/queries/volume.rs`, `indexer/src/api/overview.rs`

Recommended direction

Shared copy constant (one module, used by Charts overview, pair Vol, Protocol 24h, optional Pool title on Vol): e.g. label stays 24h Volume (USD) (or Last 24h Vol (USD) if it still fits #489); title / aria-label = one sentence: “Priced swaps in the last 24 hours, not a midnight reset.” Protocol 7d/30d: same pattern (“last 7 days” / “last 30 days”).
Put title on the label <p> (or a visible abbr) so mobile long-press / accessibility can reach it; keep data-testids (charts-overview-volume-usd, protocol-stat-volume-24h, charts-pair-volume-usd).
Glossary row in docs/design-system.md: 24h volume = trailing window. frontend.md + skills: one sentence that $0 is idle-window, not daily close.
Vitest asserts label + title/aria-label on overview, pair stats, Protocol. Do not assert a $0 after wall-clock midnight.
make verify-issue-<iid> listed in Makefile help.

Acceptance criteria

W1 Charts overview 24h Volume (USD) (and 24h Trades) disclose a trailing window — not a calendar-day reset — via short label and/or aria-label that works without hover.
W2 Pair Vol (USD) and Protocol 24h / 7d / 30d volume use the same trailing wording (7d/30d = last N days).
W3 Copy stays ≤ ~5 words on the visible label; no always-on educational banner; no raw total_volume_24h.
W4 Idle DEX still $0; unpriced + trades still —; USD compact format unchanged (C1–C3).
W5 Docs + skills + glossary updated; make verify-issue-<iid> exists.

Test plan (all paths)

ID	Case	Expect
U1	Charts overview with mocked priced 24h USD	Label/aria mentions trailing 24h; value still `$` + compact
U2	Charts overview idle (`total_trades_24h === 0`, USD `"0"`)	`$0` still allowed; copy does not promise a daily reset
U3	Charts overview unpriced (`usd` null, trades > 0)	`—`; copy unchanged
U4	Pair 24h Vol (USD)	Same trailing disclosure as overview
U5	Protocol 24h / 7d / 30d	Trailing 24h / 7d / 30d; lead paragraph not a lecture
U6	Pool Vol header	Optional `title`; sort still `volume_24h`; no catalog-rank regression
U7	Charts SORT `24h volume`	Control still works; no raw mixed-unit display regression
U8	Outage banner (#215)	Strip still skeletons/hides; no indexer URL in titles
U9	Dark + light, mobile width	No hover required to understand the window (aria or visible “Last 24h”)
U10	Cognitive load	No new always-on paragraph on `/charts`

Test plan (attack, hack, abuse)

ID	Vector	Expect
A1	Overview JSON with `<script>` / overlong `total_volume_24h_usd` in tooltip	Titles are static; adversarial USD still capped by `formatChartsOverviewVolumeUsd` (#548 A4)
A2	Inject indexer URL into copy	Forbidden; grep titles for `http`, `VITE_`, hostnames
A3	Homoglyph / RTL in new strings	Source is repo constants only
A4	Changing the window to calendar-day “to make it hit $0”	Reject — would desync CG/CMC and pair stats; DoS risk if implemented as live midnight scan on GET
A5	Using volume copy to imply insured USD / settlement	Forbidden (X5)
A6	Clickjack / overlay on new help control	No extra interactive “?” required; if added, must not cover Connect / nav

Verification criteria

make verify-issue-<iid> (Vitest Charts + Protocol + StatBox; optional Playwright /charts mocked overview).
Manual: /charts and /protocol on a phone-width viewport — a new user can tell volume is last 24 hours, not “since launch” and not “since midnight”.
With continuous activity, volume need not be $0; with a fixture of zero 24h swaps, volume is $0.
No change to GET /api/v1/overview field semantics in this issue.

## Summary Retail on **Charts & Analytics** (`/charts` at dex.cl8y.com) reads **24h Volume (USD)** as a calendar-day counter that should hit **`$0`** (e.g. at midnight). It does not. The indexer figure is a **trailing 24-hour window** (`Utc::now() − 24h` over `swap_events`). With ongoing mainnet activity the number is expected to stay above `$0` and can trend up for days. The UI never says that. This issue owns **copy + progressive disclosure** on Charts, Protocol, pair 24h stats, and related 24h volume labels so the existing rolling math is obvious. It does **not** change the window to UTC calendar days. Related (do **not** treat as done here): [#548](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/issues/548) USD-only overview; [#550](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/issues/550) Protocol 24h/7d/30d; [#565](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/issues/565) pair **Vol (USD)**; [#243](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/issues/243) / [#333](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/issues/333) rollups. Indexer rollups that **fail to decay** (token stats, idle traders, stale `global_stats_24h` if the aggregator dies) are a **separate linked issue**. ## Current codebase ### What `/charts` actually shows [`ChartsPage.tsx`](frontend-dapp/src/pages/ChartsPage.tsx) loads `GET /api/v1/overview` and renders: | Box | Source | Label / tooltip today | |-----|--------|------------------------| | 24h Volume (USD) | `total_volume_24h_usd` | Label `24h Volume (USD)`; `title="24h volume in USD"` | | 24h Trades | `total_trades_24h` | Label only — no window hint | | Pair **Vol (USD)** | `GET /api/v1/pairs/{addr}/stats` `volume_usd` | `title="24h volume in USD"` | | Pair High/Low | `high_usd` / `low_usd` | Already says **“last 24h”** on High/Low titles | [`StatBox`](frontend-dapp/src/components/ui/StatBox.tsx) puts `title` on the card (`<div title={title}>`). Native hover only; no `aria-describedby`. Mobile (the screenshot surface) has **no hover**, so the tooltip never appears on phones. Pair list **SORT** default is `24h volume` ([`PAIR_SORT_OPTIONS`](frontend-dapp/src/pages/ChartsPage.tsx)). `/pool` column header is **Vol** sorted as `volume_24h` ([`PoolPairsTable.tsx`](frontend-dapp/src/components/pool/PoolPairsTable.tsx)) — no window text. [`/protocol`](frontend-dapp/src/components/protocol/ProtocolGlobalStats.tsx) labels `24h volume`, `7d volume`, `30d volume` with a lead that explains USD/oracle provenance, **not** trailing vs calendar. No `title` on those `StatBox`es. ### Indexer window (correct for this issue) [`refresh_global_stats`](indexer/src/db/queries/volume.rs) / [`get_global_stats_live`](indexer/src/db/queries/volume.rs): - Cutoff = `Utc::now() - Duration::hours(24)` (and 7d / 30d). - `SUM(volume_usd) FILTER (WHERE block_timestamp >= cutoff)`. - Rollup table `global_stats_24h`, refresh ~5 min ([`volume_aggregator.rs`](indexer/src/indexer/volume_aggregator.rs)), `/overview` cached **60s** ([`overview.rs`](indexer/src/api/overview.rs)). - Pair stats [`get_24h_stats_for_pair`](indexer/src/db/queries/swap_events.rs) uses the same `now − 24h` live filter. - Tests already assert **old swaps are excluded** (`global_stats_rollup_excludes_swaps_older_than_24h`). Idle DEX with zero 24h trades is allowed to show `$0` ([#548](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/issues/548) **C3**). There is **no UTC midnight reset**. A growing DEX with continuous swaps will not print `$0` on Charts. That is intended. ### Docs / glossary gap - [`docs/frontend.md`](docs/frontend.md) § Charts overview documents USD formatting, not trailing vs calendar. - [`docs/indexer-invariants.md`](docs/indexer-invariants.md) says “Overview global 24h stats” / rollup lag, not retail wording. - [`docs/design-system.md`](docs/design-system.md) terminology glossary has no **24h volume** row. - [`docs/user-incident-faq.md`](docs/user-incident-faq.md) is incident controls only — **wrong place** for this FAQ. ## Why this is needed 1. **The report is a product-trust bug even when the math is right.** “It never goes back to 0” is the expected shape of a trailing window on a live DEX. The UI currently looks like a broken cumulative counter. 2. **Mobile cannot see the existing tooltip**, and that tooltip does not mention a trailing window anyway (`24h volume in USD`). 3. **Inconsistent chrome:** pair High/Low already say “last 24h”; volume boxes do not. Protocol 24h/7d/30d look like calendar buckets. 4. **Do not “fix” this by switching to calendar-day volume.** That would disagree with CG/CMC 24h, pair stats, `pair_volume_24h`, and every existing test cutoff. ## Constraints / guardrails 1. **Keep trailing `now − 24h` (and 7d / 30d).** No UTC-day, no “resets at 00:00”, no cron that zeros the rollup. 2. **Copy (#489):** labels ≤ ~5 words. **No always-on lecture banner** on `/charts` or `/protocol`. Progressive disclosure = native `title` / `aria-label` (and optional one-line glossary in docs). Do not paste indexer SQL into the UI. 3. **Do not resurrect raw `total_volume_24h`.** Charts stays USD-only ([#548](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/issues/548) **C1**). Idle → `$0`; unpriced + trades → `—`. 4. **Do not imply settlement or a peg.** USD is advisory (**X5**). Tooltip must not say “guaranteed USD” or “daily close”. 5. **Do not leak `VITE_INDEXER_URL` or hostnames** in titles ([#215](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/issues/215)). 6. **Static copy only** in labels/titles — never interpolate overview JSON into `title` (XSS / layout). 7. **Accessible on mobile:** hover-only `title` is not enough. Prefer a visible short label change **or** an `aria-label` on the value that screen readers and (if needed) a tap-safe `title` on the label text. Do not add a permanent help paragraph. 8. **Out of scope:** ingest / `volume_usd` formula; rollup SQL decay (linked indexer issue); CG/CMC; trader **lifetime** Volume (USD) ([#553](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/issues/553)); candle histogram. ## Relevant files | Area | Path | |------|------| | Charts overview + pair stats | `frontend-dapp/src/pages/ChartsPage.tsx` | | Charts tests | `frontend-dapp/src/pages/ChartsPage.test.tsx` | | StatBox | `frontend-dapp/src/components/ui/StatBox.tsx` | | Protocol stats | `frontend-dapp/src/components/protocol/ProtocolGlobalStats.tsx`, `frontend-dapp/src/pages/ProtocolPage.test.tsx` | | Pool Vol header | `frontend-dapp/src/components/pool/PoolPairsTable.tsx` | | Copy / format helpers | `frontend-dapp/src/utils/chartsOverviewStats.ts` | | Docs | `docs/frontend.md` (§ Charts overview, Protocol), `docs/design-system.md` (glossary), `skills/AGENTS_FRONTEND_CHARTS_OVERVIEW.md`, `skills/AGENTS_FRONTEND_PROTOCOL_STATS.md`, `skills/AGENTS_FRONTEND_COPY_COGNITIVE_LOAD.md` | | Indexer (read-only for this issue) | `indexer/src/db/queries/volume.rs`, `indexer/src/api/overview.rs` | ## Recommended direction 1. **Shared copy constant** (one module, used by Charts overview, pair Vol, Protocol 24h, optional Pool `title` on Vol): e.g. label stays **`24h Volume (USD)`** (or **`Last 24h Vol (USD)`** if it still fits #489); `title` / `aria-label` = one sentence: **“Priced swaps in the last 24 hours, not a midnight reset.”** Protocol 7d/30d: same pattern (“last 7 days” / “last 30 days”). 2. **Put `title` on the label `<p>` (or a visible `abbr`)** so mobile long-press / accessibility can reach it; keep `data-testid`s (`charts-overview-volume-usd`, `protocol-stat-volume-24h`, `charts-pair-volume-usd`). 3. **Glossary** row in `docs/design-system.md`: **24h volume** = trailing window. **frontend.md** + skills: one sentence that `$0` is idle-window, not daily close. 4. **Vitest** asserts label + `title`/`aria-label` on overview, pair stats, Protocol. Do not assert a `$0` after wall-clock midnight. 5. **`make verify-issue-<iid>`** listed in Makefile help. ## Acceptance criteria - [ ] **W1** Charts overview **24h Volume (USD)** (and **24h Trades**) disclose a **trailing** window — not a calendar-day reset — via short label and/or `aria-label` that works without hover. - [ ] **W2** Pair **Vol (USD)** and Protocol **24h / 7d / 30d volume** use the same trailing wording (7d/30d = last N days). - [ ] **W3** Copy stays ≤ ~5 words on the visible label; no always-on educational banner; no raw `total_volume_24h`. - [ ] **W4** Idle DEX still `$0`; unpriced + trades still `—`; USD compact format unchanged (**C1–C3**). - [ ] **W5** Docs + skills + glossary updated; `make verify-issue-<iid>` exists. ## Test plan (all paths) | ID | Case | Expect | |----|------|--------| | U1 | Charts overview with mocked priced 24h USD | Label/aria mentions trailing 24h; value still `$` + compact | | U2 | Charts overview idle (`total_trades_24h === 0`, USD `"0"`) | `$0` still allowed; copy does not promise a daily reset | | U3 | Charts overview unpriced (`usd` null, trades > 0) | `—`; copy unchanged | | U4 | Pair 24h **Vol (USD)** | Same trailing disclosure as overview | | U5 | Protocol 24h / 7d / 30d | Trailing 24h / 7d / 30d; lead paragraph not a lecture | | U6 | Pool **Vol** header | Optional `title`; sort still `volume_24h`; no catalog-rank regression | | U7 | Charts SORT `24h volume` | Control still works; no raw mixed-unit display regression | | U8 | Outage banner (#215) | Strip still skeletons/hides; no indexer URL in titles | | U9 | Dark + light, mobile width | No hover required to understand the window (aria or visible “Last 24h”) | | U10 | Cognitive load | No new always-on paragraph on `/charts` | ## Test plan (attack, hack, abuse) | ID | Vector | Expect | |----|--------|--------| | A1 | Overview JSON with `<script>` / overlong `total_volume_24h_usd` in tooltip | Titles are **static**; adversarial USD still capped by `formatChartsOverviewVolumeUsd` ([#548](https://gitlab.com/PlasticDigits/cl8y-dex-terraclassic/-/issues/548) **A4**) | | A2 | Inject indexer URL into copy | Forbidden; grep titles for `http`, `VITE_`, hostnames | | A3 | Homoglyph / RTL in new strings | Source is repo constants only | | A4 | Changing the window to calendar-day “to make it hit $0” | **Reject** — would desync CG/CMC and pair stats; DoS risk if implemented as live midnight scan on GET | | A5 | Using volume copy to imply insured USD / settlement | Forbidden (**X5**) | | A6 | Clickjack / overlay on new help control | No extra interactive “?” required; if added, must not cover Connect / nav | ## Verification criteria 1. `make verify-issue-<iid>` (Vitest Charts + Protocol + StatBox; optional Playwright `/charts` mocked overview). 2. Manual: `/charts` and `/protocol` on a phone-width viewport — a new user can tell volume is **last 24 hours**, not “since launch” and not “since midnight”. 3. With continuous activity, volume **need not** be `$0`; with a fixture of **zero 24h swaps**, volume **is** `$0`. 4. No change to `GET /api/v1/overview` field semantics in this issue.

PlasticDigits commented

2026-08-19 11:53:04 +00:00

(Migrated from gitlab.com)

marked as related to #577

PlasticDigits commented

2026-08-20 01:38:12 +00:00

(Migrated from gitlab.com)

mentioned in merge request !1096

PlasticDigits commented

2026-08-20 01:53:01 +00:00

(Migrated from gitlab.com)

mentioned in merge request !1099

PlasticDigits commented

2026-08-20 03:14:44 +00:00

(Migrated from gitlab.com)

mentioned in commit f6b79a17d8

mentioned in commit f6b79a17d81ac50108bd4d8f68368fb21d6ef101

PlasticDigits (Migrated from gitlab.com) closed this issue

2026-08-20 03:14:44 +00:00

PlasticDigits commented

2026-08-20 03:20:37 +00:00

(Migrated from gitlab.com)

mentioned in commit 39c6cb382a

mentioned in commit 39c6cb382a050b39e446b5926cacf61b7fbbfed0

PlasticDigits commented

2026-08-20 03:29:35 +00:00

(Migrated from gitlab.com)

mentioned in commit 2db2d42baa

mentioned in commit 2db2d42baa05ffaae1411e6483ce57a97170ad6a

PlasticDigits commented

2026-08-20 03:54:13 +00:00

(Migrated from gitlab.com)

Merged via !1096.

make verify-issue-576 passed after resolving Makefile conflicts with origin/main (kept verify-issue-573). Remaining unchecked items are production/visual, not code:

Phone-width /charts and /protocol: confirm a new user can tell volume is last 24 hours (visible Last 24h + aria-label), not since launch / midnight
Dark + light: no always-on lecture banner; outage banner still hides indexer URLs

Indexer rollup decay is #577 (!1099), not this issue.

Merged via !1096. `make verify-issue-576` passed after resolving Makefile conflicts with `origin/main` (kept `verify-issue-573`). Remaining unchecked items are production/visual, not code: - Phone-width `/charts` and `/protocol`: confirm a new user can tell volume is last 24 hours (visible Last 24h + aria-label), not since launch / midnight - Dark + light: no always-on lecture banner; outage banner still hides indexer URLs Indexer rollup decay is #577 (!1099), not this issue.

PlasticDigits commented

2026-08-20 03:54:26 +00:00

(Migrated from gitlab.com)

mentioned in issue #569