s0racle-sdk 0.0.1

package/README.md

@@ -0,0 +1,139 @@
+# s0racle-sdk
+
+<p align="center">
+  <img src="https://avatars.githubusercontent.com/u/288873784?s=200&v=4" alt="s0racle" width="120" />
+</p>
+
+<p align="center">
+  TypeScript SDK for reading live Solana network health from the s0racle oracle.
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License" />
+  <img src="https://img.shields.io/badge/Solana-devnet-9945FF?logo=solana" alt="Solana devnet" />
+  <img src="https://img.shields.io/badge/npm-0.1.0-CB3837?logo=npm" alt="npm 0.1.0" />
+  <img src="https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript" alt="TypeScript" />
+</p>
+
+---
+
+## Overview
+
+s0racle publishes live Solana network health on-chain — validator reachability, slot latency, client diversity, and stake-weighted reach — aggregated from distributed observer nodes across multiple regions.
+
+This SDK gives you a clean TypeScript interface to read that data. One function call, typed response, no Anchor boilerplate, no manual PDA derivation.
+
+## Install
+
+```bash
+npm install s0racle-sdk @solana/web3.js
+```
+
+## Quick Start
+
+```ts
+import { Connection } from "@solana/web3.js";
+import { createS0racleClient } from "s0racle-sdk";
+
+const connection = new Connection("https://api.devnet.solana.com");
+const client = createS0racleClient({ connection });
+
+const health = await client.getNetworkHealth();
+
+console.log(health.healthScore);          // 0–100
+console.log(health.tpuReachabilityPct);   // % validators reachable right now
+console.log(health.avgSlotLatencyMs);     // how far behind is the network
+console.log(health.agaveCount, health.firedancerCount, health.jitoCount);
+```
+
+## Stake-Weighted Reach & Client Diversity
+
+Raw validator counts don't tell the full story. s0racle weights reachability by stake and tracks which clients are running — so you know if the network can actually finalize, not just respond.
+
+```ts
+import { isConsensusCritical, stakeReachStatus, clientDiversityIndex } from "s0racle-sdk";
+
+for (const region of health.regionScores) {
+  if (region.observerCount === 0) continue;
+
+  console.log(stakeReachStatus(region.reachableStakePct)); // healthy | degraded | critical
+  console.log(clientDiversityIndex(region));               // 0 = monoculture, 100 = perfectly even
+
+  if (isConsensusCritical(region.reachableStakePct)) {
+    // under 67% stake reachable — network cannot finalize
+    // pause writes, widen spreads, or alert users
+  }
+}
+```
+
+Thresholds: `>= 80%` healthy · `>= 67%` degraded · `< 67%` critical
+
+## Health Score
+
+```
+healthScore  = (reachabilityPct × 70%) + (latencyScore × 30%)
+latencyScore = max(0, (400 - slotLatencyMs) × 100 / 400)
+```
+
+Reachability is weighted higher because a degraded but reachable network can still process transactions — an unreachable one cannot.
+
+## API
+
+### `createS0racleClient(options)`
+
+| Option | Type | Default |
+|---|---|---|
+| `connection` | `Connection` | required |
+| `programId` | `PublicKey` | s0racle devnet address |
+| `wallet` | `Wallet` | read-only by default |
+
+### Read methods
+
+| Method | Returns |
+|---|---|
+| `getNetworkHealth()` | `Promise<NetworkHealth>` |
+| `getRegistry()` | `Promise<Registry>` |
+| `getObserver(pubkey)` | `Promise<Observer>` |
+| `getAllObservers()` | `Promise<Observer[]>` |
+| `getObserversByRegion(region)` | `Promise<Observer[]>` |
+
+### Utility helpers
+
+| Function | What it does |
+|---|---|
+| `healthStatus(health)` | `"healthy"` · `"degraded"` · `"critical"` |
+| `isStale(health, slot)` | True if data is older than 150 slots |
+| `isDegraded(health)` | True if score below 70 |
+| `isConsensusCritical(pct)` | True if stake reach below 67% |
+| `stakeReachStatus(pct)` | Threshold label for stake reach |
+| `dominantClient(region)` | Which client runs most validators here |
+| `clientDiversityIndex(region)` | 0–100 diversity score |
+| `regionLabel(region)` | Human readable region name |
+
+### Regions
+
+`Asia` · `US` · `EU` · `SouthAmerica` · `Africa` · `Oceania` · `Other`
+
+## Examples
+
+```bash
+cd examples
+npm install
+npm run read       # fetch and print NetworkHealth
+npm run observers  # list observers by region
+npm run diversity  # stake-weighted consensus check
+```
+
+## Status
+
+Early development — API may change before `1.0.0`.
+
+Program ID (devnet): `2paXpX8Ze3tvYezviSwQJSSihG3LbrDiD7SNsaFwgTow`
+
+## Links
+
+GitHub: [github.com/s0racle](https://github.com/s0racle)
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,182 @@
+import { PublicKey, Connection, TransactionInstruction } from '@solana/web3.js';
+import { Wallet } from '@coral-xyz/anchor';
+
+declare enum Region {
+    Asia = "Asia",
+    US = "US",
+    EU = "EU",
+    SouthAmerica = "SouthAmerica",
+    Africa = "Africa",
+    Oceania = "Oceania",
+    Other = "Other"
+}
+interface Attestation {
+    slot: bigint;
+    timestamp: bigint;
+    avgRttUs: number;
+    p95RttUs: number;
+    slotLatencyMs: number;
+    tpuReachable: number;
+    tpuProbed: number;
+    agaveCount: number;
+    firedancerCount: number;
+    jitoCount: number;
+    solanaLabsCount: number;
+    otherCount: number;
+    reachableStakePct: number;
+}
+interface RegionScore {
+    region: Region;
+    observerCount: number;
+    healthScore: number;
+    reachabilityPct: number;
+    avgRttUs: number;
+    slotLatencyMs: number;
+    lastUpdatedSlot: bigint;
+    agaveCount: number;
+    firedancerCount: number;
+    jitoCount: number;
+    solanaLabsCount: number;
+    otherCount: number;
+    reachableStakePct: number;
+}
+interface NetworkHealth {
+    healthScore: number;
+    tpuReachabilityPct: number;
+    avgSlotLatencyMs: number;
+    activeObserverCount: number;
+    activeRegionCount: number;
+    lastUpdatedSlot: bigint;
+    lastUpdatedTs: bigint;
+    minHealthEver: number | null;
+    maxHealthEver: number;
+    totalAttestations: bigint;
+    regionScores: RegionScore[];
+    agaveCount: number;
+    firedancerCount: number;
+    jitoCount: number;
+    solanaLabsCount: number;
+    otherCount: number;
+}
+interface Observer {
+    publicKey: PublicKey;
+    authority: PublicKey;
+    region: Region;
+    stakeLamports: bigint;
+    registeredAt: bigint;
+    lastAttestationSlot: bigint;
+    attestationCount: bigint;
+    latestAttestation: Attestation;
+    isActive: boolean;
+}
+interface Registry {
+    authority: PublicKey;
+    pendingAuthority: PublicKey | null;
+    minStakeLamports: bigint;
+    observerCount: number;
+    activeCount: number;
+    maxObservers: number;
+    paused: boolean;
+    version: number;
+}
+interface AttestationSubmittedEvent {
+    observer: PublicKey;
+    region: Region;
+    score: number;
+    reachabilityPct: number;
+    slotLatencyMs: number;
+    slot: bigint;
+    agaveCount: number;
+    firedancerCount: number;
+    jitoCount: number;
+    solanaLabsCount: number;
+    otherCount: number;
+    reachableStakePct: number;
+}
+interface ObserverRegisteredEvent {
+    observer: PublicKey;
+    region: Region;
+    stakeLamports: bigint;
+}
+interface ObserverDeregisteredEvent {
+    observer: PublicKey;
+}
+interface ObserverSlashedEvent {
+    observer: PublicKey;
+    slashBps: number;
+    amountSlashed: bigint;
+}
+interface ConfigUpdatedEvent {
+    minStakeLamports: bigint | null;
+    maxObservers: number | null;
+    paused: boolean | null;
+}
+
+declare const PROGRAM_ID: PublicKey;
+declare function getRegistryPDA(programId?: PublicKey): [PublicKey, number];
+declare function getNetworkHealthPDA(programId?: PublicKey): [PublicKey, number];
+declare function getObserverPDA(observer: PublicKey, programId?: PublicKey): [PublicKey, number];
+
+interface SubmitAttestationParams {
+    tpuReachable: number;
+    tpuProbed: number;
+    avgRttUs: number;
+    p95RttUs: number;
+    slotLatencyMs: number;
+    agaveCount: number;
+    firedancerCount: number;
+    jitoCount: number;
+    solanaLabsCount: number;
+    otherCount: number;
+    reachableStakePct: number;
+}
+interface UpdateConfigParams {
+    minStakeLamports: bigint | null;
+    maxObservers: number | null;
+    paused: boolean | null;
+}
+
+interface S0racleClientOptions {
+    connection: Connection;
+    programId?: PublicKey;
+    wallet?: Wallet;
+}
+interface S0racleClient {
+    readonly programId: PublicKey;
+    readonly connection: Connection;
+    getNetworkHealth(): Promise<NetworkHealth>;
+    getRegistry(): Promise<Registry>;
+    getObserver(observerPubkey: PublicKey): Promise<Observer>;
+    getAllObservers(): Promise<Observer[]>;
+    getObserversByRegion(region: Region): Promise<Observer[]>;
+    registerObserver(observer: PublicKey, region: Region): Promise<TransactionInstruction>;
+    submitAttestation(authority: PublicKey, params: SubmitAttestationParams): Promise<TransactionInstruction>;
+    deregisterObserver(caller: PublicKey, observerWallet: PublicKey): Promise<TransactionInstruction>;
+    crankAggregation(cranker: PublicKey, observerAccounts: PublicKey[]): Promise<TransactionInstruction>;
+    initialize(authority: PublicKey, minStakeLamports: bigint, maxObservers: number): Promise<TransactionInstruction>;
+    slashObserver(authority: PublicKey, observerWallet: PublicKey, treasury: PublicKey, slashBps: number): Promise<TransactionInstruction>;
+    updateConfig(authority: PublicKey, params: UpdateConfigParams): Promise<TransactionInstruction>;
+    proposeAuthority(authority: PublicKey, newAuthority: PublicKey): Promise<TransactionInstruction>;
+    acceptAuthority(newAuthority: PublicKey): Promise<TransactionInstruction>;
+    onAttestationSubmitted(callback: (event: AttestationSubmittedEvent, slot: number) => void): number;
+    onObserverRegistered(callback: (event: ObserverRegisteredEvent, slot: number) => void): number;
+    onObserverDeregistered(callback: (event: ObserverDeregisteredEvent, slot: number) => void): number;
+    onObserverSlashed(callback: (event: ObserverSlashedEvent, slot: number) => void): number;
+    onConfigUpdated(callback: (event: ConfigUpdatedEvent, slot: number) => void): number;
+    removeEventListener(listenerId: number): Promise<void>;
+}
+declare function createS0racleClient(opts: S0racleClientOptions): S0racleClient;
+
+declare function isStale(networkHealth: NetworkHealth, currentSlot: bigint): boolean;
+declare function isObserverStale(observer: Observer, currentSlot: bigint): boolean;
+declare function isDegraded(networkHealth: NetworkHealth, threshold?: number): boolean;
+declare function healthStatus(networkHealth: NetworkHealth, currentSlot?: bigint): "healthy" | "degraded" | "critical" | "stale";
+declare function regionLabel(region: Region): string;
+declare function lamportsToSol(lamports: bigint): number;
+declare function latencyScore(slotLatencyMs: number): number;
+declare function isConsensusCritical(reachableStakePct: number): boolean;
+declare function stakeReachStatus(reachableStakePct: number): "healthy" | "degraded" | "critical";
+declare function dominantClient(region: RegionScore): "agave" | "firedancer" | "jito" | "other";
+declare function clientDiversityIndex(region: RegionScore): number;
+
+export { type Attestation, type AttestationSubmittedEvent, type ConfigUpdatedEvent, type NetworkHealth, type Observer, type ObserverDeregisteredEvent, type ObserverRegisteredEvent, type ObserverSlashedEvent, PROGRAM_ID, Region, type RegionScore, type Registry, type S0racleClient, type S0racleClientOptions, type SubmitAttestationParams, type UpdateConfigParams, clientDiversityIndex, createS0racleClient, dominantClient, getNetworkHealthPDA, getObserverPDA, getRegistryPDA, healthStatus, isConsensusCritical, isDegraded, isObserverStale, isStale, lamportsToSol, latencyScore, regionLabel, stakeReachStatus };

package/dist/index.d.ts

@@ -0,0 +1,182 @@
+import { PublicKey, Connection, TransactionInstruction } from '@solana/web3.js';
+import { Wallet } from '@coral-xyz/anchor';
+
+declare enum Region {
+    Asia = "Asia",
+    US = "US",
+    EU = "EU",
+    SouthAmerica = "SouthAmerica",
+    Africa = "Africa",
+    Oceania = "Oceania",
+    Other = "Other"
+}
+interface Attestation {
+    slot: bigint;
+    timestamp: bigint;
+    avgRttUs: number;
+    p95RttUs: number;
+    slotLatencyMs: number;
+    tpuReachable: number;
+    tpuProbed: number;
+    agaveCount: number;
+    firedancerCount: number;
+    jitoCount: number;
+    solanaLabsCount: number;
+    otherCount: number;
+    reachableStakePct: number;
+}
+interface RegionScore {
+    region: Region;
+    observerCount: number;
+    healthScore: number;
+    reachabilityPct: number;
+    avgRttUs: number;
+    slotLatencyMs: number;
+    lastUpdatedSlot: bigint;
+    agaveCount: number;
+    firedancerCount: number;
+    jitoCount: number;
+    solanaLabsCount: number;
+    otherCount: number;
+    reachableStakePct: number;
+}
+interface NetworkHealth {
+    healthScore: number;
+    tpuReachabilityPct: number;
+    avgSlotLatencyMs: number;
+    activeObserverCount: number;
+    activeRegionCount: number;
+    lastUpdatedSlot: bigint;
+    lastUpdatedTs: bigint;
+    minHealthEver: number | null;
+    maxHealthEver: number;
+    totalAttestations: bigint;
+    regionScores: RegionScore[];
+    agaveCount: number;
+    firedancerCount: number;
+    jitoCount: number;
+    solanaLabsCount: number;
+    otherCount: number;
+}
+interface Observer {
+    publicKey: PublicKey;
+    authority: PublicKey;
+    region: Region;
+    stakeLamports: bigint;
+    registeredAt: bigint;
+    lastAttestationSlot: bigint;
+    attestationCount: bigint;
+    latestAttestation: Attestation;
+    isActive: boolean;
+}
+interface Registry {
+    authority: PublicKey;
+    pendingAuthority: PublicKey | null;
+    minStakeLamports: bigint;
+    observerCount: number;
+    activeCount: number;
+    maxObservers: number;
+    paused: boolean;
+    version: number;
+}
+interface AttestationSubmittedEvent {
+    observer: PublicKey;
+    region: Region;
+    score: number;
+    reachabilityPct: number;
+    slotLatencyMs: number;
+    slot: bigint;
+    agaveCount: number;
+    firedancerCount: number;
+    jitoCount: number;
+    solanaLabsCount: number;
+    otherCount: number;
+    reachableStakePct: number;
+}
+interface ObserverRegisteredEvent {
+    observer: PublicKey;
+    region: Region;
+    stakeLamports: bigint;
+}
+interface ObserverDeregisteredEvent {
+    observer: PublicKey;
+}
+interface ObserverSlashedEvent {
+    observer: PublicKey;
+    slashBps: number;
+    amountSlashed: bigint;
+}
+interface ConfigUpdatedEvent {
+    minStakeLamports: bigint | null;
+    maxObservers: number | null;
+    paused: boolean | null;
+}
+
+declare const PROGRAM_ID: PublicKey;
+declare function getRegistryPDA(programId?: PublicKey): [PublicKey, number];
+declare function getNetworkHealthPDA(programId?: PublicKey): [PublicKey, number];
+declare function getObserverPDA(observer: PublicKey, programId?: PublicKey): [PublicKey, number];
+
+interface SubmitAttestationParams {
+    tpuReachable: number;
+    tpuProbed: number;
+    avgRttUs: number;
+    p95RttUs: number;
+    slotLatencyMs: number;
+    agaveCount: number;
+    firedancerCount: number;
+    jitoCount: number;
+    solanaLabsCount: number;
+    otherCount: number;
+    reachableStakePct: number;
+}
+interface UpdateConfigParams {
+    minStakeLamports: bigint | null;
+    maxObservers: number | null;
+    paused: boolean | null;
+}
+
+interface S0racleClientOptions {
+    connection: Connection;
+    programId?: PublicKey;
+    wallet?: Wallet;
+}
+interface S0racleClient {
+    readonly programId: PublicKey;
+    readonly connection: Connection;
+    getNetworkHealth(): Promise<NetworkHealth>;
+    getRegistry(): Promise<Registry>;
+    getObserver(observerPubkey: PublicKey): Promise<Observer>;
+    getAllObservers(): Promise<Observer[]>;
+    getObserversByRegion(region: Region): Promise<Observer[]>;
+    registerObserver(observer: PublicKey, region: Region): Promise<TransactionInstruction>;
+    submitAttestation(authority: PublicKey, params: SubmitAttestationParams): Promise<TransactionInstruction>;
+    deregisterObserver(caller: PublicKey, observerWallet: PublicKey): Promise<TransactionInstruction>;
+    crankAggregation(cranker: PublicKey, observerAccounts: PublicKey[]): Promise<TransactionInstruction>;
+    initialize(authority: PublicKey, minStakeLamports: bigint, maxObservers: number): Promise<TransactionInstruction>;
+    slashObserver(authority: PublicKey, observerWallet: PublicKey, treasury: PublicKey, slashBps: number): Promise<TransactionInstruction>;
+    updateConfig(authority: PublicKey, params: UpdateConfigParams): Promise<TransactionInstruction>;
+    proposeAuthority(authority: PublicKey, newAuthority: PublicKey): Promise<TransactionInstruction>;
+    acceptAuthority(newAuthority: PublicKey): Promise<TransactionInstruction>;
+    onAttestationSubmitted(callback: (event: AttestationSubmittedEvent, slot: number) => void): number;
+    onObserverRegistered(callback: (event: ObserverRegisteredEvent, slot: number) => void): number;
+    onObserverDeregistered(callback: (event: ObserverDeregisteredEvent, slot: number) => void): number;
+    onObserverSlashed(callback: (event: ObserverSlashedEvent, slot: number) => void): number;
+    onConfigUpdated(callback: (event: ConfigUpdatedEvent, slot: number) => void): number;
+    removeEventListener(listenerId: number): Promise<void>;
+}
+declare function createS0racleClient(opts: S0racleClientOptions): S0racleClient;
+
+declare function isStale(networkHealth: NetworkHealth, currentSlot: bigint): boolean;
+declare function isObserverStale(observer: Observer, currentSlot: bigint): boolean;
+declare function isDegraded(networkHealth: NetworkHealth, threshold?: number): boolean;
+declare function healthStatus(networkHealth: NetworkHealth, currentSlot?: bigint): "healthy" | "degraded" | "critical" | "stale";
+declare function regionLabel(region: Region): string;
+declare function lamportsToSol(lamports: bigint): number;
+declare function latencyScore(slotLatencyMs: number): number;
+declare function isConsensusCritical(reachableStakePct: number): boolean;
+declare function stakeReachStatus(reachableStakePct: number): "healthy" | "degraded" | "critical";
+declare function dominantClient(region: RegionScore): "agave" | "firedancer" | "jito" | "other";
+declare function clientDiversityIndex(region: RegionScore): number;
+
+export { type Attestation, type AttestationSubmittedEvent, type ConfigUpdatedEvent, type NetworkHealth, type Observer, type ObserverDeregisteredEvent, type ObserverRegisteredEvent, type ObserverSlashedEvent, PROGRAM_ID, Region, type RegionScore, type Registry, type S0racleClient, type S0racleClientOptions, type SubmitAttestationParams, type UpdateConfigParams, clientDiversityIndex, createS0racleClient, dominantClient, getNetworkHealthPDA, getObserverPDA, getRegistryPDA, healthStatus, isConsensusCritical, isDegraded, isObserverStale, isStale, lamportsToSol, latencyScore, regionLabel, stakeReachStatus };