@cardano-ogmios/schema
Advanced tools
Changelog
[5.4.0] - 2022-05-22
The server now returns slightly better faults when detecting a misuse of the TxMonitor
protocol (e.g. when sending a HasTx
before an AwaitAcquire
).
The server now fails with an explicit error when given a Request
containing a reflection
field; reflection
are only used in responses, while requests use mirror
. See #217.
Changelog
[5.3.0] - 2022-05-07
In the Local-Tx-Monitor protocol, NextTx
can now take an (optional) extra argument { "fields": "all" }
to instrument the server in returning not only a transaction id in NextTxResponse
, but a full transaction object. See #190.
Transaction JSON objects from all eras now contains an extra field raw
, which represents the raw serialized transaction (CBOR) as a base64-encoded text string. This is the case of the chain-sync protocol, but also for the tx-monitor protocol. The field is however absent in the ogmios.v1:compact
mode. See #190.
Transaction JSON objects from the Alonzo era now contains an extra field inputSource
which a string set to either inputs
or collaterals
. This captures the fact that since the introduction of Plutus scripts in Alonzo, some transactions may be recorded as failed transactions in the ledger. Those transactions do not successfully spend their inputs but instead, consume their collaterals as an input source to compensate block validators for their work.
The complete [API reference][] for the server is available in a new form at: https://ogmios.dev/api/. This should make the various protocol messages easier to explore and provide a less awkward visualization of the server API than the previous TypeScript documentation. The old TypeScript documentation remains however available at: https://ogmios.dev/typescript/api/.
Upgrade internal dependencies to cardano-node@1.34.1
Fixed the supervisor script for the cardano-node-ogmios
Docker image, which would wrongly ignore signals sent from the Docker daemon (e.g. docker container stop ...
). See #168
![TypeScript][] The tx-submission client now only creates a single event listener to interact with the server. This solves the Node.js warning "possible memory leak detected" when firing many submission requests at once (and going beyond the internal default maxNumberOfListeners
set by node.js on event emitters). See #197.
![TypeScript][] The options passed to the WebSocket constructors are now ignored on the browser, since they aren't supported and were causing the constructor to "crash". See #194.
![TypeScript][] ⚠️ Some schema type interface renaming:
Tx
→ TxByron
BlockBodyShelley
→ TxShelley
BlockBodyAllegra
→ TxAllegra
BlockBodyMary
→ TxMary
BlockBodyAlonzo
→ TxAlonzo
N/A
Changelog
[5.2.0] - 2022-02-15
EvaluateTx
query which evaluates execution units of scripts present in a transaction. This effectively piggybacks on the Alonzo's tools from the cardano-ledger while providing a more user-friendly interface regarding network parameters. The API offers well-detailed errors and an interface similar to the SubmitTx
. See discussion on #172.rewardsProvenance'
query coming as a replacement for the now-deprecated rewardsProvenance
query. See discussion on #171.![TypeScript][] Support for the new evaluateTx
query in the TxSubmissionClient
& repl.
![TypeScript][] Support for the new rewardsProvenance'
query as rewardsProvenanceNew
in the StateQueryClient
& repl.
SubmitTx
. While this is technically a breaking-change, it was introduced in a backward-compatible way. Existing applications using the existing SubmitTx
query will see no change and will keep receiving successes as "SubmitSuccessful"
text responses. However, queries which pass transactions using the submit
field (instead of the currently expected bytes
field) will receive, on success, an augmented response which contains a transaction id "SubmitSuccessful": { "txId": "..." }
. See discussion on #174.SubmitTx
protocol which should gives a little clearer errors for ill-formed transactions.TxSubmission/errors.ts
into TxSubmission/submissionErrors.ts
. Similarly, the submission are also now nested under a submissionErrors
field in the TxSubmission
top-level object.N/A
Changelog
[5.1.0] - 2022-01-24
LocalTxMonitor
support in Ogmios. See The user guide for more details.⚠️ This new protocol is NOT enabled in cardano-node@1.33.*
. Until its inclusion in a next release, a custom build of cardano-node is required to include a more recent version of ouroboros-network
which adds support for that protocol to the Ouroboros' mini-protocols; namely: 32af9168
.
A version of cardano-node@1.33.0
patched with the necessary commits can be found at CardanoSolutions/cardano-node@1.33.0+local-tx-monitor.
ogmios health-check
command, useful to perform simple health check on a running server. For example, to monitor a container via Docker health check mechanism:
HEALTHCHECK --interval=10s --timeout=5s --retries=1 CMD /bin/ogmios health-check
1.33.*
eco-system.networkSynchronization
and currentEra
can be null
when the server isn't connected to a node. #154Metrics
trace is now correctly tagged with MetricsRuntimeStatsDisabled
.N/A
Changelog
[5.0.0] - 2021-12-20
New state-query systemStart
to access the blockchain start time (UTC).
New state-query chainTip
to access the blockchain current tip (may slightly differ from the ledgerTip
which may be behind catching up).
blockHeight
to access the blockchain current highest block number (or "origin"
if the chain is just starting).eraSummaries
to access all era bounds and slotting parameters details, required for proper slot arithmetic.off
.systemStart
, chainTip
, blockHeight
& eraSummaries
in the client
and repl
.RelativeTime
is no-longer serialised as a string (with s
as suffix) but, as an integer representing the number of seconds.⚠️ Serialised Plutus scripts are now labelled either plutus:v1
or plutus:v2
(instead of plutus
).
⚠️ Some breaking changes in the SubmitTx errors returned by the server for the sake of consistency. All submission errors are now returned as singleton objects within an array. The key of each object indicates the type of error and the value gives additional details about the errors. This is also true for era-mismatch errors. Some errors used to be returned as plain strings, they are now wrapped as singleton object with null
as a value; this is the case for:
invalidMetadata
mirNegativeTransferNotCurrentlyAllowed
mirProducesNegativeUpdate
mirTransferNotCurrentlyAllowed
missingAtLeastOneInputUtxo
missingCollateralInputs
triesToForgeAda
validationTagMismatch
wrongCertificateType
Upgraded internal dependencies to Cardano eco-system 1.31.0
⚠️ ![TypeScript][] Lovelace
is now a native BigInt.
⚠️ ![TypeScript][] getServerHealth
's connection
argument is now wrapped into an object, mapped to the field connection
. (see #135)
⚠️ ![TypeScript][] Replaced schema definitions for Hash16
and Hash64
with more precise type definitions. For hashes, definitions now follows a convention Digest[ALGORITHM]::PRE-IMAGE
where ALGORITHM
and PRE-IMAGE
points to the corresponding has algorithm used to hash the PRE-IMAGE
. The length of the digest is given by minLength
and maxLength
JSON-schema constraints. Consequently, TypeScript types / interfaces generated from the JSON-schema definitions have been altered.
⚠️ Log level severities critical
, alert
and emergency
have been removed. error
is now the highest severity.
⚠️ The Nix setup has been highly simplified, resulting in removal of the NixOS services configuration and probably some other stuff.
Changelog
[4.2.1] - 2021-11-16
N / A
432000
per epoch after the first epoch.N/A
Changelog
[4.2.0] - 2021-11-05
Enabled Alonzo transaction in the submission protocol (oversight from previous releases). Doing so, explicit compiler warnings have been added to the relevant code to avoid overseeing this in the next upgrade.
Added query response and requests to logs trace, large responses are truncated (e.g. querying the entire UTXO or, informations about all stake pools).
Gracefully handled shutdown and process cleanup on SIGTERM
.
Documented Mary last point to the points of interests for the chain-sync protocol.
Bumped cardano-node's integration to 1.31.0
![TypeScript][] The State-Query client can now release
acquired points to perform queries against the most recent tip (which was also the default when creating a client with no point).
N/A
Changelog
[4.1.0] - 2021-09-08
Generate and store test vectors for various JSON requests and responses. This should ease integration for many clients who seek for good coverage of the server inputs/outputs.
Documented example state queries in the user-guide.
![TypeScript][] The ConnectionConfig
has an additional, optional, configuration parameter maxPayload
to configure the maximum allowed message size in bytes. The default is chosen quite large as the utxo
query can result in large payloads.
![TypeScript][] New helpers isByronEpochBoundaryBlock
and isByronStandardBlock
.
StateQueryClient
now wraps every query in a try/catch to cope with malformed queries leading to client fault
results from the server.QueryResponse[poolIds]
and QueryResponse[poolParameters]
are no longer marked as "optional".delegationAndRewards
would cause the client to throw an exception.N/A
Changelog
[4.0.0] - 2021-09-06
alonzo
block type, with various additions related to Alonzo.New state-queries:
Query | Description
--- | ---
poolIds
| The list of all pool identifiers currently registered and active.
poolParameters
| Stake pool parameters submitted with registration certificates.
poolsRanking
| Retrieve stake pools ranking (a.k.a desirabilities).
rewardsProvenance
| Get details about rewards calculation for the ongoing epoch.
Added missing properties in Byron's protocol parameters update. Somehow, an additionalProperties: true
had slipped through and caused the tests to pass with an incomplete schema.
Nested logs are now also structured, in particular those coming from the Handshake
or TxSubmission
protocols. Before, any message from these layers where actually plain strings with unintelligible gibberish. Now, the submitted transaction payload is shown encoded as hexadecimals and errors are also serialized to json using the same model / codec as the one used for websockets. The handshake is also more verbose now clearly showing what version is being requested and what the node replies / select. All in all, better logs.
The Dockerfile now includes a build definition for building cardano-node
and ogmios
into the same image, which is the default and suggested mode of operation. To build an image with only Ogmios, use the build --target ogmios
. Docker Hub now hosts two image repositories: cardanosolutions/cardano-node-ogmios
and cardanosolutions/ogmios
.
Docker Hub images are now tagged with a network suffix (e.g. -mainnet
). In the case of mainnet, the -mainnet
suffix is optional, and points to the same build as the defaults.
A new repository for hosting Cardano configurations of various services was created and is now used in Ogmios. Configuration for cardano-node (and therefore Ogmios) or, network genesis can be found in input-output-hk/cardano-configurations. Configurations are updated automatically by a nightly job to be always up-to-date. They can be pulled into projects as git submodules.
New possible errors from the transaction submission (stemming from the Alonzo integration):
collateralHasNonAdaAssets
collateralIsScript
collateralTooSmall
collectErrors
datumsMismatch
executionUnitsTooLarge
extraDataMismatch
extraRedeemers
mirNegativeTransferNotCurrentlyAllowed
mirProducesNegativeUpdate
mirTransferNotCurrentlyAllowed
missingDatumHashesForInputs
missingRequiredDatums
missingRequiredRedeemers
missingRequiredSignatures
outsideForecast
poolMetadataHashTooBig
tooManyCollateralInputs
unspendableDatums
unspendableScriptInputs
validationTagMismatch
![TypeScript][] Compatibility with aforementioned server additions.
![TypeScript][] The ChainSyncClient
now implements an in-memory queue to ensure requestNext
responses are processed sequentially when there are async operations in the message handlers. This behaviour can be bypassed where sequential processsing is not required, by setting the new construction option sequential
to false
.
![TypeScript][] The StateQueryClient
can now re-acquire new points at will, useful for long-running clients for which previously acquired points may expire.
![TypeScript][] The TypeScript client is now fully documented!
⚠️ The utxo
query can now accept a list TxIn
as argument, and still supports list of Address
. Note that lists can't be heterogeneous and it's not possible to mix TxIn
and Address
.
⚠️ Asset quantities and transaction metadata's integers are now parsed as native BigInt
.
The memory
and steps
JSON representations for prices
are no longer coins, but ratio (represented as strings in the API).
The moveInstantaneousRewards
certificates have a new optional field value
and not only a rewards
map as before. When value
is present, it signifies that rewards are moved to the other pot.
Auxiliary data's scriptPreImages
in Allegra & Mary has been replaced with a field scripts
which has one field native
. The value of native
corresponds to what used to be the value of scriptPreImages
. In Alonzo, scripts
may also have another field plutus
with a serialized Plutus script.
Transactions witnesses' address
has been renamed into signatures
, and the structure of the object has been changed to be a map from public keys to signatures (instead of an object with two field key
& signature
).
Transactions witnesses' script
has been renamed into scripts
.
Transaction submission errors' networkMismatch
now returns an invalidEntities
list of object in the form of { "type": ..., "entity": }
where type
is a text tag designating the type of entity for which there is a network identifier mismatch. Values can be address
, rewardAccount
and since Alonzo transactionBody
. The entity
field contains some details specific to the type of entity. Before, it used to be two distinct fields invalidAddresses
and invalidRewardAccounts
.
Empty transaction metadata are no longer materialized by an object with two null fields ({ "hash": null, "body": null }
). Empty transaction metadata are now equal to null
.
map
metadatum in transactions' metadata are no longer materialized as a list of list of singleton objects: [[{ "k": ... }, { "v": ... }], ...]
but instead, as a list of object with two fields k
and v
: [{ "k": ..., "v": ...}, ...]
. This was an oversight from the encoder which was never intended to end up that way but happened to slip in because the schema for metadatum was not specified / documented (and therefore, also escaped testing). This is now documented properly.
The TxOut
(and thus Utxo) model definitions have been unified and harmonized across all eras. That is, pre-Mary eras now also wrap Ada values in an object with a field "coins": ...
. This reduces the discrepancy between eras for there's now a single TxOut representation valid across all eras. Some fields are however optional and only present in some eras (e.g. datum
starting from Alonzo)
⚠️ ![TypeScript][] State queries (resp. the StateQueryClient
) now automatically runs queries against the last known tip if no explicit point is provided. It used to acquire a point on the first query which would eventually become too old. The behavior is now equivalent to acquiring a new point on every query!
⚠️ ![TypeScript][] SubmitTx
no-longer returns Byron errors. Consequently, submit errors are no longer scoped under errors.byron
or errors.shelley
but simply errors
.
⚠️ ![TypeScript][] Fixed proposedProtocolParameters
query. All fields are actually required AND, more importantly, it can now return either Shelley protocol parameters or, Alonzo protocol parameters.
![TypeScript][] The ChainSyncClientMessageHandlers
methods now must return a promise.
![TypeScript][] Various reworks and renaming of the TypeScript types
AssetQuantity
is now a native bigint
Int
are now native bigint
DelegationsAndRewards
renamed into DelegationsAndRewardsByAccounts
DelegationsAndRewards1
renamed into DelegationsAndRewards
NonMyopicMemberRewards1
renamed into NonMyopicMemberRewards
TxTooLarge1
renamed into TxTooLarge
FeeTooSmall1
renamed into FeeTooSmall
NetworkMismatch1
renamed into NetworkMismatch
Proposal
renamed into UpdateProposalShelley
Utxo1
, Utxo2
, UtxoMary
have been unified into a single Utxo
type. Refer to server breaking changes for details.Tip
& Point
renamed into TipOrOrigin
and PointOrOrigin
. As a consequence, Tip1
and Point1
are now simply Tip
and Point
.NullX
merged into a single Null
typeledgerTip1
to GetLedgerTip
and so forth for all queries.datumsMismatch
, a previously introduced error from the transaction submission has been removed / replaced.
SubmitTx
can no longer return SubmitTxError[Byron]
. All the child error types have been removed accordingly, namely:
UtxoValidationError
TxValidationError
LovelaceError
![TypeScript][] ChainSyncClient
no longer exposes a requestNext function. Instead you must invoke the callback provided as the second argument in each of rollBackward and rollForward handlers.
![TypeScript][] ChainSyncClient
no longer exposes JSON-WSP reflection as there would be unexpected results given the first n messages would all share the same reflected value.