oib/aitbc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Based on the repository's commit message style and the changes in the diff, here's an appropriate commit message:

Browse Source 
```
feat: add websocket tests, PoA metrics, marketplace endpoints, and enhanced observability

- Add comprehensive websocket tests for blocks and transactions streams including multi-subscriber and high-volume scenarios
- Extend PoA consensus with per-proposer block metrics and rotation tracking
- Add latest block interval gauge and RPC error spike alerting
- Enhance mock coordinator
This commit is contained in:
oib
2025-12-22 07:55:09 +01:00
parent fb60505cdf
commit d98b2c7772
70 changed files with 3472 additions and 246 deletions
Download Patch File Download Diff File Expand all files Collapse all files

143
apps/explorer-web/README.md
View File

@ -6,7 +6,6 @@ Static web explorer for the AITBC blockchain node, displaying blocks, transactio
## Development Setup
- Install dependencies:
```bash
npm install
```
@ -14,145 +13,33 @@ Static web explorer for the AITBC blockchain node, displaying blocks, transactio
```bash
npm run dev
```
- The explorer ships with mock data in `public/mock/` that powers the tables by default.
The dev server listens on `http://localhost:5173/` by default. Adjust via `--host`/`--port` flags in the `systemd` unit or `package.json` script.
### Data Mode Toggle
## Data Mode Toggle
- Configuration lives in `src/config.ts` and can be overridden with environment variables.
- Use `VITE_DATA_MODE` to choose between `mock` (default) and `live`.
- When switching to live data, set `VITE_COORDINATOR_API` to the coordinator base URL (e.g. `http://localhost:8000`).
- When switching to live data, set `VITE_COORDINATOR_API` to the coordinator base URL (e.g., `http://localhost:8000`).
- Example `.env` snippet:
```bash
VITE_DATA_MODE=live
VITE_COORDINATOR_API=https://coordinator.dev.internal
```
With live mode enabled, the SPA will request `/v1/<resource>` routes from the coordinator instead of the bundled mock JSON.
## Next Steps
## Feature Flags & Auth
- Build out responsive styling and navigation interactions.
- Extend the data layer to support coordinator authentication and pagination when live endpoints are ready.
- Document coordinator API assumptions once the backend contracts stabilize.
- Document any backend expectations (e.g., coordinator accepting bearer tokens) alongside the environment variables in deployment manifests.
## Coordinator API Contracts (Draft)
## End-to-End Tests
- **Blocks** (`GET /v1/blocks?limit=&offset=`)
- Expected payload:
```json
{
"items": [
{
"height": 12045,
"hash": "0x...",
"timestamp": "2025-09-27T01:58:12Z",
"tx_count": 8,
"proposer": "miner-alpha"
}
],
"next_offset": 12040
}
```
- TODO: confirm pagination fields and proposer metadata.
- Install browsers after `npm install` by running `npx playwright install`.
- Launch the dev server (or point `EXPLORER_BASE_URL` at an already running instance) and run:
```bash
npm run test:e2e
```
- Tests automatically persist live mode and stub coordinator responses to verify overview, blocks, and transactions views.
- **Transactions** (`GET /v1/transactions?limit=&offset=`)
- Expected payload:
```json
{
"items": [
{
"hash": "0x...",
"block": 12045,
"from": "0x...",
"to": "0x...",
"value": "12.5",
"status": "Succeeded"
}
],
"next_offset": "0x..."
}
```
- TODO: finalize value units (AIT vs wei) and status enum.
## Playwright
- **Addresses** (`GET /v1/addresses/{address}`)
- Expected payload:
```json
{
"address": "0x...",
"balance": "1450.25",
"tx_count": 42,
"last_active": "2025-09-27T01:48:00Z",
"recent_transactions": ["0x..."]
}
```
- TODO: detail pagination for recent transactions and add receipt summary references.
- **Receipts** (`GET /v1/jobs/{job_id}/receipts`)
- Expected payload:
```json
{
"job_id": "job-0001",
"items": [
{
"receipt_id": "rcpt-123",
"miner": "miner-alpha",
"coordinator": "coordinator-001",
"issued_at": "2025-09-27T01:52:22Z",
"status": "Attested",
"payload": {
"miner_signature": "0x...",
"coordinator_signature": "0x..."
}
}
]
}
```
- TODO: confirm signature payload structure and include attestation metadata.
## Styling Guide
- **`public/css/base.css`**
- Defines global typography, color scheme, and utility classes (tables, placeholders, code tags).
- Use this file for cross-page primitives and reset/normalization rules.
- When adding new utilities (e.g., badges, alerts), document them in this section and keep naming consistent with the existing BEM-lite approach.
- **`public/css/layout.css`**
- Contains structural styles for the Explorer shell (header, footer, cards, forms, grids).
- Encapsulate component-specific classes with a predictable prefix, such as `.blocks__table`, `.addresses__input-group`, or `.receipts__controls`.
- Prefer utility classes from `base.css` when possible, and only introduce new layout classes when a component requires dedicated styling.
- **Adding New Components**
- Create semantic markup first in `src/pages/` or `src/components/`, using descriptive class names that map to the page or component (`.transactions__filter`, `.overview__chart`).
- Extend `layout.css` with matching selectors to style the new elements; keep related rules grouped together for readability.
- For reusable widgets across multiple pages, consider extracting shared styles into a dedicated section or introducing a new partial CSS file when the component becomes complex.
## Deployment Notes
- **Environment Variables**
- `VITE_DATA_MODE`: `mock` (default) or `live`.
- `VITE_COORDINATOR_API`: Base URL for coordinator API when `live` mode is enabled.
- Additional Vite variables can be added following the `VITE_*` naming convention.
- **Mock vs Live**
- In non-production environments, keep `VITE_DATA_MODE=mock` to serve the static JSON under `public/mock/` for quick demos.
- For staging/production deployments, set `VITE_DATA_MODE=live` and ensure the coordinator endpoint is reachable from the frontend origin; configure CORS accordingly on the backend.
- Consider serving mock JSON from a CDN or static bucket if you want deterministic demos while backend dependencies are under development.
- **Build & Deploy**
- Build command: `npm run build` (outputs to `dist/`).
- Preview locally with `npm run preview` before publishing.
- Deploy the `dist/` contents to your static host (e.g., Nginx, S3 + CloudFront, Vercel). Ensure environment variables are injected at build time or through runtime configuration mechanisms supported by your hosting provider.
## Error Handling (Live Mode)
- **Status Codes**
- `2xx`: Treat as success; map response bodies into the typed models in `src/lib/models.ts`.
- `4xx`: Surface actionable messages to the user (e.g., invalid job ID). For `404`, show “not found” states in the relevant page. For `429`, display a rate-limit notice and back off.
- `5xx`: Show a generic coordinator outage message and trigger retry logic.
- **Retry Strategy**
- Use an exponential backoff with jitter when retrying `5xx` or network failures (suggested base delay 500 ms, max 5 attempts).
- Do not retry on `4xx` except `429`; instead, display feedback.
- **Telemetry & Logging**
- Consider emitting console warnings or hooking into an analytics layer when retries occur, noting the endpoint and status code.
- Bubble critical errors via a shared notification component so users understand whether data is stale or unavailable.
- Run `npm run test:e2e` to execute the end-to-end tests.
- The tests will automatically persist live mode and stub coordinator responses to verify overview, blocks, and transactions views.