network

Get top-level chain overview stats.

Reads the single-statement network-stats query (latest ledger row + ledgers 60s aggregate for TPS + deduped counts of accounts / contracts) and caches the assembled response keyed on the chain head (latest_ledger_sequence) in process memory — see network/cache.rs. See the task 0045 spec and network::queries::fetch_stats for the full data-source mapping.

Per request we first read the head cheaply (crate::common::head — SELECT max(sequence), a primary-key probe) and look up the cache under it: an unchanged head is a HIT (the new ledger has not landed), an advanced head is a MISS that recomputes once. So a new ledger is visible on the first request after it is written — there is no up-to-TTL window serving the previous head (task 0291).

Concurrent cold-cache requests deduplicate via moka::future::Cache::try_get_with — the first task runs the async DB query and the rest wait on its result instead of fanning out N round-trips.

get/v1/network/stats

Request

  • The document declares no server URL.
  • Auth: one of:
    • API key in header x-api-key
    • HTTP bearer

Response

Chain overview stats

generated_atstring date-time required

Wall-clock time the underlying SELECT ran on the DB (NOW() at fetch time). Preserved across cache hits — frontend uses this to distinguish indexer-health lag from cache-age staleness.

latest_ledger_closed_atstring date-time nullable

Close time of the newest ledger in the database. null only when no ledgers are indexed (cold-bootstrap cluster).

latest_ledger_sequenceinteger required

Sequence of the newest ledger in the database (ordered by closed_at DESC). 0 sentinel indicates an empty cluster (no ledger 0 exists in Stellar).

total_accountsinteger required

Indexed account count: count() over accounts_recent, the deduped MV the /accounts list also pages from — so this KPI and that list agree. Exact to ±1 vs accounts FINAL, modulo the ~2-minute MV refresh. Safe to render as a total.

total_contractsinteger required

Indexed Soroban contract count: count() FROM soroban_contracts FINAL. Exact — FINAL is affordable on a table this size.

tps_60snumber double required

Transactions per second over a 60s rolling window. Computed as SUM(ledgers.transaction_count) divided by the actual span between MIN/MAX closed_at in the window. Stable on partial / single-ledger windows (NULLIF guards zero-span).

Changes

No recorded changes to this operation across all 50 revisions of this API.