Files
zeekayandHanzo Dev 28372d9f1e chain letters are lowercase
The primary-network chains answer to either case; one spelling beats two.
/v1/chain/c/rpc, /v1/chain/p, /v1/chain/x across the estate.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-08 15:28:19 -07:00

526 lines
19 KiB
TypeScript

// The ONE place this explorer talks to the Zoo chain.
//
// Everything rendered on the site comes through here, so there is exactly one
// answer to "where did that number come from". Before this file existed the
// page invented its own: `blockHeight: 1234567`, `Math.random()` for TPS, a
// `$25.50` price. Nothing read from anything.
//
// A read never returns a bare number. It returns either a value with the
// provenance and timestamp needed to grade it, or the reason it failed — so a
// caller cannot accidentally turn a failure into a plausible-looking figure.
import {
type Measure,
type Health,
graded,
idle,
live,
empty,
pending,
stamp,
unavailable,
UNSERVED,
// The explicit .ts extension lets `node --test` run this module directly, with
// no build step and no test-runner dependency. TypeScript allows it via
// allowImportingTsExtensions; webpack resolves the literal filename.
} from './measure.ts'
/**
* Zoo mainnet C-Chain.
*
* The canonical path is `/v1/chain/c/rpc` or `/v1/chain/zoo`.
* The legacy `/ext/bc` and `/v1/bc` paths are migrated.
*/
export const RPC_URL =
process.env.NEXT_PUBLIC_ZOO_RPC_URL || 'https://rpc.zoo.network/v1/chain/c/rpc'
/** The P-Chain serves the validator set. */
export const P_RPC_URL =
process.env.NEXT_PUBLIC_ZOO_P_RPC_URL || 'https://rpc.zoo.network/v1/chain/p'
/** Zoo mainnet. Verified: eth_chainId → 0x30e08. */
export const CHAIN_ID = 200200
/** How long a head stays "fresh" before the surface must say how old it is. */
export const FRESH_BUDGET_SEC = 600
/** How many blocks the block/transaction lists read. */
export const RECENT_BLOCKS = 10
const TIMEOUT_MS = 10_000
// --- transport ---------------------------------------------------------------
type RpcCall = { method: string; params: unknown }
/**
* One HTTP round trip, one or many JSON-RPC calls.
*
* Batching matters here: the block list needs ten blocks, and ten sequential
* round trips against a public endpoint is both slow and a good way to get rate
* limited. The endpoint accepts a JSON array and answers with one — verified.
*
* Every failure mode ends as a thrown Error carrying a human reason, because the
* caller's job is to turn that reason into an `unavailable` Measure, and a reason
* a reader cannot act on is nearly as bad as a fabricated number.
*/
async function rpcBatch(url: string, calls: RpcCall[]): Promise<unknown[]> {
const body = calls.map((c, i) => ({ jsonrpc: '2.0', id: i, method: c.method, params: c.params }))
let res: Response
try {
res = await fetch(url, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify(calls.length === 1 ? body[0] : body),
signal: AbortSignal.timeout(TIMEOUT_MS),
})
} catch (e) {
// A timeout and a DNS failure are both "we could not ask", but they are not
// the same fault, so the reason is carried through rather than flattened.
const why = e instanceof Error && e.name === 'TimeoutError'
? `no answer within ${TIMEOUT_MS / 1000}s`
: e instanceof Error ? e.message : String(e)
throw new Error(why)
}
if (!res.ok) throw new Error(`HTTP ${res.status} from the RPC endpoint`)
let json: unknown
try {
json = await res.json()
} catch {
// An HTML error page from a proxy parses as neither JSON nor a chain answer.
throw new Error('the RPC endpoint did not return JSON')
}
const rows = Array.isArray(json) ? json : [json]
const out = new Array<unknown>(calls.length)
for (const row of rows as { id?: number; result?: unknown; error?: { message?: string } }[]) {
const i = typeof row.id === 'number' ? row.id : 0
// A per-call JSON-RPC error is recorded as undefined rather than throwing the
// whole batch away: on this chain `eth_getBlockByNumber` legitimately answers
// "cannot query unfinalized data" for a height eth_blockNumber just reported,
// and one such gap must not blank the nine blocks that did come back.
out[i] = row.error ? undefined : row.result
}
return out
}
const hexToNum = (h: unknown): number => (typeof h === 'string' ? Number(BigInt(h)) : NaN)
// --- probe -------------------------------------------------------------------
export type RawBlock = {
number: string
hash: string
timestamp: string
miner: string
gasUsed: string
gasLimit: string
transactions: RawTx[]
}
export type RawTx = {
hash: string
from: string
to: string | null
value: string
gas: string
gasPrice?: string
blockNumber: string
}
export type Probe =
| {
ok: true
/** The head the node will actually SERVE — from the head block itself. */
height: number
chainId: number
headTimestamp: number
headTxCount: number
gasPriceWei: number
syncing: boolean | undefined
/**
* What eth_blockNumber claims, which on this chain is not always the same
* as the head that can be read back. See `unfinalizedAhead`.
*/
reportedHeight: number
/**
* Blocks built but not retrievable — `eth_blockNumber` minus the servable
* head. Non-zero means consensus is building without finalizing, which is
* a STALL, not a network at rest. Measured 2026-08-04: eth_blockNumber
* answered 15025 while block 15025 returned "cannot query unfinalized
* data" and the servable head was 15008.
*/
unfinalizedAhead: number
blocks: RawBlock[]
}
| { ok: false; reason: string }
/**
* Read the chain's head and the recent blocks behind it, in one round trip.
*
* `eth_getBlockByNumber('latest')` is the anchor rather than `eth_blockNumber`,
* because it yields the height AND the timestamp AND the head's transactions
* together — so freshness costs no extra request and, more importantly, the
* height can never disagree with the block it describes. `eth_blockNumber` is
* still asked, but as a CONTROL on the head rather than as the headline figure:
* when the two disagree the chain is building blocks it cannot finalize, and
* that difference is real information a visitor should see.
*/
export async function probe(url = RPC_URL): Promise<Probe> {
try {
const [head, cid, gas, sync, reported] = await rpcBatch(url, [
{ method: 'eth_getBlockByNumber', params: ['latest', true] },
{ method: 'eth_chainId', params: [] },
{ method: 'eth_gasPrice', params: [] },
{ method: 'eth_syncing', params: [] },
{ method: 'eth_blockNumber', params: [] },
])
const blk = head as RawBlock | undefined
if (!blk || typeof blk.number !== 'string') {
return { ok: false, reason: 'the endpoint answered without a head block' }
}
const height = hexToNum(blk.number)
const reportedHeight = hexToNum(reported)
// Walk back from the head for the list. The head is already in hand, so only
// the tail is requested.
const want = Array.from({ length: RECENT_BLOCKS - 1 }, (_, i) => height - 1 - i).filter((n) => n >= 0)
const tail = want.length
? await rpcBatch(url, want.map((n) => ({
method: 'eth_getBlockByNumber',
params: ['0x' + n.toString(16), true],
})))
: []
const blocks = [blk, ...(tail as (RawBlock | undefined)[])].filter(
(b): b is RawBlock => !!b && typeof b.number === 'string',
)
return {
ok: true,
height,
chainId: hexToNum(cid),
headTimestamp: hexToNum(blk.timestamp),
headTxCount: blk.transactions?.length ?? 0,
gasPriceWei: hexToNum(gas),
syncing: sync === undefined ? undefined : sync !== false,
reportedHeight: Number.isFinite(reportedHeight) ? reportedHeight : height,
unfinalizedAhead: Number.isFinite(reportedHeight) ? Math.max(0, reportedHeight - height) : 0,
blocks,
}
} catch (e) {
return { ok: false, reason: e instanceof Error ? e.message : String(e) }
}
}
// --- grading -----------------------------------------------------------------
export type ChainStatus = {
health: Health
/** One clause a visitor can act on. Always set once the probe resolves. */
reason: string
}
/**
* Turn a probe into a health grade.
*
* A green dot on a two-day-old head is unreachable by construction: `ok` is
* returned only inside the freshness budget. The interesting case is an old
* head, because "the chain produced nothing" and "this node is behind" look
* identical from a height alone:
*
* syncing → this NODE is behind the chain → degraded
* blocks unfinalized → consensus is building but not certifying → degraded
* neither → the chain produced nothing → idle
*
* The middle case is the one this chain needed. Without it a stalled chain
* grades the same as a quiet one, and "at rest" would be a comfortable lie.
*/
export function grade(p: Probe, budgetSec = FRESH_BUDGET_SEC): ChainStatus {
if (!p.ok) return { health: 'down', reason: p.reason }
const age = Math.max(0, Math.floor(Date.now() / 1000) - p.headTimestamp)
if (age <= budgetSec) return { health: 'ok', reason: 'producing blocks' }
if (p.syncing === true) return { health: 'degraded', reason: 'this node is behind the chain (eth_syncing)' }
if (p.unfinalizedAhead > 0) {
return {
health: 'degraded',
reason: `${p.unfinalizedAhead} block${p.unfinalizedAhead === 1 ? '' : 's'} built but not finalized — the chain is not advancing`,
}
}
if (p.syncing === false) return { health: 'idle', reason: 'no new block; this node is caught up with the chain' }
return { health: 'degraded', reason: 'the head is old and the node does not report eth_syncing' }
}
// --- figures -----------------------------------------------------------------
export type ChainFigures = {
height: Measure
lastBlock: Measure
headTxs: Measure
gasPrice: Measure
gasUsed: Measure
validators: Measure
blockInterval: Measure
chainId: Measure
}
const int = (n: number) => n.toLocaleString('en-US')
/**
* Grade a figure derived from the C-Chain head.
*
* On a chain at rest a flat figure is CORRECT, so it must not be painted as
* stale. Staleness is a value we expected to have moved; idleness is a network
* nothing asked to move. Same age, opposite meaning — the caller says which.
*/
function headFigure<T>(s: ChainStatus, p: Extract<Probe, { ok: true }>, value: T, source: string, idleNote: string): Measure<T> {
if (s.health === 'idle') return idle(value, source, idleNote, p.headTimestamp)
return graded(value, source, p.headTimestamp, FRESH_BUDGET_SEC)
}
/**
* The public figures, derived from one probe and the validator set.
*
* `null` for either leg means "not read yet" → `pending`. The two legs degrade
* INDEPENDENTLY: a P-Chain flap must not blank the C-Chain figures, because one
* dead endpoint blanking a whole page is how unexplained zeros get shipped.
*/
export function chainFigures(p: Probe | null, vs: ValidatorSet | null): ChainFigures {
if (!p) {
// The C-Chain read is still in flight — but the P-Chain leg may already have
// resolved, and holding a finished answer hostage to an unfinished one is
// the coupling this function exists to avoid.
const q = pending('reading the chain…')
return {
height: q, lastBlock: q, headTxs: q, gasPrice: q, gasUsed: q,
validators: validatorMeasure(vs), blockInterval: q, chainId: q,
}
}
const s = grade(p)
if (!p.ok) {
const u = unavailable('eth_getBlockByNumber', p.reason)
return {
height: u,
lastBlock: u,
headTxs: u,
gasPrice: unavailable('eth_gasPrice', p.reason),
gasUsed: u,
validators: validatorMeasure(vs),
blockInterval: u,
chainId: u,
}
}
// The head height, with the unfinalized gap as its CONTROL. A visitor who sees
// 15,008 while a block explorer elsewhere says 15,025 deserves to know which
// is servable and why they differ, rather than being left to guess.
const height: Measure = {
...headFigure(s, p, int(p.height), 'eth_getBlockByNumber · latest', 'no new block has been produced'),
control: p.unfinalizedAhead > 0
? `eth_blockNumber reports ${int(p.reportedHeight)}, but block ${int(p.reportedHeight)} cannot be read back ("cannot query unfinalized data"). ${int(p.height)} is the highest block this endpoint will actually serve.`
: undefined,
}
// The head's age IS this tile's value, so the "as of …" stamp <Stat> renders
// from `asOf` would just say the same thing twice. The wall-clock time goes in
// the note instead, which is the part the age does not already tell you.
const lastBlock: Measure = {
...headFigure(s, p, ago_(p.headTimestamp), 'eth_getBlockByNumber · timestamp', 'the chain is not producing blocks'),
asOf: undefined,
note: stamp(p.headTimestamp),
}
// The head block's transaction count is the best evidence that a quiet chain
// did real work rather than being stuck. A zero here is the block's genuine
// content, so it is `empty` with the control that proves the read worked.
const headTxs: Measure = p.headTxCount === 0
? empty(
'eth_getBlockByNumber · transactions',
'The last block carried no transactions.',
'The block itself was read successfully, so this zero is the block\'s real content.',
)
: headFigure(s, p, int(p.headTxCount), 'eth_getBlockByNumber · transactions', 'in the last block produced')
// Gas price is a node's current quote. It does not depend on block production,
// so it is live even while the chain is at rest.
const gasPrice: Measure = Number.isFinite(p.gasPriceWei)
? live(`${(p.gasPriceWei / 1e9).toFixed(2)} Gwei`, 'eth_gasPrice')
: unavailable('eth_gasPrice', 'The endpoint did not return a gas price.')
// An identifier, not a quantity — so no thousands separator ("200200", never
// "200,200"). A visitor copying it into a wallet must get the real thing.
const chainId: Measure = Number.isFinite(p.chainId)
? live(String(p.chainId), 'eth_chainId')
: unavailable('eth_chainId', 'The endpoint did not return a chain id.')
// Head-block gas utilisation. A zero is the block's real content, not a
// failure, so it is `empty` with the control that proves the read worked.
const head = p.blocks[0]
const used = head ? hexToNum(head.gasUsed) : NaN
const limit = head ? hexToNum(head.gasLimit) : NaN
const gasUsed: Measure = !Number.isFinite(used) || !Number.isFinite(limit) || limit === 0
? unavailable('eth_getBlockByNumber · gasUsed', 'The head block did not report gas usage.')
: used === 0
? empty(
'eth_getBlockByNumber · gasUsed',
'The last block consumed no gas.',
'The block was read successfully and reports a gas limit, so this zero is the block\'s real content.',
)
: headFigure(
s, p,
`${((used / limit) * 100).toFixed(1)}%`,
'eth_getBlockByNumber · gasUsed ÷ gasLimit',
'of the last block produced',
)
return {
height,
lastBlock,
headTxs,
gasPrice,
gasUsed,
validators: validatorMeasure(vs),
blockInterval: intervalMeasure(p, s),
chainId,
}
}
/** Mean seconds between the recent blocks that were actually read. */
function intervalMeasure(p: Extract<Probe, { ok: true }>, s: ChainStatus): Measure {
const ts = p.blocks.map((b) => hexToNum(b.timestamp)).filter(Number.isFinite)
if (ts.length < 2) {
return empty(
'eth_getBlockByNumber · timestamps',
'Not enough blocks have been produced to measure an interval.',
`${ts.length} block${ts.length === 1 ? '' : 's'} were read back from the head.`,
)
}
const span = ts[0] - ts[ts.length - 1]
const mean = span / (ts.length - 1)
return headFigure(
s,
p,
`${mean.toFixed(1)}s`,
`eth_getBlockByNumber · mean over ${ts.length} blocks`,
'measured over the last blocks produced',
)
}
// --- validators --------------------------------------------------------------
export type ValidatorSet = { ok: true; count: number } | { ok: false; reason: string }
/**
* The validator registry does not depend on block production, so it is `live`
* even while the C-Chain is at rest. Grading it idle would imply the SET is
* somehow at rest, which is not what is being measured.
*/
function validatorMeasure(vs: ValidatorSet | null): Measure {
if (!vs) return pending('platform.getCurrentValidators')
if (!vs.ok) return unavailable('platform.getCurrentValidators', vs.reason)
if (vs.count === 0) {
return empty(
'platform.getCurrentValidators',
'The P-Chain reports no current validators.',
'The call itself succeeded and returned a validator list, so this zero is the list\'s real length.',
)
}
return live(int(vs.count), 'platform.getCurrentValidators')
}
export async function readValidators(url = P_RPC_URL): Promise<ValidatorSet> {
try {
const [res] = await rpcBatch(url, [{ method: 'platform.getCurrentValidators', params: {} }])
const list = (res as { validators?: unknown[] } | undefined)?.validators
if (!Array.isArray(list)) throw new Error('the P-Chain answered without a validator list')
return { ok: true, count: list.length }
} catch (e) {
return { ok: false, reason: e instanceof Error ? e.message : String(e) }
}
}
// --- decoded views for the block and transaction lists -----------------------
export type BlockRow = {
number: number
hash: string
timestamp: number
miner: string
txCount: number
gasUsed: number
gasLimit: number
}
export type TxRow = {
hash: string
from: string
to: string | null
valueWei: bigint
gas: number
timestamp: number
blockNumber: number
}
export function blockRows(p: Probe | null): BlockRow[] {
if (!p || !p.ok) return []
return p.blocks.map((b) => ({
number: hexToNum(b.number),
hash: b.hash,
timestamp: hexToNum(b.timestamp),
miner: b.miner,
txCount: b.transactions?.length ?? 0,
gasUsed: hexToNum(b.gasUsed),
gasLimit: hexToNum(b.gasLimit),
}))
}
/** Transactions from the blocks already read — no extra round trip. */
export function txRows(p: Probe | null, limit = 10): TxRow[] {
if (!p || !p.ok) return []
const out: TxRow[] = []
for (const b of p.blocks) {
const ts = hexToNum(b.timestamp)
for (const t of b.transactions ?? []) {
if (out.length >= limit) return out
out.push({
hash: t.hash,
from: t.from,
to: t.to,
valueWei: BigInt(t.value ?? '0x0'),
gas: hexToNum(t.gas),
timestamp: ts,
blockNumber: hexToNum(t.blockNumber ?? b.number),
})
}
}
return out
}
/** ZOO from wei, to 4dp, without going through a lossy Number for the whole value. */
export function formatZoo(wei: bigint): string {
const whole = wei / 10n ** 18n
const frac = (wei % 10n ** 18n) / 10n ** 14n // 4 decimal places
return `${whole.toLocaleString('en-US')}.${frac.toString().padStart(4, '0')}`
}
// Re-exported so components import their vocabulary from one module.
export { UNSERVED }
// Local copy of `ago` to keep this module free of a UI import cycle.
function ago_(unix: number): string {
const sec = Math.max(0, Math.floor(Date.now() / 1000) - unix)
const d = Math.floor(sec / 86400)
const h = Math.floor((sec % 86400) / 3600)
const m = Math.floor((sec % 3600) / 60)
if (d > 0) return `${d}d ${h}h ago`
if (h > 0) return `${h}h ${m}m ago`
if (m > 0) return `${m}m ago`
return `${sec}s ago`
}