CIP-42: Standardized Daemon Status (/statusz)

​

Abstract

​

Background

​

Specification

​

Endpoint

​

Envelope

{
  "system": "cbfs-relay",
  "version": "0.3.1",
  "network": "mesa",
  "status": "healthy",
  "uptime_seconds": 86400,
  "boot_id": 17293822569102704642,
  "counters": { "blob_uploads_total": 12034 },
  "gauges":   { "store_used_bytes": 1073741824, "store_capacity_bytes": 10737418240 }
}

• system — one of node, indexer, cbfs-relay, cbssd, cbqsd, runner. Reports self-identify: a consumer polls a URL list and buckets by this field, so fleets (relays, runners) need no per-instance config.
• version — build version string; display-only, daemon’s choice of format.
• network — the network the daemon believes it is on (e.g. mesa, canyon, local). Empty string is the defined sentinel for “this daemon does not know its network”; consumers display it as absent, never as a network named "".
• status — the daemon’s judgment of its own duty: healthy | degraded | unhealthy are the only values a daemon emits (a cbqsd that cannot read finalized chain state is unhealthy; a runner missing three heartbeats is degraded). unreachable is a poller judgment and never appears on the wire. A fourth wire value, unknown, exists as reader vocabulary: both wire enums carry a #[serde(other)] Unknown fallback, so an unrecognized string buckets instead of failing the report — and a bucketed report re-serialized through the typed struct legally emits the literal "unknown". Strict validators MUST accept it. Consumers MUST NOT re-serialize a bucketed report as if it were the original (the source string is not preserved); forward raw bytes instead. When merging judgments from multiple sources, the worse one wins, in the order healthy < degraded < unhealthy; an unrecognized status MUST be treated as at least as severe as degraded.
• uptime_seconds — seconds since the daemon started.
• boot_id — random per-process identity, generated once at startup. Counter deltas are only meaningful within one boot_id: a restart that re-reaches its old count, or a load balancer swapping the instance behind the URL, presents as an increase that no decrease rule can catch. Pollers MUST skip the delta interval whenever boot_id changes. 0 is the sentinel for a daemon that predates the field; pollers then fall back to decrease-only detection.
• counters — monotonic series: never decreasing within one boot_id. Most are process-lifetime totals; an externally monotonic series (e.g. chain height) is also a valid counter — it just keeps climbing across boots. Daemons never compute rates for this endpoint; pollers derive activity from deltas between their own ticks, scoped to one boot_id. A decrease within one boot_id MUST be treated as a reset (skip the interval, never compute an underflowed delta).
• gauges — integer (u64) point-in-time values, possibly the daemon’s most recent cached observation (e.g. a chain probe on its own cadence) — the poll interval, not the envelope, bounds staleness. Every declared gauge is a discrete integer quantity (counts, bytes, seconds, heights, epochs); f64 is excluded because a non-finite value serializes to JSON null and poisons the report parse exactly when a daemon is in trouble, and byte counters lose precision above 2^53.
• detail — free-form system-specific JSON for drill-downs; it may evolve without an envelope change. Omitted from the JSON when the daemon has none (readers of the typed struct see Value::Null either way).

​

Transport

​

Compatibility

​

Security considerations

• Information disclosure. The envelope necessarily carries version and uptime_seconds — exactly the pair COW-762 withholds from the validator’s public surface, because build fingerprints and restart timing aid targeting of consensus nodes. Hence the validator row is dev-mode-only: in production the route is not registered at all, and public consumers use the chain view. For non-consensus daemons the same pair is less sensitive but not free: the default posture is loopback (cbfs relay, cbssd, runner). The two deliberate exceptions are the indexer, whose entire surface is already public read and whose operator accepts version disclosure as part of running a public archive, and cbqsd, whose broker listener is an operator-run, TLS-terminated service endpoint — its report adds traffic counters, never queue contents or key material. cbssd’s gauges (shares_held, committee_epoch) reveal committee participation shape, which is why its row is loopback-only with a MUST-refuse bind check.
• Denial of service. Handlers MUST be cheap reads of in-process state (atomic counters, cached observations, a small directory listing) and MUST NOT perform network calls on the request path. Public rows inherit whatever rate limiting their listener already carries.
• Fail-closed bind checks. Where the endpoint table says loopback only, the implementation MUST enforce it in code (refuse the bind or conditionally mount), not in deployment convention; cbssd’s existing refusal is the reference behavior.

​

Implementation status