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:

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:

Supported Platforms

Linux 64-bit
Docker

Sign off

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

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 cardano-db-sync@2.1.0: "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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly