Skip to content

Commit 9bc76a4

Browse files
intelliDeanintelliDean
committed
feat(sdk): add FlashStat TypeScript SDKs, examples, and tests
1 parent fcce60c commit 9bc76a4

31 files changed

Lines changed: 4347 additions & 1 deletion

‎.gitignore‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,4 +9,7 @@ flashstat.toml
99
.github
1010

1111
simple.md
12-
PROPOSAL.md
12+
PROPOSAL.md
13+
sdks/typescript/node_modules
14+
sdks/typescript/packages/*/dist
15+
sdks/typescript/packages/*/node_modules

‎README.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,10 @@ The system combines cryptographic TEE (Intel TDX) attestation verification with
1212

1313
## Table of Contents
1414

15+
- [TypeScript SDK](#typescript-sdk)
16+
- [@flashstat/core](#flashstatcore)
17+
- [@flashstat/viem](#flashstatviem)
18+
- [@flashstat/react](#flashstatreact)
1519
- [Features](#features)
1620
- [Architecture](#architecture)
1721
- [Workspace Layout](#workspace-layout)
@@ -62,6 +66,135 @@ The system combines cryptographic TEE (Intel TDX) attestation verification with
6266

6367
---
6468

69+
## TypeScript SDK
70+
71+
FlashStat ships three TypeScript packages for integrating real-time block confidence into any JavaScript application. All packages are located in `sdks/typescript/`.
72+
73+
| Package | Install | For |
74+
|---|---|---|
75+
| `@flashstat/core` | Zero dependencies | Any Node.js / browser app |
76+
| `@flashstat/viem` | Peer: `viem >=2` | OP-Stack / Unichain builders |
77+
| `@flashstat/react` | Peer: `react >=18` | dApp frontends |
78+
79+
### @flashstat/core
80+
81+
The standalone HTTP + WebSocket client. No external dependencies.
82+
83+
```typescript
84+
import { FlashStatClient } from '@flashstat/core';
85+
86+
const client = new FlashStatClient({ url: 'http://127.0.0.1:9944' });
87+
88+
// Query confidence for a specific block hash
89+
const confidence = await client.getConfidence('0xabc...');
90+
if (confidence > 95) {
91+
console.log('✓ Safe to act — high-confidence Flashblock');
92+
}
93+
94+
// Subscribe to live blocks
95+
const unsub = client.subscribeBlocks((block) => {
96+
console.log(`Block #${block.number} — ${block.confidence.toFixed(1)}% (${block.status})`);
97+
});
98+
99+
// Subscribe to reorg / equivocation events
100+
client.subscribeEvents((event) => {
101+
if (event.severity === 'Equivocation') {
102+
console.error('🚨 Sequencer equivocation at block', event.blockNumber);
103+
}
104+
});
105+
106+
// Clean up
107+
unsub();
108+
client.destroy();
109+
```
110+
111+
### @flashstat/viem
112+
113+
Extends any Viem `PublicClient` with FlashStat actions — one line of setup.
114+
115+
```typescript
116+
import { createPublicClient, http } from 'viem';
117+
import { unichain } from 'viem/chains';
118+
import { flashStatActions } from '@flashstat/viem';
119+
120+
const client = createPublicClient({
121+
chain: unichain,
122+
transport: http(),
123+
}).extend(flashStatActions({ url: 'http://127.0.0.1:9944' }));
124+
125+
// All standard Viem methods still work, plus:
126+
const confidence = await client.getFlashConfidence('0xabc...');
127+
const latest = await client.getLatestFlashBlock();
128+
const reorgs = await client.getFlashRecentReorgs(10);
129+
const rankings = await client.getFlashSequencerRankings();
130+
```
131+
132+
### @flashstat/react
133+
134+
React hooks and a context provider for live UI updates.
135+
136+
```tsx
137+
import { FlashStatProvider, useFlashConfidence, useReorgEvents } from '@flashstat/react';
138+
139+
// 1. Wrap your app once
140+
function App() {
141+
return (
142+
<FlashStatProvider url="http://127.0.0.1:9944">
143+
<YourApp />
144+
</FlashStatProvider>
145+
);
146+
}
147+
148+
// 2. Use hooks anywhere in the tree
149+
function TransactionStatus({ hash }: { hash: string }) {
150+
const { confidence, status, isLoading } = useFlashConfidence(hash);
151+
152+
if (isLoading) return <Spinner />;
153+
154+
return (
155+
<div>
156+
<p>Status: {status}</p>
157+
<p>Confidence: {confidence.toFixed(1)}%</p>
158+
{confidence > 95 && <p>✅ Safe to proceed</p>}
159+
</div>
160+
);
161+
}
162+
163+
// 3. Alert users to reorg events in real time
164+
function ReorgAlert() {
165+
const { events } = useReorgEvents(5);
166+
const equivocations = events.filter(e => e.severity === 'Equivocation');
167+
168+
if (equivocations.length === 0) return null;
169+
return <Banner>🚨 Sequencer equivocation detected!</Banner>;
170+
}
171+
```
172+
173+
**Available hooks:**
174+
175+
| Hook | Description |
176+
|---|---|
177+
| `useFlashConfidence(hash)` | Live-updating confidence score for a block hash |
178+
| `useLatestFlashBlock()` | Most recent block, updated via WebSocket |
179+
| `useReorgEvents(limit?)` | Recent reorg/equivocation events, live-updated |
180+
| `useSequencerRankings(pollMs?)` | Reputation leaderboard, polled on an interval |
181+
| `useFlashHealth(pollMs?)` | Node health snapshot |
182+
183+
#### Running the Next.js Example
184+
185+
```bash
186+
# Terminal 1 — start the Rust server
187+
cargo run --release --bin flashstat-server
188+
189+
# Terminal 2 — start the dashboard
190+
cd sdks/typescript/examples/nextjs-dashboard
191+
npm install && npm run dev
192+
193+
# Open http://localhost:3000
194+
```
195+
196+
---
197+
65198
## Architecture
66199

67200
```

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

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# FlashStat Next.js Dashboard Example
2+
3+
A minimal Next.js 14 app (App Router) that uses `@flashstat/react` to display
4+
a live FlashStat dashboard directly in the browser.
5+
6+
## What it shows
7+
8+
- **Live block feed** — every new Flashblock appears with its confidence score and status badge
9+
- **Reorg alert banner** — flashes red when an equivocation or reorg is detected
10+
- **Sequencer leaderboard** — auto-refreshes every 10 seconds
11+
- **System health** — uptime, total blocks, reorg count
12+
13+
## Running
14+
15+
```bash
16+
# 1. Start the Rust server first
17+
cargo run --release --bin flashstat-server
18+
19+
# 2. In another terminal, run the Next.js app
20+
cd sdks/typescript/examples/nextjs-dashboard
21+
npm install
22+
npm run dev
23+
```
24+
25+
Open http://localhost:3000
26+
27+
## Environment variables
28+
29+
| Variable | Default | Description |
30+
|---|---|---|
31+
| `NEXT_PUBLIC_FLASHSTAT_URL` | `http://127.0.0.1:9944` | FlashStat server URL |
32+
33+
Set it in `.env.local` for production deployments.

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
/** @type {import('next').NextConfig} */
2+
const nextConfig = {};
3+
4+
export default nextConfig;

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

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
{
2+
"name": "flashstat-nextjs-dashboard",
3+
"private": true,
4+
"version": "0.1.0",
5+
"scripts": {
6+
"dev": "next dev",
7+
"build": "next build",
8+
"start": "next start"
9+
},
10+
"dependencies": {
11+
"@flashstat/core": "workspace:*",
12+
"@flashstat/react": "workspace:*",
13+
"next": "14.2.3",
14+
"react": "^18.3.0",
15+
"react-dom": "^18.3.0"
16+
},
17+
"devDependencies": {
18+
"@types/node": "^20",
19+
"@types/react": "^18",
20+
"@types/react-dom": "^18",
21+
"typescript": "^5.4.5"
22+
}
23+
}

0 commit comments

Comments
 (0)