Skip to content

[FR] cardano-testnet: add a status command #6691

Description

@palas

Part of #6687 (subtask 2 of 2). Depends on the manifest sub-issue.

Problem

There is no way to ask a running testnet "are you alive?". A dead node is silent (nothing
monitors the child processes after startup), and a chain stall (#5762) is only visible by
reading logs. Consumers write their own polling loops.

Proposal

cardano-testnet status [--output-dir DIR] [--json] [--timeout SECONDS]

Same --output-dir flag and ./testnet default as the cardano command. Read-only, always
terminates (per-node timeout, default 5s). It reads manifest.json, then asks every node
for its chain tip over its socket (getLocalChainTip — the same lightweight query the
chain watchdog polls with), and reports:

Per node: ok (fresh tip) / stalled (answers, no fresh tip) / unreachable (no answer,
process alive or unknown) / down (no answer, process known dead). The PID check is only a
hint; the socket answer decides.

A tip is "fresh" when younger than max(60s, 2 x forecast horizon) — the same threshold the
chain watchdog already uses for "chain dead" (60s at default settings; status applies it to
the tip's age in one snapshot). One shared number, no new magic value. A node answering
"no blocks yet" (tip at genesis) counts as stalled.

Network state and exit code (answers "what if one node is unhealthy?"):

state rule exit
RUNNING every node ok 0
DEGRADED chain producing (>= 1 node ok), some node not 0
STALLED nodes answer, no fresh tip anywhere 3
STOPPED no node answers 4
NO-TESTNET no manifest.json in the directory (+ hint) 5

Exit 0 = "the chain is producing blocks" (the rule from #6687), so
cardano-testnet status && run-tests works, even when a relay died. Exit 1 stays what it
already means everywhere: the command itself failed. Strict "all healthy" checks use the
JSON field status == "running".

--json prints one stable object (schemaVersion'd like the manifest, schema in the repo):
overall status, best tip (slot/block/hash/age), and the per-node list with tips and ages.
Polling status until exit 0 is the intended "wait until ready" loop (NO-TESTNET covers
the not-started-yet window; the manifest only appears once the network is ready).

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

type: enhancementAn improvement on the existing functionality

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions