• 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

Hydra-node and cardano-node running, check Installation.

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

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

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.

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. You can either use the commitFunds or commitBlueprintfunction on HydraInstance by selecting specific UTxOs and make them available for layer 2 transactions:

commitBlueprintTo commit using blueprint you can specify UTxOs to commit just like commitFunds but it takes additional parameter. A Cardano transaction in the text envelope format used as type hydraTransaction in Mesh That is, a JSON object wrapper with some 'type' around a 'cborHex' encoded transaction. The hydra-node uses this format as follows:

• type: This can either be Tx ConwayEra, Unwitnessed Tx ConwayEra or Witnessed Tx ConwayEra
• cborhex: The base16-encoding of the CBOR encoding of some binary data, this can be passed from a built unsigned transaction
• description: An optional description for the transaction

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

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

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 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, transactions in hydra head does not return a hash instead 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

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.