Hydra Protocol Versions

Hydra SDK talks to a hydra-node, and the node follows the Hydra Head protocol's own release cycle. This page tracks that cycle and which node versions the SDK supports.

Version timeline

v1.3.0 — Stable v1 line

1.3.0 is the largest and most stable release in the v1 line, and is fully supported by @hydra-sdk/bridge. Highlights relevant to SDK integrations:

• ~4× cheaper fees for init / open and related on-chain transactions, thanks to improved fee estimation.
• Out-of-sync protection (breaking) — the node now rejects inputs while it is behind the chain, surfacing NodeUnsynced / NodeSynced state. Client code should wait for NodeSynced before submitting.
• Richer Greetings (breaking) — the greeting message now carries currentSlot and sync status; @hydra-sdk/bridge reads these extended fields.
• Longer contestation period (breaking) — defaultContestationPeriod changed from 10 minutes to 12 hours, which affects how long closing a head takes.
• Bounded transactions per snapshot and fixes for deposits/decommits across chain rollbacks.

Compatible tooling: cardano-node 10.6.2 · cardano-cli 10.15.0.0 · mithril 2524.0

Everything below describes the V2 line. It changes the head lifecycle and on-chain scripts; V2 stabilized with 2.2.0.

2.0.0 — Protocol simplification

Remove commit phase — directly open heads

The most fundamental change in Hydra V2: the commit phase is removed. In V1, opening a head required all participants to commit UTxOs during an initialization phase (Init → Commit → CollectCom). In V2:

• Heads open directly after initialization — no commit, collectCom, or abort transactions.
• Funds are added incrementally via deposit transactions while the head is already open.
• This decision is documented in ADR-33.

Benefits:

• Simplified lifecycle: removes the multi-step head opening process, reducing operational complexity.
• Resolved "non-abortable head" issue: previously, a participant committing too large a UTxO could make the head un-abortable. This problem no longer exists.
• Lower costs: eliminating collectCom and abort transactions reduces total on-chain costs for most use cases. See transaction cost benchmarks.

API changes:

• /commit endpoint behavior changes — it now accepts deposit transactions directly since heads open without a prior commit phase.
• Head initialization endpoint (GET /head-initialization) removed.
• All on-chain scripts changed — new script hashes across all networks.

HydraHeadV2 token

The head token name has been upgraded from HydraHeadV1 to HydraHeadV2. This ensures version differentiation and prevents interaction between V1 and V2 heads — code that identifies heads on L1 by token name must be updated.

Era-aware Plutus scripts

L2 ledger Globals now uses era-aware EpochInfo queried from the blockchain instead of fixedEpochInfo, ensuring correct POSIXTime values for time-sensitive Plutus scripts on multi-era chains (mainnet/testnet).

Snapshot & deposit fixes

2.1.0 — Persistence & resilience

SQLite-backed event store

File-based persistence (the append-only JSON state file) is replaced with a SQLite-backed event store (hydra.db):

• Events are persisted in <persistence-dir>/hydra.db.
• On first startup after upgrading, existing state files are automatically migrated into hydra.db and renamed to state.migrated.
• Startup and recovery performance improve significantly.

Deposit security hardening

The deposit Plutus validator has been hardened against malformed increment transactions, closing a security gap in on-chain deposit handling.

Snapshot latency improvement

Snapshot confirmation latency is reduced by ~7% on average by caching pre-computed signable bytes in SeenSnapshot. This avoids repeated UTxO serialization and hashing on every AckSn verification during signing rounds.

Blockfrost error resilience

Transient chain-following errors in the Blockfrost backend (DecodeError, MissingNextBlockHash, etc.) are now retried with exponential backoff instead of crashing the node.

Other changes

• List replaced with Seq to speed up transaction processing in certain operations.
• Several StateChanged event fields were renamed or removed (see breaking changes below).
• Upgraded to cardano-node protocol version 12+.

Compatible tooling: cardano-node 11.0.1 · cardano-cli 11.0.0 · mithril 2617

2.2.0 — Partial fanout & cheaper L2

This is the current stable V2 release.

Partial fanout — no more per-head UTxO ceiling

Until now, the number of UTxOs a head could hold was effectively capped by what fit in a single fanout transaction. Partial fanout removes that limit:

• A head with an arbitrarily large UTxO set is closed out across multiple steps — each PartialFanoutTx distributes as many outputs as fit in one transaction, and a final FinalPartialFanoutTx burns the head tokens to complete the process.
• Every step is verified on-chain with a BLS accumulator membership proof.
• The chunk size is determined dynamically (binary search over valid sizes) rather than by a hard-coded limit.

This resolves the conservative-deposit caveat from V2's early releases.

Cheaper L2 transactions

utxoCostPerByte is set to zero on L2, so a NewTx can be submitted with as little as 1 lovelace — lowering the cost of transacting inside a head.

Revamped hydra-tui

A substantially revised hydra-tui: pending-deposit recovery from Open and Closed/Final states, a dark/light theme toggle persisted to config, an event-history filter (all vs errors only), and tab navigation.

Correctness & performance fixes

• Fixed replaying persisted events from a previous head corrupting the state of a newly opened head.
• Fixed a recovered incremental-commit deposit reappearing in the L2 UTxO after sideloading a snapshot (which made the same UTxO spendable on L1 and L2 at once).
• Added a mustNotMintOrBurn guard to the Increment and Decrement validator transitions.
• Reduced on-disk event-store growth by dropping redundant newLocalUTxO fields (post-tx UTxO is recomputed arithmetically).
• Lazy Map replaced with strict Map to improve memory usage.

Compatible tooling: cardano-node 11.0.1 · cardano-cli 11.0.0 · mithril 2617

Breaking changes summary (V2)

2.1.0 — StateChanged event schema

2.2.0 — Fanout & UTxO fields

Hydra script hashes

On-chain scripts have new hashes with each protocol change. For the v1.3.0 and V2 lines (both supported by the bridge):

2.2.0 publishes two script hashes per network because partial fanout adds the accumulator script. Always confirm the full hashes against the networks.json for your exact node version.

Migrating a node from V1 to V2

V1 → V2 is a breaking, one-way change at the protocol level — different protocol, token, and scripts, with no backward compatibility between a V1 and a V2 node. @hydra-sdk/bridge supports both lines, so no SDK change is required; when you switch a node from V1 to V2:

1. Close all active heads before upgrading the node.
2. Update script references — all hydra script hashes changed; update your network/script configuration.
3. Update API consumers — adjust client code for the new StateChanged event schema, the HeadIsFinalized/ClosedState field changes, and the removed head-initialization endpoint.
4. Adapt the deposit workflow — replace the commit-then-open pattern with direct-open-then-deposit.
5. Verify the persistence directory — existing state files are auto-migrated to SQLite on first startup.
6. Upgrade companion tools — cardano-node >= 11.0.1, cardano-cli >= 11.0.0, mithril >= 2617.

References

• ADR-33 — Directly Open Heads
• Transaction Cost Benchmarks
• GitHub Releases
• Full Changelog
• Hydra Head Protocol Documentation