diff options
| -rw-r--r-- | web-site/docs/SPEC.md | 326 |
1 files changed, 326 insertions, 0 deletions
diff --git a/web-site/docs/SPEC.md b/web-site/docs/SPEC.md new file mode 100644 index 0000000..59fdd2a --- /dev/null +++ b/web-site/docs/SPEC.md @@ -0,0 +1,326 @@ +# zkVM Benchmarks Website Specification + +## Overview + +The zkVM Benchmarks website (`zk-wars.blocksense.network`) presents performance data for various Zero-Knowledge Virtual Machines (zkVMs). It enables technical users (developers, engineers, researchers) to quickly determine the best-performing toolchain and hardware configuration for specific cryptographic benchmarks. + +## Audience + +* Primary: Developers, engineers, researchers in ZK technology. +* Secondary: Accessible to non-technical users interested in performance comparisons. + +## User Goals + +* Quickly identify the best-performing toolchain overall. +* Evaluate toolchain performance for predefined and custom cryptographic benchmarks. +* Determine optimal hardware configurations. + +## Key Features + +### Benchmark Data Display + +For each toolchain and benchmark program, the website displays: + +* Proof generation time +* Proof generation memory usage +* Proof verification time +* Proof verification memory usage +* Circuit compilation time +* Circuit compilation memory usage +* Proof size + +Results are presented per hardware configuration. Cold/hot executions are reported separately when available. + +### Data Visualization Components + +* **Ranked Horizontal Bar Chart**: Best-performing toolchains listed clearly with visual bar representations. +* **Performance Metrics Table**: Numeric values with background-colored cells acting as proportional bars. +* **Line Charts**: Visualize performance trends based on input variables. + +### Benchmark Definition + +#### Predefined Benchmarks + +Examples include: + +* Merkle Tree generation +* Merkle proof verification +* ECDSA signature verification + +#### Custom Comparison Builder + +* Users select primitives (e.g., signature verification, hashing) and specify execution counts. +* UI is analogous to an online shopping cart: + + * Users select primitives via an auto-complete search box or hierarchical browsing. + * Primitives organized in categories (e.g., Hashing, Signatures, Arithmetic Operations, Symmetric Encryption). + +### Combined Comparison Calculation + +* Metrics are calculated as a simple linear sum of individual primitives. +* Results displayed as aggregated metrics, with detailed breakdown accessible via tap-to-expand interaction. +* Detailed breakdown shows percentage contributions for each primitive. + +## UI/UX Considerations + +### Interaction Model + +* Tap-to-expand interactions for detailed breakdowns (desktop and mobile). +* Dropdown menus for selecting comparison metrics (proof generation time, verification time, both). + +### Tables and Charts + +* Numeric tables use cell backgrounds to visually indicate performance proportionally. +* Combined metric charts use color-coded bars to indicate different contributions (generation vs verification). + +### Hardware Configuration + +* Predefined hardware presets (limited set). +* Detailed hardware specs shown upon selection. + +### Navigation Structure + +Hybrid approach: + +* SPA-like dynamic interactions with deep-linked, SEO-friendly URLs. +* Descriptive path segments for benchmarks, toolchain-specific pages, hardware-specific pages. + +### URL Structure + +* Benchmark pages: `zk-wars.blocksense.network/benchmarks/<use-case>?hardware=<preset>&hash=<hash>&metric=<metric>` +* Custom benchmarks: `zk-wars.blocksense.network/benchmarks/custom?data=<encoded-state>` +* Toolchain pages: `zk-wars.blocksense.network/toolchains/<toolchain-name>?hardware=<preset>` +* Hardware pages: `zk-wars.blocksense.network/hardware/<preset-name>` +* Hardware comparisons: `zk-wars.blocksense.network/hardware/<preset-name>/vs/<second-preset-name>` + +### URL State Management + +* Dropdown selection changes use `replaceState` (no new history entry). +* Navigating between pages or comparisons uses `pushState`. + +### Shared URLs + +* Users can share/bookmark benchmarks via a generated URL encoding the UI state. +* Invalid URL parameters load defaults with subtle warning icons next to affected UI components. + +### Responsive Design + +* Fully responsive; all data/features available on both desktop and mobile. +* Tables adapt by stacking columns/rows vertically on smaller screens. + +## Technical Implementation + +### Frontend + +* Next.js (React framework). +* Server-side rendering (SSR) or Static Site Generation (SSG) for SEO and performance. +* Client-side JSON fetching for dynamic data interactions. + +### Data Management + +Benchmark data stored as structured JSON files with the following schema: + +```json +{ + "benchmarking": [{ + "name": "<benchmark-program-name>", + "compile": { + "timeStarted": "<ISO-timestamp>", + "runs": <number-of-runs>, + "totalDuration": <total-duration-seconds>, + "mean": <mean-duration-seconds>, + "deviation": <standard-deviation-seconds>, + "min": <min-duration-seconds>, + "max": <max-duration-seconds>, + "memory": <memory-usage-bytes>, + "size": <proof-or-circuit-size-in-bytes> + }, + "prove": { <same-as-compile> }, + "verify": { <same-as-compile> } + }], + "hardware": { + "cpu": [{"model": "<cpu-model>", "cores": <cores-count>, "speed": <speed-GHz>}], + "memory": {"model": "<memory-model>", "size": <size-bytes>, "speed": <speed-MHz>}, + "hardwareAcceleration": [{"model": "<gpu-model>", "cores": <cores-count>, "speed": <speed-MHz>}], + "accelerated": false + } +} +``` + +In the static build of the web-site. The client will have a pre-populated cache with all benchmark +data available without making requests to the server. + +### Development Dependencies + +* Managed via Nix, provided as a Nix flake. + +### Hosting & Deployment + +* Hosted statically via Cloudflare. +* Consider exporting the complete site as static HTML files for performance. + +## Performance and Accessibility Goals + +* Extremely fast initial page loads (target ≤1s). +* Compliance with WCAG 2.1 AA standards. +* Compatible with all major desktop/mobile browsers. + +## Branding & Visual Design + +* Matches existing BlockSense Network branding (see `https://blocksense.network`). +* Domain: `zk-wars.blocksense.network`. + +## Scalability & Maintenance + +* Adding new hardware configurations or benchmarks is straightforward (structured JSON updates). +* Initially manageable dataset size; potential infinite scrolling if datasets grow significantly. + +--- + +# Detailed Page & Visual Design + +> **Branding Note** – All visual examples assume the BlockSense design language (see [https://blocksense.network](https://blocksense.network)). **Primary font is `Geist`** for all headings and body copy, backed by `sans-serif`. Example palette (confirm with latest brand assets): primary accent `#2F80ED`, secondary accent `#9747FF`, dark text `#1B1F23`, light text `#6B7280`, background `#F9FAFB`. + +## Shared Design Tokens + +| Token | Usage | Example | +| ------------ | --------------------- | ------------------------------------------ | +| Font family | Primary text | `Geist`, 1.2 rem base, 1.5 rem line‑height | +| Radius‑md | Card & button corners | `0.75 rem` | +| Elevation‑1 | Card shadow | `0 2px 6px rgba(0,0,0,.06)` | +| Spacing‑unit | Base grid | `0.5 rem` | + +All pages use a **12‑column fluid grid** (`max‑width: 1440px`) with generous whitespace. Cards always span full width on ≤ 768 px screens and collapse to an 8‑column grid on tablets. + +--- + +## 1. Landing / "Benchmarks Overview" Page + +**Purpose** – Entry point; lets users pick a predefined benchmark or jump to custom builder. + +### Layout + +1. **Hero bar** (full‑width, gradient accent): title *"Blocksense ZK Wars"*, subtitle "Your performance guide to the ZK world", CTA buttons: + + * "Browse Standard Benchmarks" → scrolls to benchmark list + * "Build Custom Comparison" → `/benchmarks/custom` +2. **Benchmark cards grid** – 8 predefined benchmarks in a `Card` component (image/emoji, title, short description). 3‑column desktop ▸ 1‑column mobile. A card named "More" that leads to `/benchmarks/` +3. **Featured Rankings** – horizontal bar chart comparing top 5 toolchains for the default hardware preset & an aggregated set of benchmarks; embedded in a card with dropdowns (metric & hardware). Two charts will be displayed (best on CPU and best on GPU). +4. **Footer** – links, GitHub repo badge, BlockSense branding. + +### Interactions + +* Benchmark card click → `/benchmarks/<slug>` +* Dropdown changes update chart via `replaceState`. + +### Visual Notes + +* Cards use Elevation‑1 shadow; on hover desk‑top card lifts (`translate‑y‑1`, shadow‑lg). Mobile: subtle scale‑in. + +--- + +## 2. Predefined Benchmark Detail Page `/benchmarks/<slug>` + +### Header + +* Breadcrumb: Home ▸ Benchmark ▸ *Merkle Proof Verification* +* Title; dropdowns for **hardware** + **metric** (proof‑gen / verify / both). + +### Main Section + +| Column | Content | +| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 8‑col (desktop) | **Performance Table** – toolchain in first column; proof times in second; cell background renders proportional bar (best = 100%). Third narrow column optional \:info: icon opens side drawer with raw JSON snippet for that row. | +| 4‑col (desktop) | **Benchmark Info Card** – text summary, primitive list & counts, link "Re‑mix in Builder". | + +### Expanded Row + +* Clicking a toolchain row accordion reveals a horizontal stacked bar (gen vs verify) + memory & proof size chips. + +### Mobile + +* Table transforms: each toolchain becomes a `Disclosure` card; metrics stack vertically; bars shrink to 100 % width of card. + +--- + +## 3. Custom Comparison Builder `/benchmarks/custom` + +### Builder Panel (left on desktop, top on mobile) + +* **Primitive Search** (command‑palette style): type to filter, ↵ to add. +* **Cart List** – each primitive row: name, qty stepper, subtotal metric preview badge. +* **Hardware & Metric dropdowns** at bottom. +* Sticky "Update Results" button triggers recalculation & URL `replaceState`. + +### Results Panel (right on desktop, below on mobile) + +* Aggregated result card: big number for total proof time; stacked bar showing breakdown (hover/tap segments → tooltip with % and ms). +* Full results table identical to Benchmark Detail. + +### UX Notes + +* Builder uses slide‑in side sheet on ≤ 1024 px to maximise space. + +--- + +## 4. Toolchain Detail Page `/toolchains/<name>` + +### Header + +* Avatar/logo, repository link, commit SHA, hardware dropdown. + +### Body + +1. **Benchmark List Table** – each benchmark row: benchmark icon, metric bar cell, comparison badge "+12 % vs best". +2. **Filter chip bar** – filter by primitive category (hashing, signatures …). + +### Expansion + +* Row expand shows line chart of performance vs input size (if data). Chart built with Recharts; accessible via keyboard. + +--- + +## 5. Hardware Detail Page `/hardware/<preset>` + +### Masthead Card + +* Hardware name, specs grid (CPU, RAM, optional GPU). Button "Compare with…" → opens modal to pick second preset (`pushState`). + +### Aggregated Rankings Section + +* Horizontal bar ranking of toolchain totals across all benchmarks. + +### Benchmark Tabs + +* Tab list of benchmark categories; contents: same table pattern. + +--- + +## 6. Hardware Comparison Page `/hardware/<a>/vs/<b>` + +### Split‑view Layout + +* Sticky header showing A vs B specs side‑by‑side. +* **Comparison Table**: rows = benchmark categories; two metric cells with background bars; difference column coloured subtle gray. Expandable accordions show per‑benchmark table (bars again) identical to row pattern. Multiple sections can be expanded concurrently. + +--- + +## 7. Global Components + +* **Warning Icon** (invalid URL param): outline ⚠ icon next to dropdown; tooltip reveals issue. +* **Share Button**: Icon button copies current canonical URL; toast “Link copied!”. +* **Loading Skeletons**: shimmer rectangles mimic bar charts & table cells. + +--- + +# Implementation Checklist (Visual) + +* [ ] Design tokens defined in Tailwind config. +* [ ] Components scaffolded with shadcn/ui. +* [ ] Charts implemented with Recharts + accessible labels. +* [ ] Mobile breakpoints tested ≤ 360 px wide. +* [ ] Colour contrast verified (WCAG 2.1 AA). + +--- + +*End of visual design section.* |