IntersectMBO / IntersectMBO/cardano-node

[FR] cardano-testnet: add a status command

Open
#6,691 0 comments 0 reactions 1 assignee Claimed by @palas View on GitHub
type: enhancement
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.