Known issues and limitations

Before running a Hydra node on the Cardano mainnet, it is important to be aware of several known issues and limitations. Operating a Hydra node requires a deep understanding of the underlying infrastructure, and you may risk your funds if you are unfamiliar with the implementation and usage processes.

Head protocol limits

Due to the limitations on transaction sizes and execution budgets on Cardano, the Hydra protocol has the following constraints:

• The protocol can only handle a maximum number of participants in a head. When attempting to configure too many peers, the Hydra node will inform you of the current configured maximum.

Currently, participants may be denied access to their funds by other protocol participants at different stages within a Hydra head because of the complexity or size of the UTXO being deposited or created while the head is open:

• The Hydra head cannot be finalized if it holds more than approximately 40 UTxOs (see the cost of FanOut transaction for latest numbers), although it can be closed
• Tokens that are minted and not burned within an open Hydra head will prevent the head from being finalized

See these resources for additional information about reducing the risk of locking up funds in a Hydra head:

• Always abortable head
• Limit size/complexity of UTXOs in the head
• Only sign closable snapshots.

Static topology

The network topology needs to be statically configured and match across all hydra-node instances. Currently this means that the --peer command line options need to match between nodes. Otherwise the etcd node of the networking later will report errors in the logs.

Known errors are:

• cluster ID mismatch - the cluster was initiated with a different list of --peers

  • check configuration with other participants. There should be a corresponding log entry NetworkClusterIDMismatch with the information on:
    • clusterPeers - loaded peers info received from etcd cluster.
    • configuredPeers - peers info coming from hydra-node arguments.

• member ... has already been bootstrapped - missing information in <persistence-dir>/etcd

  • restart your hydra-node with the ETCD_INITIAL_CLUSTER_STATE environment variable set to existing (new is the default), see also https://etcd.io/docs/v3.3/op-guide/configuration/

We should be able to work around these UX issues using etcd discovery eventually.

Auto-compaction (amount of time a peer can be offline)

Because we do not want the hydra-node to take up unbounded disk space, we set a conservative amount of history that the internal etcd process will store.

This can be controlled via environment variables that you can read more about here: Etcd Configuration

Adapting to new breaking changes

If the hydra-node has breaking changes in regards to reading the files it stores in the persistence folder, it used to be recommended to just delete the entire folder.

Now, because of etcd, it is important to only delete the hydra-node specific files; not the files associated with etcd. In particular you may like to delete the following files:

• persistence/state*

Note that, as with any adjustments of this kind, it is good practice to make a backup first!

Training wheels

The following restrictions apply when depositing funds into a Hydra head (via POST /commit):

• Byron addresses are not supported. Any UTxO held at a Byron-era address will be rejected with an error. Only Shelley-era (and later) addresses are accepted.
• Mainnet ADA recommendation. When running on mainnet, we recommend only up to 100 ADA be deposited into a Hydra head in a single deposit transaction. This is a recommendation only, and we will lift it once we implement partial fanout.

Deposit periods

The --deposit-period allows an individual hydra-node operator to decide how long they want a deposit to have settled at least. However, differences bigger than defaultTTL * waitDelay (currently 10 minutes) result in non-approved snapshots. This is due to the way the HeadLogic is implemented and snapshot requests are not retried currently. See hydra#1999 for more context.

Known bugs

Refer to the project repository issue tracker for known issues. If you discover any security-relevant problems, please follow our security policy.