feat: honest live WebSocket updates and broader realtime sync

.env.example

@@ -19,7 +19,8 @@ WEBSOCKET_ENABLED=true
 # Networks the realtime monitor polls (comma-separated: mainnet,testnet).
 # Only list networks you actually run a node for.
 WEBSOCKET_NETWORKS=mainnet
-BLOCKCHAIN_POLL_INTERVAL=10000
+# Block + mempool poll interval (ms). Default 4000.
+BLOCKCHAIN_POLL_INTERVAL=4000
 WEBSOCKET_HEARTBEAT_INTERVAL=30000
 WEBSOCKET_MAX_CONNECTIONS_PER_IP=5
 WEBSOCKET_MAX_PAYLOAD_BYTES=65536

README.md

@@ -2,6 +2,10 @@
 
 Modern, responsive block explorer for **FairCoin**. Vite + React SPA frontend with an Express API server (run with Bun) that talks JSON-RPC to a FairCoin node and caches responses in MongoDB. Real-time updates are pushed over WebSocket.
 
+## Realtime model
+
+WebSocket (`WS /api/ws`) pushes **change notifications** (new blocks, mempool updates, network stats, transaction confirmations). Canonical blockchain data is always loaded over **HTTP** (`GET /api/*`) via React Query: the client invalidates (and optionally paints) caches on push, then refetches the full API shape. When the socket is down, live hooks fall back to a 30s HTTP poll. In local dev, Vite proxies `/api` with `ws: true` so the browser can upgrade `/api/ws` to the API server.
+
 ## Stack
 
 - **Frontend**: Vite, React 18, TypeScript, TanStack Query, Tailwind CSS 4, shadcn/Radix UI, react-router
@@ -62,7 +66,7 @@ MONGODB_URI=mongodb://localhost:27017/faircoin-explorer
 # WebSocket / realtime monitor
 WEBSOCKET_ENABLED=true
 WEBSOCKET_NETWORKS=mainnet          # comma-separated; add testnet if you run a testnet node
-BLOCKCHAIN_POLL_INTERVAL=10000
+BLOCKCHAIN_POLL_INTERVAL=4000       # block/mempool poll (ms); default 4s
 WEBSOCKET_HEARTBEAT_INTERVAL=30000
 WEBSOCKET_MAX_CONNECTIONS_PER_IP=5
 WEBSOCKET_MAX_PAYLOAD_BYTES=65536
@@ -88,7 +92,7 @@ The Express server exposes a read-only JSON API under `/api`:
 - `GET /api/validate-address?address=`, `/api/fee-estimate`
 - `GET /api/price`, `/api/price/history`, `/api/stats/history`
 - `GET /api/bridge/reserves` (proxied WFAIR bridge reserves)
-- `WS /api/ws` (new blocks, mempool updates, network stats)
+- `WS /api/ws` — push of chain changes (`new-block`, `block-count`, `mempool-update` with top-N txs, `transaction-confirmed`, `network-stats`). Canonical data still comes from HTTP `/api/*`; the socket tells the client when to refetch.
 
 ## MCP server (for AI assistants)
 
@@ -149,5 +153,6 @@ Only key generation is done in-process (using the audited `@noble/curves` secp25
 
 ## Notes
 
+- Realtime model: the server polls the FairCoin RPC (default every 4s) and pushes change events on `WS /api/ws`. Clients should treat HTTP `/api/*` as the source of truth and use the socket to invalidate/refetch.
 - Address balances/history require a FairCoin node with `addressindex=1`; without it the explorer degrades gracefully to validation-only data.
-- The MongoDB cache populates on demand; `npm run sync-db` (full historical sync) is optional.
+- The MongoDB cache populates on demand; `bun run sync-db` (full historical sync) is optional.