Data Types

This module contains user-friendly datatypes for Ogmios objects.

Behind the scenes, ogmios-python uses objects derived from the cardano.json and ogmios.json schema files provided by Ogmios. These types are useful for validating that data passed to and from the Ogmios server is properly formatted. However, the schema types are not conducive to Pythonic use. Therefore, we use intermediate datatypes for user-facing functions of this library.

See also

Cardano schema: cardano.json, Ogmios schema: ogmios.json schema

class ogmios.datatypes.Ada(amount: int, is_lovelace: bool = False)

Bases: object

A class representing an amount of ada.

Parameters:

ada (int) – The amount of ada.

class ogmios.datatypes.Address(address: str)

Bases: object

A class representing an address.

class ogmios.datatypes.AlonzoUpdatableParameters(minUtxoDepositCoefficient: int, collateralPercentage: int, plutusCostModels: dict, maxCollateralInputs: int, maxExecutionUnitsPerBlock: dict, maxExecutionUnitsPerTransaction: dict, maxValueSize: dict, scriptExecutionPrices: dict)

Bases: object

A class representing the Alonzo updatable parameters of the blockchain.

Parameters:

  • minUtxoDepositCoefficient (int) – The minimum UTXO deposit coefficient.

  • collateralPercentage (int) – The collateral percentage.

  • plutusCostModels (dict) – The plutus cost models.

  • maxCollateralInputs (int) – The maximum collateral inputs.

  • maxExecutionUnitsPerBlock (dict) – The maximum execution units per block.

  • maxExecutionUnitsPerTransaction (dict) – The maximum execution units per transaction.

  • maxValueSize (dict) – The maximum value size.

  • scriptExecutionPrices (dict) – The script execution prices.

class ogmios.datatypes.Block(blocktype: Types, **kwargs)

Bases: object

Represents a block in the blockchain.

Parameters:

  • blocktype (ogmios.model.model_map.Types) – The type of the block (EBB, BFT, or Praos)

  • kwargs – Additional arguments depending on the block type.

Raises:

InvalidOgmiosParameter – If an unsupported block type is provided.

to_point() → Point

Returns a Point representation of the Block

to_tip() → Tip

Returns a Tip representation of the Block

class ogmios.datatypes.BootstrapProtocolParameters(heavyDelegationThreshold: dict | None = None, maxBlockBodySize: dict | None = None, maxBlockHeaderSize: dict | None = None, maxUpdateProposalSize: dict | None = None, maxTransactionSize: dict | None = None, multiPartyComputationThreshold: dict | None = None, scriptVersion: int | None = None, slotDuration: int | None = None, unlockStakeEpoch: int | None = None, updateProposalThreshold: dict | None = None, updateProposalTimeToLive: int | None = None, updateVoteThreshold: dict | None = None, softForkInitThreshold: dict | None = None, softForkMinThreshold: dict | None = None, softForkDecrementThreshold: dict | None = None, minFeeCoefficient: int | None = None, minFeeConstant: Ada | None = None)

Bases: object

A class representing the bootstrap protocol parameters of the blockchain.

Parameters:

  • heavyDelegationThreshold (dict) – The heavy delegation threshold.

  • maxBlockBodySize (dict) – The maximum block body size.

  • maxBlockHeaderSize (dict) – The maximum block header size.

  • maxUpdateProposalSize (dict) – The maximum update proposal size.

  • maxTransactionSize (dict) – The maximum transaction size.

  • multiPartyComputationThreshold (dict) – The multi-party computation threshold.

  • scriptVersion (int) – The script version.

  • slotDuration (int) – The slot duration.

  • unlockStakeEpoch (int) – The unlock stake epoch.

  • updateProposalThreshold (dict) – The update proposal threshold.

  • updateProposalTimeToLive (int) – The update proposal time to live.

  • updateVoteThreshold (dict) – The update vote threshold.

  • softForkInitThreshold (dict) – The soft fork init threshold.

  • softForkMinThreshold (dict) – The soft fork min threshold.

  • softForkDecrementThreshold (dict) – The soft fork decrement threshold.

  • minFeeCoefficient (int) – The minimum fee coefficient.

  • minFeeConstant (Lovelace) – The minimum fee constant.

class ogmios.datatypes.ConwayUpdatableParameters(stakePoolVotingThresholds: dict, delegateRepresentativeVotingThresholds: dict, constitutionalCommitteeMinSize: int, constitutionalCommitteeMaxTermLength: int, governanceActionLifetime: int, governanceActionDeposit: Ada, delegateRepresentativeDeposit: Ada, delegateRepresentativeMaxIdleTime: int)

Bases: object

A class representing the Conway updatable parameters of the blockchain.

Parameters:

  • stakePoolVotingThresholds (dict) – The stake pool voting thresholds.

  • delegateRepresentativeVotingThresholds (dict) – The delegate representative voting thresholds.

  • constitutionalCommitteeMinSize (int) – The constitutional committee minimum size.

  • constitutionalCommitteeMaxTermLength (int) – The constitutional committee maximum term length.

  • governanceActionLifetime (int) – The governance action lifetime.

  • governanceActionDeposit (Ada) – The governance action deposit.

  • delegateRepresentativeDeposit (Ada) – The delegate representative deposit.

class ogmios.datatypes.Direction(value)

Bases: Enum

An enum representing the direction of a blockchain traversal.

backward = 'backward'
forward = 'forward'
class ogmios.datatypes.Era(value)

Bases: Enum

An enum representing the eras of the Cardano blockchain.

allegra = 'allegra'
alonzo = 'alonzo'
babbage = 'babbage'
static by_index(index)
byron = 'byron'
conway = 'conway'
static get_index(era)
mary = 'mary'
shelley = 'shelley'
class ogmios.datatypes.EraSummary(start_time: int, start_slot: int, start_epoch: int, end_time: int, end_slot: int, end_epoch: int, epoch_length: int, slot_length: int, safe_zone: int | None = None)

Bases: object

Summary of the slotting parameters and boundaries for each known era. Useful for doing slot-arithmetic and time conversions.

Parameters:

  • start_time (int) – The start time of the era (in seconds, relative to the network start).

  • start_slot (int) – The start slot of the era.

  • start_epoch (int) – The start epoch of the era.

  • end_time (int) – The end time of the era (in seconds, relative to the network start).

  • end_slot (int) – The end slot of the era.

  • end_epoch (int) – The end epoch of the era.

  • epoch_length (int) – The epoch length of the era.

  • slot_length (int) – The slot length of the era, in milliseconds.

  • safe_zone (int) – Number of slots from the tip of the ledger in which it is guaranteed that no hard fork can take place. This should be (at least) the number of slots in which we are guaranteed to have k blocks.

class ogmios.datatypes.GenesisConfiguration(era: Era, **kwargs)

Bases: object

A class representing the genesis configuration of the blockchain. Input parameters depend on the era of the genesis configuration.

Raises:

InvalidOgmiosParameter – If an unsupported era is provided.

class ogmios.datatypes.GovernanceProtocolParameters(stakePoolVotingThresholds: dict, delegateRepresentativeVotingThresholds: dict, constitutionalCommitteeMinSize: int, constitutionalCommitteeMaxTermLength: int, governanceActionLifetime: int, governanceActionDeposit: Ada, delegateRepresentativeDeposit: Ada, delegateRepresentativeMaxIdleTime: int)

Bases: object

A class representing the governance protocol parameters of the blockchain.

NOTE: This data structure is currently missing from the ogmios schema, so strict type checking is not enforced. This will be updated when the schema is updated.

Parameters:

  • stakePoolVotingThresholds (dict) – The stake pool voting thresholds.

  • delegateRepresentativeVotingThresholds (dict) – The delegate representative voting thresholds.

  • constitutionalCommitteeMinSize (int) – The constitutional committee minimum size.

  • constitutionalCommitteeMaxTermLength (int) – The constitutional committee maximum term length.

  • governanceActionLifetime (int) – The governance action lifetime.

  • governanceActionDeposit (Ada) – The governance action deposit.

  • delegateRepresentativeDeposit (Ada) – The delegate representative deposit.

  • delegateRepresentativeMaxIdleTime (int) – The delegate representative maximum idle time.

class ogmios.datatypes.Origin

Bases: object

A class representing the origin of the blockchain.

The origin is the first block in the blockchain. It is the only block that does not have a parent block.

class ogmios.datatypes.Point(slot: int, id: str)

Bases: object

A class representing a point in the blockchain.

Parameters:

  • slot (int) – The slot number of the point.

  • id (str) – The block hash of the point.

class ogmios.datatypes.ProtocolParameters(minFeeCoefficient: int, minFeeConstant: int | Ada, minUtxoDepositCoefficient: int, minUtxoDepositConstant: int | Ada, maxBlockBodySize: dict, maxBlockHeaderSize: dict, stakeCredentialDeposit: Ada, stakePoolDeposit: int | Ada, stakePoolRetirementEpochBound: int, stakePoolPledgeInfluence: str, minStakePoolCost: int | Ada, desiredNumberOfStakePools: int, monetaryExpansion: str, treasuryExpansion: str, version: dict, collateralPercentage: int | None = None, maxCollateralInputs: int | None = None, plutusCostModels: dict | None = None, scriptExecutionPrices: dict | None = None, maxExecutionUnitsPerTransaction: dict | None = None, maxExecutionUnitsPerBlock: dict | None = None, maxValueSize: dict | None = None, extraEntropy: str | None = None, maxTransactionSize: dict | None = None, federatedBlockProductionRatio: str | None = None)

Bases: object

A class representing the protocol parameters of the blockchain.

Parameters:

  • minFeeCoefficient (int) – The minimum fee coefficient.

  • minFeeConstant (Ada) – The minimum fee constant.

  • minUtxoDepositCoefficient (int) – The minimum UTXO deposit coefficient.

  • minUtxoDepositConstant (Ada) – The minimum UTXO deposit constant.

  • maxBlockBodySize (dict) – The maximum block body size.

  • maxBlockHeaderSize (dict) – The maximum block header size.

  • stakeCredentialDeposit (Ada) – The stake credential deposit.

  • stakePoolDeposit (Ada) – The stake pool deposit.

  • stakePoolRetirementEpochBound (int) – The stake pool retirement epoch bound.

  • stakePoolPledgeInfluence (str) – The stake pool pledge influence.

  • minStakePoolCost (Ada) – The minimum stake pool cost.

  • desiredNumberOfStakePools (int) – The desired number of stake pools.

  • monetaryExpansion (str) – The monetary expansion.

  • treasuryExpansion (str) – The treasury expansion.

  • version (dict) – The version.

  • collateralPercentage (int) – The collateral percentage.

  • maxCollateralInputs (int) – The maximum collateral inputs.

  • plutusCostModels (dict) – The plutus cost models.

  • scriptExecutionPrices (dict) – The script execution prices.

  • maxExecutionUnitsPerTransaction (dict) – The maximum execution units per transaction.

  • maxExecutionUnitsPerBlock (dict) – The maximum execution units per block.

  • maxValueSize (dict) – The maximum value size.

  • extraEntropy (str) – The extra entropy.

  • maxTransactionSize (dict) – The maximum transaction size.

  • federatedBlockProductionRatio (str) – The federated block production ratio.

class ogmios.datatypes.Script(language: str, cbor: str | None = None, json: dict | None = None)

Bases: object

A class representing a script.

Parameters:

  • language (str) – The language of the script.

  • cbor (str) – The CBOR representation of the script.

  • json (dict) – The JSON representation of the script.

class ogmios.datatypes.Tip(slot: int, id: str, height: int)

Bases: object

A class representing the tip of the blockchain.

Parameters:

  • slot (int) – The slot number of the tip.

  • id (str) – The block hash of the tip.

  • height (int) – The block height of the tip.

to_point() → Point

Returns a Point representation of the Tip

class ogmios.datatypes.TxOutputReference(tx_id: str, index: int)

Bases: object

A class representing a transaction output reference.

Parameters:

  • transaction (str) – The transaction ID of the output.

  • index (int) – The index of the output.

class ogmios.datatypes.Utxo(tx_id: str, index: int, address: str, value: dict, datum_hash: str | None = None, datum: str | None = None, script: Script | None = None)

Bases: object

A class representing a UTxO.

Parameters:

  • tx_id (str) – The transaction ID of the UTxO.

  • index (int) – The index of the UTxO.

  • address (str) – The address of the UTxO.

  • value (int) – The lovelace value of the UTxO (ada / 1e6)

  • datum_hash (str) – The datum hash of the UTxO.

  • datum (str) – The datum of the UTxO.

  • script (Script) – The script of the UTxO.