Getting Started with Kuber-Hydra

This page covers setup options, API references, and practical end-to-end examples for Hydra development with Kuber.

What Kuber-Hydra gives you

Kuber-Hydra provides a relay API around Hydra nodes so you can:

• Build and submit in-head transactions with a familiar TxBuilder flow.
• Query head state, UTxOs, and protocol parameters from one place.
• Drive full head lifecycle operations (initialize, commit, close, fanout) without wiring low-level Hydra protocol code yourself.

You focus on transaction logic while Kuber-Hydra handles most integration details.

What you will run

• A Cardano node (local devnet or testnet/mainnet)
• 3 Hydra nodes for Alice, Bob, and Carol
• 3 Kuber-Hydra relay servers for Alice, Bob, and Carol

Recommended prerequisites

Before running examples, make sure you have:

• Node.js 18+
• A package manager (pnpm, yarn, or npm)
• Docker Desktop (required for local devnet flow)
• Wallet/signing key files for participants
• Enough funds for commit/collateral scenarios

If you are just starting, use local devnet first. It is faster, deterministic, and easier to debug.

Choose your setup path

⚡ Quick start: Local devnet

Use this for fast iteration and repeatable testing. You can run full head lifecycle and transaction scenarios without waiting for public-network confirmations.

🌐 Real network: Testnet/Mainnet

Use this when validating wallet behavior, infrastructure setup, and production-like transaction flow.

Transaction Builder API

Kuber-Hydra builds in-head transactions through buildTx(tx, submit?).

• Create a transaction object with fields like inputs, outputs, mint, metadata, and optional validity windows.
• Pass that object to buildTx to construct a transaction inside the Hydra head.
• Set submit to true when you want to build and submit in one step.

For the API method, see Transaction builder API (buildTx). For the full transaction object schema and field behavior, see TxBuilder Object Reference. See more details there.

First run checklist

See more for API details

• Kuber-Hydra API reference

1. Start local cluster and verify relays are reachable.
2. Query queryHeadState from Alice relay.
3. Initialize head.
4. Commit at least one UTxO per participant.
5. Wait for Open.
6. Submit one simple transfer transaction. (See - Submitting Hydra transactions)
7. Close and fanout.
8. Verify final L1 balances.

If that path works, you are ready for advanced examples.

Practical examples

• Working with wallets
• Committing UTxOs to Hydra
• Submitting Hydra transactions
• Minting native tokens
• Burning native tokens
• Paying to a script
• Payment to 100+ new addresses (minimum 2 ADA)
• Full end-to-end Hydra flow
• Devnet cluster workflow

Core API references

• Kuber-Hydra API reference
• Transaction builder API (buildTx)
• Hydra head status query API (queryHeadState)
• UTxO query API
• Protocol parameters query API

Troubleshooting

• Head not Open when submitting tx: wait for state transition and retry.
• Commit fails due to low balance/collateral: fund wallet and select larger UTxO.
• High-fanout outputs fail: chunk outputs into multiple transactions.
• Inconsistent local runs: reset devnet and rerun from a known state.

Recommended path

1. Start with Local devnet.
2. Run Working with wallets and Submitting Hydra transactions.
3. Run practical advanced examples: mint, burn, pay-to-script, and high-fanout payments.
4. Finish with the Full end-to-end example.