IntersectMBO / IntersectMBO/cardano-node
[FR] cardano-testnet: write a machine-readable manifest.json on startup
- Dominant language
- Haskell
- Stars
- 3.2k
- Forks
- 754
- Avg merge
- 4d 20h
- Merged PRs (30d)
- 20
Description
Part of #6687 (subtask 1 of 2). Delivers the structured output asked for in #5848.
## Problem
When the network starts, cardano-testnet knows every socket, port and key path, but only
prints them as log text. Consumers re-discover them by scanning the directory layout:
cardano-transaction-lib parses `socket/node1/sock`, `node-data/nodeN/port` and
`utxo-keys/utxoN/utxo.skey`; our own bench/tx-generator does the same in
`TestnetDiscovery.hs`, which even carries a comment asking for a metadata file.
## Proposal
After the existing readiness checks pass (block no. >= 1 on every node, SPOs visible in the
ledger), and right before the "Testnet started" log line, write `/manifest.json`:
- `schemaVersion` (starts at 1), `createdAt`, `cardanoTestnetVersion`
- `network`: `magic`, `era`, `systemStart`
- `paths`: node config file, the five genesis files
- `nodes[]`: `name`, `role` ("spo"/"relay"), `host`, `port`, `socketPath`, `grpc`
(null when disabled; otherwise transport + endpoint), `pid` (nullable), `pidFile`,
`topologyFile`, `stdoutFile`, `stderrFile`
- `wallets[]`: the funded utxo keys — `name`, bech32 `address`, `signingKeyFile`,
`verificationKeyFile`
Rules:
1. All paths are relative to the manifest's own directory. Exception: a value starting with
`\\.\pipe\` is a Windows named pipe, used as-is. (Relative paths survive moved/mounted
dirs and avoid the ~108-char unix socket path limit.)
2. Written atomically (temp file + rename). Readers never see a partial file.
3. Written once, never modified. The file appearing IS the ready signal; health questions
are the status command's job (follow-up issue).
4. The run command deletes any pre-existing manifest.json before starting nodes, so a
waiting script can never read a stale one.
5. Stability: the manifest is the supported interface; the rest of the directory layout
stays free to change. Additive changes only within a schemaVersion; removals/renames
bump it. A JSON Schema (draft 2020-12, like bench/trace-schemas/) lives in the repo.
A golden test pins the writer's output, and the golden sample is validated against the
schema with check-jsonschema (the validator bench/trace-schemas already uses), so the
writer, the sample and the schema cannot drift apart.
Contributor guide
Assessment
This issue has not been assessed yet.