0.10.0

First release of hydra-node and hydra-plutus scripts which can be used on mainnet. Includes the technical changes required and must-have issues we want to see fixed before using a Hydra Head with real ADA, as well as documentation how to run hydra on mainnet.

⚠️ IMPORTANT: There are several known issues, which are explained in the documentation.

---

Built artifacts

• 📦 Static x86_64-linux binaries: here (also attached)
• 🐳 Docker image: here

Hydra Scripts

Transaction IDs to be used as --hydra-scripts-tx-id when running hydra-node on the following networks:

• preview: d237926e174a2ca386174a5810d30f0ca6db352219dd7eacdc7d5969ae75d58f checked in smoke test #111
• preprod: 31b833c943fc267ee532c772be032183d5842b69492afaf5daa360171168c238 checked in smoke test #112
• mainnet: af1a00e23a9b5c3a811d5c265dd25edfc81fd43f0fbf94229c4c0a5ab18aa5de checked in smoke test #113 🎉

---

This release contains several breaking changes and you'll need to apply the following procedure to upgrade all the nodes running a head:

1. Close the head
2. Stop hydra-node
3. Remove persistent files stored in --persistence-dir, in particular
   server-output and state
4. Upgrade hydra-node version
5. Start new hydra-node version

Only when this procedure has been applied to all Hydra nodes can you open a new head again.

---

• Make hydra-node compatible to mainnet #713

  • BREAKING Change to command line options: Replaced --network-id with --mainnet or --testnet-magic.

  • Hard-coded temporary limit of 100 ADA for commits to a head on mainnet. This will be incraeased or be made configurable in future versions.

• BREAKING Change in internal handling of rollbacks. Now, the hydra-node does only rollback it's low level state and not report when a rollback happened, under the optimistic assumption that the Hydra protocol transactions are still applicable and the Head is unaffected by the rollback. This was needed to avoid #784 and will be further improved in #185. This removes RolledBack server output from the API and also changes the log format of the internal Rollback event.

• Reject commits of UTxO containing ReferenceScript to avoid a head not being finalizable by the hydra-node. The layer 1 scripts still accept these outputs, but we would not be able to automatically finalize a head which was opened from commits with reference scripts. Reference scripts on the layer 2 ledger (e.g. included in transactions via NewTx) are non-problematic. #766

• All participants try to collect once seeing the last commitTx. #786 This may lead to misleading errors on the logs about not being able to post collect transactions (see also #839).

• The hydra-node detects misconfiguration and mismatch of command line options with persisted state. #764

• Fixed a bug where the hydra-node would crash sometimes when the cardano-node switches onto a fork, which is a common event on mainnet. [#560][560]

• BREAKING Hydra scripts changed, need to use new --hydra-scripts-tx-id

  • Check contract continuity of state machine, i.e. that the output with the state datum and ST is actually owned by vHead. #777

  • Collect the right value in collect transactions (had been dropped for cost reasons, but found a constant cost way to do it).

  • The right headId is enforced in commit transactions.

  • Updated plutus-tx tool-chain. This also resulted in changed return type of validatorScript functions of script modules to SerialisedScript. #826

  • Use of a custom script context for vInitial and vCommit validators to reduce cost of transactions again. #825

  • The hydra scripts are persisted in hydra-plutus/scripts and golden tests ensure they are not changed accidentally. #772

• BREAKING Changes to hydra-node API

  • Configurable API using query parameters. #380 Clients can decide to:

    • Skip observing history of events before they connected
    • View the transactions in the server output encoded as CBOR
    • Prevent utxo display in SnapshotConfirmed server outputs #808

  • Greetings message is now only sent last (after replaying history) on connection and added additional information #813:

    • headStatus - representing current hydra head status
    • snapshotUtxo - containing UTxOs and updating on each SnapshotConfirmed message

  • Updated hydra-tui to handle Greetings message accordingly. Make sure to use the same version.

  • Reference scripts in the hydra-node API (e.g. on NewTx) are not decodable when using SimpleScriptV2 envelope anymore (just use SimpleScript).

• Versioned the documentation website, now the last released, stable is the default available at https://hydra.family/head-protocol, while the bleeding-edge from master branch is available at https://hydra.family/head-protocol/unstable. #803 #805 #783

• Add the specification to the repository and website. #693

• Disabled aarch64-darwin support, until a cardano-node for this platform is also available.

• Use the server-provided timestamp of messages in the hydra-tui. #837

• BREAKING Changes to hydra-cardano-api #826:

  • Removed HasPlutusScriptVersion and plutusScriptVersion with upstream version from cardano-api.
  • Renamed getScriptData to txOutScriptData to not conflict with the new function in cardano-api.
  • Changed toScriptData, toLedgerData, fromLedgerData, txOutScriptData and lookupScriptData to return or require a HashableScriptData instead.
  • Added fromScriptData generic conversion function.
  • Changed signature of totalExecutionCost to be more clearly Babbage era specific.
  • Changed fromPlutusScript to take new SerialisedScript type (it's just an alias now).
  • Added genTxIn and arbitrary instance for TxIn.
  • Added getChainPoint.

Full Changelog: 0.9.0...0.10.0

New Contributors:

• @matiwinnetou made their first contribution in #779

Contributors to this release: @ch1bo @pgrange @v0d1ch @ffakenz @matiwinnetou @abailly-iohk

0.9.0

🐲 We renamed the repository from hydra-poc to hydra!

This release features a hydra-node with fully specified behavior of on-chain hydra-plutus scripts and off-chain head-logic, decreased costs for opening/closing a Head and scalable contestation deadline semantics.

---

⚠️ Delete your persistence directory!

This release contains several breaking changes and you'll need to apply the following procedure to upgrade all the nodes running a head:

1. Close the head
2. Stop hydra-node
3. Remove persistent files stored in --persistence-dir, in particular server-output and state
4. Upgrade hydra-node version
5. Start new hydra-node version

Only when this procedure has been applied to all Hydra nodes can you open a new head again.

---

Changes to hydra-node

• BREAKING Changes in the persistence format #725, #745.

• BREAKING Changes to the API:

  • Removed TxSeen and TxExpired server outputs. Use the TxValid and TxInvalid responses instead.
  • All participants now see TxValid for all valid transactions (it replaces TxSeen).
  • Renamed ReadyToCommit -> HeadIsInitializing
  • Added a headId to most server outputs. #678
  • Added a timestamp and a monotonic sequence number. #618

• BREAKING Addressed short-comings in hydra-plutus scripts #452 and improved their performance / reduced cost #652, #701, #709. Roughly the cost of transactions according to our benchmarks changed:

  • Init increased by 10%.
  • Commit reduced by 50%.
  • Collect reduced by 30%.
  • Close reduced by 0.2-0.3₳
  • Contest reduced by 0.1-0.2₳.
  • Abort reduced by 0.1-0.3₳.
  • Fanout reduced by 0.2-0.3₳.

• BREAKING Change the way contestation period and deadline are handled:

  • There is a new hydra-node flag --contestation-period expressed in seconds to control the close tx validity bounds as well as determine the contestation deadline. For example, with --contestation-period 60s, the node will close the head 60s after submitting the close transaction and other parties will have another 60s to contest. This means the deadline may be up 2 * --contestation-period after a close transaction. #615 and ADR21
  • If hydra-node receives a init transaction with not matching --contestation-period then this tx is ignored which implies that all parties need to agree on the same value for contestation period.
  • Removed contestationPeriod from the Init API request payload.
  • The deadline get's pushed by --contestation-period on each contest transaction. #716

• Change the way the internal wallet initializes its state. #621

  • The internal wallet does now always query ledger state and parameters at the tip. This should fix the AcquireFailure issues.

• Added NoFuelUTXOFound error next to the already existing NotEnoughFuel. Previously the node would fail with NotEnoughFuel when utxo was not found. Now NotEnoughFuel is used when there is not enough fuel and NoFuelUTXOFound when utxo was not to be found.

• Added support have hydra-node to start following the chain from genesis by setting --start-chain-from 0.

• Added script sizes to hydra-node --script-info and published transaction cost benchmarks.

• Changes to the logs:

  • HeadLogic Outcome is now being logged on every protocol step transition.
  • Added intermediate LastSeenSnapshot and extended RequestedSnapshot seen snapshot states.
  • Changed wallet-related logs of BeginInitialize, EndInitialize and added SkipUpdate.

Changes to hydra-cardano-api

• BREAKING Remove Hydra.Cardano.Api.SlotNo module.
• BREAKING Replace fromConsensusPointHF with fromConsensusPointInMode and toConsensusPointHF with toConsensusPointInMode.
• Re-export new AcquiringFailure type from cardano-api.
• Add fromPlutusCurrencySymbol conversion function.
• Introduce new Hydra.Cardano.Api.Pretty module and move functions renderTx, renderTxWithUTxO and renderTxs from hydra-node package to this new module.

Other changes

• hydra-cluster executable can be used to provide a local cardano "network" with --devnet argument

• Switched to using nix flakes and CHaP

  • Makes configuration of binary-caches easier to discover (you get asked about adding them).
  • Will make bumping dependencies (e.g. cardano-node) easier.
  • Build commands for binaries and docker images change, see updated Contribution Guidelines

Full Changelog: 0.8.1...0.9.0

Contributors of this release: @v0d1ch @pgrange @ffakenz @perturbing @andreabedini @abailly-iohk @ch1bo

New Contributors:

• @dermetfan made their first contribution in #625
• @olgahryniuk made their first contribution in #684
• @NetWalker108 made their first contribution in #703
• @perturbing made their first contribution in #731

---

Built artifacts

• 📦 Static x86_64-linux binaries: here (also attached)
• 🐳 Docker image: here

Hydra Scripts

Transaction IDs to be used as --hydra-scripts-tx-id when running hydra-node on the following networks:

• preview: 74b587d08d12aa679bdfeb3eaa57d698e426045dd529d4130d7d8ca0c18d54b0 checked & published in #43
• preprod: 6fd13073c47411af7f3adf31f46e61f570872a832822fdc5da5b214766651bfd checked & published in #44

0.8.1

• BREAKING Implemented ADR18 to keep only a single state:

  • The hydra-node now only uses a single state file in --persistence-dir to keep it's state.
  • The chainState does not include read-only chain context information anymore (is smaller now).
  • Include the chainState in InvalidStateToPost errors.
  • Moved received transaction ids into RolledForward log message.
  • Reduce log size by removing ChainContext. #598

• BREAKING Changed internal wallet logs to help with debugging #600

  • Split ApplyBlock into BeginUpdate and EndUpdate
  • Split InitializedWallet into BeginInitialize and EndInitialize

• After restarting hydra-node, clients will receive the whole history. #580

  • This history will be stored in the server-output file in --persistence-dir.
  • Clients should use Greetings to identify the end of a restart/replay of events.

• Fixed observing the chain for Hydra L1 transactions after restart. 599

• hydra-cardano-api now published on Cardano Haskell Packages (CHaP). #504

---

Built artifacts

• 📦 Static x86_64-linux binaries: here (also attached)
• 🐳 Docker image: here

Hydra Scripts

Transaction IDs to be used as --hydra-scripts-tx-id when running hydra-node on the following networks:

• preview: 4081fab39728fa3c05c0edc4dc7c0e8c45129ca6b2b70bf8600c1203a79d2c6d

0.8.0

• BREAKING Hydra keys now use the text envelope format.

  • hydra-tools executable now produces keys in the same format as cardano keys so this should make key handling simpler.
  • Take a look at the example on how to use hydra-tools to generate necessary hydra keys.

• BREAKING hydra-node command line flag --node-id is now mandatory.

  • Instead of Host we are using the node-id in the server messages like + PeerConnected/Disconnected which are also used in
  • the TUI to distinguish between different connected peers.
  • This also changes the way how NodeIds are represented on the API.

• BREAKING Keep track of contestationDeadline instead of remainingContestationPeriod and fix ReadyToFanout. #483

  • Clients can now rely on ReadyToFanout, such that sending a Fanout input after seeing this output will never be "too early".
  • The HeadIsClosed server output now contains the deadline instead of the remaining time.
  • See hydra-tui for an example how to use the contestationDeadline and ReadyToFanout.
  • See ADR20 for details and the rationale.

• BREAKING Several changes to the API:

  • The InitialSnapshot only contains the initialUTxO as the rest of the information was useless. #533
  • Renamed CannotSpendInput -> InternalWalletError and CannotCoverFees -> NotEnoughFuel. #582

• BREAKING Changed logs to improve legibility and trace on-chain posting errors. #472

  • Strip chain layer logs to only contain TxId instead of full transactions in the nominal cases.
  • Renamed log entry prefixes Processing -> Begin and Processed -> End.
  • Added PostingFailed log entry.

• BREAKING The hydra-cluster executable (our smoke test) does require --publish-scripts or --hydra-scripts-tx-id now as it may be provided with pre-published hydra scripts.

• The hydra-node does persist L1 and L2 states on disk now: #187

  • New --persistence-dir command line argument to configure location.
  • Writes two JSON files headstate and chainstate to the persistence directory.
  • While introspectable, modification of these files is not recommended.

• Fixed bugs in hydra-node:

  • Crash after 3k blocks because of a failed time conversion. #523
  • Internal wallet was losing memory of spent fuel UTxOs in presence of transaction failures. #525
  • Node does not see some UTxOs sent to the internal wallet on startup. #526
  • Prevent transactions from being resubmitted for application over and over. #485

• Prevent misconfiguration of hydra-node by logging the command line options used and error out when:

  • provided number of Hydra parties exceeds a known working maximum (currently 4)
  • number of provided Cardano and Hydra keys is not the same

• Added a hydra-tools executable, to help with generating Hydra keys and get hold of the marker datum hash. #474

• Compute transaction costs as a "min fee" and report it in the tx-cost benchmark.

• Update hydra-node-options section in docs.

• Publish test results on website. #547

• Improved hydra-tui user experience:

  • Fixed too fast clearing of errors and other feedback #506
  • Introduced a pending state to avoid resubmission of transactions #526
  • Can show full history (scrollable) #577

• Build & publish static Linux x86_64 executables on each release 👇 #546

---

Built artifacts

• 📦 Static x86_64-linux binaries: here (also attached)
• 🐳 Docker image: here

Hydra Scripts

Transaction IDs to be used as --hydra-scripts-tx-id when running hydra-node on the following networks:

• preview: 4081fab39728fa3c05c0edc4dc7c0e8c45129ca6b2b70bf8600c1203a79d2c6d
  published & checked during smoke test run #32 (failing because no PlutusV2 cost model was on the testnet at that time)

0.7.0

• BREAKING Switch to BabbageEra and PlutusV2.

  • hydra-cardano-api now uses Era = BabbageEra and constructs PlutusV2 scripts.
  • hydra-plutus scripts now use the serialiseData builtin to CBOR encode data on-chain.
  • hydra-node now expects BabbageEra blocks and produces BabbageEra transactions.
  • hydra-cluster now spins up a stake pool instead of a BFT node (not possible in Praos anymore).
  • As a consequence, the Hydra scripts in hydra-plutus have now different script hashes.

• BREAKING Use reference inputs and reference scripts in abort transaction.

  • Need to provide a --hydra-scripts-tx-id to the hydra-node containing the current (--script-info) Hydra scripts.
  • Added the publish-scripts sub-command to hydra-node to publish the current Hydra scripts.

• Added a hydra-cluster executable, which runs a single scenario against a known network (smoke test) #430 #423.

• Use deadline when posting a fanoutTx instead of the current slot #441.

• The user manual is now also available in Japanese thanks to @btbf! 🇯🇵

• Fixed display of remaining contestation period in hydra-tui #437.

---

Hydra Scripts

Transaction IDs to be used as --hydra-scripts-tx-id when running hydra-node on the following networks:

• vasil-dev: 5d0aff357c3dc586fc6903bb5c7ef0b4d07eef2475c58fa200e85d65a752f532
  ✔️ published & checked during smoke test run #19
• preview: bde2ca1f404200e78202ec37979174df9941e96fd35c05b3680d79465853a246
  ✔️ published & checked during smoke test run #20

0.6.0

Added

• Implement on-chain contestation logic #192:

  • Node will automatically post a Contest transaction when it observes a Close or Contest with an obsolete snapshot
  • Posting a fan-out transaction is not possible before the contestation dealine has passed

• Transactions can now be submitted as raw CBOR-serialized object, base16 encoded, using the NewTx client input. This also supports the text-envelope format from cardano-cli out of the box. See the api Reference.

• BREAKING The hydra-node does not finalize Heads automatically anymore.

  • Instead clients do get a new ReadyToFanout server output after the contestation period and
  • Clients can use the Fanout client input command to deliberately finalize a Head when it is closed and the contestation period passed.

• Remaining contestation period is included in HeadIsClosed and displayed in hydra-tui.

Changed

• BREAKING: The starting state of a Head is renamed to IdleState, which is visible in the log API.

Fixed

• Head script to check UTxO hash upon closing the head correctly #338. Previously it was possible to close the head with arbitrary UTxO.
• Clients can fanout a Head closed without any off-chain transactions (eg. with initial snapshot) #395

0.5.0

Added

• Start hydra-node tracking the chain starting at a previous point using new --start-chain-from command line option #300.
  • This is handy to re-initialize a stopped (or crashed) hydra-node with an already inititalized Head
  • Note that off-chain state is NOT persisted, but this feature is good enough to continue opening or closing/finalizing a Head
• Handle rollbacks #184
  • Not crash anymore on rollbacks
  • Rewind the internal head state to the point prior to rollback point
  • Added RolledBack server output, see API reference
  • See the user manual for a detailed explanation on how rollbacks are handled.
• Hydra Network section on the website about networking requirements and considerations
• Benchmarks section on the website with continuously updated and published results on transaction costs of Hydra protocol transactions
  • These are also performed and reported now on every PR -> Example
• New architectural decision records:
  • ADR-0017: UDP for Hydra networking
  • ADR-0018: Single state in Hydra.Node
• Improved hydra-node --version to show an easier to understand and accurate revision based on git describe
• Added hydra-node --script-info to check hashes of plutus scripts available in a hydra-node.
  • This can also be seen as the "script version" and should stabilize as we progress in maturity of the codebase.

Changed

• BREAKING Switch to Ed25519 keys and proper EdDSA signatures for the Hydra Head protocol
  • The --hydra-signing-key and consequently --hydra-verification-key are now longer and not compatible with previous versions!
• BREAKING The Hydra plutus scripts have changed in course of finalizing #181
  • All Hydra protocol transactions need to be signed by a Head participant now
  • This changes the script address(es) and the current hydra-node would not detect old Heads on the testnet.
• BREAKING Renamed server output UTxO -> GetUTxOResponse
  • This should be a better name for the response of GetUTxO client input on our API :)
• Updated our dependencies (plutus, cardano-ledger, etc.) to most recent released versions making scripts smaller and Head transactions slighly cheaper already, see benchmarks for current limits.

Fixed

• Reject commit transactions locking a UTxO locked by Byron addresses, part of #182
  • This would render a Head unclosable because Byron addresses are filtered out by the ledger and not visible to plutus scripts
• Fix instructions in demo setup without docker to use 0.0.0.0 and correct paths.

Known Issues

• TUI quickly flashes an error on fanout. This is because all nodes try to post a fanout transaction, but only one of the participants' transactions wins. Related to #279
• Recipient addresses to send money to in the TUI are inferred from the current UTXO set. If a party does not commit a UTXO or consumes all its UTXO in a Head, it won't be able to send or receive anything anymore.
• TUI crashes when user tries to post a new transaction without any UTXO remaining.
• The internal wallet of hydra-node requires a UTXO to be marked as "fuel" to drive the Hydra protocol transactions. See user manual.

0.4.0

Added

• Our user manual 📖 is now available! It includes installation and usage instructions, a full API reference and also a knowledge base about Hydra concepts. The manual will be an ever-evolving source of documentation that we'll maintain alongside the project.ndividual Head instances #180.
• Mint and burn state token used to thread state across the OCV state machine, and participation tokens for each party in the head #181
• Provide (mandatory) command-line options --ledger-genesis and --ledger-protocol-parameters to configure the ledger that runs inside a head. Options are provided as filepath to JSON files which match formats from cardano-cli and cardano-node #180.ano-api](https://github.com/input-output-hk/cardano-node/tree/master/cardano-api#cardano-api) specialized to the latest Cardano's era, and with useful extra utility functions.

Changed

• --network-magic option for the hydra-node and hydra-tui has been changed to --network-id. Also, the hydra-tui command-line used to default to mainnet when not provided with any --network-magic option, it doesn't anymore, --network-id is mandatory. #180
• Optimize the CollectCom transition of the on-chain Hydra contract to allow collecting commits from more than 2 parties! #254
• Use a faucet to distribute funds in test suites and the demo/ setup.
• Internally, better decouple the management of the on-chain head state from the network component. While not visible to the end user, this improvement paves the way for better handling rollbacks and on-chain "instability" of newly posted transactions. #184
• Internally, improved and consolidate generators used for property-based testing to cover a wider range of cases, be more consistent and also faster (avoiding to generate too large nested data-structures).

Fixed

• Hydra.Network.Ouroboros not using hard-coded valency values anymore to allow more than 7 peer connections #203.
• Build issues due to explicit packages list in nix shell #223.
• hydra-tui to show form focus, indicate invalid fields in dialogs and only allow valid values to be submitted #224.
• Repaired benchmarks and improved collected metrics; in particular, benchmarks now collect CPU usage and provide average confirmation times over 5s windows.
• Fixed a bug in the Fanout transaction scheduling and submission where clients would attempt to post a fanout transaction before a 'Close' transaction is even observed. Now, every participant of the head will attempt to post a fanout a transaction after they successfully observed a transaction. Of course, the layer 1 will enforce that only one fanout is posted #279.

Known Issues

• Only no or one utxo can be committed to a Head.
• Recipient addresses to send money to in the TUI are inferred from the current UTXO set. If a party does not commit a UTXO or consumes all its UTXO in a Head, it won't be able to send or receive anything anymore.
• TUI crashes when user tries to post a new transaction without any UTXO remaining.
• The internal wallet of hydra-node requires a UTXO to be marked as "fuel" to drive the Hydra protocol transactions. See user manual.
• Aborting a head with more than 2 participants (i.e. > 2) requires increase in tx size limit over current mainchain parameters to ~20KB.
• Head can collect at most 3 commits and each party can commit either 1 or 0 UTXO to a Head.
• The head cannot be finalized if holding more than ~100 assets (or ~50 ada-only UTxO entries) with the standard tx size of 16KB.

0.3.0

Added

• Implementation of on-chain verification of Hydra Head lifecycle without contests. This first version with its various shortcuts is documented on examples of the full and abort on-chain life-cycles of a Hydra Head
• Enable nix-shell on Mac
• Build separate docker images for hydra-node and hydra-tui available as packages from GitHub repo
• Utility executable inspect-script to dump contracts for further analysis
• CBOR encoder and Merkle-Tree in Plutus as separate packages plutus-cbor and plutus-merkle-tree, released & tagged separately

Changed

• Package local-cluster is now hydra-cluster.
• Use cardano-api types and functions to interact with chain.
• Refine computation of fees from internal wallet.
• Remove several sources of error in chain interaction component.

Known issues

• collectComTx requires increase in tx size limit over current mainchain parameters to 32KB, which should be alleviated with Plutus optimisations and merging all contracts in one in future releases
• Head can collect at most 9 commits and each party can commit either 1 or 0 UTXO to a Head
• fanoutTx cannot handle more than 100 UTxO with the standard tx size of 16KB (200 with the temporary increase for test purpose).
• Known issues from 0.2.0 still apply

0.2.0

Added

• Direct chain integration which allows to connect to a real cardano-node /
  devnet; no on-chain validators though.
• Support alonzo transactions inside the Hydra Head. For now using a freeCostModel.
• Command line options --node-socket, --network-magic and
  --cardano-{signing,verification}-key to hydra-node and hydra-tui to
  configure the Cardano network access.

Changed

• Command line options of hydra-node quite significantly to distinguish hydra
  credentials from cardano credentials.
• Commit and transaction creation logic of TUI to use cardano credentials.

Removed

• ZeroMQ mock-chain executable, chain component and corresponding hydra-node
  command line options.
• ZeroMQ based network component.
• Aliases from party identifiers.

Fixed

• hydra-tui to correctly show current state when re-connecting.

Known issues

• Only no or one utxo can be committed to a Head.
• Recipient addresses to send money to in the TUI are inferred from the current
  UTXO set. If a party does not commit a UTXO or consumes all its UTXO in a
  Head, it won't be able to send or receive anything anymore.
• TUI crashes when user tries to post a new transaction wihout any UTXO
  remaining.
• Not an issue, but a workaround: The internal wallet of hydra-node requires a
  UTXO to be marked as "fuel" to drive the Hydra protocol transactions.