Docs + frontend: indexer-first reads, eliminate browser RPC fallbacks for display data

PlasticDigits commented

2026-06-07 13:57:29 +00:00

(Migrated from gitlab.com)

Summary

Document and implement an indexer-first data policy for Arena display surfaces. Browser JSON-RPC must not be used as a fallback when the indexer is unavailable or VITE_INDEXER_URL is unset. RPC in the wallet client remains limited to transaction signing, gas estimation, allowance/balance checks required at submit time, and other writes — with backoff, coalescing, and rate-limit awareness.

This issue bundles documentation updates, frontend behavior changes, and guardrail/invariant work. It does not include podium prize amounts (see linked issue for GET /v1/arena/podiums payout fields).

Current codebase

Indexer already centralizes head RPC

The Rust indexer runs a background chain_timer poller (indexer/src/chain_timer.rs) that batches eth_call reads at a shared read_block_number and serves:

GET /v1/arena/timers — deadlines, epochs, total_doub_raised, paused
GET /v1/arena/podiums — UX-ordered leaders + scores (no prize amounts today)
GET /v1/arena/buys, /activity, /wallet/{address}/stats, vault-funding, donate-pools

See docs/indexer/design.md § Arena HTTP.

Frontend still falls back to browser RPC in multiple places

Location	Behavior today
`usePodiumReads.ts`	Indexer when `VITE_INDEXER_URL` set; else 8× `podium` + epoch multicall ~1 Hz
`ArenaTimerChips.tsx`	Indexer timers; else 3× `podiumDeadline` RPC
`useArenaSaleSession.ts`	Arena v2 forces RPC (`indexerOn = indexerBaseUrl() && !isArenaV2`) — core sale reads always via wagmi multicall
`useWarbowBpMovingEventWatch`	`useWatchContractEvent` when indexer off
`useArenaHeroTimer.ts`	Mixed indexer + RPC refresh paths
`wagmi-config.ts`	Multi-URL RPC transport with fallbacks for all wallet traffic

Docs currently describe indexer as optional and RPC as acceptable fallback, e.g. docs/frontend/arena-views.md (“GET /v1/arena/podiums or RPC”), skills/play-active-time-arena/SKILL.md, and comments in usePodiumReads.ts.

Why this hurts production

MegaETH / public RPC rate limits (#221): each connected browser polling head state multiplies load.
Inconsistent UX: indexer-down currently degrades to empty/stale RPC reads instead of a clear “indexer required” state.
Arena v2 regression: sale session intentionally bypasses indexer sale-state even when configured.

Why the new implementation is needed

Cost & reliability: One indexer poller per deployment is cheaper and easier to throttle than N browsers × M multicalls.
Product clarity: Arena v2 is indexer-backed; display surfaces should not silently reintroduce v1-style RPC mirrors.
Operational guardrails: Agents and contributors need explicit docs so new features do not add useReadContracts for data the indexer can serve.

Constraints & guardrails

Onchain authority unchanged (yieldomega-guardrails SKILL): prizes, winners, routing remain contract truth; indexer is derived.
Writes stay on RPC: buy, claimCred, WarBow actions, topUpPodiumPools, approvals — no indexer substitution.
Preflight at submit time may still use fresh RPC (allowance, nextBuyAllowedAt, simulate) — document as allowed exception.
E2E Anvil: Playwright mock wallet specs may omit indexer; document minimal vs full-stack modes in docs/testing/e2e-anvil.md.
503 / offline UX: When indexer unreachable, show IndexerStatusBar / cached stale state — not browser RPC backfill.
AGPL: indexer changes remain AGPL-3.0.
Do not remove RPC URL fallbacks from wagmi transport for write reliability — only stop display-data RPC mirrors.

Relevant files

Docs (update/create policy sections):

AGENTS.md — Cloud agent verification table
docs/frontend/arena-views.md
docs/frontend/design.md
docs/frontend/wallet-connection.md
docs/indexer/design.md § API guidelines
docs/testing/invariants-and-business-logic.md
docs/testing/manual-qa-checklists.md
skills/play-active-time-arena/SKILL.md
.cursor/skills/yieldomega-guardrails/SKILL.md

Frontend (remove display RPC fallbacks / enable indexer for v2 session):

Indexer (if gaps block frontend):

indexer/src/api_arena.rs — extend timers/sale-state fields if v2 session needs more than timers today
indexer/src/chain_timer.rs / sale_state.rs

Recommended direction

Documentation

Add a canonical “Indexer-first / RPC-minimal” section (pick one home: docs/frontend/arena-views.md + link from AGENTS.md).
Table of allowed browser RPC vs indexer-only display reads.
State explicitly: VITE_INDEXER_URL is required for production Arena; unset = degraded/dev-only with visible banner.
Document indexer outage behavior: stale cache + status bar; no silent RPC fallback.

Frontend

usePodiumReads: Remove useReadContracts podium/epoch path; when indexer off or failing, return empty/placeholder + source: "unavailable".
ArenaTimerChips: Indexer-only for deadlines.
useArenaSaleSession: Remove !isArenaV2 gate; map GET /v1/arena/timers (and extend indexer if needed) via existing useArenaSaleStateQuery / arenaV2SaleSessionBridge.
useWarbowBpMovingEventWatch: Disable contract event watches when indexer configured (already partial); rely on indexer poll + invalidation only.
Audit arena folder for remaining refetchInterval display reads; migrate or justify in docs.

Indexer (only if required for v2 session)

Ensure GET /v1/arena/timers (or a thin GET /v1/arena/head) exposes all fields arenaV2SaleSessionBridge needs so frontend can drop core multicall entirely.

Invariants

Add e.g. INV-FRONTEND-INDEXER-FIRST-DISPLAY: no wagmi read path for podium/timers/sale head when VITE_INDEXER_URL set.

Acceptance criteria

Docs list indexer-first policy, allowed RPC exceptions, and production env requirement for VITE_INDEXER_URL.
With VITE_INDEXER_URL set, browser makes no recurring eth_call multicalls for podiums, podium deadlines, or core sale head fields (verify via DevTools / VITE_RPC_DEBUG=1).
With indexer down but URL set, UI shows explicit indexer-unavailable state — not live RPC backfill.
With VITE_INDEXER_URL unset, UI shows dev/degraded banner; no hidden RPC polling for those surfaces.
Arena v2 sale session uses indexer timers/sale-state when indexer configured.
New invariant(s) documented and referenced from guardrails SKILL.
cd frontend && npm run typecheck && npm run lint && npm test PASS.
cd indexer && cargo clippy --all-targets -- -D warnings && cargo test PASS (if indexer API touched).

Test plan (functional paths)

Path	Steps	Expected
Full stack healthy	`start-qa-local-full-stack.sh`, open `/arena` with indexer URL	Podiums, timers, buy hub populated; no display multicall spam in RPC debug
Indexer stopped	Kill indexer process, reload `/arena`	Status bar / stale message; podiums do not repopulate via RPC
Indexer URL unset	Remove `VITE_INDEXER_URL`, restart Vite	Clear degraded copy; no 1 Hz podium multicall
Buy still works	Connected wallet, indexer up	Buy tx submits via RPC; allowance/balance reads only around CTA
WarBow panel	Steal after indexer invalidation	Leaderboard refreshes via indexer poll, not event watch
Protocol AUDIT	`/arena/protocol`	Activity/buys from indexer; donate still writes on-chain
E2E minimal	`e2e-anvil.sh` without indexer	Documented skip or mock; no regression in CI
E2E full	Stack + `verify-podium-live-anvil.sh`	Still PASS

Test plan (attack, hack, abuse vectors)

Vector	Mitigation to verify
Malicious indexer JSON inflates timers/podiums	Frontend treats indexer as display-only; writes still revert on-chain; document no trust for balances at submit without wallet RPC check
Indexer MITM / stale cache tricks user into wrong buy timing	Stale banner when `reportIndexerFetchAttempt` fails; submit-time `deadline`/`nextBuyAllowedAt` still read via RPC at click (allowed exception)
RPC rate-limit DoS via forced browser fallback	Removing display fallbacks reduces attack surface; wallet RPC backoff unchanged
Fake “indexer down” forcing users to broken UI	UX must not hide buy CTA solely due to indexer; chain writes still available when wallet RPC healthy
Supply-chain: new hook re-adds RPC poll	Invariant + `frontend` lint/grep check in CI optional: ban `enabled: !indexerOn` patterns in arena hooks

Verification criteria

# Docs grep — no “or RPC” as equal fallback for podiums/timers without indexer-first qualifier
rg 'or RPC' docs/frontend/arena-views.md  # should be updated

# Frontend
cd frontend && npm run typecheck && npm run lint && npm test

# Indexer (if touched)
cd indexer && cargo clippy --all-targets -- -D warnings && cargo test

# Anvil smoke (display still correct)
bash scripts/verify-podium-live-anvil.sh

# Manual: VITE_RPC_DEBUG=1 — confirm no recurring podium/deadline multicall with indexer on

Out of scope (separate issue)

Podium prize DOUB/USD amounts on GET /v1/arena/podiums and ArenaSimplePage wiring.

## Summary Document and implement an **indexer-first** data policy for Arena display surfaces. Browser JSON-RPC must not be used as a fallback when the indexer is unavailable or `VITE_INDEXER_URL` is unset. RPC in the wallet client remains limited to **transaction signing, gas estimation, allowance/balance checks required at submit time**, and other writes — with backoff, coalescing, and rate-limit awareness. This issue bundles **documentation updates**, **frontend behavior changes**, and **guardrail/invariant** work. It does **not** include podium prize amounts (see linked issue for `GET /v1/arena/podiums` payout fields). --- ## Current codebase ### Indexer already centralizes head RPC The Rust indexer runs a background **`chain_timer`** poller ([`indexer/src/chain_timer.rs`](indexer/src/chain_timer.rs)) that batches `eth_call` reads at a shared `read_block_number` and serves: - `GET /v1/arena/timers` — deadlines, epochs, `total_doub_raised`, `paused` - `GET /v1/arena/podiums` — UX-ordered leaders + scores (no prize amounts today) - `GET /v1/arena/buys`, `/activity`, `/wallet/{address}/stats`, vault-funding, donate-pools See [`docs/indexer/design.md`](docs/indexer/design.md) § Arena HTTP. ### Frontend still falls back to browser RPC in multiple places | Location | Behavior today | |----------|----------------| | [`usePodiumReads.ts`](frontend/src/pages/arena/usePodiumReads.ts) | Indexer when `VITE_INDEXER_URL` set; else **8× `podium` + epoch multicall** ~1 Hz | | [`ArenaTimerChips.tsx`](frontend/src/pages/arena/ArenaTimerChips.tsx) | Indexer timers; else **3× `podiumDeadline` RPC** | | [`useArenaSaleSession.ts`](frontend/src/pages/arena/useArenaSaleSession.ts) | **Arena v2 forces RPC** (`indexerOn = indexerBaseUrl() && !isArenaV2`) — core sale reads always via wagmi multicall | | [`useWarbowBpMovingEventWatch`](frontend/src/pages/arena/usePodiumReads.ts) | `useWatchContractEvent` when indexer **off** | | [`useArenaHeroTimer.ts`](frontend/src/pages/arena/useArenaHeroTimer.ts) | Mixed indexer + RPC refresh paths | | [`wagmi-config.ts`](frontend/src/wagmi-config.ts) | Multi-URL RPC transport with fallbacks for all wallet traffic | Docs currently describe indexer as **optional** and RPC as acceptable fallback, e.g. [`docs/frontend/arena-views.md`](docs/frontend/arena-views.md) (“`GET /v1/arena/podiums` or RPC”), [`skills/play-active-time-arena/SKILL.md`](skills/play-active-time-arena/SKILL.md), and comments in [`usePodiumReads.ts`](frontend/src/pages/arena/usePodiumReads.ts). ### Why this hurts production - **MegaETH / public RPC rate limits** ([#221](https://gitlab.com/PlasticDigits/yieldomega/-/issues/221)): each connected browser polling head state multiplies load. - **Inconsistent UX**: indexer-down currently degrades to empty/stale RPC reads instead of a clear “indexer required” state. - **Arena v2 regression**: sale session intentionally bypasses indexer sale-state even when configured. --- ## Why the new implementation is needed 1. **Cost & reliability**: One indexer poller per deployment is cheaper and easier to throttle than N browsers × M multicalls. 2. **Product clarity**: Arena v2 is indexer-backed; display surfaces should not silently reintroduce v1-style RPC mirrors. 3. **Operational guardrails**: Agents and contributors need explicit docs so new features do not add `useReadContracts` for data the indexer can serve. --- ## Constraints & guardrails - **Onchain authority unchanged** ([`yieldomega-guardrails` SKILL](.cursor/skills/yieldomega-guardrails/SKILL.md)): prizes, winners, routing remain contract truth; indexer is derived. - **Writes stay on RPC**: `buy`, `claimCred`, WarBow actions, `topUpPodiumPools`, approvals — no indexer substitution. - **Preflight at submit time** may still use fresh RPC (allowance, `nextBuyAllowedAt`, simulate) — document as allowed exception. - **E2E Anvil**: Playwright mock wallet specs may omit indexer; document minimal vs full-stack modes in [`docs/testing/e2e-anvil.md`](docs/testing/e2e-anvil.md). - **503 / offline UX**: When indexer unreachable, show [`IndexerStatusBar`](frontend/src/components/IndexerStatusBar.tsx) / cached stale state — **not** browser RPC backfill. - **AGPL**: indexer changes remain AGPL-3.0. - Do **not** remove RPC URL fallbacks from **wagmi transport** for write reliability — only stop **display-data** RPC mirrors. --- ## Relevant files **Docs (update/create policy sections):** - [`AGENTS.md`](AGENTS.md) — Cloud agent verification table - [`docs/frontend/arena-views.md`](docs/frontend/arena-views.md) - [`docs/frontend/design.md`](docs/frontend/design.md) - [`docs/frontend/wallet-connection.md`](docs/frontend/wallet-connection.md) - [`docs/indexer/design.md`](docs/indexer/design.md) § API guidelines - [`docs/testing/invariants-and-business-logic.md`](docs/testing/invariants-and-business-logic.md) - [`docs/testing/manual-qa-checklists.md`](docs/testing/manual-qa-checklists.md) - [`skills/play-active-time-arena/SKILL.md`](skills/play-active-time-arena/SKILL.md) - [`.cursor/skills/yieldomega-guardrails/SKILL.md`](.cursor/skills/yieldomega-guardrails/SKILL.md) **Frontend (remove display RPC fallbacks / enable indexer for v2 session):** - [`frontend/src/pages/arena/usePodiumReads.ts`](frontend/src/pages/arena/usePodiumReads.ts) - [`frontend/src/pages/arena/ArenaTimerChips.tsx`](frontend/src/pages/arena/ArenaTimerChips.tsx) - [`frontend/src/pages/arena/useArenaSaleSession.ts`](frontend/src/pages/arena/useArenaSaleSession.ts) - [`frontend/src/pages/arena/useArenaHeroTimer.ts`](frontend/src/pages/arena/useArenaHeroTimer.ts) - [`frontend/src/pages/arena/arenaV2SaleSessionBridge.ts`](frontend/src/pages/arena/arenaV2SaleSessionBridge.ts) - [`frontend/src/lib/indexerApi.ts`](frontend/src/lib/indexerApi.ts) - [`frontend/src/providers/IndexerConnectivityContext.tsx`](frontend/src/providers/IndexerConnectivityContext.tsx) **Indexer (if gaps block frontend):** - [`indexer/src/api_arena.rs`](indexer/src/api_arena.rs) — extend timers/sale-state fields if v2 session needs more than timers today - [`indexer/src/chain_timer.rs`](indexer/src/chain_timer.rs) / [`sale_state.rs`](indexer/src/sale_state.rs) --- ## Recommended direction ### Documentation 1. Add a canonical **“Indexer-first / RPC-minimal”** section (pick one home: `docs/frontend/arena-views.md` + link from `AGENTS.md`). 2. Table of **allowed browser RPC** vs **indexer-only display** reads. 3. State explicitly: **`VITE_INDEXER_URL` is required for production Arena**; unset = degraded/dev-only with visible banner. 4. Document indexer outage behavior: stale cache + status bar; **no silent RPC fallback**. ### Frontend 1. **`usePodiumReads`**: Remove `useReadContracts` podium/epoch path; when indexer off or failing, return empty/placeholder + `source: "unavailable"`. 2. **`ArenaTimerChips`**: Indexer-only for deadlines. 3. **`useArenaSaleSession`**: Remove `!isArenaV2` gate; map `GET /v1/arena/timers` (and extend indexer if needed) via existing [`useArenaSaleStateQuery`](frontend/src/pages/arena/useArenaSaleState.ts) / [`arenaV2SaleSessionBridge`](frontend/src/pages/arena/arenaV2SaleSessionBridge.ts). 4. **`useWarbowBpMovingEventWatch`**: Disable contract event watches when indexer configured (already partial); rely on indexer poll + invalidation only. 5. Audit arena folder for remaining `refetchInterval` display reads; migrate or justify in docs. ### Indexer (only if required for v2 session) - Ensure `GET /v1/arena/timers` (or a thin `GET /v1/arena/head`) exposes all fields `arenaV2SaleSessionBridge` needs so frontend can drop core multicall entirely. ### Invariants - Add e.g. **`INV-FRONTEND-INDEXER-FIRST-DISPLAY`**: no wagmi read path for podium/timers/sale head when `VITE_INDEXER_URL` set. --- ## Acceptance criteria - [ ] Docs list indexer-first policy, allowed RPC exceptions, and production env requirement for `VITE_INDEXER_URL`. - [ ] With `VITE_INDEXER_URL` set, browser makes **no** recurring `eth_call` multicalls for podiums, podium deadlines, or core sale head fields (verify via DevTools / `VITE_RPC_DEBUG=1`). - [ ] With indexer **down** but URL set, UI shows explicit indexer-unavailable state — **not** live RPC backfill. - [ ] With `VITE_INDEXER_URL` **unset**, UI shows dev/degraded banner; no hidden RPC polling for those surfaces. - [ ] Arena v2 sale session uses indexer timers/sale-state when indexer configured. - [ ] New invariant(s) documented and referenced from guardrails SKILL. - [ ] `cd frontend && npm run typecheck && npm run lint && npm test` PASS. - [ ] `cd indexer && cargo clippy --all-targets -- -D warnings && cargo test` PASS (if indexer API touched). --- ## Test plan (functional paths) | Path | Steps | Expected | |------|-------|----------| | Full stack healthy | `start-qa-local-full-stack.sh`, open `/arena` with indexer URL | Podiums, timers, buy hub populated; no display multicall spam in RPC debug | | Indexer stopped | Kill indexer process, reload `/arena` | Status bar / stale message; podiums do not repopulate via RPC | | Indexer URL unset | Remove `VITE_INDEXER_URL`, restart Vite | Clear degraded copy; no 1 Hz podium multicall | | Buy still works | Connected wallet, indexer up | Buy tx submits via RPC; allowance/balance reads only around CTA | | WarBow panel | Steal after indexer invalidation | Leaderboard refreshes via indexer poll, not event watch | | Protocol AUDIT | `/arena/protocol` | Activity/buys from indexer; donate still writes on-chain | | E2E minimal | `e2e-anvil.sh` without indexer | Documented skip or mock; no regression in CI | | E2E full | Stack + `verify-podium-live-anvil.sh` | Still PASS | --- ## Test plan (attack, hack, abuse vectors) | Vector | Mitigation to verify | |--------|---------------------| | **Malicious indexer JSON** inflates timers/podiums | Frontend treats indexer as display-only; writes still revert on-chain; document no trust for balances at submit without wallet RPC check | | **Indexer MITM / stale cache** tricks user into wrong buy timing | Stale banner when `reportIndexerFetchAttempt` fails; submit-time `deadline`/`nextBuyAllowedAt` still read via RPC at click (allowed exception) | | **RPC rate-limit DoS** via forced browser fallback | Removing display fallbacks reduces attack surface; wallet RPC backoff unchanged | | **Fake “indexer down” forcing users to broken UI** | UX must not hide buy CTA solely due to indexer; chain writes still available when wallet RPC healthy | | **Supply-chain: new hook re-adds RPC poll** | Invariant + `frontend` lint/grep check in CI optional: ban `enabled: !indexerOn` patterns in arena hooks | --- ## Verification criteria ```bash # Docs grep — no “or RPC” as equal fallback for podiums/timers without indexer-first qualifier rg 'or RPC' docs/frontend/arena-views.md # should be updated # Frontend cd frontend && npm run typecheck && npm run lint && npm test # Indexer (if touched) cd indexer && cargo clippy --all-targets -- -D warnings && cargo test # Anvil smoke (display still correct) bash scripts/verify-podium-live-anvil.sh # Manual: VITE_RPC_DEBUG=1 — confirm no recurring podium/deadline multicall with indexer on ``` --- ## Out of scope (separate issue) - Podium **prize** DOUB/USD amounts on `GET /v1/arena/podiums` and `ArenaSimplePage` wiring.

PlasticDigits commented

2026-06-07 13:57:54 +00:00

(Migrated from gitlab.com)

mentioned in issue #302

ghost1 commented

2026-06-08 06:14:54 +00:00

(Migrated from gitlab.com)

mentioned in commit a907b30e10

mentioned in commit a907b30e102fe28e041eb41e2e3eff157c646aa4

ghost1 commented

2026-06-08 06:14:55 +00:00

(Migrated from gitlab.com)

mentioned in commit 3508d688da

mentioned in commit 3508d688da35868357e6a53093c7e87f9a038416

PlasticDigits commented

2026-06-08 06:15:09 +00:00

(Migrated from gitlab.com)

mentioned in merge request !446

PlasticDigits commented

2026-06-08 06:15:12 +00:00

(Migrated from gitlab.com)

Implementation complete for https://gitlab.com/PlasticDigits/yieldomega/-/work_items/301 — MR: https://gitlab.com/PlasticDigits/yieldomega/-/merge_requests/76

Summary

Indexer GET /v1/arena/timers now includes Arena v2 sale-head fields batched at read_block_number.
Frontend removed browser RPC fallbacks for podiums, timer chips, hero timer, and core sale head; Arena v2 buy hub reads indexer timers via coreReadRowsFromArenaTimers.
Added INV-FRONTEND-301-INDEXER-FIRST-DISPLAY and canonical policy docs in docs/frontend/arena-views.md.

Verification (all PASS)

Item	Command
Frontend	`cd frontend && npm run typecheck && npm run lint && npm test`
Indexer	`DATABASE_POOL_MAX=5 cargo clippy --all-targets -- -D warnings && cargo test`
Podium smoke	`bash scripts/verify-podium-live-anvil.sh`
Static gate	`indexerFirstDisplay.test.ts`

Issue remains open pending MR review/merge.

Implementation complete for https://gitlab.com/PlasticDigits/yieldomega/-/work_items/301 — MR: https://gitlab.com/PlasticDigits/yieldomega/-/merge_requests/76 **Summary** - Indexer `GET /v1/arena/timers` now includes Arena v2 sale-head fields batched at `read_block_number`. - Frontend removed browser RPC fallbacks for podiums, timer chips, hero timer, and core sale head; Arena v2 buy hub reads indexer timers via `coreReadRowsFromArenaTimers`. - Added `INV-FRONTEND-301-INDEXER-FIRST-DISPLAY` and canonical policy docs in `docs/frontend/arena-views.md`. **Verification (all PASS)** | Item | Command | |------|---------| | Frontend | `cd frontend && npm run typecheck && npm run lint && npm test` | | Indexer | `DATABASE_POOL_MAX=5 cargo clippy --all-targets -- -D warnings && cargo test` | | Podium smoke | `bash scripts/verify-podium-live-anvil.sh` | | Static gate | `indexerFirstDisplay.test.ts` | Issue remains open pending MR review/merge.

PlasticDigits commented

2026-06-08 06:54:06 +00:00

(Migrated from gitlab.com)