Skip to content

Commit 11fa679

Browse files
dimka90dimka90
authored
Merge pull request #1 from geanlabs/devnet-1
Devnet 1
2 parents e17392e + d7b42a1 commit 11fa679

20 files changed

Lines changed: 2823 additions & 1 deletion

File tree

‎.github/workflows/pages.yml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
name: Deploy LeanViz to GitHub Pages
2+
3+
on:
4+
push:
5+
branches:
6+
- devnet-1
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: read
11+
pages: write
12+
id-token: write
13+
14+
concurrency:
15+
group: pages
16+
cancel-in-progress: true
17+
18+
jobs:
19+
deploy:
20+
environment:
21+
name: github-pages
22+
url: ${{ steps.deployment.outputs.page_url }}
23+
runs-on: ubuntu-latest
24+
steps:
25+
- name: Checkout
26+
uses: actions/checkout@v4
27+
28+
- name: Setup Pages
29+
uses: actions/configure-pages@v5
30+
31+
- name: Upload artifact
32+
uses: actions/upload-pages-artifact@v3
33+
with:
34+
path: web
35+
36+
- name: Deploy
37+
id: deployment
38+
uses: actions/deploy-pages@v4

‎README.md‎

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,25 @@
1-
# leanviz
1+
# leanviz
2+
3+
LeanViz is a standalone, client-agnostic dashboard for Lean consensus networks.
4+
5+
## Run
6+
Serve the static files:
7+
`python3 -m http.server 7070 --directory web`
8+
9+
Open:
10+
`http://localhost:7070/index.html`
11+
12+
API check page:
13+
`http://localhost:7070/health.html`
14+
15+
## Configure
16+
Edit `web/config/config.json` or use query params:
17+
- `?beacon=http://localhost:5052`
18+
- `?metrics=http://localhost:9090`
19+
- `?mode=live`
20+
- `?ns=eth` (use `/eth/v1/...` instead of `/lean/v0/...`)
21+
22+
## Docs
23+
- `docs/api-contract.md`
24+
- `docs/runbook.md`
25+
- `docs/changes.md`

‎docs/api-contract.md‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
# LeanViz Monitoring API Contract (v0)
2+
3+
This document defines the minimum API surface required by the LeanViz dashboard.
4+
It is intentionally small and focused on monitoring data.
5+
6+
## Status
7+
- UI defaults to Lean-style paths (`/lean/v0/...`).
8+
- Clients may also serve `/eth/v1/...` as a compatibility alias during migration.
9+
10+
## Base URL
11+
All endpoints are relative to a base URL (configured in `web/config/config.json`).
12+
13+
## Endpoints (Required)
14+
1. `GET /lean/v0/beacon/genesis`
15+
2. `GET /lean/v0/beacon/headers/head`
16+
3. `GET /lean/v0/beacon/states/head/finality_checkpoints`
17+
4. `GET /lean/v0/beacon/states/head/validators`
18+
5. `GET /lean/v0/node/peers`
19+
6. `GET /lean/v0/node/syncing`
20+
7. `GET /lean/v0/events` (SSE)
21+
22+
Compatibility alias (optional):
23+
- `/eth/v1/...` with the same semantics
24+
25+
## Response Shape (Minimum Fields)
26+
The UI only depends on the following fields. Extra fields are ignored.
27+
28+
1. `/beacon/headers/head`
29+
- `data.root` or `root`
30+
- `data.header.message.slot` or `slot`
31+
- `data.header.message.proposer_index` or `proposer_index`
32+
33+
2. `/beacon/states/head/finality_checkpoints`
34+
- `data.current_justified.slot` or `current_justified_slot`
35+
- `data.current_justified.epoch` or `current_justified.epoch`
36+
- `data.current_justified.root` or `current_justified.root`
37+
- `data.finalized.slot` or `finalized_slot`
38+
- `data.finalized.epoch` or `finalized.epoch`
39+
- `data.finalized.root` or `finalized.root`
40+
41+
3. `/beacon/states/head/validators`
42+
- `data[]` array length determines validator count
43+
- `data[i].index` or `data[i].validator.index`
44+
- `data[i].status` or `data[i].validator.status`
45+
46+
4. `/node/peers`
47+
- `data[]` array length determines peer count
48+
49+
5. `/node/syncing`
50+
- `data.head_slot` (optional; used only for display)
51+
52+
## Example Responses
53+
1. `/beacon/headers/head`
54+
```json
55+
{
56+
"data": {
57+
"root": "0xabc123...",
58+
"header": {
59+
"message": {
60+
"slot": "107",
61+
"proposer_index": "22"
62+
}
63+
}
64+
}
65+
}
66+
```
67+
68+
2. `/beacon/states/head/finality_checkpoints`
69+
```json
70+
{
71+
"data": {
72+
"current_justified": {
73+
"epoch": "3",
74+
"slot": "96",
75+
"root": "0xdef456..."
76+
},
77+
"finalized": {
78+
"epoch": "3",
79+
"slot": "98",
80+
"root": "0x789abc..."
81+
}
82+
}
83+
}
84+
```
85+
86+
3. `/beacon/states/head/validators`
87+
```json
88+
{
89+
"data": [
90+
{ "index": "0", "status": "active_ongoing" },
91+
{ "index": "1", "status": "active_ongoing" }
92+
]
93+
}
94+
```
95+
96+
4. `/node/peers`
97+
```json
98+
{
99+
"data": [
100+
{ "peer_id": "16Uiu2H..." }
101+
]
102+
}
103+
```
104+
105+
5. `/node/syncing`
106+
```json
107+
{
108+
"data": {
109+
"head_slot": "107"
110+
}
111+
}
112+
```
113+
114+
## SSE Events
115+
Endpoint: `/events?topics=head,block,finalized_checkpoint,chain_reorg,attester_slashing,proposer_slashing`
116+
117+
The UI uses only:
118+
- `head` or `block` events
119+
- `slot`
120+
- `proposer_index` (optional)
121+
- `block` or `root`
122+
- `finalized_checkpoint` events
123+
- `slot` or `finalized_slot`
124+
- `epoch` (optional)
125+
- `block` or `root`
126+
- `chain_reorg` events
127+
- payload is not parsed
128+
- `attester_slashing` or `proposer_slashing` events
129+
- `validator_index` or `proposer_index` or `index`
130+
131+
## Example SSE Events
132+
```
133+
event: head
134+
data: {"slot":"107","proposer_index":"22","block":"0xabc123..."}
135+
136+
event: finalized_checkpoint
137+
data: {"slot":"98","epoch":"3","block":"0x789abc..."}
138+
```
139+
140+
## CORS
141+
The API must allow the dashboard origin.
142+
Recommended:
143+
- `Access-Control-Allow-Origin: *` (dev)
144+
- Restrict origin in production.
145+
146+
## Notes
147+
- The UI will run in "demo" mode if API calls fail.
148+
- Missing fields will degrade the display but should not crash the UI.

‎docs/changes.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Change Notes
2+
3+
This file tracks significant refactors and structural changes in the LeanViz codebase.
4+
5+
## 2026-03-11
6+
- Extracted dashboard into a standalone repo layout under `web/`.
7+
- Split monolithic HTML into `index.html`, `styles/main.css`, and JS modules.
8+
- Added runtime config support via `web/config/config.json` and query params.
9+
- Split JS into modules: `api/`, `render/`, `sim/`, `state`, `dom`, and `utils`.
10+
- Preserved visual design and animation behavior.
11+
- Default API namespace switched to `/lean/v0` with optional `/eth/v1` override.
12+
- Added `web/health.html` API check page.

‎docs/runbook.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# LeanViz Runbook
2+
3+
## Local Dev
4+
Serve the static files:
5+
`python3 -m http.server 7070 --directory web`
6+
7+
Open:
8+
`http://localhost:7070/index.html`
9+
10+
API check page:
11+
`http://localhost:7070/health.html`
12+
13+
## Configure API URLs
14+
Edit `web/config/config.json`:
15+
```
16+
{
17+
"beaconUrl": "http://localhost:5052",
18+
"metricsUrl": "http://localhost:9090",
19+
"mode": "demo",
20+
"apiNamespace": "lean"
21+
}
22+
```
23+
24+
Or use query params:
25+
- `?beacon=http://localhost:5052`
26+
- `?metrics=http://localhost:9090`
27+
- `?mode=live`
28+
- `?ns=eth` (use `/eth/v1/...` instead of `/lean/v0/...`)
29+
30+
## Troubleshooting
31+
- If UI shows no movement, check console errors.
32+
- If API is unreachable, UI falls back to demo mode.

‎web/config/config.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{
2+
"beaconUrl": "http://localhost:5052",
3+
"metricsUrl": "http://localhost:9090",
4+
"mode": "demo",
5+
"apiNamespace": "lean"
6+
}

0 commit comments

Comments
 (0)