Documentation

The three ports a hydra-node binds: API, peer-to-peer listen, and the optional Prometheus monitoring endpoint. Callers allocate these via allocateHydraNodePorts (or pre-allocate a full cluster) and thread them through prepareHydraNode / withHydraNode.

Allocate ports for every node in a cluster up front. The returned map must be passed to every prepareHydraNode / withHydraNode call for nodes in this cluster so peers can be addressed correctly.

Listen ports are taken via randomUnusedTCPPortsWithDerived so each listen port's derived etcd client port — peerPortToClientPort — is actually held bound at allocation time. That defends against two failure modes: an unrelated process on the host occupying the derived port (which a plain randomUnusedTCPPorts would not catch and which explodes as EADDRINUSE the moment etcd starts), and an unlucky draw where the derived port lands on top of another node's api/monitoring port (which used to make the GRPC client talk to Warp instead of etcd).

Api and monitoring ports are then acquired in a second batch and checked to be disjoint from both the listen ports and the derived client ports; on collision we retry that second batch.

Get the protocol-parameters from the hydra-node.

Get the latest snapshot from the hydra-node. NOTE: While we usually avoid parsing responses using the same data types as the system under test, this parses the response as a ConfirmedSnapshot type as we often need to pick it apart.

Get the latest snapshot UTxO from the hydra-node. NOTE: While we usually avoid parsing responses using the same data types as the system under test, this parses the response as a UTxO type as we often need to pick it apart.

Create an input as expected by send.

Create an output as expected by waitFor and waitForAll.

Submit a decommit transaction to the hydra-node.

Prepare RunOptions to run a hydra-node with given ChainConfig and using the config from config/.

The nodePorts map must contain an entry for this hydraNodeId and for every peer this node should connect to. Use allocateHydraNodePortsFor to build it for a cluster, or allocateHydraNodePorts + a singleton map for a standalone node.

Helper to make it easy to obtain a commit tx using some wallet utxo

failAfter with the budget scaled like scaleWaitTime. Use for whole-test backstops in end-to-end tests.

Wait some time for a single API server output from each of given nodes. This function waits for delay seconds for message expected to be seen by all given nodes.

Wait up to some delay for some JSON Value to match given function.

This is a generalisation of waitMatch to multiple nodes.

Wait for the node's confirmed snapshot to hold exactly the given UTxO.

NOTE: snapshotutxo serves the latest confirmed snapshot, which can still predate an increment or decommit just after its finalisation event. Sampling it once therefore races on a slow machine, reporting the UTxO as it was one snapshot ago. The last value seen is kept so that a genuine mismatch is still reported as a mismatch, rather than as a bare timeout.

Wait up to some time for an API server output to match the given predicate. The budget is scaled to the environment, see scaleWaitTime.

Run a hydra-node just like withHydraNode; but before running any action, observe a Greetings message with the node in sync first. NOTE that importantly, any messages seen BEFORE we observe this will be lost; i.e. unobservable by subsequent waitFors.

See prepareHydraNode for how to build the port map.

Run a hydra-node with given ChainConfig and using the config from config and catching up with chain backend/.

Run a hydra-node with given RunOptions.

Like withPreparedHydraNode but with extra environment entries for the hydra-node process (also inherited by its etcd child). Use this instead of a process-global setEnv, which would leak into every other concurrently spawned node.

Convenience: run a single hydra-node with no peers and freshly allocated dynamic ports. Equivalent to withHydraNode with a singleton port map.

Convenience: withHydraNodeCatchingUp for a single node with freshly allocated dynamic ports.

Run a hydra-node with given ChainConfig and using the config from config/, but, importantly, do NOT wait for the sync status to be reported.

Convenience: withUnsyncedHydraNode for a single node with freshly allocated dynamic ports.

Scale a wait budget to the environment. Blockfrost runs triple it (the follower observes ~1 block behind tip plus one poll interval, on a network with much longer block times than the devnet timings most waits are written for) and HYDRA_TEST_WAIT_MULTIPLIER multiplies further; CI sets it to compensate for slow shared runners, local runs default to 1. Only failure latency is affected: a passing wait returns as soon as its message arrives.

Budgets get a constant floor: the many N * blockTime waits come to well under a second on the 0.1s devnet, underestimating the fixed costs they also cover (tx submission, observation, node processing). Sub-second waits fired exactly when several suites shared one machine.

Wait some time for a list of outputs from each of given nodes. This function is the generalised version of waitFor, allowing several messages to be waited for and received in any order.

Wait up to some time and succeed if no API server output matches the given predicate. The window is deliberately NOT scaled by scaleWaitTime: the timeout here is the success path, so scaling it would slow every passing run.

Like waitMatch but with the given wall-clock budget, unscaled.

Like withHydraCluster but connecting each node's API client with the given query string (e.g. "/?history=yes&snapshot-utxo=no") instead of the default "/?history=yes", and adjusting each node's RunOptions (e.g. to disable logging) before it is started.

Like withHydraNode but connecting the API client with the given query string instead of the default "/?history=yes", and adjusting the node's RunOptions before it is started.

Allocate three unused TCP ports from the OS for a single hydra-node.

Process-global cache mapping each (workDir, nodeId) to its allocated ports. The cache exists because restart-style tests (re-running withSoloHydraNode or similar against the same workDir) depend on etcd's persistent cluster state, which is keyed by the listen URL. If a restart picked fresh ports, etcd would refuse to start.

Allocate ports for a single hydra-node, memoizing the result for the given (workDir, nodeId) so that subsequent calls reuse the same ports.

Prepare protocol-parameters to run a hydra-node with given ChainConfig and using the config from config/.

Like withPreparedHydraNode but connecting the API client with the given query string instead of the default "/?history=yes".