Skip to main content
User manualDeveloper documentation
TopologiesUse casesFAQs

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 (see the cost of CollectCom transaction). 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 committed or created while the head is open:

  • The Hydra head cannot be finalized if it holds more than approximately 80 assets (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
  • If one or more participants commit UTXOs that are too large to be processed together in a CollectCom or Abort transaction, the Hydra head will remain stuck in the initialising stage.

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

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

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

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 file:

  • persistence/state

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

Training wheels​

There is a hard-coded limit on the mainnet where only up to 100 ada can be committed into the Hydra head. This is a safety precaution and will be increased as more experience is gained in running Hydra heads on the mainnet.

Known bugs​

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