hydra-head

This is a guidance skill. Provides best practices and templates. For execution, use hydra-head-operator.

When to use

•Setting up or operating hydra-node
•Understanding Hydra Head lifecycle
•Debugging connectivity or configuration issues

Operating rules (must follow)

•Confirm network (mainnet/preprod/preview/devnet)
•Use hydra.family docs as source of truth
•Never execute—only provide guidance
•Treat all .sk files as secrets

Key concepts

Key roles

•Cardano keys: Identify participant on L1, pay tx fees
•Hydra keys: Multi-sign snapshots inside the head

Lifecycle

code

Init → Commit → Open → [L2 transactions] → Close → Contest → Fanout

Important parameters

•Contestation period: Safety window for contesting after Close
•Deposit period: Window for recognizing deposits

Setup guide

1. Generate keys

bash

# Cardano payment keys
cardano-cli conway address key-gen \
  --verification-key-file cardano.vk \
  --signing-key-file cardano.sk

# Hydra keys
hydra-node gen-hydra-key --output-file hydra
# Creates hydra.sk and hydra.vk

chmod 600 *.sk

2. Exchange keys with peers

Each participant needs:

•Their own cardano.sk and hydra.sk
•All peers' cardano.vk and hydra.vk

3. Get scripts tx id

bash

# From hydra-node release notes for your network
# Preview: <scripts-tx-id-preview>
# Preprod: <scripts-tx-id-preprod>
# Mainnet: <scripts-tx-id-mainnet>

4. Configure hydra-node

bash

hydra-node run \
  --node-id "alice" \
  --persistence-dir ./hydra-data \
  \
  # Cardano connection (choose one):
  --node-socket /path/to/node.socket \
  --testnet-magic 1 \
  # OR:
  --blockfrost blockfrost.txt \
  \
  # Identity:
  --cardano-signing-key cardano.sk \
  --hydra-signing-key hydra.sk \
  \
  # Peers (repeat for each):
  --cardano-verification-key bob-cardano.vk \
  --hydra-verification-key bob-hydra.vk \
  --peer "bob.example.com:5001" \
  \
  # Protocol:
  --hydra-scripts-tx-id <scripts-tx-id> \
  --contestation-period 120s \
  \
  # API:
  --api-host 0.0.0.0 \
  --api-port 4001 \
  --host 0.0.0.0 \
  --port 5001

Head operations

Open a head

bash

# Via hydra-tui
hydra-tui --connect localhost:4001

# Via API
curl -X POST localhost:4001/init
# Then each party commits
curl -X POST localhost:4001/commit \
  -H "Content-Type: application/json" \
  -d '{"utxo": {...}}'

L2 transactions

bash

# Submit transaction
curl -X POST localhost:4001/submit \
  -H "Content-Type: application/json" \
  -d '{"transaction": "..."}'

Close and fanout

bash

curl -X POST localhost:4001/close
# Wait for contestation period
curl -X POST localhost:4001/fanout

Examples

Example: 2-party head on preprod

User request: "Set up a 2-party Hydra head on preprod"

Response:

bash

# === Party 1 (Alice) ===

# 1. Create directory
mkdir -p ~/hydra/alice && cd ~/hydra/alice

# 2. Generate keys
cardano-cli conway address key-gen \
  --verification-key-file cardano.vk \
  --signing-key-file cardano.sk

hydra-node gen-hydra-key --output-file hydra
chmod 600 *.sk

# 3. Get preprod scripts tx id from release notes
SCRIPTS_TX_ID="..."

# 4. Exchange keys with Bob (get bob-cardano.vk, bob-hydra.vk)

# 5. Run node
hydra-node run \
  --node-id "alice" \
  --persistence-dir ./data \
  --node-socket $CARDANO_NODE_SOCKET_PATH \
  --testnet-magic 1 \
  --cardano-signing-key cardano.sk \
  --hydra-signing-key hydra.sk \
  --cardano-verification-key bob-cardano.vk \
  --hydra-verification-key bob-hydra.vk \
  --peer "bob-host:5001" \
  --hydra-scripts-tx-id $SCRIPTS_TX_ID \
  --contestation-period 120s \
  --api-port 4001 \
  --port 5001

# === After both nodes running ===

# 6. Init head (either party)
curl -X POST localhost:4001/init

# 7. Commit funds
hydra-tui --connect localhost:4001
# Select UTxO to commit

# 8. Head opens when all commit

Verification checklist

• All nodes same hydra-node version
• Scripts tx id matches network
• cardano-node fully synced and socket ready
• All peers exchanged correct vkeys
• PeerConnected messages in logs
• Network ports open between peers

Common issues

See hydra-head-troubleshooter skill for:

•"No head observed"
•"Head doesn't make progress"
•"Peer out of sync"
•AckSn/PeerConnected issues

Safety / key handling

•Never share .sk files
•Keep separate directories per participant
•Test on devnet/preprod first
•Back up persistence directory

References

•shared/PRINCIPLES.md
•hydra-head-operator (for execution)
•hydra-head-troubleshooter (for debugging)
•See reference/sources.md for doc provenance