Documentation

Lookup a config file similar reading a file from disk. If the env variable HYDRA_CONFIG_DIR is set, filenames will be resolved relative to its value otherwise they will be looked up in the package's data path.

Get the "well-known" keys for given actor. The signing key is Secret-wrapped so callers cannot accidentally log or serialise it.

Create and save new signing key at the provided path, returning the key Secret-wrapped. NOTE: Uses TextEnvelope format.

Expected time between blocks (on average)

Timing parameters that determine the behavior of a (cluster of) hydra-node.

Truncate a duration to a whole-second DepositPeriod.

Set up reasonable timing parameters for testing given a BlockTime.

Like mkTestTiming but scales Timing by the number of concurrent deposits expected. Each increment tx must be processed sequentially on-chain, so N concurrent deposits require N times the base deposit period.

Timing for the smoke test run by the hydra-cluster executable against a public network, where a block takes ~20s and the run is dominated by waiting out Timing rather than by anything the scenario asserts.

A deposit becomes active at created + depositActivation, where created is the deposit tx's upper validity bound, set a grace time ahead of the chain tip by draftDepositTx. That grace time caps at min maxGraceTime (depositPeriod / 2), 200s here, so the wait is 200 + depositActivation and only the second term is ours: at one block time it drops from 200 + 400 to 200 + 20.

Timing is cut to the point where the close transaction's validity window stops changing, and no further. The contestation deadline is closeTxUpperBound + contestationPeriod with the close tx bounded at now + min contestationPeriod maxGraceTime, so at 10 * blockTime = 200s the wait halves from 600s to 400s while that min still yields 200s, exactly as it does at mkTestTiming's 400s. Going below 200s would start shortening the window every close, contest and increment has to be included in, with no resubmit on expiry, and would drag two things with it: the derived unsyncedPeriod (half the contestation period, against a Blockfrost follower that only observes blocks with a successor and so lags a block gap by construction) and submissionRetryPolicy, whose ~180s worst case is documented against a 200s window.

Timing keeps its mkTestTiming value. It is not on the critical path -- it sets how long a deposit stays active, not how long anything waits -- and shortening it only shrinks windows: the grace time is capped at half of it, so both the deposit tx's validity and the active window depositPeriod - graceTime fall with it. UtilSpec guards the value used here.

Get a timeout until a deposit should have happened given a Timing. A deposit becomes active after Timing and then needs about one Timing to be picked up and incremented, so both are accounted for (with the defaults where they are equal this is 2 * depositPeriod).

The slack term covers the two on-chain round trips (deposit and increment: submit, include, observe) plus multi-node processing. Those costs are dominated by fixed latencies, not by block time, so the slack has a constant floor; with the devnet's 0.1s blocks a pure 5 * blockTime came to 0.5s and timed out regularly on loaded CI runners.

Budget for observing the effect of one L1 transaction on the API: submission, block inclusion, chain-follower observation and node processing. The constant floor covers the fixed latencies, which dominate at devnet block times; a pure blockTime multiple (e.g. a literal 3s) fired regularly on loaded CI runners.

Budget for a hydra-node (re)start up to its Greetings. Process spawn, etcd bootstrap and websocket connect are fixed costs, unrelated to block time, so this is a constant.

Create a (test) chain config for a given actor.