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 HydraProvider
with 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
- Hydra-node and cardano-node running, check Installation.
cardano-node
and Hydra-node
to quickly follow this tutorial. Check the setup example/demo for a devnet hereStep 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
toalice-node.addr
andbob-node.addr
addresses. - Send any amount of
tADA
toalice-funds.addr
andbob-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 0txFeePerByte
to 0executionUnitPrices.priceMemory
to 0executionUnitPrices.priceSteps
to 0
Generate Mock CLI keys for demo (not for testing or production).
Generates Cardano wallet addresses using Mesh SDK.
Fetch and display wallet UTxOs for all participants.
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 to0.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 feeshydra-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 thecardano-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, afterClose
, all participants have at minimumCP
to submit aContest
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.
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 initializedCommitted
- Funds are committed to the headHeadIsOpen
- Head is open and ready for transactions
Connect your to the Hydra node.
initializing the Hydra head.
commits funds to Hydra head.
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 SnapshotConfirmed
message shortly after with the new UTxO set.
Transaction Flow
The transaction goes through these steps:
NewTx
- Transaction submitted to headTxValid
- Transaction validated by all nodesSnapshotConfirmed
- New state confirmed
Fetching UTxOs from the Hydra head.
Fetching UTxOs for a specific address.
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 stateCOMMIT
- Committing to Hydra headOPEN
- Head open for transactionsNEW TX
- New transaction submitted in Hydra headCLOSE
- Ready to fanoutCONTEST
- Head closed, contestation periodFANOUT
- Head finalized on layer one
Congratulations! You've completed the full lifecycle of a Hydra head from initialization to finalization.
closing the Hydra head.
fan out the Hydra head to layer 1.