Cardano GraphQL

Overview

Cross-platform, typed, and queryable API for Cardano. The project contains multiple packages for composing GraphQL services to meet specific application demands, and a docker compose stack serving the included cardano-graphql-server Dockerfile, the extended hasura Dockerfile, cardano-node-ogmios. The schema is defined in native .graphql, and used to generate a TypeScript package for client-side static typing. A mutation is available to submit a signed and serialized transaction to the local node.

Apollo Server exposes the NodeJS execution engine over a HTTP endpoint, and includes support for open source metrics via Prometheus, and implementing operation filtering to deny unexpected queries. Should you wish to have more control over the server, or stitch the schema with an existing service, consider importing the executable schema from the @cardano-graphql/api-* packages only.

GraphQL is a query language and execution environment with server and client implementations across many programming languages. The language can be serialized for network transmission, schema implementations hashed for assurance, and is suited for describing most domains.

TypeScript (and JS) has the largest pool of production-ready libraries, developers, and interoperability in the GraphQL and web ecosystem in general. TypeScript definitions for the schema, generated by GraphQL Code Generator, are available on npm.

Ogmios is a protocol translation service written in Haskell running on top of cardano-node. It offers a JSON interface through WebSockets and enables applications to speak Ouroboros' client mini-protocols via remote procedure calls.

Getting Started

Check the releases for the latest version.

git clone \
  --single-branch \
  --branch 8.0.0 \
  --recurse-submodules \
  https://github.com/input-output-hk/cardano-graphql.git \
  && cd cardano-graphql

Up

Choose one of the following:

A) Build and Run via Docker Compose

Boot the docker compose stack using a convention for container and volume scoping based on the network, as well as optionally hitting the remote cache to speed up the build. The containers are detached, so you can terminate the log console session freely. See Docker Compose docs to tailor for your use-case

DOCKER_BUILDKIT=1 \
COMPOSE_DOCKER_CLI_BUILD=1 \
RESTORE_SNAPSHOT=https://update-cardano-mainnet.iohk.io/cardano-db-sync/13/db-sync-snapshot-schema-13-block-8291499-x86_64.tgz \
docker compose up -d --build &&\
docker compose logs -f

DOCKER_BUILDKIT=1 \
COMPOSE_DOCKER_CLI_BUILD=1 \
NETWORK=preprod \
API_PORT=3101 \
HASURA_PORT=8091 \
OGMIOS_PORT=1338 \
POSTGRES_PORT=5433 \
METADATA_SERVER_URI="https://metadata.cardano-testnet.iohkdev.io" \
docker compose -p preprod up -d --build &&\
docker compose -p preprod logs -f

DOCKER_BUILDKIT=1 \
COMPOSE_DOCKER_CLI_BUILD=1 \
NETWORK=preview \
API_PORT=3102 \
HASURA_PORT=8092 \
OGMIOS_PORT=1339 \
POSTGRES_PORT=5434 \
METADATA_SERVER_URI="https://metadata.cardano-testnet.iohkdev.io" \
docker compose -p preview up -d --build &&\
docker compose -p preview logs -f

B) Pull and Run via Docker Compose

Pull images from Docker Hub and run using a convention for container and volume scoping based on the network. The containers are detached, so you can terminate the log console session freely. See Docker Compose docs to tailor for your use-case.

export NETWORK=mainnet &&\
docker pull inputoutput/cardano-graphql-server:8.0.0-${NETWORK} &&\
docker pull inputoutput/cardano-graphql-background:8.0.0-${NETWORK} &&\
docker pull inputoutput/cardano-graphql-hasura:8.0.0 &&\
docker pull cardanosolutions/cardano-node-ogmios:v5.5.8_1.35.5-${NETWORK} &&\
RESTORE_SNAPSHOT=https://update-cardano-mainnet.iohk.io/cardano-db-sync/13/db-sync-snapshot-schema-13-block-8291499-x86_64.tgz \
docker compose up -d &&\
docker compose logs -f

export NETWORK=preprod &&\
docker pull inputoutput/cardano-graphql-server:8.0.0-${NETWORK} &&\
docker pull inputoutput/cardano-graphql-background:8.0.0-${NETWORK} &&\
docker pull inputoutput/cardano-graphql-hasura:8.0.0 &&\
docker pull cardanosolutions/cardano-node-ogmios:v5.5.8_1.35.5-${NETWORK} &&\
API_PORT=3101 \
HASURA_PORT=8091 \
OGMIOS_PORT=1338 \
POSTGRES_PORT=5433 \
docker compose -p ${NETWORK} up -d &&\
docker compose -p ${NETWORK} logs -f

export NETWORK=preview &&\
docker pull inputoutput/cardano-graphql-server:8.0.0-${NETWORK} &&\
docker pull inputoutput/cardano-graphql-background:8.0.0-${NETWORK} &&\
docker pull inputoutput/cardano-graphql-hasura:8.0.0 &&\
docker pull cardanosolutions/cardano-node-ogmios:v5.5.8_1.35.5-${NETWORK} &&\
API_PORT=3102 \
HASURA_PORT=8092 \
OGMIOS_PORT=1339 \
POSTGRES_PORT=5434 \
docker compose -p ${NETWORK} up -d &&\
docker compose -p ${NETWORK} logs -f

Down

The following commands will not remove volumes, however should you wish to do so, append -v

docker compose down

docker compose -p preprod down

docker compose -p preview down

Check Cardano DB sync progress

Use the GraphQL Playground in the browser at http://localhost:3100/graphql:

{ cardanoDbMeta { initialized syncPercentage }}

or via command line:

curl \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"query": "{ cardanoDbMeta { initialized syncPercentage }}"}' \
  http://localhost:3100/graphql

ℹ️ Wait for initialized to be true to ensure the epoch dataset is complete. After the first sync you may need to restart the services using docker compose restart cardano-graphql if the GraphQL server isn't running.

Query the full dataset

{ cardano { tip { number slotNo epoch { number } } } }

curl \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"query": "{ cardano { tip { number slotNo epoch { number } } } }"}' http://localhost:3100/graphql

🎉

{ "data": { "cardano": { "tip": { "number": 4391749, "slotNo": 4393973, "epoch": { "number": 203 } } } } }

For more information, have a look at the Wiki 📖.

How to install (Linux / Docker)

Docker

See Using Docker.

From Source

See Building.

Documentation