API Reference

Complete API reference for Hydra-Yaci, including WebSocket API, example scripts, and NPM commands.

NPM Scripts API
WebSocket API
Example Scripts
REST API (Yaci DevKit)
Lucid Evolution API
Monitoring API

NPM Scripts API

Prerequisites and Setup

`npm run prerequisites`

Check system requirements and prerequisites.

Usage:

npm run prerequisites

Checks:

Node.js installation and version
npm installation
Docker installation
curl and jq utilities
Yaci DevKit status
Port availability (4001-4003, 5001-5003, 6001-6003)

Exit Codes:

0 - All checks passed
1 - One or more checks failed

`npm run setup`

Setup project directories and download Hydra binaries.

Usage:

npm run setup

Actions:

Creates hydra-nodes directory structure
Downloads Hydra node binaries (if supported)
Creates Docker wrapper scripts
Sets up configuration files

Key Management

`npm run keys:generate`

Generate cryptographic keys for all participants.

Usage:

npm run keys:generate

Generates:

Hydra protocol signing and verification keys
Cardano payment signing and verification keys
Cardano addresses

Output Location:

hydra-nodes/alice/keys/
hydra-nodes/bob/keys/
hydra-nodes/carol/keys/

Wallet Management

`npm run wallets:fund`

Fund participant wallets using Yaci DevKit.

Usage:

npm run wallets:fund

Amount:

Configured by INITIAL_FUNDS in .env
Default: 1000 ADA

Requirements:

Yaci DevKit running
Keys already generated
Yaci node created and started

Hydra Node Management

`npm run hydra:start`

Start all Hydra nodes (Alice, Bob, Carol).

Usage:

npm run hydra:start

Starts:

3 Docker containers
WebSocket API on ports 4001, 4002, 4003
P2P networking on ports 5001, 5002, 5003
Monitoring on ports 6001, 6002, 6003

Requirements:

Docker running
Keys generated
Wallets funded
Hydra scripts published

`npm run hydra:stop`

Stop all Hydra nodes.

Usage:

npm run hydra:stop

Actions:

Stops Docker containers
Preserves state and keys
Closes network connections

Maintenance

`npm run reset`

Reset all state and keys.

Usage:

npm run reset

Warning: This deletes all generated keys and state!

Deletes:

All participant keys
Generated addresses
Hydra node state
Transaction history

Examples

`npm run example:status`

Check Yaci DevKit status and blockchain information.

Usage:

npm run example:status

Output:

Current epoch
Block count
Transaction count
Latest block information
Network magic

`npm run example:addresses`

Generate and display participant addresses.

Usage:

npm run example:addresses

Output:

Alice’s address
Bob’s address
Carol’s address

`npm run example:fund`

Fund wallets from Yaci faucet.

Usage:

npm run example:fund

Amount:

Configured in script
Default: 1000 ADA per wallet

`npm run example:open`

Open a Hydra head.

Usage:

npm run example:open

Actions:

Connects to Hydra nodes
Sends Init message
Waits for initialization
Returns head ID

`npm run example:workflow`

Run complete Hydra workflow.

Usage:

npm run example:workflow

Workflow:

Check Yaci status
Generate addresses
Fund wallets
Open Hydra head
Commit funds
Send test payment
Close head

WebSocket API

Connection

Connect to a Hydra node’s WebSocket API:

const ws = new WebSocket('ws://localhost:4001');

Endpoints:

Alice: ws://localhost:4001
Bob: ws://localhost:4002
Carol: ws://localhost:4003

Client Messages (Client → Server)

Init

Initialize a new Hydra head.

{
  "tag": "Init"
}

Requirements:

All participants connected
Wallets funded

Response: HeadIsInitializing

Commit

Commit UTxO to the head.

{
  "tag": "Commit",
  "utxo": {
    "<tx_id>#<index>": {
      "address": "addr_test1...",
      "value": {
        "lovelace": 1000000
      }
    }
  }
}

Requirements:

Head in initializing state
UTxO exists in wallet

Response: Committed

NewTx

Submit a new transaction to the head.

{
  "tag": "NewTx",
  "transaction": {
    "type": "Tx ConwayEra",
    "description": "",
    "cborHex": "84a500818258..."
  }
}

Requirements:

Head is open
Valid transaction CBOR

Response: TxValid or TxInvalid

Close

Close the Hydra head.

{
  "tag": "Close"
}

Requirements:

Head is open

Response: HeadIsClosed

Abort

Abort head initialization.

{
  "tag": "Abort"
}

Requirements:

Head is initializing
Not all participants committed

Response: HeadIsAborted

Server Messages (Server → Client)

Greetings

First message when connecting.

{
  "tag": "Greetings",
  "me": {
    "vkey": "a5c2e70fe94108c2cb1c559942f0152525ae2350f6dc7ce631b3c5313aff7932"
  },
  "headStatus": "Idle",
  "hydraNodeVersion": "1.2.0",
  "hydraHeadId": null,
  "snapshotUtxo": {},
  "networkInfo": {
    "networkConnected": true,
    "peersInfo": {
      "host.docker.internal:5001": true,
      "host.docker.internal:5002": true
    }
  }
}

HeadIsInitializing

Head initialization started.

{
  "tag": "HeadIsInitializing",
  "headId": "4ea01a230b166e43748e28b9ecc729dcfca925038be66d7f9a3238b8",
  "parties": [
    {"vkey": "a2a080fd6497ffba122fc8450b74e0732ae760952d52d3be144469472ee231fc"},
    {"vkey": "8f6f9e73f34cf65a8471c76f50aacafae66401a6fab3bd918fc67a7de8b43df1"},
    {"vkey": "a5c2e70fe94108c2cb1c559942f0152525ae2350f6dc7ce631b3c5313aff7932"}
  ]
}

Committed

Participant committed funds.

{
  "tag": "Committed",
  "party": {
    "vkey": "a5c2e70fe94108c2cb1c559942f0152525ae2350f6dc7ce631b3c5313aff7932"
  },
  "utxo": {
    "<tx_id>#<index>": {
      "address": "addr_test1...",
      "value": {"lovelace": 1000000}
    }
  }
}

HeadIsOpen

Head successfully opened.

{
  "tag": "HeadIsOpen",
  "utxo": {
    "<tx_id>#<index>": {
      "address": "addr_test1...",
      "value": {"lovelace": 3000000}
    }
  }
}

TxValid

Transaction confirmed valid.

{
  "tag": "TxValid",
  "transaction": {
    "type": "Tx ConwayEra",
    "cborHex": "..."
  },
  "utxo": {...}
}

TxInvalid

Transaction rejected.

{
  "tag": "TxInvalid",
  "transaction": {...},
  "validationError": {
    "reason": "MissingInput",
    "utxo": "<tx_id>#<index>"
  }
}

SnapshotConfirmed

Snapshot confirmed by all parties.

{
  "tag": "SnapshotConfirmed",
  "snapshot": {
    "snapshotNumber": 1,
    "utxo": {...},
    "confirmedTransactions": [...]
  }
}

HeadIsClosed

Head closed on-chain.

{
  "tag": "HeadIsClosed",
  "snapshotNumber": 5,
  "contestationDeadline": "2024-01-15T12:00:00Z"
}

HeadIsFinalized

Head finalized and funds distributed.

{
  "tag": "HeadIsFinalized",
  "utxo": {
    "<tx_id>#<index>": {
      "address": "addr_test1...",
      "value": {"lovelace": 1500000}
    }
  }
}

Example Scripts

check-yaci.js

Check Yaci DevKit status.

Usage:

node examples/check-yaci.js

Output:

Connection status
Epoch information
Block information
Network details

generate-address.js

Generate Cardano addresses from keys.

Usage:

node examples/generate-address.js

Output:

Alice’s address
Bob’s address
Carol’s address

fund-from-faucet.js

Fund wallets from Yaci faucet.

Usage:

node examples/fund-from-faucet.js

Parameters:

Uses addresses from generated keys
Amount from environment or default

open-hydra-head.js

Open a Hydra head.

Usage:

node examples/open-hydra-head.js

Flow:

Connect to all nodes
Send Init
Wait for HeadIsInitializing
Display head ID

commit-fund.js

Commit funds to head.

Usage:

node examples/commit-fund.js

Parameters:

UTxO to commit
Amount to commit

send-payment.js

Send payment within Hydra head.

Usage:

node examples/send-payment.js

Parameters:

Recipient address
Amount in lovelace

close-head.js

Close the Hydra head.

Usage:

node examples/close-head.js

Flow:

Connect to node
Send Close
Wait for HeadIsClosed
Wait for HeadIsFinalized

REST API (Yaci DevKit)

Base URL

http://localhost:8080/api/v1

Endpoints

GET /epochs/latest

Get latest epoch information.

Response:

{
  "epoch": 0,
  "blkCount": 45,
  "txCount": 0,
  "startTime": 1704364800,
  "endTime": null
}

GET /blocks/latest

Get latest block.

Response:

{
  "number": 45,
  "hash": "abc123...",
  "time": 1704364845,
  "epoch": 0,
  "slot": 900
}

GET /addresses/{address}

Get address information and balance.

Response:

{
  "address": "addr_test1...",
  "balance": {
    "lovelace": 1000000000
  },
  "utxos": [...]
}

POST /transactions

Submit a transaction.

Request:

{
  "cborHex": "84a500818258..."
}

Response:

{
  "txHash": "def456..."
}

Lucid Evolution API

Initialize Lucid

import { Lucid } from '@lucid-evolution/lucid';
import { Blockfrost } from '@lucid-evolution/provider';

const lucid = await Lucid.new(
  new Blockfrost('http://localhost:8080/api/v1'),
  'Custom'
);

Build Transaction

const tx = await lucid
  .newTx()
  .payToAddress('addr_test1...', { lovelace: 1000000n })
  .complete();

const signedTx = await tx.sign().complete();
const txHash = await signedTx.submit();

Query UTxOs

const utxos = await lucid.utxosAt('addr_test1...');

Get Wallet Address

const address = await lucid.wallet.address();

Monitoring API

Prometheus Metrics

Endpoints:

Alice: http://localhost:6001/metrics
Bob: http://localhost:6002/metrics
Carol: http://localhost:6003/metrics

Key Metrics

hydra_head_status

Current head status (0=Idle, 1=Initializing, 2=Open, 3=Closed).

hydra_head_status 2.0

hydra_snapshot_number

Current snapshot number.

hydra_snapshot_number 5.0

hydra_tx_confirmation_time_seconds

Transaction confirmation time.

hydra_tx_confirmation_time_seconds_bucket{le="0.1"} 10

hydra_connected_peers

Number of connected peers.

hydra_connected_peers 2.0

Error Codes

WebSocket Errors

Code	Message	Description
1000	Normal closure	Clean shutdown
1001	Going away	Node shutting down
1006	Abnormal closure	Connection lost

HTTP Status Codes

Code	Description
200	Success
400	Bad request
404	Not found
500	Internal server error
503	Service unavailable

Type Definitions

UTxO

type UTxO = {
  [key: string]: {
    address: string;
    value: {
      lovelace: number;
      [assetId: string]: number;
    };
    datum?: string;
    datumHash?: string;
    scriptRef?: string;
  };
};

Party

type Party = {
  vkey: string;
};

Transaction

type Transaction = {
  type: "Tx ConwayEra" | "Tx BabbageEra";
  description: string;
  cborHex: string;
};

HeadStatus

type HeadStatus = 
  | "Idle"
  | "Initializing"
  | "Open"
  | "Closed"
  | "Final";

Rate Limits

WebSocket: No rate limit
Yaci API: 100 requests/second
Prometheus: 1 request/second recommended

Best Practices

Always handle WebSocket reconnection
Validate transaction CBOR before submitting
Wait for SnapshotConfirmed before assuming finality
Monitor Prometheus metrics for performance
Use proper error handling for all API calls

Additional Resources

Need more examples? Check the Usage Guide or example scripts.

API Reference

Table of Contents

NPM Scripts API

Prerequisites and Setup

npm run prerequisites

npm run setup

Key Management

npm run keys:generate

Wallet Management

npm run wallets:fund

Hydra Node Management

npm run hydra:start

npm run hydra:stop

Maintenance

npm run reset

Examples

npm run example:status

npm run example:addresses

npm run example:fund

npm run example:open

npm run example:workflow

WebSocket API

Connection

Client Messages (Client → Server)

Init

Commit

NewTx

Close

Abort

Server Messages (Server → Client)

Greetings

HeadIsInitializing

Committed

HeadIsOpen

TxValid

TxInvalid

SnapshotConfirmed

HeadIsClosed

HeadIsFinalized

Example Scripts

check-yaci.js

generate-address.js

fund-from-faucet.js

open-hydra-head.js

commit-fund.js

send-payment.js

close-head.js

REST API (Yaci DevKit)

Base URL

Endpoints

GET /epochs/latest

GET /blocks/latest

GET /addresses/{address}

POST /transactions

Lucid Evolution API

Initialize Lucid

Build Transaction

Query UTxOs

Get Wallet Address

Monitoring API

Prometheus Metrics

Key Metrics

hydra_head_status

hydra_snapshot_number

hydra_tx_confirmation_time_seconds

hydra_connected_peers

Error Codes

WebSocket Errors

HTTP Status Codes

Type Definitions

UTxO

Party

Transaction

HeadStatus

Rate Limits

Best Practices

Additional Resources

`npm run prerequisites`

`npm run setup`

`npm run keys:generate`

`npm run wallets:fund`

`npm run hydra:start`

`npm run hydra:stop`

`npm run reset`

`npm run example:status`

`npm run example:addresses`

`npm run example:fund`

`npm run example:open`

`npm run example:workflow`