updating the SDK

.gitignore

@@ -9,4 +9,7 @@ flashstat.toml
 .github
 
 simple.md
-PROPOSAL.md
+PROPOSAL.md
+sdks/typescript/node_modules
+sdks/typescript/packages/*/dist
+sdks/typescript/packages/*/node_modules

README.md

@@ -12,6 +12,10 @@ The system combines cryptographic TEE (Intel TDX) attestation verification with
 
 ## Table of Contents
 
+- [TypeScript SDK](#typescript-sdk)
+  - [@flashstat/core](#flashstatcore)
+  - [@flashstat/viem](#flashstatviem)
+  - [@flashstat/react](#flashstatreact)
 - [Features](#features)
 - [Architecture](#architecture)
 - [Workspace Layout](#workspace-layout)
@@ -62,6 +66,135 @@ The system combines cryptographic TEE (Intel TDX) attestation verification with
 
 ---
 
+## TypeScript SDK
+
+FlashStat ships three TypeScript packages for integrating real-time block confidence into any JavaScript application. All packages are located in `sdks/typescript/`.
+
+| Package | Install | For |
+|---|---|---|
+| `@flashstat/core` | Zero dependencies | Any Node.js / browser app |
+| `@flashstat/viem` | Peer: `viem >=2` | OP-Stack / Unichain builders |
+| `@flashstat/react` | Peer: `react >=18` | dApp frontends |
+
+### @flashstat/core
+
+The standalone HTTP + WebSocket client. No external dependencies.
+
+```typescript
+import { FlashStatClient } from '@flashstat/core';
+
+const client = new FlashStatClient({ url: 'http://127.0.0.1:9944' });
+
+// Query confidence for a specific block hash
+const confidence = await client.getConfidence('0xabc...');
+if (confidence > 95) {
+  console.log('✓ Safe to act — high-confidence Flashblock');
+}
+
+// Subscribe to live blocks
+const unsub = client.subscribeBlocks((block) => {
+  console.log(`Block #${block.number} — ${block.confidence.toFixed(1)}% (${block.status})`);
+});
+
+// Subscribe to reorg / equivocation events
+client.subscribeEvents((event) => {
+  if (event.severity === 'Equivocation') {
+    console.error('🚨 Sequencer equivocation at block', event.blockNumber);
+  }
+});
+
+// Clean up
+unsub();
+client.destroy();
+```
+
+### @flashstat/viem
+
+Extends any Viem `PublicClient` with FlashStat actions — one line of setup.
+
+```typescript
+import { createPublicClient, http } from 'viem';
+import { unichain } from 'viem/chains';
+import { flashStatActions } from '@flashstat/viem';
+
+const client = createPublicClient({
+  chain: unichain,
+  transport: http(),
+}).extend(flashStatActions({ url: 'http://127.0.0.1:9944' }));
+
+// All standard Viem methods still work, plus:
+const confidence  = await client.getFlashConfidence('0xabc...');
+const latest      = await client.getLatestFlashBlock();
+const reorgs      = await client.getFlashRecentReorgs(10);
+const rankings    = await client.getFlashSequencerRankings();
+```
+
+### @flashstat/react
+
+React hooks and a context provider for live UI updates.
+
+```tsx
+import { FlashStatProvider, useFlashConfidence, useReorgEvents } from '@flashstat/react';
+
+// 1. Wrap your app once
+function App() {
+  return (
+    <FlashStatProvider url="http://127.0.0.1:9944">
+      <YourApp />
+    </FlashStatProvider>
+  );
+}
+
+// 2. Use hooks anywhere in the tree
+function TransactionStatus({ hash }: { hash: string }) {
+  const { confidence, status, isLoading } = useFlashConfidence(hash);
+
+  if (isLoading) return <Spinner />;
+
+  return (
+    <div>
+      <p>Status: {status}</p>
+      <p>Confidence: {confidence.toFixed(1)}%</p>
+      {confidence > 95 && <p>✅ Safe to proceed</p>}
+    </div>
+  );
+}
+
+// 3. Alert users to reorg events in real time
+function ReorgAlert() {
+  const { events } = useReorgEvents(5);
+  const equivocations = events.filter(e => e.severity === 'Equivocation');
+
+  if (equivocations.length === 0) return null;
+  return <Banner>🚨 Sequencer equivocation detected!</Banner>;
+}
+```
+
+**Available hooks:**
+
+| Hook | Description |
+|---|---|
+| `useFlashConfidence(hash)` | Live-updating confidence score for a block hash |
+| `useLatestFlashBlock()` | Most recent block, updated via WebSocket |
+| `useReorgEvents(limit?)` | Recent reorg/equivocation events, live-updated |
+| `useSequencerRankings(pollMs?)` | Reputation leaderboard, polled on an interval |
+| `useFlashHealth(pollMs?)` | Node health snapshot |
+
+#### Running the Next.js Example
+
+```bash
+# Terminal 1 — start the Rust server
+cargo run --release --bin flashstat-server
+
+# Terminal 2 — start the dashboard
+cd sdks/typescript/examples/nextjs-dashboard
+npm install && npm run dev
+
+# Open http://localhost:3000
+```
+
+---
+
 ## Architecture
 
 ```

sdks/typescript/examples/nextjs-dashboard/README.md

@@ -0,0 +1,33 @@
+# FlashStat Next.js Dashboard Example
+
+A minimal Next.js 14 app (App Router) that uses `@flashstat/react` to display
+a live FlashStat dashboard directly in the browser.
+
+## What it shows
+
+- **Live block feed** — every new Flashblock appears with its confidence score and status badge
+- **Reorg alert banner** — flashes red when an equivocation or reorg is detected
+- **Sequencer leaderboard** — auto-refreshes every 10 seconds
+- **System health** — uptime, total blocks, reorg count
+
+## Running
+
+```bash
+# 1. Start the Rust server first
+cargo run --release --bin flashstat-server
+
+# 2. In another terminal, run the Next.js app
+cd sdks/typescript/examples/nextjs-dashboard
+npm install
+npm run dev
+```
+
+Open http://localhost:3000
+
+## Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `NEXT_PUBLIC_FLASHSTAT_URL` | `http://127.0.0.1:9944` | FlashStat server URL |
+
+Set it in `.env.local` for production deployments.

sdks/typescript/examples/nextjs-dashboard/next.config.mjs

@@ -0,0 +1,4 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {};
+
+export default nextConfig;

sdks/typescript/examples/nextjs-dashboard/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "flashstat-nextjs-dashboard",
+  "private": true,
+  "version": "0.1.0",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start"
+  },
+  "dependencies": {
+    "@flashstat/core": "workspace:*",
+    "@flashstat/react": "workspace:*",
+    "next": "14.2.3",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "@types/react": "^18",
+    "@types/react-dom": "^18",
+    "typescript": "^5.4.5"
+  }
+}