IntersectMBO / IntersectMBO/cardano-node

[FR] cardano-testnet: write a machine-readable manifest.json on startup

Open
#6,690 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 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

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.