Hydra Poc Versions Save

• 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 :point_down: #546

---

Built artifacts

• :package: Static x86_64-linux binaries: here (also attached)
• :whale: 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)

• 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! :jp:

• 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 :heavy_check_mark: published & checked during smoke test run #19
• preview: bde2ca1f404200e78202ec37979174df9941e96fd35c05b3680d79465853a246 :heavy_check_mark: published & checked during smoke test run #20

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

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.

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.

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

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.