Cardano Layer 2 : Hydra - wimsio/universities GitHub Wiki

Introduction
Prerequisites
Installation
Configuration & Connect to Cardano
Prepare Keys & Funding
Start Hydra Nodes
Open & Test the Hydra Head 7.1. Open the Head 7.2. Test a Transaction
Closing the Hydra Head
Glossary of Terms
Hydra Documentation Hydra Documentation

1. Introduction Hydra is a layer‑2 scaling solution for Cardano that uses off‑chain state channels (Hydra Heads) to boost throughput and minimize costs while preserving the security of the base chain.

2. Prerequisites

Two machines or terminals (for two participants) reachable over the network
At least 100 tADA in a preprod wallet per participant
Installed utilities: curl, tar, jq (≥1.6), unzip, websocat

3. Installation

Create a local bin/ directory:
```
mkdir -p bin
```

Download and extract Hydra:

hydra_version=0.22.0
curl -L -O https://github.com/cardano-scaling/hydra/releases/download/${hydra_version}/hydra-x86_64-linux-${hydra_version}.zip
unzip -d bin hydra-x86_64-linux-${hydra_version}.zip

Download Cardano node and CLI:

cardano_node_version=10.1.4
curl -L -O https://github.com/input-output-hk/cardano-node/releases/download/${cardano_node_version}/cardano-node-${cardano_node_version}-linux.tar.gz
tar xf cardano-node-${cardano_node_version}-linux.tar.gz -C bin cardano-node cardano-cli

Make binaries executable:
```
chmod +x bin/*
```
Verify installation:
```
bin/hydra-node --help
```

4. Configuration & Connect to Cardano

Add bin/ to your PATH and set environment variables:

export PATH=$(pwd)/bin:$PATH
export CARDANO_NODE_SOCKET_PATH=$(pwd)/node.socket
export CARDANO_NODE_NETWORK_ID=1

Fetch preprod snapshot using Mithril:

curl -s https://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/release-preprod/genesis.vkey > genesis.vkey
curl -s https://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/release-preprod/ancillary.vkey > ancillary.vkey
mithril-client --origin-tag HYDRA cardano-db download latest --include-ancillary

Run the Cardano node:

cardano-node run \
  --config config.json \
  --topology topology.json \
  --socket-path $CARDANO_NODE_SOCKET_PATH \
  --database-path db

Wait for sync (cardano-cli query tip should show "syncProgress": "100.00").

5. Prepare Keys & Funding

Generate node and funds keys for Alice and Bob:

mkdir -p credentials
# Alice node keys
cardano-cli address key-gen \
  --verification-key-file credentials/alice-node.vk \
  --signing-key-file credentials/alice-node.sk
cardano-cli address build \
  --payment-verification-key-file credentials/alice-node.vk \
  --out-file credentials/alice-node.addr
# Alice funds keys (similarly for Bob)
cardano-cli address key-gen \
  --verification-key-file credentials/alice-funds.vk \
  --signing-key-file credentials/alice-funds.sk
cardano-cli address build \
  --payment-verification-key-file credentials/alice-funds.vk \
  --out-file credentials/alice-funds.addr

Fund each *‑funds.addr with ≥30 tADA via the preprod faucet.

Generate Hydra signing keys:

hydra-node gen-hydra-key --output-file credentials/alice-hydra
hydra-node gen-hydra-key --output-file credentials/bob-hydra

Exchange public keys (*.vk) and note each node’s IP:port (e.g. 127.0.0.1:5001).

6. Start Hydra Nodes On each machine, run:

hydra-node \
  --node-id alice-node \
  --persistence-dir persistence-alice \
  --cardano-signing-key credentials/alice-node.sk \
  --hydra-signing-key credentials/alice-hydra.sk \
  --hydra-scripts-tx-id $(jq -r '.preprod."'${hydra_version}'"' networks.json) \
  --ledger-protocol-parameters protocol-parameters.json \
  --testnet-magic 1 \
  --api-port 4001 \
  --listen 0.0.0.0:5001 \
  --peer 127.0.0.1:5002 \
  --hydra-verification-key credentials/bob-hydra.vk \
  --cardano-verification-key credentials/bob-node.vk

Repeat for Bob, swapping ports, IDs, and keys.

7. Open & Test the Hydra Head 7.1. Open the Head

Init via WebSocket:
```
{ "tag": "Init" }
```

Commit UTxOs:

# Alice example
cardano-cli query utxo --address $(cat credentials/alice-funds.addr) --out-file alice-utxo.json
curl -X POST localhost:4001/commit --data @alice-utxo.json > alice-commit.json
cardano-cli latest transaction sign --tx-file alice-commit.json --signing-key-file credentials/alice-funds.sk --out-file alice-signed.json
cardano-cli latest transaction submit --tx-file alice-signed.json

Repeat for Bob (port 4002).

7.2. Test a Transaction

Query head UTxOs:

curl -s localhost:4001/snapshot/utxo | jq 'with_entries(select(.value.address == "$(cat credentials/alice-funds.addr)"))' > utxo.json

Build raw tx (10 ADA transfer):

LOVELACE=10000000
cardano-cli latest transaction build-raw \
  --tx-in $(jq -r 'to_entries[0].key' < utxo.json) \
  --tx-out $(cat credentials/bob-funds.addr)+${LOVELACE} \
  --tx-out $(cat credentials/alice-funds.addr)+$(jq ".value.value.lovelace - ${LOVELACE}" < utxo.json) \
  --fee 0 --out-file tx.json

Sign & submit via WebSocket:

cardano-cli latest transaction sign --tx-body-file tx.json --signing-key-file credentials/alice-funds.sk --out-file signed.json
printf '{"tag":"NewTx","transaction":'$(jq -c . signed.json)'}' | websocat ws://localhost:4001

Expect TxValid and SnapshotConfirmed events.

8. Closing the Hydra Head

Send close tag:
```
{ "tag": "Close" }
```
Wait for HeadIsClosed and ReadyToFanout, then optionally fanout:
```
{ "tag": "Fanout" }
```

Verify final on‑chain UTxOs:

cardano-cli query utxo --address $(cat credentials/alice-funds.addr)

9. Glossary of Terms

Hydra: A layer‑2 solution for Cardano that uses state channels (“Heads”) to enable fast, off‑chain transactions.
Layer‑2: A secondary framework built on top of a blockchain to improve scalability and transaction speed.
Hydra Head: An off‑chain state channel where participants commit UTxOs and conduct transactions rapidly.
UTxO: Unspent Transaction Output; the model Cardano uses to track funds.
Mithril: A protocol to snapshot and verify Cardano’s ledger state off‑chain.
Preprod Network: A public Cardano test network used for development and testing without real ADA.
API Port: The HTTP/WebSocket port on which the hydra-node exposes its API.
Fanout: The process of distributing final head balances back on‐chain after closing a head.

References:

Hydra Documentation Hydra Documentation
Hydra – Cardano’s solution for ultimate Layer 2 scalability Hydra – Cardano’s solution for ultimate Layer 2 scalability https://iohk.io/en/blog/posts/2021/09/17/hydra-cardano-s-solution-for-ultimate-scalability/?__cf_chl_tk=BpSz_dITTNNYh2BQShDtjAO2ngV2t_1Zawt3d1lIrLQ-1750956197-1.0.1.1-DBpUGIm1vHXe58Zo8o8kblhIEgY47uHAl7PupuD4cfw