s0racle-sdk

TypeScript SDK for reading live Solana network health from the s0racle oracle.

---

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

npm install s0racle-sdk @solana/web3.js

Quick Start

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.

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

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

License

MIT