@hydra-sdk/core – Utilities

Hydra SDK provides a comprehensive collection of utility functions for working with Cardano blockchain data, WASM operations, and common development tasks.

Overview

Utilities are organized into multiple categories:

Import

All utilities are exported as namespaced modules for better organization:

typescript
import {
    Serializer,
    Deserializer,
    Resolver,
    Converter,
    BuildKeys,
    ParserUtils,
    TimeUtils,
    DatumUtils,
    PolicyUtils,
    MetadataUtils,
    ProviderUtils,
    CostModels,
    KeysUtils,
    SLOT_CONFIG_NETWORK
} from '@hydra-sdk/core'

Keys Utilities 1.1.5+

KeysUtils.cardanoCliKeygen() → CardanoCLiKeyPair

Generate an ed25519 key pair compatible with Cardano CLI.

Description: Generate signing and verification keys compatible with Cardano CLI format.

Example:

typescript
import { KeysUtils } from '@hydra-sdk/core'

const cardanoKeys = KeysUtils.cardanoCliKeygen()
console.log({
    skey: cardanoKeys.sk.cborHex, // PaymentSigningKeyShelley_ed25519
    vkey: cardanoKeys.vk.cborHex // PaymentVerificationKeyShelley_ed25519
})

Returns: CardanoCLiKeyPair

typescript
{
  sk: HydraCliSkey,
  vk: HydraCliVkey,
}

KeysUtils.hydraCliKeygen() → HydraCliKeyPair

Generate an ed25519 key pair compatible with Hydra.

Description: Generate signing and verification keys compatible with Hydra CLI format.

Example:

typescript
import { KeysUtils } from '@hydra-sdk/core'

const hydraKeys = KeysUtils.hydraCliKeygen()
console.log({
    skey: hydraKeys.sk.cborHex, // HydraSigningKey_ed25519
    vkey: hydraKeys.vk.cborHex // HydraVerificationKey_ed25519
})

Returns: HydraCliKeyPair

typescript
{
  sk: HydraCliSkey,
  vk: HydraCliVkey,
}

KeysUtils.genVkey(skey: CardanoCLiSkey | HydraCliSkey) → CardanoCLiVkey | HydraCliVkey

Generate a verification key from a signing key.

Parameters:

  • skey (CardanoCLiSkey | HydraCliSkey): Source signing key

Example:

typescript
import { KeysUtils } from '@hydra-sdk/core'

const skey = KeysUtils.cardanoCliKeygen().sk
const vkey = KeysUtils.genVkey(skey)
console.log('Verification Key:', vkey.cborHex)

Returns: CardanoCLiVkey | HydraCliVkey Corresponding verification key

KeysUtils.mnemonicToCliKey(mnemonic: string[], accountIndex?: number, keyIndex?: number)

→ CardanoCliKeyPair 1.1.6+

Convert a BIP-39 mnemonic phrase to Cardano CLI compatible key pair.

Description: Derives payment keys from a mnemonic phrase using BIP-44 derivation path (m/1852'/1815'/account'/0/keyIndex). This allows you to generate keys that are compatible with Cardano wallets and CLI tools.

Parameters:

  • mnemonic (string): BIP-39 mnemonic words (12 or 24 words)
  • accountIndex (number, optional): Account index in derivation path (default: 0)
  • keyIndex (number, optional): Key index in derivation path (default: 0)

Example:

typescript
import { KeysUtils, AppWallet } from '@hydra-sdk/core'

// Generate a random mnemonic
const mnemonic = AppWallet.brew()

// Convert to CLI keys with default indexes
const keys = KeysUtils.mnemonicToCliKey(mnemonic)
console.log({
    skey: keys.sk.cborHex,
    vkey: keys.vk.cborHex
})

// Use specific account index (for multiple accounts)
const account1Keys = KeysUtils.mnemonicToCliKey(mnemonic, 1)

// Use specific key index (for multiple addresses)
const addressKeys = KeysUtils.mnemonicToCliKey(mnemonic, 0, 5)

Returns: CardanoCLiKeyPair

typescript
{
  sk: CardanoCLiSkey,  // PaymentSigningKeyShelley_ed25519
  vk: CardanoCLiVkey   // PaymentVerificationKeyShelley_ed25519
}

Important Notes:

  • Uses BIP-44 derivation path: m/1852'/1815'/accountIndex'/0/keyIndex
  • Different accountIndex values create different accounts from the same mnemonic
  • Different keyIndex values create different payment addresses for the same account
  • Keys are deterministic - same mnemonic + indexes always produce the same keys
  • Compatible with Cardano CLI and most Cardano wallets

Data Parsing

ParserUtils.bytesToHex(bytes: ArrayBuffer | Uint8Array | Buffer) → string

Convert bytes to hex string.

Parameters:

  • bytes (ArrayBuffer | Uint8Array | Buffer): Bytes data to convert

Example:

typescript
import { ParserUtils } from '@hydra-sdk/core'

const bytes = new Uint8Array([72, 101, 108, 108, 111])
const hex = ParserUtils.bytesToHex(bytes)
console.log(hex) // "48656c6c6f"

Returns: string Hex string

ParserUtils.hexToBytes(hex: string) → Buffer

Convert hex string to bytes.

Parameters:

  • hex (string): Hex string to convert

Example:

typescript
import { ParserUtils } from '@hydra-sdk/core'

const bytes = ParserUtils.hexToBytes('48656c6c6f')
console.log(bytes) // <Buffer 48 65 6c 6c 6f>

Returns: Buffer Bytes data

ParserUtils.stringToHex(str: string) → string

Convert UTF-8 string to hex.

Parameters:

  • str (string): UTF-8 string

Example:

typescript
import { ParserUtils } from '@hydra-sdk/core'

const hex = ParserUtils.stringToHex('Hello World')
console.log(hex) // "48656c6c6f20576f726c64"

Returns: string Hex string

ParserUtils.hexToString(hex: string) → string

Convert hex string to UTF-8.

Parameters:

  • hex (string): Hex string to convert

Example:

typescript
import { ParserUtils } from '@hydra-sdk/core'

const str = ParserUtils.hexToString('48656c6c6f20576f726c64')
console.log(str) // "Hello World"

Returns: string UTF-8 string

ParserUtils.toBytes(strOrHex: string) → Uint8Array

Convert string or hex to bytes.

Parameters:

  • strOrHex (string): String or hex string

Example:

typescript
import { ParserUtils } from '@hydra-sdk/core'

const bytes1 = ParserUtils.toBytes('Hello World')
const bytes2 = ParserUtils.toBytes('48656c6c6f')
console.log(bytes1, bytes2)

Returns: Uint8Array Bytes data

ParserUtils.fromUTF8(str: string) → string

Convert UTF-8 string to hex (alias).

Parameters:

  • str (string): UTF-8 string

Example:

typescript
import { ParserUtils } from '@hydra-sdk/core'

const hex = ParserUtils.fromUTF8('Hello')
console.log(hex) // "48656c6c6f"

Returns: string Hex string

ParserUtils.toUTF8(hex: string) → string

Convert hex string to UTF-8 (alias).

Parameters:

  • hex (string): Hex string

Example:

typescript
import { ParserUtils } from '@hydra-sdk/core'

const str = ParserUtils.toUTF8('48656c6c6f')
console.log(str) // "Hello"

Returns: string UTF-8 string

Datum Utilities

DatumUtils.mkInt(n: string | number | bigint) → PlutusData

Create an integer datum.

Parameters:

  • n (string | number | bigint): Integer value

Example:

typescript
import { DatumUtils } from '@hydra-sdk/core'

const intDatum = DatumUtils.mkInt(42)
const bigIntDatum = DatumUtils.mkInt(9007199254740991n)
console.log(intDatum.to_hex())

Returns: PlutusData Integer datum

DatumUtils.mkBytes(hex: string) → PlutusData

Create a bytes datum from hex string.

Parameters:

  • hex (string): Hex string of bytes data

Example:

typescript
import { DatumUtils } from '@hydra-sdk/core'

const bytesDatum = DatumUtils.mkBytes('deadbeef')
console.log(bytesDatum.to_hex())

Returns: PlutusData Bytes datum

DatumUtils.mkConstr(alt: number, fields: PlutusData[]) → PlutusData

Create a constructor datum.

Parameters:

  • alt (number): Constructor index (0-based)
  • fields (PlutusData): Array of Plutus data fields

Example:

typescript
import { DatumUtils } from '@hydra-sdk/core'

const constrDatum = DatumUtils.mkConstr(0, [
    DatumUtils.mkInt(42),
    DatumUtils.mkBytes('deadbeef')
])
console.log(constrDatum.to_hex())

Returns: PlutusData Constructor datum

DatumUtils.mkMap(entries: Array<[PlutusData, PlutusMapValues]>) → PlutusData

Create a map datum.

Parameters:

  • entries (Array<PlutusData, PlutusMapValues>): Array of key-value pairs

Example:

typescript
import { DatumUtils } from '@hydra-sdk/core'

const mapDatum = DatumUtils.mkMap([
    [DatumUtils.mkInt(1), DatumUtils.mkBytes('value1')],
    [DatumUtils.mkInt(2), DatumUtils.mkBytes('value2')]
])
console.log(mapDatum.to_hex())

Returns: PlutusData Map datum

Policy Utilities

PolicyUtils.buildPolicyScriptFromPubkey(pubkeyScript: PubkeyScript) → string

Build a policy script from public key.

Parameters:

  • pubkeyScript (PubkeyScript):
    • type: 'sig'
    • keyHash (string): Public key hash

Example:

typescript
import { PolicyUtils } from '@hydra-sdk/core'

const policyScript = PolicyUtils.buildPolicyScriptFromPubkey({
    type: 'sig',
    keyHash: 'abc123def456...'
})
console.log('Policy Script:', policyScript)

Returns: string Native script in JSON format

PolicyUtils.buildMintingPolicyScriptFromAddress(addressBech32: string) → string

Build a minting policy script from an address.

Parameters:

  • addressBech32 (string): Cardano address (bech32)

Example:

typescript
import { PolicyUtils } from '@hydra-sdk/core'

const mintingScript = PolicyUtils.buildMintingPolicyScriptFromAddress(
    'addr1qx2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer3jcu5d8ps7zex2k2xt3uqxgjqnnj83ws8lhrn648jjxtwq2ytjqp'
)
console.log('Minting Script:', mintingScript)

Returns: string Script in JSON format

PolicyUtils.buildMintingPolicyScriptFromKeyHash(keyHash: string) → string

Build a minting policy script from key hash.

Parameters:

  • keyHash (string): Public key hash (hex)

Example:

typescript
import { PolicyUtils } from '@hydra-sdk/core'

const mintingScript =
    PolicyUtils.buildMintingPolicyScriptFromKeyHash('abc123...')
console.log('Minting Script:', mintingScript)

Returns: string Script in JSON format

PolicyUtils.policyIdFromNativeScript(nativeScript: string) → string

Extract Policy ID from native script.

Parameters:

  • nativeScript (string): Native script in JSON string format

Example:

typescript
import { PolicyUtils } from '@hydra-sdk/core'

const policyId = PolicyUtils.policyIdFromNativeScript(policyScript)
console.log('Policy ID:', policyId)

Returns: string Policy ID (hex hash)

Metadata Utilities

MetadataUtils.metadataObjToMetadatum(metadata: any) → TransactionMetadatum

Convert various data types to Cardano transaction metadata.

Parameters:

  • metadata (any): Data to convert (string, number, bigint, Uint8Array, array, object, Map)

Example:

typescript
import { MetadataUtils } from '@hydra-sdk/core'

// Convert string
const stringMetadata = MetadataUtils.metadataObjToMetadatum('Hello World')

// Convert number
const numberMetadata = MetadataUtils.metadataObjToMetadatum(42)

// Convert bigint
const bigintMetadata = MetadataUtils.metadataObjToMetadatum(9007199254740991n)

// Convert bytes
const bytesMetadata = MetadataUtils.metadataObjToMetadatum(
    new Uint8Array([1, 2, 3, 4])
)

// Convert array
const arrayMetadata = MetadataUtils.metadataObjToMetadatum([
    'item1',
    42,
    new Uint8Array([5, 6])
])

// Convert object to map
const objectMetadata = MetadataUtils.metadataObjToMetadatum({
    name: 'NFT Name',
    image: 'ipfs://...',
    attributes: ['trait1', 'trait2']
})

// Convert Map
const mapMetadata = MetadataUtils.metadataObjToMetadatum(
    new Map([
        ['key1', 'value1'],
        ['key2', 42]
    ])
)

Returns: TransactionMetadatum Cardano formatted metadata

Important Notes:

  • Maximum metadata bytes size: 64 bytes
  • Maximum metadata text size: 64 characters
  • Arrays and Maps are processed recursively, pay attention to total metadata size

Time Utilities

TimeUtils.slotToBeginUnixTime(slot: number, slotConfig: SlotConfig) → number

Convert slot to Unix timestamp.

Parameters:

  • slot (number): Slot number
  • slotConfig (SlotConfig): Slot configuration (PREPROD, MAINNET, etc.)

Example:

typescript
import { TimeUtils, SLOT_CONFIG_NETWORK } from '@hydra-sdk/core'

const timestamp = TimeUtils.slotToBeginUnixTime(
    1000,
    SLOT_CONFIG_NETWORK.PREPROD
)
const date = new Date(timestamp * 1000)
console.log('Slot start time:', date.toLocaleString())

Returns: number Unix timestamp (seconds)

TimeUtils.unixTimeToEnclosingSlot(unixTime: number, slotConfig: SlotConfig) → number

Convert Unix timestamp to slot.

Parameters:

  • unixTime (number): Unix timestamp (seconds)
  • slotConfig (SlotConfig): Slot configuration

Example:

typescript
import { TimeUtils, SLOT_CONFIG_NETWORK } from '@hydra-sdk/core'

const slot = TimeUtils.unixTimeToEnclosingSlot(
    Math.floor(Date.now() / 1000),
    SLOT_CONFIG_NETWORK.PREPROD
)
console.log('Current slot:', slot)

Returns: number Slot number

TimeUtils.resolveSlotNo(unixTime: number) → string

Determine slot number based on timestamp.

Parameters:

  • unixTime (number): Unix timestamp (seconds or milliseconds)

Example:

typescript
import { TimeUtils } from '@hydra-sdk/core'

const slotNo = TimeUtils.resolveSlotNo(Date.now())
console.log('Current slot:', slotNo)

Returns: string Slot number as string

TimeUtils.resolveEpochNo(unixTime: number) → number

Determine epoch number based on timestamp.

Parameters:

  • unixTime (number): Unix timestamp (seconds or milliseconds)

Example:

typescript
import { TimeUtils } from '@hydra-sdk/core'

const epochNo = TimeUtils.resolveEpochNo(Date.now())
console.log('Current epoch:', epochNo)

Returns: number Epoch number

TimeUtils.buildHydraSlotConfig(unixTime: number) → SlotConfig

Build Hydra slot configuration for a specific timestamp.

Parameters:

  • unixTime (number): Unix timestamp (seconds)

Example:

typescript
import { TimeUtils } from '@hydra-sdk/core'

const slotConfig = TimeUtils.buildHydraSlotConfig(Date.now())
console.log('Hydra Slot Config:', {
    zeroTime: slotConfig.zeroTime,
    zeroSlot: slotConfig.zeroSlot,
    slotLength: slotConfig.slotLength
})

Returns: SlotConfig Slot configuration

Provider Utilities

BlockfrostProvider.constructor(options: BlockfrostOptions) → BlockfrostProvider

Create a Blockfrost provider to query blockchain data.

Parameters:

  • options (BlockfrostOptions):
    • projectId (string): Blockfrost project ID
    • network (string): 'mainnet', 'preprod', 'preview'

Example:

typescript
import { BlockfrostProvider } from '@hydra-sdk/core'

const provider = new BlockfrostProvider({
    projectId: 'your-project-id',
    network: 'preprod'
})

// Get UTxOs
const utxos = await provider.getUtxos(address)

// Get protocol parameters
const protocolParams = await provider.getProtocolParameters()

Returns: BlockfrostProvider Provider instance

OgmiosProvider.constructor(options: OgmiosOptions) → OgmiosProvider

Create an Ogmios provider to connect WebSocket to Cardano node.

Parameters:

  • options (OgmiosOptions):
    • url (string): WebSocket URL (e.g. 'ws://localhost:1337')

Example:

typescript
import { OgmiosProvider } from '@hydra-sdk/core'

const provider = new OgmiosProvider({
    url: 'ws://localhost:1337'
})

// Get UTxOs
const utxos = await provider.getUtxos(address)

// Submit transaction
const result = await provider.submitTx(signedTx)

Returns: OgmiosProvider Provider instance

Cardano WASM Utilities

Serializer.serializeTransaction(transaction: Transaction) → string

Serialize Cardano transaction to CBOR hex format.

Parameters:

  • transaction (Transaction): Transaction object

Example:

typescript
import { Serializer } from '@hydra-sdk/core'

const serializedTx = Serializer.serializeTransaction(transaction)
console.log('Serialized TX:', serializedTx)

Returns: string CBOR hex string

Deserializer.deserializeTransaction(serializedData: string) → Transaction

Deserialize CBOR data to Cardano transaction.

Parameters:

  • serializedData (string): CBOR hex string

Example:

typescript
import { Deserializer } from '@hydra-sdk/core'

const transaction = Deserializer.deserializeTransaction(cborHex)
console.log('Transaction:', transaction)

Returns: Transaction Transaction object

Resolver.resolveAddress(bech32Address: string) → Address

Resolve and parse Cardano address.

Parameters:

  • bech32Address (string): Cardano address (bech32)

Example:

typescript
import { Resolver } from '@hydra-sdk/core'

const address = Resolver.resolveAddress(
    'addr1qx2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer3jcu5d8ps7zex2k2xt3uqxgjqnnj83ws8lhrn648jjxtwq2ytjqp'
)
console.log('Address info:', address)

Returns: Address Parsed address object

Converter.bytesToHex(bytes: Uint8Array) → string

Convert bytes to hex string.

Parameters:

  • bytes (Uint8Array): Bytes data

Example:

typescript
import { Converter } from '@hydra-sdk/core'

const hex = Converter.bytesToHex(new Uint8Array([1, 2, 3, 4]))
console.log(hex) // "01020304"

Returns: string Hex string

Converter.hexToBytes(hex: string) → Uint8Array

Convert hex string to bytes.

Parameters:

  • hex (string): Hex string

Example:

typescript
import { Converter } from '@hydra-sdk/core'

const bytes = Converter.hexToBytes('01020304')
console.log(bytes) // Uint8Array(4) [ 1, 2, 3, 4 ]

Returns: Uint8Array Bytes data

BuildKeys.deriveKeys(rootKey: string, derivationPath: string[]) → DerivedKeys

Derive cryptographic keys from root key.

Parameters:

  • rootKey (string): Root key (hex)
  • derivationPath (string): Derivation path (e.g. "m", "44'", "1815'", "0'", "0", "0")

Example:

typescript
import { BuildKeys } from '@hydra-sdk/core'

const derivedKeys = BuildKeys.deriveKeys(rootKeyHex, [
    'm',
    "44'",
    "1815'",
    "0'",
    '0',
    '0'
])
console.log('Derived keys:', derivedKeys)

Returns: DerivedKeys Derived keys

Cost Models

CostModels.buildCostModels() → Costmdls

Build cost models for Plutus scripts.

Example:

typescript
import { CostModels } from '@hydra-sdk/core'

const costModels = CostModels.buildCostModels()
console.log('Cost Models:', costModels)

Returns: Costmdls Cost models object

Complete Examples

Basic Data Conversion

typescript
import {
    ParserUtils,
    DatumUtils,
    PolicyUtils,
    SLOT_CONFIG_NETWORK,
    TimeUtils
} from '@hydra-sdk/core'

// Convert data
const hex = ParserUtils.stringToHex('Hello Cardano')
const bytes = ParserUtils.hexToBytes(hex)
console.log('Hex:', hex)
console.log('Bytes:', bytes)

// Work with time
const currentSlot = TimeUtils.unixTimeToEnclosingSlot(
    Math.floor(Date.now() / 1000),
    SLOT_CONFIG_NETWORK.PREPROD
)
const readableTime = new Date(
    TimeUtils.slotToBeginUnixTime(currentSlot, SLOT_CONFIG_NETWORK.PREPROD) * 1000
)
console.log('Current slot:', currentSlot)
console.log('Readable time:', readableTime.toLocaleString())

// Create datum
const datum = DatumUtils.mkConstr(0, [
    DatumUtils.mkInt(42),
    DatumUtils.mkBytes(hex)
])
console.log('Datum hex:', datum.to_hex())

Working with Keys

typescript
import { KeysUtils } from '@hydra-sdk/core'

// Generate Cardano CLI keys
const cardanoKeys = KeysUtils.cardanoCliKeygen()
console.log({
    signingKey: cardanoKeys.sk.cborHex,
    verificationKey: cardanoKeys.vkey.cborHex
})

// Generate Hydra keys
const hydraKeys = KeysUtils.hydraCliKeygen()
console.log({
    hydraSigningKey: hydraKeys.sk.cborHex,
    hydraVkey: hydraKeys.vkey.cborHex
})

// Generate verification key from signing key
const vkey = KeysUtils.genVkey(cardanoKeys.sk)
console.log('Verification Key:', vkey.cborHex)

Creating Minting Policy

typescript
import { PolicyUtils, ParserUtils } from '@hydra-sdk/core'

// Build policy from key hash
const keyHash = '...' // Your public key hash
const policyScript = PolicyUtils.buildMintingPolicyScriptFromKeyHash(keyHash)

// Extract Policy ID
const policyId = PolicyUtils.policyIdFromNativeScript(policyScript)
console.log('Policy ID:', policyId)

// Build policy from address
const address = 'addr1qx2fxv2...'
const addressPolicy = PolicyUtils.buildMintingPolicyScriptFromAddress(address)
const addressPolicyId = PolicyUtils.policyIdFromNativeScript(addressPolicy)
console.log('Address Policy ID:', addressPolicyId)

Handling Metadata

typescript
import { MetadataUtils } from '@hydra-sdk/core'

// NFT metadata
const nftMetadata = MetadataUtils.metadataObjToMetadatum({
    name: 'My NFT',
    image: 'ipfs://QmXxxx...',
    description: 'A beautiful NFT',
    attributes: [
        { trait_type: 'Rarity', value: 'Rare' },
        { trait_type: 'Color', value: 'Blue' }
    ]
})

// Custom metadata with numbers and bytes
const customMetadata = MetadataUtils.metadataObjToMetadatum(
    new Map([
        ['owner', 'Alice'],
        ['value', 1000000],
        ['hash', new Uint8Array([0x12, 0x34, 0x56, 0x78])]
    ])
)

console.log('NFT Metadata:', nftMetadata)
console.log('Custom Metadata:', customMetadata)

Query Blockchain with Provider

typescript
import { BlockfrostProvider, OgmiosProvider } from '@hydra-sdk/core'

// Using Blockfrost
const blockfrostProvider = new BlockfrostProvider({
    projectId: 'your-blockfrost-project-id',
    network: 'preprod'
})

const utxos = await blockfrostProvider.getUtxos(address)
const protocolParams = await blockfrostProvider.getProtocolParameters()

console.log('UTxOs:', utxos)
console.log('Protocol Params:', protocolParams)

// Using Ogmios
const ogmiosProvider = new OgmiosProvider({
    url: 'ws://localhost:1337'
})

const ogmiosUtxos = await ogmiosProvider.getUtxos(address)
console.log('Ogmios UTxOs:', ogmiosUtxos)

Type Definitions

All utilities come with comprehensive TypeScript definitions:

typescript
import type {
    SlotConfig,
    Network,
    PlutusData,
    ConstrPlutusData,
    PlutusMap,
    CardanoCLiSkey,
    CardanoCLiVkey,
    HydraCliSkey,
    HydraCliVkey,
    TransactionMetadatum
} from '@hydra-sdk/core'