cardano-testnet: Add --nodes flag for per-node binary configuration

[palas]

Description

Adds a --nodes CLI flag to cardano-testnet that allows specifying the role (SPO or relay) and optionally a custom cardano-node binary for each node in the testnet. This enables running testnets with mixed node versions, which is needed for testing compatibility across node releases.

The new flag coexists with the existing --num-pool-nodes via <|> in the parser, so either can be used:

--nodes spo,spo:node-bin=/path/to/custom-node,relay,relay
--num-pool-nodes 3   # unchanged, still works

At creation time, custom binaries are validated by running --version and the result is recorded in a YAML env file (node-data/nodeN/env). At runtime, the env file is read to resolve the binary, falling back to the default resolution when no env file exists.

Base PR: #6563 (enforces SPOs come first and splits node list into SPO and relay)

Checklist

• Commit sequence broadly makes sense and commits have useful messages
• New tests are added if needed and existing tests are updated. These may include:
  • golden tests
  • property tests
  • roundtrip tests
  • integration tests
    See Running tests for more details
• Any changes are noted in the CHANGELOG.md for affected package
• The version bounds in .cabal files are updated
• CI passes. See note on CI. The following CI checks are required:
  • Code is linted with hlint. See .github/workflows/check-hlint.yml to get the hlint version
  • Code is formatted with stylish-haskell. See .github/workflows/stylish-haskell.yml to get the stylish-haskell version
  • Code builds on Linux, MacOS and Windows for ghc-9.6 and ghc-9.12
• Self-reviewed the diff

[carbolymer]

Exception handling is most important here

[Copilot]

Pull request overview

Adds per-node configuration support to cardano-testnet via a new --nodes CLI flag, allowing each node to be designated as SPO/relay and optionally pinned to a specific cardano-node binary (recorded in the generated env and reused when starting from --node-env).

Changes:

• Introduces --nodes SPEC[,SPEC...] parsing (with role ordering validation and optional node-bin= path) and updates CLI help golden files.
• Extends testnet node configuration types to carry an optional per-node binary path, and persists that choice into node-data/nodeN/env.
• Updates node startup to optionally use a custom binary via a new procCustom helper and a startNode signature change.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
cardano-testnet/test/cardano-testnet-test/Cardano/Testnet/Test/Node/Shutdown.hs	Updates test to new node options type (NodeWithOptions).
cardano-testnet/test/cardano-testnet-test/Cardano/Testnet/Test/Gov/ProposeNewConstitutionSPO.hs	Updates test to new node options type (NodeWithOptions).
cardano-testnet/test/cardano-testnet-test/Cardano/Testnet/Test/Cli/LeadershipSchedule.hs	Updates test node creation + startNode call to pass optional custom binary.
cardano-testnet/test/cardano-testnet-test/Cardano/Testnet/Test/Cli/KesPeriodInfo.hs	Updates startNode call to pass optional custom binary.
cardano-testnet/test/cardano-testnet-golden/files/golden/help/create-env.cli	Updates golden help output to document --nodes.
cardano-testnet/test/cardano-testnet-golden/files/golden/help/cardano.cli	Updates golden help output to document --nodes.
cardano-testnet/test/cardano-testnet-golden/files/golden/help.cli	Updates top-level golden help usage to show --nodes alternative.
cardano-testnet/src/Testnet/Start/Types.hs	Replaces exported node option types with NodeWithOptions/TestnetNodesWithOptions and adds nodeBin.
cardano-testnet/src/Testnet/Start/Cardano.hs	Writes/reads per-node env YAML for custom binaries; threads nodeBin into node startup.
cardano-testnet/src/Testnet/Runtime.hs	Extends startNode to accept an optional custom node binary.
cardano-testnet/src/Testnet/Process/RunIO.hs	Adds procCustom helper for running an explicitly provided binary path.
cardano-testnet/src/Parsers/Run.hs	Uses new readNodesWithOptionsFromEnv reader.
cardano-testnet/src/Parsers/Cardano.hs	Adds --nodes flag and Parsec-based parseNodeSpecs implementation.
cardano-testnet/src/Cardano/Testnet.hs	Updates re-exports to the renamed node options API.
cardano-testnet/changelog.d/20260506_035740_palas_testnet_specify_node_bin_per_node.md	Adds changelog entry for --nodes.
cardano-testnet/cardano-testnet.cabal	Adds parsec dependency for --nodes parsing.
cardano-node/src/Cardano/Node/Testnet/Paths.hs	Adds defaultNodeEnvFile path helper.
cardano-node-chairman/test/Spec/Chairman/Cardano.hs	Updates chairman test to use the new default node options value.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[palas]

Addressed in: 9ff2ba9

[Jimbo4350]

LGTM; suggested some minor changes. Will have another look after changes/discussion.

[Jimbo4350]

This needs to exist in documentation somewhere it can't only be in the help text.

[Jimbo4350]

Why? Does the order actually matter or is it a matter of the presence of SPOs? Can you also separate the parsing and validation logic here?

[palas]

We have several options, but I thought this was the least problematic one. For example, we could:

• Allow random orderings: but that would affect a lot of code that assumes SPOs go before relays, this wasn't a problem before because you couldn't specify, also we would need to store a mapping between pools and nodes, which currently are just folders numbered with consecutive numbers starting in 1.
• Sort them before generating the config: but I think that would be misleading. For example, if someone writes relay,relay,spo,relay, we could silently do node1=spo, node2=relay, node3=relay, node4=relay, but I think that would break the users expectations.
• Complain when spos are not the first nodes: this forces the user to reorder and avoids the false expectation. Also, it allows us to not have to modify the rest of the code. And it has another very good advantage, we can easily enforce that there is at least one spo by just using a pair (spo=NEL NodeWithOptions, relay=[NodeWithOptions]). If we don't ensure that SPO nodes go first, this becomes tricker.

So I thought the last one (complaining) was the best approach.

About parsing versus validation: I can do that, but I think it is a bad idea, because:

• As it is, it is impossible to "forget" to validate, and that is very good. In fact, I already forgot validating in one place last week and copilot caught it.
• The types already enforce what is being validated, so we would need to introduce a new intermediate type that doesn't enforce it for it to be returned by the parser.

Also it goes against the idea of "parse, don't validate".