@cardano-ogmios/client - npm Package Versions

[5.4.0] - 2022-05-22

Added

• ![TypeScript][] TypeScript client for the 'TxMonitor' mini-protocol. Documentation available at https://ogmios.dev/typescript-client/tx-monitor/.

Changed

• 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.

---

---

[5.3.0] - 2022-05-07

Added

• 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.

Changed

• 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

Removed

N/A

---

---

[5.2.0] - 2022-02-15

Added

• Extended the local-tx-submission protocol with a new 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.

• New 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.

Changed

• Added transaction id as part of the successful response to a 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.

• Improved error reporting for the SubmitTx protocol which should gives a little clearer errors for ill-formed transactions.

• ![TypeScript][] ⚠️ Renamed client's TxSubmission/errors.ts into TxSubmission/submissionErrors.ts. Similarly, the submission are also now nested under a submissionErrors field in the TxSubmission top-level object.

Removed

N/A

---

---

[5.1.0] - 2022-01-24

Added

• New 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.

• New fields in the health object:
  • connectionStatus → "connected" or "disconnected", to reflect status with the node. #154
  • currentEpoch → which returns the current known epoch of the linked node #164
  • slotInEpoch → which returns the relative number of slots elapsed in the current epoch #164

• New 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
  

• Bumped internal dependencies to Cardano's 1.33.* eco-system.

Changed

• networkSynchronization and currentEra can be null when the server isn't connected to a node. #154
• The Metrics trace is now correctly tagged with MetricsRuntimeStatsDisabled.
• Fixed an issue with the Docker monitoring scripts of cardano-node-ogmios, causing issues on restart. #159
• ![TypeScript][] Relax upper-bound constraint on required node.js engine. This should make it possible to install the TypeScript packages on more recent versions on node.js than the one specified on the repository.

Removed

N/A

---

---

[5.0.0] - 2021-12-20

Added

• 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).

• New state-query blockHeight to access the blockchain current highest block number (or "origin" if the chain is just starting).

• New state-query eraSummaries to access all era bounds and slotting parameters details, required for proper slot arithmetic.

• Log-levels can now be configured per-component. For example, one can decrease the min severity for the health component while keeping the state-query logs at another.

• Logs can now be shutdown completely via the special keyword off.

• Static binaries for Linux are now produced by the Nix build and uploaded as build artifacts for the corresponding Github workflow (i.e. Nix).

• ![TypeScript][] Add support for systemStart, chainTip, blockHeight & eraSummaries in the client and repl.

Changed

🏢 Server

• ⚠️ 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.

Removed

• ⚠️ 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.

---

---

[4.2.1] - 2021-11-16

Added

N / A

Changed

• Fixed configuration parsing which would wrongly use Shelley's slots per epoch instead of Byron's. This had an impact on the reported slot number in the chain-sync protocol, where slot numbers would be wrongly offset by 432000 per epoch after the first epoch.

Removed

N/A

[4.2.0] - 2021-11-05

Added

• 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).

Changed

• ![TypeScript][] Some internal rework and cleanup; mostly chasing dangling promises by avoiding attaching even handlers when not needed.

Removed

N/A

---

---

[4.1.0] - 2021-09-08

Added

• 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.

Changed

• ![TypeScript][] The StateQueryClient now wraps every query in a try/catch to cope with malformed queries leading to client fault results from the server.
• ![TypeScript][] Type definitions for QueryResponse[poolIds] and QueryResponse[poolParameters] are no longer marked as "optional".
• ![TypeScript][] Fixed bug #125 where empty results of delegationAndRewards would cause the client to throw an exception.
• ![TypeScript][] Handled some floating promises.

Removed

N/A

---

---