v6.0.0

Caution

For those integrating from a previous release candidate (e.g. v6.0.0-rc5), please acknowledge the following (hopefully last) important changes to the API:

• The old format (pre v6.0.0-rc1) for metadata can be recovered on-demand using the --metadata-detailed-schema flag.
• All values are now returned as a map of maps; including in places where there's only lovelace (e.g. fee, total collateral, etc..)

  Old (v6.0.0-rc5)	New (v6.0.0)
  { "lovelace": 123 }	{ "ada": { "lovelace": 123 } }

• The format of redeemer pointers has now changed; redeemers are no longer encoded as plain strings, but as objects. Maps from redeemer pointers to validators have therefore been inlined as associative lists. As follows:

  Old (v6.0.0-rc5)	New (v6.0.0)
  { "publish:2": "a0" }	{ "validator": { "index": 2, "purpose": "publish" }, "redeemer": "a0" }

Added

• Integration with cardano-node==8.7.2 and cardano-ledger-conway==1.11.0.0. It adds (preliminary) support for the Conway era. This support only covers what is currently available in the Cardano node / ledger. However, since the implementation of this era isn't finalized but mostly stable, there's a non-zero chance some of the interface will slightly adjust in the future.

• Ogmios now accept queries via HTTP (POST). Request bodies are the same as those passed to the websocket and so are responses. In fact, most Ogmios queries follow a simple request/response pattern and are therefore well-suited to be run over HTTP. It is a reasonable approach for many queries that aren't stateful (e.g. direct queries via the local-state-query protocol, or simply transactions submission / evaluation).

  Note
  The HTTP server and the WebSocket server are both mounted on the same port. So, it suffices to route HTTP requests through /. The JSON payload is the same.

• Ability to retrieve any genesis configuration (Byron, Shelley, Alonzo or Conway) via the state-query protocol.

• A new flag --metadata-detailed-schema (disabled by default) to control how the server returns JSON metadata. When set, the server will return a JSON description of the encoded data; when omitted, it'll attempt to convert CBOR metadata as plain JSON object, and default to hex-encoded cbor otherwise. See also notes in ADR-017.

• A new command inspect transaction to help with debugging the deserialization of transaction.

• The health now contains an extra network and version. Also, beware that era names are now returned in lowercase (first letter used to be capitalised!).

• sanchonet network to the list of well-known networks.

• arm64 static executables for Linux are now available in the continuous delivery pipeline, and as release artifacts.

• Multi-arch (amd64, arm64) docker images are now also available.

Changed

• The server now return an internalError when an unexpected error occurs in the communication between Ogmios and the node. Before, Ogmios would simply log an exception and no response would be sent back to client applications. Now, clients correctly receive an unsuccessful response with the same id as present in the request. See #346.

• Add an extra promise handler to cope with unexpected websocket disconnections when submitting messages to the server. See #346.

• Escape the word 'constructor' to constr when present as key in metadata, and when not using --metadata-detailed-schema. JavaScript (and thus TypeScript) forbids using that word as an object key.

Changed

Tip

There are still many test vectors available for every element of the Ogmios API. Use them!

• ⚠️ BREAKING-CHANGE ⚠️ Many major changes in the interface. A complete migration guide is available in ADR-017, yet please refer to the API reference for details and exhaustiveness. Many representations have been made easier to parse and field names have been improved (more consistent across the entire API and better self-documented).

• Ogmios will no longer retry connecting to a node that is configured for another network but exit with an non-zero code and a clear error message indicating the network mismatch.

• The default dashboard on localhost has been greatly rework and simplified. It also better handles errors.

• Responses from the server no longer includes raw binary cbor by default. This was the case in particular for transactions. This behavior can be restored by configuring the server with --include-cbor to always include binary version of some specific objects such as transactions. This flag can be declined in more fine-grained flags if necessary:

  • --include-transaction-cbor
  • --include-metadata-cbor
  • --include-script-cbor

  where --include-cbor turns all three flags at once.

Removed

• ⚠️ BREAKING-CHANGE ⚠️ Compact mode is no more. Responses are more compact by default already and it is no longer possible to ask for a compact mode.

• ⚠️ BREAKING-CHANGE ⚠️ Ogmios no longer returns null or empty fields. Where a field's value would be null prior to v6.0.0, Ogmios now simply omit the field altogether. This is also true for most responses that return empty lists as well. All-in-all, please refer to the documentation / JSON-schema in case of doubts (fields that may be omitted are no longer marked as required).

Tested with

• cardano-node == 8.7.2 (Mainnet, Preprod, Preview, SanchoNet)

Details

v5.6.0...v6.0.0

A big thank to all those who provided feedback, reported issues, suggested improvements and contributed to make them happen.

Contributions & acknowledgements

• @AndrewWestberg
• @droark
• @Quantumplation
• @angerman
• @lehins
• @mkazlauskas
• @xray-robot
• @sorki
• @rhyslbw
• @michalrus
• @rdlrt
• @TerminadaPool
• @GrzegorzDrozda