hydra-head

Hydra Head

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

这是一份指导类skill。提供最佳实践和模板。执行操作请使用
hydra-head-operator
。

When to use

适用场景

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

搭建或运维hydra-node
理解Hydra Head生命周期
调试连接或配置问题

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

确认网络环境（主网/preprod/预览网/开发网）
以hydra.family文档为权威来源
仅提供指导，绝不执行操作
所有
```
.sk
```
文件均视为机密文件

Docker fallback mode

Docker备用模式

If

hydra-node

is not installed locally, use the wrapper script in this skill folder to run hydra-node inside Docker (Hydra upstream recommends Docker images for quickest start).

bash

chmod +x {baseDir}/scripts/hydra-node.sh
{baseDir}/scripts/hydra-node.sh --help
{baseDir}/scripts/hydra-node.sh gen-hydra-key --output-file hydra

For full multi-node Head demos, prefer the hydra.family Docker Compose demo (it's the canonical "known-good" setup).

如果本地未安装

hydra-node

，可使用本skill文件夹中的包装脚本在Docker内运行hydra-node（Hydra官方推荐使用Docker镜像快速启动）。

bash

chmod +x {baseDir}/scripts/hydra-node.sh
{baseDir}/scripts/hydra-node.sh --help
{baseDir}/scripts/hydra-node.sh gen-hydra-key --output-file hydra

如需进行完整的多节点Head演示，优先使用hydra.family提供的Docker Compose演示（这是经过验证的标准可靠配置）。

Key concepts

核心概念

Key roles

密钥角色

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

Cardano密钥：在L1链上标识参与者，支付交易手续费
Hydra密钥：在Head内对快照进行多签

Lifecycle

生命周期

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

Init → Commit → Open → [L2交易] → Close → Contest → Fanout

Important parameters

重要参数

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

争议期：Close操作后的安全争议窗口
存款期：识别存款的时间窗口

Setup guide

搭建指南

1. Generate keys

1. 生成密钥

bash

undefined

bash

undefined

Cardano payment keys

Cardano支付密钥

cardano-cli conway address key-gen
--verification-key-file cardano.vk
--signing-key-file cardano.sk

Hydra keys

Hydra密钥

hydra-node gen-hydra-key --output-file hydra

Creates hydra.sk and hydra.vk

chmod 600 *.sk

undefined

chmod 600 *.sk

undefined

2. Exchange keys with peers

2. 与节点交换密钥

Each participant needs:

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

每个参与者需要：

自己的
```
cardano.sk
```
和
```
hydra.sk
```
所有节点的
```
cardano.vk
```
和
```
hydra.vk
```

3. Get scripts tx id

3. 获取脚本交易ID

bash

undefined

bash

undefined

From hydra-node release notes for your network

从对应网络的hydra-node发布说明中获取

Preview: <scripts-tx-id-preview>

预览网: <scripts-tx-id-preview>

Preprod: <scripts-tx-id-preprod>

Preprod网: <scripts-tx-id-preprod>

Mainnet: <scripts-tx-id-mainnet>

主网: <scripts-tx-id-mainnet>

undefined

undefined

4. Configure hydra-node

4. 配置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

bash

hydra-node run \
  --node-id "alice" \
  --persistence-dir ./hydra-data \
  \
  # Cardano连接（二选一）:
  --node-socket /path/to/node.socket \
  --testnet-magic 1 \
  # OR:
  --blockfrost blockfrost.txt \
  \
  # 身份信息:
  --cardano-signing-key cardano.sk \
  --hydra-signing-key hydra.sk \
  \
  # 节点信息（每个节点重复该部分）:
  --cardano-verification-key bob-cardano.vk \
  --hydra-verification-key bob-hydra.vk \
  --peer "bob.example.com:5001" \
  \
  # 协议参数:
  --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

Head操作

Open a head

打开Head

bash

undefined

bash

undefined

Via hydra-tui

通过hydra-tui操作

hydra-tui --connect localhost:4001

Via API

通过API操作

curl -X POST localhost:4001/init

Then each party commits

然后各方提交资产

curl -X POST localhost:4001/commit
-H "Content-Type: application/json"
-d '{"utxo": {...}}'

undefined

curl -X POST localhost:4001/commit
-H "Content-Type: application/json"
-d '{"utxo": {...}}'

undefined

L2 transactions

L2交易

bash

undefined

bash

undefined

Submit transaction

提交交易

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

undefined

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

undefined

Close and fanout

关闭与提取资金

bash

curl -X POST localhost:4001/close

bash

curl -X POST localhost:4001/close

Wait for contestation period

等待争议期结束

curl -X POST localhost:4001/fanout

undefined

curl -X POST localhost:4001/fanout

undefined

Examples

示例

Example: 2-party head on preprod

示例：Preprod网上的双节点Head

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

Response:

bash

undefined

用户请求： "在Preprod网上搭建一个双节点Hydra Head"

响应：

bash

undefined

=== Party 1 (Alice) ===

=== 节点1（Alice） ===

1. Create directory

1. 创建目录

mkdir -p ~/hydra/alice && cd ~/hydra/alice

2. Generate keys

2. 生成密钥

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

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

3. 从发布说明中获取Preprod网的脚本交易ID

SCRIPTS_TX_ID="..."

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

4. 与Bob交换密钥（获取bob-cardano.vk, bob-hydra.vk）

5. Run node

5. 启动节点

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)

6. 初始化Head（任意一方均可操作）

curl -X POST localhost:4001/init

7. Commit funds

7. 提交资产

hydra-tui --connect localhost:4001

Select UTxO to commit

选择要提交的UTxO

8. Head opens when all commit

8. 所有节点提交完成后，Head自动打开

undefined

undefined

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

所有节点使用相同版本的hydra-node
脚本交易ID与当前网络匹配
cardano-node已完全同步且socket就绪
所有节点已交换正确的验证密钥
日志中出现PeerConnected消息
节点间的网络端口已开放

Common issues

常见问题

See

hydra-head-troubleshooter

skill for:

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

如需解决以下问题，请查看

hydra-head-troubleshooter

skill：

"未检测到Head"
"Head无进展"
"节点不同步"
AckSn/PeerConnected相关问题

Safety / key handling

安全/密钥管理

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

绝不分享
```
.sk
```
文件
为每个参与者创建独立目录
先在开发网/Preprod网进行测试
备份持久化目录

References

参考资料

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

```
shared/PRINCIPLES.md
```
```
hydra-head-operator
```
（用于执行操作）
```
hydra-head-troubleshooter
```
（用于调试）
查看
```
reference/sources.md
```
了解文档来源

hydra-head

Original

Translation

hydra-head

Hydra Head

When to use

适用场景

Operating rules (must follow)

操作规则（必须遵守）

Docker fallback mode

Docker备用模式

Key concepts

核心概念

Key roles

密钥角色

Lifecycle

生命周期

Important parameters

重要参数

Setup guide

搭建指南

1. Generate keys

1. 生成密钥

Cardano payment keys

Cardano支付密钥

Hydra keys

Hydra密钥

Creates hydra.sk and hydra.vk

Creates hydra.sk and hydra.vk

2. Exchange keys with peers

2. 与节点交换密钥

3. Get scripts tx id

3. 获取脚本交易ID

From hydra-node release notes for your network

从对应网络的hydra-node发布说明中获取

Preview: <scripts-tx-id-preview>

预览网: <scripts-tx-id-preview>

Preprod: <scripts-tx-id-preprod>

Preprod网: <scripts-tx-id-preprod>

Mainnet: <scripts-tx-id-mainnet>

主网: <scripts-tx-id-mainnet>

4. Configure hydra-node

4. 配置hydra-node

Head operations

Head操作

Open a head

打开Head

Via hydra-tui

通过hydra-tui操作

Via API

通过API操作

Then each party commits

然后各方提交资产

L2 transactions

L2交易

Submit transaction

提交交易

Close and fanout

关闭与提取资金

Wait for contestation period

等待争议期结束

Examples

示例

Example: 2-party head on preprod

示例：Preprod网上的双节点Head

=== Party 1 (Alice) ===

=== 节点1（Alice） ===

1. Create directory

1. 创建目录

2. Generate keys

2. 生成密钥

3. Get preprod scripts tx id from release notes

3. 从发布说明中获取Preprod网的脚本交易ID

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

4. 与Bob交换密钥（获取bob-cardano.vk, bob-hydra.vk）

5. Run node

5. 启动节点

=== After both nodes running ===

=== 双方节点均启动后 ===

6. Init head (either party)