World all

Import interface hermes:binary/api

Binary Data API

Binary Data types and functions.

Permissions

This API is ALWAYS available. cspell: words Binary API Interface - Imports ONLY

Types

type bstr

bstr

Binary String (bstr) is a list of bytes. This type is used to indicate the data is an arbitrary array of bytes.

tuple b128

128 bit value

Tuple Fields
  • 0: u64
  • 1: u64

tuple b256

256 bit value

Tuple Fields
  • 0: u64
  • 1: u64
  • 2: u64
  • 3: u64

tuple b512

512 bit value

Tuple Fields
  • 0: u64
  • 1: u64
  • 2: u64
  • 3: u64
  • 4: u64
  • 5: u64
  • 6: u64
  • 7: u64

Import interface hermes:hash/api

Data Hash API

Hashing Data types and functions.

Permissions

This API is ALWAYS available. Hashing API Interface - Imports ONLY

Types

type bstr

bstr

#### `type b256` [`b256`](#b256)

#### `type blake2b256` [`b256`](#b256)

A 256-bit (32-byte) cryptographic hash value produced by the BLAKE2b hash function.

enum errno

Errors that can occur during hashing.

Enum Cases

  • key-too-big

  • hash-too-big

    The key exceeds the supported size of the hash function.

  • salt-too-big

    The hash size requested is larger than supported by the hash function.

  • personal-too-big

    The salt exceeds the supported size of the hash function.

  • invalid-digest-byte-length

    The personal exceeds the supported size of the hash function.

Functions

blake2s: func

BLAKE2s Hash Function

Hash a binary buffer with BLAKE2s.

Parameters

  • buf: The binary data buffer to hash.
  • outlen: Optional. The size of the digest. If the outlen is not defined, it defaults to 32.

Returns

  • Either a buffer the size requested, with the hash.
  • Or an error:
  • hash_too_big if outlen is specified and is > 32 bytes.
  • invalid_digest_byte_length if outlen is specified and is = 0.
Params
  • buf: bstr
  • outlen: option<u8>
Return values

blake2smac: func

BLAKE2sMac Hash Function

Hash a binary buffer with BLAKE2s with MAC (Message Authentication Code) mode.

Parameters

  • buf: The binary data buffer to hash.
  • outlen: Optional. The size of the digest. If the outlen is not defined, it defaults to 32.
  • key: The key to use with the hash. With MAC mode, key is needed to be defined Should not be > 32 bytes.
  • salt: Optional. Salt uses to increase the randomness and uniqueness of the hash output Should not be > 8 bytes. If not defined, salt is not used.
  • personal: Optional. Personal allows to add customization to the hash function behavior. Should not be > 8 bytes. If not defined, personal is not used.

Returns

  • Either a buffer the size requested, with the hash.
  • Or an error:
  • key_too_big if key is > 32 bytes.
  • hash_too_big if outlen is specified and is > 32 bytes.
  • salt_too_big if salt is specified and is > 8 bytes.
  • personal_too_big if personal is specified and is > 8 bytes.

Note:

key length is checked before outlen so if both sizes are invalid, only key_too_big will be returned. If salt length exceeds 8 bytes, salt_too_big will be returned. if personal length exceeds 8 bytes, personal_too_big will be returned.

Params
  • buf: bstr
  • outlen: option<u8>
  • key: bstr
  • salt: option<bstr>
  • personal: option<bstr>
Return values

blake2b: func

BLAKE2b Hash Function

Hash a binary buffer with BLAKE2b.

Parameters

  • buf: The binary data buffer to hash.
  • outlen: Optional. The size of the digest. If the outlen is not defined, it defaults to 64.

Returns

  • Either a buffer the size requested, with the hash.
  • Or an error:
  • hash_too_big if outlen is specified and is > 64 bytes.
  • invalid_digest_byte_length if outlen is specified and is = 0.
Params
  • buf: bstr
  • outlen: option<u8>
Return values

blake2bmac: func

BLAKE2bMac Hash Function

Hash a binary buffer with BLAKE2b with MAC (Message Authentication Code) mode.

Parameters

  • buf: The binary data buffer to hash.
  • outlen: Optional. The size of the digest. If the outlen is not defined, it defaults to 64.
  • key: The key to use with the hash. With MAC mode, key is needed to be defined Should not be > 64 bytes.
  • salt: Optional. Salt uses to increase the randomness and uniqueness of the hash output Should not be > 16 bytes. If not defined, salt is not used.
  • personal: Optional. Personal allows to add customization to the hash function behavior. Should not be > 16 bytes. If not defined, personal is not used.

Returns

  • Either a buffer the size requested, with the hash.
  • Or an error:
  • key_too_big if key is specified and is > 64 bytes.
  • hash_too_big if outlen is specified and is > 64 bytes.
  • salt_too_big if salt is specified and is > 16 bytes.
  • personal_too_big if personal is specified and is > 16 bytes.

Note:

key length is checked before outlen so if both sizes are invalid, only key_too_big will be returned. If salt length exceeds 16 bytes, salt_too_big will be returned. if personal length exceeds 16 bytes, personal_too_big will be returned.

Params
  • buf: bstr
  • outlen: option<u8>
  • key: bstr
  • salt: option<bstr>
  • personal: option<bstr>
Return values

blake3: func

BLAKE3 Hash Function

Hash a binary buffer with BLAKE3.

Parameters

  • buf: The binary data buffer to hash.
  • outlen: Optional. The size of the digest. If the outlen is not defined, it defaults to 32.
  • key: Optional. The key to use with the hash. If not defined, the hash is not keyed. Should not be > 32 bytes.

Returns

  • Either a buffer the size requested, with the hash.
  • Or an error:
  • key_too_big if key is specified and is > 32 bytes.
  • hash_too_big if outlen is specified and is > 32 bytes.

Note:

key length is checked before outlen so if both sizes are invalid, only key_too_big will be returned.

Params
  • buf: bstr
  • outlen: option<u8>
  • key: option<bstr>
Return values

Import interface hermes:cbor/api

CBOR API

CBOR Data types and functions.

Permissions

This API is ALWAYS available. cspell: words CBOR API Interface - Imports ONLY

Types

type bstr

bstr

#### `type cbor` [`bstr`](#bstr)

CBOR is a binary cbor data type. This type is used to indicate the binary array MUST be CBOR data.

Import interface hermes:cardano/api

Cardano Blockchain API

Cardano Blockchain API functionality exposed to the Hermes WASM Modules.

Permissions

This API is ALWAYS available.

Types

type blake2b256

blake2b256

#### `type cbor` [`cbor`](#cbor)

#### `type slot` `u64`

Slot on the Cardano blockchain.

type txn-idx

u16

Cardano transaction index.

type txn-hash

blake2b256

Cardano transaction hash.

variant cardano-network

Cardano blockchain network.

Variant Cases

  • mainnet

    Cardano Mainnet Network :- "NetworkId": 1, "NetworkMagic": 764824073

  • preprod

    Cardano Preprod Network :- "NetworkId": 0, "NetworkMagic": 1

  • preview

    Cardano Preview Network :- "NetworkId": 0, "NetworkMagic": 2

  • testnet-magic: u64

    Custom Test Network :- "NetworkId": 0, "NetworkMagic": u64

variant sync-slot

A sync slot variation.

Variant Cases

  • genesis

    Genesis (first block) of the blockchain.

  • specific: slot

    A specific slot in the blockchain.

  • tip

    The live tip of the blockchain, following the upstream node.

  • immutable-tip

    The immutable tip of the blockchain e.g., The last block which has reached the absolute finality and can never roll back.

enum subscribe-error

Errors that can happen for subscribing to blocks

Enum Cases
  • invalid-start-slot

    The slot requested is not valid.

enum create-network-error

Errors that can happen when initialize network.

Enum Cases

  • network-not-supported

    Network not supported.

  • unknown-network

    Unknown network.

enum block-error

Errors that can happen for block.

Enum Cases
  • block-not-found

    Block is not found.

enum transaction-error

Errors that can happen for transaction.

Enum Cases
  • txn-not-found

    Transaction not found

resource network

Cardano network

resource block

Cardano block

resource transaction

Cardano transaction

resource subscription-id

Functions

[static]network.new: func

Create a new Cardano network instance.

Parameters

  • network: The Cardano network to connect to (e.g., Mainnet, Preprod, Preview).

Returns

  • ok(network): A resource network, if successfully create network resource.
  • error(create-network-error): If creating network resource failed.
Params
Return values

[method]network.subscribe-block: func

Subscribe to blockchain block events, start from a specified starting point.

This sets up a subscription to receive new block and block rollback updates starting from the given start.

Parameters

  • start: The slot to begin following from.

Returns

  • ok(u32): A unsigned integer representing the underlying 32-bit subscription resource ID. This is used to distinguish events from different subscribers and provides control over subscription management.The ID must be unique across all active subscriptions.
  • error(subscribe-error): If subscription failed.
Params
Return values

[method]network.subscribe-immutable-roll-forward: func

Subscribe to blockchain immutable rolls forward.

This sets up a subscription to receive event when the immutable part of the blockchain roll forwards.

Parameters

  • start: The slot to begin following from.

Returns

  • ok(u32): A unsigned integer representing the underlying 32-bit subscription resource ID. This is used to distinguish events from different subscribers and provides control over subscription management.The ID must be unique across all active subscriptions.
  • error(subscribe-error): If subscription failed.
Params
Return values

[method]network.get-block: func

Get a block relative to start by step.

Parameters

  • start: Slot to begin retrieval from, current tip if None.
  • step -0 : the block at start, will return None if there is no block exactly at this start slot. -+n: the n‑th block after the given start slot. –‑n: the n‑th block before the given start slot.

Note: For both +n and -n, the start does not need to be a true block. They will return the block which appears at this block offset, given the arbitrary start point. If the start block does exist, it will never be returned with a positive or negative step, as it is step 0.

Example, Given three consecutive blocks at slots 100, 200 and 300 the following will be returned:

  • start = 100, step = 0 -> 100 (Exact match)
  • start = 100, step = 2 -> 300 (Skips 200)
  • start = 150, step = 1 -> 200 (Rounds up from 150)
  • start = 200, step = 1 -> 300 (Forward iteration)
  • start = 300, step = -2 -> 100 (Skips 200)
  • start = 250, step = -2 -> 100 (Rounds down to 200 first)

Returns

  • Returns a block resource, None if block cannot be retrieved.
Params
Return values

[method]network.get-tips: func

Retrieve the current tips of the blockchain.

Returns

  • A tuple of two slots:
  • The immutable tip.
  • The mutable tip. None if the tips cannot be retrieved.
Params
Return values

[method]block.is-immutable: func

Returns whether the block is part of the immutable section of the chain.

Returns

  • true if the block is in the immutable part.
  • false if the block is in the mutable part.
Params
Return values
  • bool

[method]block.is-rollback: func

Returns whether the block is the first block of a rollback.

Returns

  • ok(bool) True if the block is the first block of a rollback, otherwise, False.
  • error(block-error): If block cannot be retrieved.
Params
Return values

[method]block.get-txn: func

Retrieves a transaction at the specified index within the block.

Parameters

  • index : The index of the transaction to retrieve.

Returns

  • ok(transaction) : A transaction resource at the given index
  • error(transaction-error): If a transaction data does not exist in the block at the given index.
Params
Return values

[method]block.get-slot: func

Retrieves the slot number that this block belongs to.

Returns

  • slot : The slot number of the block.
Params
Return values

[method]block.raw: func

Returns the raw CBOR representation of the block.

Returns

  • cbor : The CBOR format of the block.
Params
Return values

[method]block.get-fork: func

Fork count is a counter that is incremented every time there is a roll-back in live-chain. It is used to help followers determine how far to roll-back to resynchronize without storing full block history. The fork count starts at 1 for live blocks and increments if the live chain tip is purged due to a detected fork, but it does not track the exact number of forks reported by peers.

  • 0 - for all immutable data
  • 1 - for any data read from the blockchain during a backfill on initial sync
  • 2+ - for each subsequent rollback detected while reading live blocks.

** Returns **

  • u64 : The fork count.
Params
Return values
  • u64

[method]transaction.get-metadata: func

Returns the transaction auxiliary metadata in CBOR format.

Parameters

  • label: A metadata label used as a key to get the associated metadata.

Returns

  • option<cbor> : The CBOR format of the metadata, None if the label requested is not present.
Params
Return values

[method]transaction.get-txn-hash: func

Returns the transaction hash.

Returns

  • option<txn-hash> : Cardano transaction hash - Blake2b-256, None if cannot retrieve the transaction hash.
Params
Return values

[method]transaction.raw: func

Returns the raw CBOR representation of the transaction.

Returns

  • option<cbor> : The CBOR format of the transaction, None if cannot retrieve the raw transaction.
Params
Return values

[method]subscription-id.get-network: func

Returns the network that this subscription is in.

Returns

Params
Return values

[method]subscription-id.unsubscribe: func

Unsubscribing block event of this subscription-id instance. Once this function is called, the subscription instance, subscription-id will be removed.

Params

Export interface hermes:cardano/event-on-block

Types

type block

block

#### `type subscription-id` [`subscription-id`](#subscription_id)

#### `type cbor` [`cbor`](#cbor)

----

Functions

on-cardano-block: func

Trigger when a Cardano block event is fired.

Parameters

  • subscription-id : A unique identifier of the block subscription.
  • block : A block resource where information of the block can be retrieve.
Params

Export interface hermes:cardano/event-on-immutable-roll-forward

Types

type block

block

#### `type subscription-id` [`subscription-id`](#subscription_id)

----

Functions

on-cardano-immutable-roll-forward: func

Trigger when a Cardano immutable roll-forward event is fired.

Parameters

  • subscription-id : A unique identifier of the block subscription.
  • block : A block resource where information of the block can be retrieve.

Notes

Roll-forward events are guaranteed to be fully processed before the next block event is delivered. The block event delivered immediately after a roll-forward will correspond to the block at the roll-forward target slot. This means that roll-forward processing does not need to reset or re-subscribe the blockchain follower.

Params