Hydra SDKHydra SDKDocumentation
API Reference

@hydra-sdk/core - Utilities

Comprehensive collection of utility functions for Cardano blockchain data, WASM operations, and common development tasks

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:

  • - Create and manage cryptographic keys
  • - Convert between data formats
  • - Work with Plutus data structures
  • - Build Plutus script redeemers
  • - Validate addresses and transaction outputs
  • - Manage minting policies
  • - Convert transaction metadata
  • - Calculate slots and time
  • - Abstract blockchain data providers
  • - Low-level blockchain operations

Import

All utilities are exported as namespaced modules for better organization:

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

Keys Utilities 1.1.5+

KeysUtils.cardanoCliKeygen() → { sk: CardanoCLiSkey; vk: CardanoCLiVkey }

Generate an ed25519 key pair compatible with Cardano CLI.

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

Example:

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: { sk: CardanoCLiSkey; vk: CardanoCLiVkey }

{
  sk: CardanoCLiSkey,
  vk: CardanoCLiVkey,
}

KeysUtils.hydraCliKeygen() → { sk: HydraCliSkey; vk: HydraCliVkey }

Generate an ed25519 key pair compatible with Hydra.

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

Example:

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: { sk: HydraCliSkey; vk: HydraCliVkey }

{
  sk: HydraCliSkey,
  vk: HydraCliVkey,
}

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

Generate a verification key from a signing key.

Parameters:

  • skey (CardanoCLiSkey | HydraCliSkey | CardanoCliExtendedSkey): Source signing key

Example:

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

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

Returns: CardanoCLiVkey | CardanoCliExtendedVkey Corresponding verification key. A BIP32-Ed25519 signing key (5880...) carries a chain code, so it yields an extended verification key (5840...); every other shape yields a plain one (5820...).

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

→ { sk: CardanoCliExtendedSkey; vk: CardanoCliExtendedVkey } 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:

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: { sk: CardanoCliExtendedSkey; vk: CardanoCliExtendedVkey }

{
  sk: CardanoCliExtendedSkey,  // PaymentExtendedSigningKeyShelley_ed25519_bip32, cborHex 5880... (128-byte xprv)
  vk: CardanoCliExtendedVkey   // PaymentExtendedVerificationKeyShelley_ed25519_bip32, cborHex 5840... (64-byte xpub)
}

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
  • The pair is extended (BIP32-Ed25519), because that is what mnemonic derivation produces. It resolves to the same payment credential as AppWallet.getAccount(accountIndex, keyIndex).enterpriseAddressBech32 and can be passed straight to CardanoCliWallet
Changed in 1.5.0. Earlier versions truncated the derived BIP32-Ed25519 key to 32 bytes and labelled it PaymentSigningKeyShelley_ed25519. That produced a valid but unrelated key: its address did not match the mnemonic's wallet, so funds sent to the address of one were unspendable by the other. If you persisted keys from an earlier version, re-derive them and move any funds across.

Data Parsing

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

Convert bytes to hex string.

Parameters:

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

Example:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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

DatumUtils.mkList(elements: PlutusData[]) → PlutusData

Create a list datum from an array of Plutus data elements.

Example:

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

const listDatum = DatumUtils.mkList([DatumUtils.mkInt(1), DatumUtils.mkInt(2)])
console.log(listDatum.to_hex())

Returns: PlutusData

DatumUtils.mkBool(value: boolean) → PlutusData

Create a boolean datum. Encoded as Constr(0, []) for false and Constr(1, []) for true.

Example:

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

const trueDatum = DatumUtils.mkBool(true)
console.log(trueDatum.to_hex())

Returns: PlutusData

DatumUtils.mkOption(value?: PlutusData | null) → PlutusData

Create an optional datum. Some is Constr(0, [value]); None (no/null value) is Constr(1, []).

Example:

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

const some = DatumUtils.mkOption(DatumUtils.mkInt(42))
const none = DatumUtils.mkOption()

Returns: PlutusData

DatumUtils.mkBytesList(items: Array<string | Uint8Array>) → PlutusData

Create a list datum from an array of byte strings (hex) or Uint8Array values.

Example:

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

const bytesList = DatumUtils.mkBytesList(['deadbeef', new Uint8Array([1, 2, 3])])

Returns: PlutusData

DatumUtils.mkIntList(items: Array<string | number | bigint>) → PlutusData

Create a list datum from an array of integer values.

Example:

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

const intList = DatumUtils.mkIntList([1, 2, 9007199254740991n])

Returns: PlutusData

DatumUtils.mkOutputRef(ref: { txHash: string; index: number | bigint }) → PlutusData

Create an output reference datum, encoded as Constr(0, [Bytes(txHash), Int(index)]).

Example:

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

const outputRef = DatumUtils.mkOutputRef({
    txHash: '1d2e5b97f1cad7bea2b06144abc4974012fa786c9e7e5faddd03243b967a03f6',
    index: 0
})

Returns: PlutusData

DatumUtils.mkAddress(bech32: string) → PlutusData

Encode a bech32 Cardano address into its Plutus data representation.

Example:

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

const addrDatum = DatumUtils.mkAddress('addr1qx2fxv2umyhttkxyxp8x0...')

Returns: PlutusData

DatumUtils.parseAddress(data: PlutusData, networkId?: number) → string

Decode Plutus address data back into a bech32 address string.

Parameters:

  • data (PlutusData): Plutus address data
  • networkId (number, optional): Network ID for the resulting address (default: MAINNET)

Example:

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

const bech32 = DatumUtils.parseAddress(addrDatum, NETWORK_ID.PREPROD)

Returns: string Bech32 address

Redeemer Utilities 1.4.0+

Build Plutus script redeemers. Import: import { RedeemerUtils } from '@hydra-sdk/core'.

RedeemerUtils.mkRedeemer(data: PlutusData, options?: BuildRedeemerOptions) → Redeemer

Wrap Plutus data into a Redeemer.

Parameters:

  • data (PlutusData): Redeemer data
  • options (BuildRedeemerOptions, optional):
    • tag ('spend' | 'mint' | 'reward' | 'cert' | 'vote' | 'voting_proposal', case-insensitive): Redeemer tag. Default: 'spend'
    • index (string | number | bigint): Redeemer index. Default: 0
    • exUnits ({ mem, steps }): Execution unit budget. Default: RedeemerUtils.DEFAULT_EX_UNITS

Example:

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

const data = DatumUtils.mkConstr(1, [])
const redeemer = RedeemerUtils.mkRedeemer(data, { tag: 'spend', index: 0 })

Returns: Redeemer

RedeemerUtils.mkSpendRedeemer(data: PlutusData, options?) → Redeemer

Build a redeemer with the tag preset to spend.

Example:

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

const redeemer = RedeemerUtils.mkSpendRedeemer(DatumUtils.mkConstr(0, []))

Returns: Redeemer

RedeemerUtils.mkMintRedeemer(data: PlutusData, options?) → Redeemer

Build a redeemer with the tag preset to mint.

Example:

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

const redeemer = RedeemerUtils.mkMintRedeemer(DatumUtils.mkConstr(0, []))

Returns: Redeemer

RedeemerUtils.mkUnitRedeemer(options?) → Redeemer

Build the Unit redeemer Constr(0, []) — the "no argument" redeemer.

Example:

import { RedeemerUtils } from '@hydra-sdk/core'

const redeemer = RedeemerUtils.mkUnitRedeemer()

Returns: Redeemer

RedeemerUtils.mkExUnits({ mem, steps }) → ExUnits

Build an ExUnits execution budget. RedeemerUtils.DEFAULT_EX_UNITS is { mem: '5000000', steps: '2000000000' } (a placeholder budget — evaluate scripts for production).

Example:

import { RedeemerUtils } from '@hydra-sdk/core'

const exUnits = RedeemerUtils.mkExUnits({ mem: '5000000', steps: '2000000000' })

Returns: ExUnits

Validation Utilities 1.4.0+

ValidationUtils.isValidTxOutput(output: TxOutput) → boolean

Check whether a transaction output is valid. Import: import { ValidationUtils } from '@hydra-sdk/core'.

Parameters:

  • output (TxOutput): Transaction output to verify

Example:

import { ValidationUtils } from '@hydra-sdk/core'

const isValid = ValidationUtils.isValidTxOutput(txOutput)
console.log('Output valid:', isValid)

Returns: boolean

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:

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:

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:

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:

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:

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:

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:

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(network: Network, milliseconds?: number) → string

Determine slot number for a network at a given time.

Parameters:

  • network (Network): Target network ('MAINNET' | 'PREPROD' | 'PREVIEW')
  • milliseconds (number, optional): Timestamp in milliseconds (default: Date.now())

Example:

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

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

Returns: string Slot number as string

TimeUtils.resolveEpochNo(network: Network, milliseconds?: number) → number

Determine epoch number for a network at a given time.

Parameters:

  • network (Network): Target network ('MAINNET' | 'PREPROD' | 'PREVIEW')
  • milliseconds (number, optional): Timestamp in milliseconds (default: Date.now())

Example:

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

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

Returns: number Epoch number

TimeUtils.buildHydraSlotConfig(startTimestamp: number, options?: object) → SlotConfig

Build Hydra slot configuration anchored at a Head start timestamp.

Parameters:

  • startTimestamp (number): Head start timestamp in milliseconds (required)
  • options (object, optional): Overrides for zeroSlot, slotLength, startEpoch, and epochLength

Example:

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

ProviderUtils.BlockfrostProvider(config: BlockfrostProviderConfig) → BlockfrostProvider

Create a Blockfrost provider to query and submit transactions to the Cardano blockchain.

Description: BlockfrostProvider is a wallet provider that connects to Blockfrost API for fetching UTxOs and submitting transactions. It extends BaseWalletProvider and provides both fetcher and submitter functionality.

Parameters:

  • config (BlockfrostProviderConfig):
    • apiKey (string): Your Blockfrost Project ID from Blockfrost Dashboard
    • network (BlockfrostSupportedNetworks): Network to connect to ('mainnet', 'preprod', or 'preview')
    • apiVersion (number, optional): Blockfrost API version (default: 0)
    • baseURL (string, optional): Override the default Blockfrost endpoint URL. Useful for Blockfrost-compatible APIs such as Demeter.
    • cachingOptions (object, optional): Caching configuration
      • enabled (boolean): Enable response caching (default: false)
      • maxSize (number): Maximum cache items (default: 100)
      • ttl (number): Time to live in milliseconds (default: 300000 - 5 minutes)

Properties:

  • fetcher (IFetcher): Interface for fetching blockchain data
    • fetchAddressUTxOs(address: string, asset?: string): Promise<UTxO[]> - Fetch UTxOs for an address, optionally filtered by asset
  • submitter (ISubmitter): Interface for submitting transactions
    • submitTx(txHex: string): Promise<string> - Submit a signed transaction and return transaction hash

Example:

import { ProviderUtils } from '@hydra-sdk/core'

// Basic configuration
const provider = new ProviderUtils.BlockfrostProvider({
    apiKey: 'preprodXXXXXXXXXXXXXXXXXXXX',
    network: 'preprod'
})

// With API version and caching
const providerWithCache = new ProviderUtils.BlockfrostProvider({
    apiKey: 'preprodXXXXXXXXXXXXXXXXXXXX',
    network: 'preprod',
    apiVersion: 0,
    cachingOptions: {
        enabled: true,
        maxSize: 200,
        ttl: 600000 // 10 minutes
    }
})

// Fetch all UTxOs for an address
const utxos = await provider.fetcher.fetchAddressUTxOs(
    'addr1qx2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer...'
)

// Fetch UTxOs containing a specific asset
const assetUtxos = await provider.fetcher.fetchAddressUTxOs(
    'addr1qx2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer...',
    'lovelace' // or policy_id + asset_name
)

// Submit a signed transaction
const txHash = await provider.submitter.submitTx(signedTxHex)
console.log('Transaction submitted:', txHash)

Returns: BlockfrostProvider Provider instance

ProviderUtils.OgmiosProvider(config: OgmiosProviderConfig) → OgmiosProvider

Create an Ogmios provider to query and submit transactions using JSON-RPC 2.0 protocol.

Description: OgmiosProvider is a wallet provider that connects to Ogmios API via HTTP for fetching UTxOs and submitting transactions. It extends BaseWalletProvider and uses JSON-RPC 2.0 protocol to communicate with Ogmios server.

Parameters:

  • config (OgmiosProviderConfig):
    • network (OgmiosSupportedNetworks): Network to connect to ('mainnet', 'preprod', or 'preview')
    • apiEndpoint (string, optional): Ogmios API endpoint URL

Properties:

  • fetcher (IFetcher): Interface for fetching blockchain data
    • fetchAddressUTxOs(address: string, asset?: string): Promise<UTxO[]> - Fetch UTxOs for an address, optionally filtered by asset
  • submitter (ISubmitter): Interface for submitting transactions
    • submitTx(tx: string): Promise<string> - Submit a signed transaction and return transaction hash

Example:

import { ProviderUtils } from '@hydra-sdk/core'

// Connect to remote Ogmios instance
const remoteProvider = new ProviderUtils.OgmiosProvider({
    network: 'preprod',
    apiEndpoint: 'https://preprod.ogmios.cardano-rpc.hydrawallet.app'
})

// Fetch all UTxOs for an address
const utxos = await remoteProvider.fetcher.fetchAddressUTxOs(
    'addr1qx2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer...'
)

// Fetch UTxOs containing a specific asset
const assetUtxos = await remoteProvider.fetcher.fetchAddressUTxOs(
    'addr1qx2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer...',
    'lovelace' // or policy_id + asset_name
)

// Submit a signed transaction
const txHash = await remoteProvider.submitter.submitTx(signedTxHex)
console.log('Transaction submitted:', txHash)

Returns: OgmiosProvider Provider instance with fetcher and submitter interfaces

ProviderUtils.DemeterProvider(config: DemeterProviderConfig) → DemeterProvider

Create a provider for Demeter's Blockfrost-compatible hosted endpoints. Extends BlockfrostProvider, so it exposes the same fetcher/submitter surface. Authentication is embedded in the endpoint subdomain via authToken.

Parameters:

  • config (DemeterProviderConfig):
    • authToken (string): Your Demeter auth token (also used as the authenticated subdomain)
    • network (DemeterSupportedNetworks): Network to connect to ('mainnet', 'preprod', or 'preview')
    • apiVersion (number, optional): Blockfrost API version (default: 0)
    • cachingOptions (object, optional): Same caching configuration as BlockfrostProvider

Example:

import { ProviderUtils } from '@hydra-sdk/core'

const provider = new ProviderUtils.DemeterProvider({
    authToken: 'blockfrost102lx3ckhzvkjjh7677g',
    network: 'preprod'
})

// Same fetcher / submitter interface as BlockfrostProvider
const utxos = await provider.fetcher.fetchAddressUTxOs(
    'addr1qx2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzer...'
)
const txHash = await provider.submitter.submitTx(signedTxHex)

The endpoint is built as https://{authToken}.cardano-{network}.blockfrost-m1.demeter.run/api/v{apiVersion ?? 0}.

Returns: DemeterProvider Provider instance with fetcher and submitter interfaces

Cardano WASM Utilities

Serializer.serializeAssetUnit(policyId: string, assetName: string) → string

Build an asset unit string by concatenating a policy ID and an asset name (both hex).

Parameters:

  • policyId (string): Policy ID (hex)
  • assetName (string): Asset name (hex)

Example:

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

const unit = Serializer.serializeAssetUnit('a1b2c3...', '48656c6c6f')
console.log('Asset unit:', unit)

Returns: string Asset unit (policyId + assetName)

Deserializer.deserializeTx(txCborHex: string) → FixedTransaction

Deserialize a transaction CBOR hex string into a CardanoWASM.FixedTransaction.

Parameters:

  • txCborHex (string): Transaction CBOR hex string

Example:

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

const tx = Deserializer.deserializeTx(cborHex)
console.log('Tx hash:', tx.transaction_hash().to_hex())

Returns: FixedTransaction Parsed transaction object

Deserializer.deserializeAmountsFromTx(cborHex: string) → Asset[]

Return all amounts (lovelace + native tokens) across every output of a transaction, merged by unit.

Parameters:

  • cborHex (string): Transaction CBOR hex string

Example:

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

const amounts = Deserializer.deserializeAmountsFromTx(cborHex)
console.log('Amounts:', amounts)
// => [{ unit: 'lovelace', quantity: '5000000' }, ...]

Returns: Asset[] Array of { unit, quantity } entries merged by unit

Resolver.resolveTxHash(cborHex: string) → string

Resolve the transaction hash from a transaction CBOR hex string.

Parameters:

  • cborHex (string): Transaction CBOR hex string

Example:

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

const txHash = Resolver.resolveTxHash(cborHex)
console.log('Transaction hash:', txHash)

Returns: string Transaction hash (hex)

Resolver.resolveTxBodyHash(txBody: TransactionBody) → TransactionHash

Resolve the transaction hash from a TransactionBody.

Parameters:

  • txBody (TransactionBody): Transaction body object

Example:

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

const hash = Resolver.resolveTxBodyHash(txBody)
console.log('Transaction hash:', hash.to_hex())

Returns: TransactionHash Transaction hash object

Converter.convertUTxOObjectToUTxO(utxoObject: UTxOObject) → UTxO[]

Convert a snapshot-format UTxO object into an array of UTxO items. Use Converter.convertUTxOToUTxOObject(utxos) for the reverse direction, and Converter.convertUTxOObjectToUTxOWithOptions(utxoObject, options) to tune the datum deserialization cache.

Parameters:

  • utxoObject (UTxOObject): Snapshot UTxO object

Example:

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

const utxos = Converter.convertUTxOObjectToUTxO(snapshotUtxo)
console.log('UTxO count:', utxos.length)

// Reverse conversion
const snapshot = Converter.convertUTxOToUTxOObject(utxos)

Returns: UTxO[] Array of UTxOs

Hex conversion helpers live on ParserUtils (see ) — use ParserUtils.bytesToHex / ParserUtils.hexToBytes. Converter deals with UTxO shapes, not raw hex.

BuildKeys.buildKeys(privateKeyHex: string | [string, string], accountIndex: number, keyIndex?: number) → { accountKey, paymentKey, stakeKey, dRepKey? }

Derive account, payment, stake, and dRep keys from a root private key using the BIP-44 derivation path m/1852'/1815'/accountIndex'/role/keyIndex.

Parameters:

  • privateKeyHex (string | string, string): Root private key hex (or an [accountKey, stakeKey] pair)
  • accountIndex (number): Account index
  • keyIndex (number, optional): Key index (default: 0)

Example:

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

const { accountKey, paymentKey, stakeKey } = BuildKeys.buildKeys(rootKeyHex, 0, 0)
console.log('Payment key:', paymentKey.to_hex())

Returns: { accountKey, paymentKey, stakeKey, dRepKey? } Derived Bip32PrivateKey values

BuildKeys.buildBaseAddress(networkId: number, paymentKeyHash, stakeKeyHash) → BaseAddress

Build a base address (payment + staking) from payment and stake key hashes. Companion helpers buildEnterpriseAddress and buildRewardAddress are also available.

Parameters:

  • networkId (number): Network ID (e.g. NETWORK_ID.PREPROD)
  • paymentKeyHash (Ed25519KeyHash): Payment key hash
  • stakeKeyHash (Ed25519KeyHash): Stake key hash

Example:

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

const baseAddress = BuildKeys.buildBaseAddress(
    NETWORK_ID.PREPROD,
    paymentKeyHash,
    stakeKeyHash
)
console.log('Base address:', baseAddress.to_address().to_bech32())

Returns: BaseAddress Base address object

Cost Models

CostModels.buildCostModels(models: { plutusV1?: number[]; plutusV2?: number[]; plutusV3?: number[] }) → Costmdls

Build cost models for Plutus scripts. At least one of plutusV1 / plutusV2 / plutusV3 must be provided, otherwise it throws At least one cost model must be provided. For zero-config defaults use CostModels.defaultCostModels.

Parameters:

  • models (object): Cost model lists keyed by Plutus language version

Example:

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

// Ready-made defaults for all three Plutus versions
const defaults = CostModels.defaultCostModels

// Or build from explicit cost model lists
const costModels = CostModels.buildCostModels({
    plutusV3: [/* ...cost model integers... */]
})
console.log('Cost Models:', costModels)

Returns: Costmdls Cost models object

Complete Examples

Basic Data Conversion

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

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

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

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

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

Creating Minting Policy

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

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

import { ProviderUtils } from '@hydra-sdk/core'

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

// Query UTxOs via the fetcher (there is no getUtxos/getProtocolParameters on providers)
const utxos = await blockfrostProvider.fetcher.fetchAddressUTxOs(address)
console.log('UTxOs:', utxos)

// Submit via the submitter
// const txHash = await blockfrostProvider.submitter.submitTx(signedTxHex)

// Using Ogmios
const ogmiosProvider = new ProviderUtils.OgmiosProvider({
    network: 'preprod',
    apiEndpoint: 'http://localhost:1337'
})

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

Type Definitions

All utilities come with comprehensive TypeScript definitions:

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

Related Documentation

@hydra-sdk/cardano-wasm

Cardano WASM bindings for advanced blockchain operations

Change Logs

Learn about the changes and updates in each version of the Hydra SDK