IntersectMBO / IntersectMBO/cardano-node
[FR] cardano-testnet: add a status command
- Dominant language
- Haskell
- Stars
- 3.2k
- Forks
- 754
- Avg merge
- 4d 20h
- Merged PRs (30d)
- 20
Description
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).
Contributor guide
Assessment
This issue has not been assessed yet.