2.2.0-beta

Merge pull request #322 from input-output-hk/release/2.2.0-beta

release 2.2.0-beta

Cardano GraphQL 2.1.0

This minor update provides schema and build enhancements, aligns with cardano-db-sync DB changes, resolves a few issues, replaces `whitelist` with `allow list`.

Compatible with

• cardano-node: 1.19.1
• cardano-db-sync: 5.0.0
  • NB: the database must be recreated when upgrading to the new version

New Features

• In api-cardano-db-hasura: :
  • added custom $SECRET_DIR support for docker image #307
  • added Epoch.fees attribute into the schema #306
  • added Transaction.deposit attribute into the schema #305
• #260 In the Docker build, added arguments to include genesis files #296

Improvements

• Improved logging during retry attempts #275
• Replaced DB polling with postgres notification listener for migrations #275
• Improved error handling with Cardano query delegation #275
• #282 Added support of 28 byte hex encoded hashes #280

Bug Fixes

• Added missing GraphQL model for Delegation.transaction #294
• Corrected address ordering type mismatch in GraphQL schema #315
• #308 Included pools without metadata in StakePool view to fix delegation query #312
• #303 WHITELIST_PATH is deprecated in favour of ALLOW_LIST_PATH #272, #304,
• #281 Hardened schema introspection #309
• #267 Aligned server configuration options #272
• #266 Added return of HTTP 403 error code when rejecting disallowed queries #272

Known issues

• #164 Field aliasing via delegated schema does not remap field names

Documentation

README provides complete overview and documentation:

• Getting Started
• Installation Guide
• Cardano GraphQL API
• User Guides
• Example Queries
• Wiki

Supported Platforms

• Linux 64-bit
• Docker

Sign off

Role	Approval
Technical Lead	✔️
QA Engineer	✔️
Ops	✔️
Release Manager	✔️

Cardano GraphQL 2.0.0

This new major version brings the first round of Shelley era features to the API, introduces a new genesis file API package, and hardens the migrations and metadata handling. This version is required for transitioning through the upcoming Shelley hard fork.

Compatible with

• cardano-node 1.18.0
• cardano-db-sync 3.1.0 (note, the database must be recreated using the new version)

New Features

• New queries
  • stakePools, stakePools_aggregate
  • delegations, delegations_aggregate
  • stakeRegistrations, stakeRegistrations_aggregate
  • stakeDeregistrations, stakeDeregistrations_aggregate
  • withdrawals, withdrawals_aggregate
  • genesis
• A new API package @cardano-graphql/api-genesis allows access to the network genesis files. It's integrated into the server, with the config exposed as environment variables. The docker-compose.yaml serves as a good reference
• Metadata and SQL migrations are now performed within the application layer, and make the service immune to schema mutation during cardano-db-sync restart. The Hasura CLI is included in the Dockerfile and NixOS service; however outside of this you must install and place hasura on PATH

Breaking Changes ⚠️

• The docker-compose file now mounts configuration managed in the repository, restoring the usual separation of concerns with service configuration. The Docker images still have the configuration included at build time, however, in practice, being ready to manage your own configuration if required is a good strategy. Simply copying the top level config and committing to source control gives you full control over the services using their native interface

Removed fields

• Cardano.networkName removed. Use network magic from the Genesis API to identify networks
• Cardano.protocolConst, Cardano.slotDuration, Cardano.startTime, Cardano.slotsPerEpoch removed. Access this information from the Genesis API
• cardanoDbSync.slotDiffFromNetworkTip removed in response to a change in strategy for determining sync status with cardano-db-sync

Changed fields

• Dates were previously formatted according to ISO 3339, however, ISO 8601 is being adopted with this release for alignment with the Shelley genesis file format and simplification when the precision is not required, e.g.
  2017-10-03T21:43:51.000Z changed to 2017-10-03T21:43:51Z
• Block.createdBy changed to Block.slotLeader that links to an object, with a nullable stakePool field. For previous behaviour, Block.slotLeader.description can be used, however the description prefixes have changed upstream from SlotLeader to ByronGenesis
• Block.createdAt changed to Block.forgedAt
• Block.slotWithinEpoch changed to Block.slotInEpoch

Known issues

• #164 Field aliasing via delegated schema does not remap field names

Documentation

README provides complete overview and documentation:

• Getting Started
• Installation Guide
• Cardano GraphQL API
• User Guides
• Example Queries
• Wiki

Supported Platforms

• Linux 64-bit
• Docker

Sign off

Role	Approval
Technical Lead	✔️
QA Engineer	✔️
Ops	✔️
Release Manager	✔️

Cardano GraphQL 2.0.0 Beta

This new major version brings the first round of Shelley-era features to the API, introduces a new genesis file API package, and hardens the migrations and metadata handling. This version is required for transitioning through the upcoming Shelley hard fork.

Compatible with

• cardano-node 1.18.0
• cardano-db-sync 3.0.0 (note, the database must be recreated using the new version)

New Features

• New queries
  • stakePools, stakePools_aggregate
  • delegations, delegations_aggregate
  • stakeRegistrations, stakeRegistrations_aggregate
  • stakeDeregistrations, stakeDeregistrations_aggregate
  • withdrawals, withdrawals_aggregate
  • genesis
• Metadata and SQL migrations are now performed within the application layer, and make the service immune to schema
  being removed should cardano-db-sync restart using the Hasura CLI, which is included in the Dockerfile and NixOS service; however outside of this you must install and place hasura on PATH.
• A new API package @cardano-graphql/api-genesis allows access to the network genesis files. It's integrated into the server, with the config exposed as environment variables. The docker-compose.yaml serves as a good reference.

Breaking Changes ⚠️

Removed fields

• cardanoDbSync.slotDiffFromNetworkTip removed in response to a change in strategy for determining
  sync status with cardano-db-sync
• Block.slotWithinEpoch removed due to complexity with variation across eras. The Genesis API has information
  for calculations based on the context

Changed fields

• Dates were previously formatted according to ISO 3339, however, ISO 8601 is being adopted with this release for alignment with the Shelley genesis file format and simplification when the precision is not required, e.g.
  2017-10-03T21:43:51.000Z -> 2017-10-03T21:43:51Z
• Block.createdAt -> Block.forgedAt
• Block.createdBy -> Block.slotLeader links to an object, with a nullable stakePool field. For previous behaviour, Block.slotLeader.description can be used, however the description prefixes have changed upstream from SlotLeader to ByronGenesis

Cardano GraphQL 1.0.0

Cardano GraphQL 1.0.0

First production release of a service and TypeScript libraries to query the Cardano blockchain database over a GraphQL interface. A server is composed using lower level packages, which can be used independently, offering flexibility during integration. The supplied docker-compose file provides a good starting point, and serves as a working reference for configuring alternative deployments.

Packages

@cardano-graphql/server Exposes a HTTP server to route queries to the GraphQL execution engine.
@cardano-graphql/api-cardano-db-hasura Contains the executable GraphQLSchema for the single datasource, to stitch with another schema, or simply control the server component.
@cardano-graphql/ts-client is available for statically checking API interactions, and includes a copy of the SDL .schema.
@cardano-graphql/cli assists with local docker-compose deployments, such as making volume snapshots or rebuilding the database.

The packages can be reliably built from source in a sandbox using the yarn package manager with supplied offline cache, or installed from npm.

Service dependencies:

• Cardano Node 1.14.2
• PostgreSQL,
• Cardano DB Sync Extended 2.1.0
• Hasura graphql-engine 1.2.1

New Features from development releases in the 0.x.x range

• Cardano.networkName
• Transaction.size
• Transaction.blockIndex
• Established relationships to easily access transaction and block information from inputs and outputs
  • TransactionInput.transaction
  • TransactionInput.sourceTransaction (where it was an output)
  • TransactionOutput.transaction
• CLI tool cgql with commands to assist with Docker-based deployments, including init, snapshotting, and db rebuild
• CardanoDbMeta via Query.cardanoDbMeta exposes information to understand if the dataset is complete including: initialized, syncPercentage, and slotDiffFromNetworkTip. The epoch data is incomplete until initialized = true, which takes around 2 hours for the initial sync as of block number 4388632. syncPercentage or slotDiffFromNetworkTip provides progress

Improvements

• Optimised versions of some key aggregated queries:
  • Block.transactionsCount
  • Epoch.transactionsCount
  • Epoch.blocksCount
• Explicit ordering of Transaction.outputs by their natural index
• Cardano now matches the postgres view, that is an improvement over the previous version which performed two queries
• The codebase is now modularized to enable new API segments to be added alongside as an extension, composition of services for more use cases, ability to import the executable schema and host on a different server. The packages are published, to npm, or can be built from source:
  • @cardano-graphql/server
  • @cardano-graphql/api-cardano-db-hasura
  • @cardano-graphql/client-ts
  • @cardano-graphql/cli
  • @cardano-graphql/util-dev
  • @cardano-graphql/util
• Packages are now managed via an offline npm package cache, to facilitate reproducible builds when the --offline flag
  is passed to yarn install

Breaking changes

• PostgreSQL views are now being managed in this codebase, so either
  • switch to the new Docker image inputoutput/cardano-graphql-hasura, or
  • use the Hasura CLI as demonstrated in the entrypoint. The custom Docker image makes it possible to check your own docker-compose file into source control, as it supports Docker secrets, and, also, removes the requirement to clone this source repository to get data for mounting at runtime
• Transaction and Block IDs are now labelled as hash, aligning with the domain terminology
• Block.merkelRootHash is renamed to Block.merkelRoot
• The aggregated and known very large numbers are now typed as String. Cardano JS has utilities to work with these return values, currently limited to currency conversion
• Transaction.fee, previously, String, is now BigInt
• Entrypoint for the service previously found in ./dist/index.js is now in ./packages/server/dist/index.js after building
• Cardano.blockHeight removed in favour of Cardano.tip.number, where tip is equal to the most recent Block. This unlocks
  more information such as slotNo, and capability to traverse the chain, etc.
• Dates are now coerced to RFC 3339 UTC date-time strings

Maintenance

• Upgraded to Hasura 1.2.1

Known issues

• #164 Field aliasing via delegated schema does not remap field names

Documentation

README provides complete overview and documentation:

• Getting Started
• Installation Guide
• Cardano GraphQL API
• User Guides
• Example Queries
• Wiki

Supported Platforms

• Linux 64-bit
• Docker

Sign off

Role	Approval
Technical Lead	✔️
QA Engineer	✔️
Ops	✔️
Release Manager	✔️

v1.0.0-rc.14

Reinstates nix-build support, using an offline npm package cache.

Compatible with:

cardano-node 1.14.2
cardano-db-sync-extended 2.1.0

v1.0.0-rc.13

This release will be followed closely by the production 1.0.0 release

Compatible with:

• cardano-node 1.14.2 | cardano-node 1.13.0
• cardano-db-sync-extended 2.1.0

⚠️ As per the release notes of [email protected]: "This release requires the database to be dropped and recreated." If using Docker, see the Wiki for info

Features

Establish relationships to easily access transaction and block information from inputs and outputs

• TransactionInput.transaction
• TransactionInput.sourceTransaction (where it was an output)
• TransactionOutput.transaction
• CardanoDbMeta via Query.cardanoDbMeta exposes information to understand if the dataset is complete including:
  initialized, syncPercentage, and slotDiffFromNetworkTip. The epoch data is incomplete until initialized = true
  , which takes around 2 hours for the initial sync as of block number 4388632. syncPercentage or
  slotDiffFromNetworkTip provides progress.
• The codebase is now modularized to enable new API segments to be added alongside as an extension, composition of services
  for more use-cases, ability to import the executable schema and host on a different server. The packages will be published to npm,
  or can be built from source:
  • @cardano-graphql/server
  • @cardano-graphql/api-cardano-db-hasura
  • @cardano-graphql/client-ts
  • @cardano-graphql/cli
  • @cardano-graphql/util-dev
  • @cardano-graphql/util

⚠️ Breaking Changes

• Entrypoint for the service previously found in ./dist/index.js is now ./packages/server/dist/index.js after building.
• Cardano.blockHeight removed in favour of Cardano.tip.number, where tip = the most recent Block. This unlocks
  more information such as slotNo, and capability to traverse the chain etc.
• Dates are now coerced to RFC 3339 UTC date-time strings

v1.0.0-rc.12

• Refactors the CLI to better support Docker operations
• Nix service upgrade
• Removes invalid TransactionInput.index - ⚠️ Breaking change

Compatible with:

• cardano-node 1.13.0
• cardano-db-sync-extended 2.0.0

v1.0.0-rc.11

• Breaking change in 4c75030
• Adds transaction block index in a2713ce

v1.0.0-rc.10

• Update dependencies Hasura graphql-engine to 1.1.1
• Implements whitelist feature