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