End-to-end Hydra Tutorial

Open a layer 2 state channel between two participants, build transactions, and close the Hydra head

This tutorial demonstrates how to use Hydra Head protocol on Cardano's preprod testing environment to open a layer 2 state channel between two participants using Mesh.

Hydra Head is a layer 2 scaling solution for Cardano that enables fast, low-cost transactions between participants.

This tutorial is adapted from the Hydra documentation.

Initialize Hydra with Mesh

To initialize Hydra with Mesh, you need to set the HydraProviderwith the Hydra API URL and then use it to initialize the HydraInstance. You can use one of the cardano providers, example: blockfrostProvider, or maestroProvider, to initialize the HydraInstance.

Prerequisites

  • A running cardano node is required to access cardano-cli
  • A Hydra-node
  • Another participant following this tutorial (recommended), or
  • Access to two such machines
  • 100 test ada per participant in a wallet on the preprod network
You could also set-up a Docker container for a cardano-node and Hydra-nodeto quickly follow this tutorial. Check the setup example/demo for a devnet here

Step 1. Prepare keys and funding

In a Hydra head, each participant is authenticated using two sets of keys. The first set identifies a participant on the Cardano layer 1 and is used to hold ada for paying fees. Each hydra-node requires a cardano-signing-key, and you must provide the cardano-verification-key for each participant. First, generate Cardano key pairs and addresses for both participants with cardano-cli to identify the hydra-node and manage funds on layer 1.

Alice's keys:

Bob's keys:

After generating the addresses, make sure to fund both Alice's and Bob's addresses with test ADA. if you don't have testAda, you can use cardano-faucet to fund the generated addresses

  • Send at least 30 tADA to alice-node.addr and bob-node.addr addresses.
  • Send any amount of tADA to alice-funds.addr and bob-funds.addr addresses.

Next, generate Hydra key pairs for use on layer 2. Use this Hydra-node command to generate the keys for alice and/or bob respectively:

The next step involves configuring the protocol parameters for the ledger within our Hydra head. For the purposes of this tutorial, we'll modify the default Cardano layer 1 parameters to eliminate transaction fees,

Simplifying Hydra fees and environments, change the following parameters:

  • txFeeFixed to 0
  • txFeePerByte to 0
  • executionUnitPrices.priceMemory to 0
  • executionUnitPrices.priceSteps to 0
Generate Mock CLI Keys

Generate Mock CLI keys for demo (not for testing or production).

Generate Wallet Addresses

Generates Cardano wallet addresses using Mesh SDK.

Check Wallet UTxOs

Fetch and display wallet UTxOs for all participants.

Generate Mock Hydra Keys

Generate Hydra key pairs for demo (not for testing or production).

Step 2. Configure Hydra nodes

Configure your Hydra nodes with the generated keys and network settings. Each participant needs to set up their hydra-node with the correct configuration.

Alice:

Bob:

Fields in the Hydra node configuration:

  • node-id: Unique identifier for each Hydra node. This distinguishes Alice's node from Bob's node.
  • api-host: as the API is not authenticated by default, the node is only binding to 0.0.0.0.
  • api-port: The port on which the API will listen.
  • listen: The IP address and port on which the Hydra node will listen for incoming connections.
  • peer: The IP address of another Hydra node to connect to. This is how nodes discover and communicate with each other.
  • monitoring-port: The port on which the monitoring API will listen. This is used to monitor the Hydra node's performance.
  • cardano-signing-key: These keys authenticate on-chain transactions and ensure that only authorized participants can control the head's lifecycle used to hold ada for paying fees
  • hydra-signing-key: Used for multi-signing snapshots within a head. Although these keys may eventually support an aggregated multi-signature scheme, they currently use the Ed25519 format.
  • hydra-scripts-tx-id: The hydra-node uses reference scripts to reduce transaction sizes driving the head's lifecycle. For public (test) networks, you can use the pre-published Hydra scripts with each new release, listing transaction IDs in the release notes and networks.json. Note: The value of above --hydra-scripts-tx-id comes from the hydra-node release 0.22.2.
  • ledger-protocol-parameters: This defines the updatable protocol parameters to be used on L2 such as fees or transaction sizes. These parameters follow the same format as the cardano-cli query protocol-parameters output.
  • contestation-period:This is an important protocol parameter, defined in seconds The contestation period is used to set the contestation deadline. That is, after Close, all participants have at minimum CP to submit a Contest transaction
More on hydra configuration.

Ensure both nodes can communicate with each other and change to your correct file paths in the above configuration. This configuration sets up Alice's node to listen to API connection on port 4001 Bob's node on port 4002.

Step 3. Open a Hydra head

Connect to the Hydra head

Now that both Hydra nodes are running and connected, we can start using the head API url and port together with Mesh HydraProvider in connecting to the Hydra head.

Initialize the Head

Send the initialization command to start the Hydra head:

Commit Funds

After initialization, both participants need to commit funds to the head. In this tutorial we use the commitFunds function on HydraInstance by selecting specific UTxOs and make them available for layer 2 transactions:

The hydra-node will create a draft commit transaction for you to sign. Once signed and submitted to the Cardano network, you'll see a Committed message in your WebSocket connection.

When both parties have committed their funds, the Hydra head will open automatically. You'll see a HeadIsOpen message confirming the head is operational and ready for transactions.

Hydra Head Status Flow

The head goes through these status changes:

  • HeadIsInitializing - Head is being initialized
  • Committed - Funds are committed to the head
  • HeadIsOpen - Head is open and ready for transactions
Connect to Hydra Node

Connect your to the Hydra node.

Initialize Head

initializing the Hydra head.

Commit Funds

commits funds to Hydra head.

Head Status

Monitor the Hydra head status changes.

Step 4. Use the Hydra head

Now that the Hydra head is open, you can perform transactions within the layer 2 state channel. Hydra Head operates as an isomorphic protocol, meaning that functionalities available on Cardano layer 1 are also available on layer 2. This allows us to use Mesh SDK for transaction creation within the head.

Fetch UTxOs

First, let's see what UTxOs are available in the Hydra head:

Fetch Address UTxOs

Alternatively, you can fetch Head UTxOs for a specific address:

Build and Submit Transaction

you can build transactions just like on layer 1 assuming you are sending from alice to bob:

The transaction will be validated by both hydra-nodes and either result in a TxValid message or a TxInvalid message If valid, you'll see a SnapshotConfirmedmessage shortly after with the new UTxO set.

Transaction Flow

The transaction goes through these steps:

  • NewTx - Transaction submitted to head
  • TxValid - Transaction validated by all nodes
  • SnapshotConfirmed - New state confirmed
Fetch Hydra head UTxOs

Fetching UTxOs from the Hydra head.

Fetch hydra participant Address UTxOs

Fetching UTxOs for a specific address.

Build and submit Transaction in Hydra head

Build and submit a transaction in the Hydra head.

Step 5. Close the Hydra head

You can close the head to return head utxos to layer 1. This process involves closing the head, waiting for the contestation period, and then fan out the final state.

Close the Head

Any participant can initiate closing the Hydra head. Once closed, no more transactions can be submitted to the head. The head enters a contestation period where participants can challenge the closing snapshot.

Contestation Period

After closing, there's a contestation period (configurable with --contestation-period). During this time:

  • Participants can contest the closing snapshot
  • If contested, a more recent snapshot can be used
  • After the deadline, fanout becomes possible

Fanout the Head

After the contestation period, the head participants can use the fanout to fully close the hydra-head and return the head utxos to layer one.

Check Final Balances

After fanout, check the final balances on layer one:

Head Lifecycle

The complete head lifecycle:

  • INITIALIZE - Initial state
  • COMMIT - Committing to Hydra head
  • OPEN - Head open for transactions
  • NEW TX - New transaction submitted in Hydra head
  • CLOSE - Ready to fanout
  • CONTEST - Head closed, contestation period
  • FANOUT - Head finalized on layer one

Congratulations! You've completed the full lifecycle of a Hydra head from initialization to finalization.

Close Head

closing the Hydra head.

Fanout Head

fan out the Hydra head to layer 1.