aitbc/docs/reference/bootstrap/explorer_web.md

# explorer-web.md
Chain Explorer (blocks · tx · receipts)

## 0) Purpose
A lightweight, fast, dark-themed web UI to browse a minimal AITBC blockchain:
- Latest blocks & block detail
- Transaction list & detail
- Address detail (balance, nonce, tx history)
- Receipt / logs view
- Simple search (block #, hash, tx hash, address)

MVP reads from **blockchain-node** (HTTP/WS API).
No write operations.

---

## 1) Tech & Conventions
- **Pure frontend** (no backend rendering): static HTML + JS modules + CSS.
- **No frameworks** (keep it portable and fast).
- **Files split**: HTML, CSS, JS in separate files (user preference).
- **ES Modules** with strict typing via JSDoc or TypeScript (optional).
- **Dark theme** with orange/ice accents (brand).
- **No animations** unless explicitly requested.
- **Time format**: UTC ISO + relative (e.g., “2m ago”).

---

## 2) Folder Layout (within workspace)
```
explorer-web/
├─ public/
│  ├─ index.html            # routes: / (latest blocks)
│  ├─ block.html            # /block?hash=... or /block?number=...
│  ├─ tx.html               # /tx?hash=...
│  ├─ address.html          # /address?addr=...
│  ├─ receipts.html         # /receipts?tx=...
│  ├─ 404.html
│  ├─ assets/
│  │  ├─ logo.svg
│  │  └─ icons/*.svg
│  ├─ css/
│  │  ├─ base.css
│  │  ├─ layout.css
│  │  └─ theme-dark.css
│  └─ js/
│     ├─ config.js          # API endpoint(s)
│     ├─ api.js             # fetch helpers
│     ├─ store.js           # simple state cache
│     ├─ utils.js           # formatters (hex, time, numbers)
│     ├─ components/
│     │  ├─ header.js
│     │  ├─ footer.js
│     │  ├─ searchbox.js
│     │  ├─ block-table.js
│     │  ├─ tx-table.js
│     │  ├─ pager.js
│     │  └─ keyvalue.js
│     ├─ pages/
│     │  ├─ home.js         # latest blocks + mempool/heads
│     │  ├─ block.js
│     │  ├─ tx.js
│     │  ├─ address.js
│     │  └─ receipts.js
│     └─ vendors/           # (empty; we keep it native for now)
├─ docs/
│  └─ explorer-web.md       # this file
└─ README.md
```

---

## 3) API Contracts (read-only)
Assume **blockchain-node** exposes:

### 3.1 REST (HTTP)
- `GET /api/chain/head` → `{ number, hash, timestamp }`
- `GET /api/blocks?limit=25&before=<blockNumber>` → `[{number,hash,parentHash,timestamp,txCount,miner,size,gasUsed}]`
- `GET /api/block/by-number/:n` → `{ ...fullBlock }`
- `GET /api/block/by-hash/:h` → `{ ...fullBlock }`
- `GET /api/tx/:hash` → `{ hash, from, to, nonce, value, fee, gas, gasPrice, blockHash, blockNumber, timestamp, input }`
- `GET /api/address/:addr` → `{ address, balance, nonce, txCount }`
- `GET /api/address/:addr/tx?limit=25&before=<blockNumber>` → `[{hash,blockNumber,from,to,value,fee,timestamp}]`
- `GET /api/tx/:hash/receipt` → `{ status, gasUsed, logs: [{address, topics:[...], data, index}], cumulativeGasUsed }`
- `GET /api/search?q=...`
  - Accepts block number, block hash, tx hash, or address
  - Returns a typed result: `{ type: "block"|"tx"|"address" , key: ... }`

### 3.2 WebSocket (optional, later)
- `ws://.../api/stream/heads` → emits new head `{number,hash,timestamp}`
- `ws://.../api/stream/mempool` → emits tx previews `{hash, from, to, value, timestamp}`

> If the node isn’t ready, create a tiny mock server (FastAPI) consistent with these shapes (already planned in other modules).

---

## 4) Pages & UX

### 4.1 Header (every page)
- Left: logo + “AITBC Explorer”
- Center: search box (accepts block#, block/tx hash, address)
- Right: network tag (e.g., “Local Dev”) + head block# (live)

### 4.2 Home `/`
- **Latest Blocks** (table)
  - columns: `#`, `Hash (short)`, `Tx`, `Miner`, `GasUsed`, `Time`
  - infinite scroll / “Load older”
- (optional) **Mempool feed** (compact list, toggleable)
- Empty state: helpful instructions + sample query strings

### 4.3 Block Detail `/block?...`
- Top summary (KeyValue component)
  - `Number, Hash, Parent, Miner, Timestamp, Size, GasUsed, Difficulty?`
- Transactions table (paginated)
- “Navigate”: Parent ↖, Next ↗, View in raw JSON (debug)

### 4.4 Tx Detail `/tx?hash=...`
- Summary: `Hash, Status, Block, From, To, Value, Fee, Nonce, Gas(gasPrice)`
- Receipt section (logs rendered as topics/data, collapsible)
- Input data: hex preview + decode attempt (if ABI registry exists – later)

### 4.5 Address `/address?addr=...`
- Summary: `Address, Balance, Nonce, TxCount`
- Transactions list (sent/received filter)
- (later) Token balances when chain supports it

### 4.6 Receipts `/receipts?tx=...`
- Focused receipts + logs view with copy buttons

### 4.7 404
- Friendly message + search

---

## 5) Components (JS modules)
- `header.js` : builds header + binds search submit.
- `searchbox.js` : debounced input, detects type (see utils).
- `block-table.js` : render rows, short-hash, time-ago.
- `tx-table.js` : similar render with direction arrows.
- `pager.js` : simple “Load more” with event callback.
- `keyvalue.js` : `<dl>` key/value grid for details.
- `footer.js` : version, links.

---

## 6) Utils
- `formatHexShort(hex, bytes=4)` → `0x1234…abcd`
- `formatNumber(n)` with thin-space groupings
- `formatValueWei(wei)` → AIT units when available (or plain wei)
- `timeAgo(ts)` + `formatUTC(ts)`
- `parseQuery()` helpers for `?hash=...`
- `detectSearchType(q)`:
  - `0x` + 66 chars → tx/block hash
  - numeric → block number
  - `0x` + 42 → address
  - fallback → “unknown”

---

## 7) State (store.js)
- `state.head` (number/hash/timestamp)
- `state.cache.blocks[number] = block`
- `state.cache.txs[hash] = tx`
- `state.cache.address[addr] = {balance, nonce, txCount}`
- Simple in-memory LRU eviction (optional).

---

## 8) Styling
- `base.css`: resets, typography, links, buttons, tables.
- `layout.css`: header/footer, grid, content widths (max 960px desktop).
- `theme-dark.css`: colors:
  - bg: `#0b0f14`, surface: `#11161c`
  - text: `#e6eef7`
  - accent-orange: `#ff8a00`
  - accent-ice: `#a8d8ff`
- Focus states visible. High contrast table rows on hover.

---

## 9) Error & Loading UX
- Loading spinners (minimal).
- Network errors: inline banner with retry.
- Empty: clear messages & how to search.

---

## 10) Security & Hardening
- Treat inputs as untrusted.
- Only GETs; block any attempt to POST.
- Strict `Content-Security-Policy` sample (for hosting):
  - `default-src 'self'; img-src 'self' data:; style-src 'self'; script-src 'self'; connect-src 'self' https://blockchain-node.local;`
- Avoid third-party CDNs.

---

## 11) Test Plan (manual first)
1. Home loads head + 25 latest blocks.
2. Scroll/pager loads older batches.
3. Block search by number + by hash.
4. Tx search → detail + receipt.
5. Address search → tx list.
6. Error states when node is offline.
7. Timezones: display UTC consistently.

---

## 12) Dev Tasks (Windsurf order of work)
1. **Scaffold** folders & empty files.
2. Implement `config.js` with `API_BASE`.
3. Implement `api.js` (fetch JSON + error handling).
4. Build `utils.js` (formatters + search detect).
5. Build `header.js` + `footer.js`.
6. Home page: blocks list + pager.
7. Block detail page.
8. Tx detail + receipts.
9. Address page with tx list.
10. 404 + polish (copy buttons, tiny helpers).
11. CSS pass (dark theme).
12. Final QA.

---

## 13) Mock Data (for offline dev)
Place under `public/js/vendors/mock.js` (opt-in):
- Export functions that resolve Promises with static JSON fixtures in `public/mock/*.json`.
- Toggle via `config.js` flag `USE_MOCK=true`.

---

## 14) Minimal HTML Skeleton (example: index.html)
```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width,initial-scale=1" />
    <title>AITBC Explorer</title>
    <link rel="stylesheet" href="./css/base.css" />
    <link rel="stylesheet" href="./css/layout.css" />
    <link rel="stylesheet" href="./css/theme-dark.css" />
  </head>
  <body>
    <header id="app-header"></header>
    <main id="app"></main>
    <footer id="app-footer"></footer>
    <script type="module">
      import { renderHeader } from './js/components/header.js';
      import { renderFooter } from './js/components/footer.js';
      import { renderHome }   from './js/pages/home.js';
      renderHeader(document.getElementById('app-header'));
      renderFooter(document.getElementById('app-footer'));
      renderHome(document.getElementById('app'));
    </script>
  </body>
</html>
```

---

## 15) config.js (example)
```js
export const CONFIG = {
  API_BASE: 'http://localhost:8545', // adapt to blockchain-node
  USE_MOCK: false,
  PAGE_SIZE: 25,
  NETWORK_NAME: 'Local Dev',
};
```

---

## 16) API Helpers (api.js — sketch)
```js
import { CONFIG } from './config.js';

async function jget(path) {
  const res = await fetch(`${CONFIG.API_BASE}${path}`, { method: 'GET' });
  if (!res.ok) throw new Error(`HTTP ${res.status}: ${path}`);
  return res.json();
}

export const api = {
  head:      () => jget('/api/chain/head'),
  blocks:    (limit, before) => jget(`/api/blocks?limit=${limit}&before=${before ?? ''}`),
  blockByNo: (n) => jget(`/api/block/by-number/${n}`),
  blockByHash: (h) => jget(`/api/block/by-hash/${h}`),
  tx:        (hash) => jget(`/api/tx/${hash}`),
  receipt:   (hash) => jget(`/api/tx/${hash}/receipt`),
  address:   (addr) => jget(`/api/address/${addr}`),
  addressTx: (addr, limit, before) => jget(`/api/address/${addr}/tx?limit=${limit}&before=${before ?? ''}`),
  search:    (q) => jget(`/api/search?q=${encodeURIComponent(q)}`),
};
```

---

## 17) Performance Checklist
- Use pagination/infinite scroll (no huge payloads).
- Cache recent blocks/tx in-memory (store.js).
- Avoid layout thrash: table builds via DocumentFragment.
- Defer non-critical fetches (e.g., mempool).
- Keep CSS small and critical.

---

## 18) Deployment
- Serve `public/` via Nginx under `/explorer/` or own domain.
- Set correct `connect-src` in CSP to point to blockchain-node.
- Ensure CORS on blockchain-node for the explorer origin (read-only).

---

## 19) Roadmap (post-MVP)
- Live head updates via WS.
- Mempool stream view.
- ABI registry + input decoding.
- Token balances (when chain supports).
- Export to CSV / JSON for tables.
- Theming switch (dark/light).

---