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).
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
Same
--output-dirflag and./testnetdefault as thecardanocommand. Read-only, alwaysterminates (per-node timeout, default 5s). It reads
manifest.json, then asks every nodefor its chain tip over its socket (
getLocalChainTip— the same lightweight query thechain 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 ahint; 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?"):
Exit 0 = "the chain is producing blocks" (the rule from #6687), so
cardano-testnet status && run-testsworks, even when a relay died. Exit 1 stays what italready means everywhere: the command itself failed. Strict "all healthy" checks use the
JSON field
status == "running".--jsonprints 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
statusuntil exit 0 is the intended "wait until ready" loop (NO-TESTNET coversthe not-started-yet window; the manifest only appears once the network is ready).