@meshsdk/hydra

A powerful TypeScript SDK for interacting with Hydra Heads on Cardano.

Overview

Hydra is a layer 2 protocol for Cardano that enables fast, low-cost transactions by creating off-chain "heads" where multiple parties can interact. This package provides a complete SDK for:

• Connecting to and managing Hydra Heads
• Committing and decommitting funds
• Building and submitting transactions within Hydra Heads
• Handling all Hydra protocol operations (init, abort, close, contest, fanout)
• Event-driven architecture for real-time updates

Installation

npm install @meshsdk/hydra

Quick Start

Basic Setup

import{HydraProvider,HydraInstance}from"@meshsdk/hydra";import{BlockfrostProvider}from"@meshsdk/core";consthydraProvider=newHydraProvider({httpUrl: "http://localhost:4001",// Your Hydra node URL});awaithydraProvider.connect();constblockchainProvider=newBlockfrostProvider("YOUR_BLOCKFROST_KEY");consthydraInstance=newHydraInstance({provider: hydraProvider,fetcher: blockchainProvider,submitter: blockchainProvider,});

Initialize a Head

awaithydraProvider.init();// Wait for all parties to commit// Once all parties have committed, the head will open automatically

Commit Funds

constemptyCommitTx=awaithydraInstance.commitEmpty();awaitwallet.submitTx(emptyCommitTx);

Submit Transactions in Hydra Head

consttxHash=awaithydraProvider.newTx({type: "Tx ConwayEra",cborHex: unsignedTransactionCbor,});

API Reference

HydraProvider

The main class for connecting to and managing Hydra Heads.

Constructor

newHydraProvider({httpUrl: string;wsUrl?: string;history?: boolean;address?: string;})

Methods

Connection Management

• connect() - Establishes connection to the Hydra Head
• disconnect(timeout?: number) - Disconnects from the Hydra Head (default timeout: 5 minutes)

Head Lifecycle Commands

• init() - Initializes a new Hydra Head (only when status is Idle)
• abort() - Aborts a head before it opens (only during Initializing phase)
• close() - Closes an open head, starting the contest period
• contest() - Contests a closed head if needed
• fanout() - Finalizes the head closure and distributes funds

Transaction Operations

• newTx(transaction: hydraTransaction) - Submits a transaction to the open head
• recover(txHash: string) - Recovers a deposit transaction by its hash

Data Fetching (implements IFetcher)

• fetchUTxOs(address?: string) - Fetches UTxOs from the Hydra Head
• fetchProtocolParameters() - Fetches protocol parameters

Transaction Submission (implements ISubmitter)

• submitTx(tx: string) - Submits a transaction to the Hydra Head

Event Handling

• onStatusChange(event: string, callback: Function) - Listen to Hydra events
• onMessage(callback: Function) - Register a callback for all messages

Events

The provider emits various events:

• Greetings - Initial connection message with head status
• HeadIsInitializing - Head initialization started
• HeadIsOpen - Head is now open and ready
• HeadIsClosed - Head has been closed
• HeadIsAborted - Head was aborted
• TxValid - Transaction was accepted
• TxInvalid - Transaction was rejected
• Snapshot - New snapshot created
• Commit - New commit received
• Decommit - Decommit occurred
• And more...

HydraInstance

A higher-level interface for interacting with Hydra Heads, providing convenient methods for common operations.

Constructor

newHydraInstance({provider: HydraProvider;
fetcher: 'blockchainProvider'; submitter: 'blockchainProvider';})

Methods

Commit Operations

• commitEmpty() - Creates an empty commit transaction (no funds)
• commitFunds(txHash: string, outputIndex: number) - Commits a specific UTxO to the head
• commitBlueprint(txHash: string, outputIndex: number, transaction: hydraTransaction) - Commits a UTxO as a blueprint transaction

Decommit Operations

• decommit() - Decommits all your funds from the head

Examples

Complete Workflow Example

import{HydraProvider,HydraInstance}from"@meshsdk/hydra";import{BlockfrostProvider,MeshTxBuilder,MeshWallet}from"@meshsdk/core";// Setup providersconsthydraProvider=newHydraProvider({httpUrl: "http://localhost:4001",});constblockchainProvider=newBlockfrostProvider("YOUR_BLOCKFROST_KEY");consthydraInstance=newHydraInstance({provider: hydraProvider,fetcher: blockchainProvider,submitter: blockchainProvider,});awaithydraProvider.connect();awaithydraProvider.init();constcommitTx=awaithydraInstance.commitFunds(txHash,outputIndex);awaitwallet.submitTx(commitTx);hydraProvider.onMessage("HeadIsOpen",async()=>{consttxBuilder=newMeshTxBuilder({fetcher: blockchainProvider,submitter: blockchainProvider,params: awaithydraProvider.fetchProtocolParameters(),isHydra: true,});// Add your transaction logicconstunsignedTx=awaittxBuilder.sendLovelace(address,"1000000").complete();consttxHash=awaithydraProvider.newTx({type: "Tx ConwayEra",cborHex: unsignedTx,});console.log("Transaction submitted:",txHash);});// When done, close the headawaithydraProvider.close();awaithydraProvider.fanout();

Event-Driven Example

consthydraProvider=newHydraProvider({httpUrl: "http://localhost:4001",});awaithydraProvider.connect();hydraProvider.onMessage((message)=>{switch(message.tag){case"Greetings":
console.log("Connected! Head status:",message.headStatus);break;case"HeadIsOpen":
console.log("Head is now open!");break;case"TxValid":
console.log("Transaction accepted:",message.transactionId);break;case"TxInvalid":
console.error("Transaction rejected:",message.validationError);break;case"Snapshot":
console.log("New snapshot:",message.snapshot);break;}});

Requirements

• Node.js 16+ or modern browser with ES module support
• Access to a Hydra node (local or remote)
• Mesh SDK peer dependencies installed

Documentation

For more detailed documentation, examples, and guides, visit:

• Official Documentation: meshjs.dev/hydra
• Hydra Protocol Docs: hydra.family/head-protocol

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the terms specified in the LICENSE file.

Support

For support and questions:

• Check the documentation
• Open an issue on GitHub
• Visit the Mesh community forums

---