Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/cardano-foundation/cardano-graphql
GraphQL API for Cardano
https://github.com/cardano-foundation/cardano-graphql
Last synced: about 2 months ago
JSON representation
GraphQL API for Cardano
- Host: GitHub
- URL: https://github.com/cardano-foundation/cardano-graphql
- Owner: cardano-foundation
- License: apache-2.0
- Created: 2018-10-25T11:05:16.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2024-04-28T19:04:47.000Z (8 months ago)
- Last Synced: 2024-05-02T02:01:52.077Z (7 months ago)
- Language: Nix
- Homepage:
- Size: 123 MB
- Stars: 254
- Watchers: 33
- Forks: 100
- Open Issues: 71
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Code of conduct: CODE-OF-CONDUCT.md
Awesome Lists containing this project
- awesome-cardano - Cardano Adestria
- best-of-crypto - GitHub - 14% open · ⏱️ 04.06.2024): (Smart Contract Platforms)
README
Cardano GraphQL
[![CI][img_src_CI]][workflow_CI]
## 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.
``` console
git clone \
--single-branch \
--branch 8.1.0 \
--recurse-submodules \
https://github.com/cardano-foundation/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
mainnet
Get the most recent weekly snapshot link [here](https://update-cardano-mainnet.iohk.io/cardano-db-sync/index.html#12/), and set it as `RESTORE_SNAPSHOT` below, or omit if you wish to sync from genesis.
``` console
DOCKER_BUILDKIT=1 \
COMPOSE_DOCKER_CLI_BUILD=1 \
RESTORE_SNAPSHOT=https://update-cardano-mainnet.iohk.io/cardano-db-sync/13.2/db-sync-snapshot-schema-13.2-block-10060706-x86_64.tgz \
docker compose up -d --build &&\
docker compose logs -f
```
preprod
``` console
DOCKER_BUILDKIT=1 \
COMPOSE_DOCKER_CLI_BUILD=1 \
NETWORK=preprod \
API_PORT=3101 \
HASURA_PORT=8091 \
OGMIOS_PORT=1338 \
POSTGRES_PORT=5433 \
docker compose -p preprod up -d --build &&\
docker compose -p preprod logs -f
```
preview
``` console
DOCKER_BUILDKIT=1 \
COMPOSE_DOCKER_CLI_BUILD=1 \
NETWORK=preview \
API_PORT=3102 \
HASURA_PORT=8092 \
OGMIOS_PORT=1339 \
POSTGRES_PORT=5434 \
docker compose -p preview up -d --build &&\
docker compose -p preview logs -f
```
sanchonet
``` console
DOCKER_BUILDKIT=1 \
COMPOSE_DOCKER_CLI_BUILD=1 \
NETWORK=sanchonet \
API_PORT=3102 \
HASURA_PORT=8092 \
OGMIOS_PORT=1339 \
POSTGRES_PORT=5434 \
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.
mainnet
Get the most recent weekly snapshot link [here](https://update-cardano-mainnet.iohk.io/cardano-db-sync/index.html#11/), and set it as `RESTORE_SNAPSHOT` below, or omit if you wish to sync from genesis.
``` console
export NETWORK=mainnet &&\
docker pull cardanofoundation/cardano-graphql-server:8.1.0-${NETWORK} &&\
docker pull cardanofoundation/cardano-graphql-background:8.1.0-${NETWORK} &&\
docker pull cardanofoundation/cardano-graphql-hasura:8.1.0 &&\
docker pull cardanosolutions/cardano-node-ogmios:v6.4.0_8.9.3-${NETWORK} &&\
RESTORE_SNAPSHOT=https://update-cardano-mainnet.iohk.io/cardano-db-sync/13.2/db-sync-snapshot-schema-13.2-block-10060706-x86_64.tgz \
docker compose up -d &&\
docker compose logs -f
```
preprod
``` console
export NETWORK=preprod &&\
docker pull cardanofoundation/cardano-graphql-server:8.1.0-${NETWORK} &&\
docker pull cardanofoundation/cardano-graphql-background:8.1.0-${NETWORK} &&\
docker pull cardanofoundation/cardano-graphql-hasura:8.1.0 &&\
docker pull cardanosolutions/cardano-node-ogmios:v6.4.0_8.9.3-${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
```
preview
``` console
export NETWORK=preview &&\
docker pull cardanofoundation/cardano-graphql-server:8.1.0-${NETWORK} &&\
docker pull cardanofoundation/cardano-graphql-background:8.1.0-${NETWORK} &&\
docker pull cardanofoundation/cardano-graphql-hasura:8.1.0 &&\
docker pull cardanosolutions/cardano-node-ogmios:v6.4.0_8.9.3-${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`
mainnet
``` console
docker compose down
```
preprod
``` console
docker compose -p preprod down
```
preview
``` console
docker compose -p preview down
```
### Use global Token Metadata Registry
The public Token metadata registry has a limit of daily requests, this can lead to long sync times, when resyncing from scratch.
If it's still needed to run with the global environment it's possible by removing the `token-metadata-registry` from `docker-compose.yml`.
And start it with for Mainnet:
```
METADATA_SERVER_URI="https://tokens.cardano.org" docker compose up -d
```
For other networks:
```
METADATA_SERVER_URI="https://metadata.world.dev.cardano.org"
```
### Upgrade Database to Postgres 14
If you are upgrading from Postgres 11 to 14: A resync will be needed.
To speed up the process you can use the following snapshots:
- [DB-Sync](https://update-cardano-mainnet.iohk.io/cardano-db-sync/13.2/db-sync-snapshot-schema-13.2-block-10060706-x86_64.tgz)
- [Node](https://csnapshots.io/about#Manual_download)
### Check Cardano DB sync progress
Use the GraphQL Playground in the browser at http://localhost:3100/graphql:
> **_Note_** This Query is not available in early Era's of Cardano. Check Points of Interest here: [Link](https://ogmios.dev/mini-protocols/local-chain-sync/#points-of-interest)
``` graphql
{ cardanoDbMeta { initialized syncPercentage }}
```
or via command line:
``` console
curl \
-X POST \
-H "Content-Type: application/json" \
-d '{"query": "{ cardanoDbMeta { initialized syncPercentage }}"}' \
http://localhost:3100/graphql
```
:information_source: _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
```graphql
{ cardano { tip { number slotNo epoch { number } } } }
```
``` console
curl \
-X POST \
-H "Content-Type: application/json" \
-d '{"query": "{ cardano { tip { number slotNo epoch { number } } } }"}' http://localhost:3100/graphql
```
### :tada:
``` json
{ "data": { "cardano": { "tip": { "number": 4391749, "slotNo": 4393973, "epoch": { "number": 203 } } } } }
```
For more information, have a look at the [Wiki :book:].
## How to install (Linux / Docker)
### Docker
See [Using Docker].
### From Source
See [Building].
## Documentation
| Link | Audience |
| --- | --- |
| [API Documentation] | Users of the Cardano GraphQL API |
| [Wiki :book:] | Anyone interested in the project and our development process |
| [Example Queries - Cardano DB Hasura] | Users of the Cardano DB Hasura API |
[img_src_CI]: https://github.com/cardano-foundation/cardano-graphql/workflows/CI/badge.svg
[workflow_CI]: https://github.com/cardano-foundation/cardano-graphql/actions?query=workflow%3ACI
[packages]: ./packages
[docker compose stack]: ./docker-compose.yml
[Docker Compose docs]: https://docs.docker.com/compose/
[cardano-graphql-server Dockerfile]: ./Dockerfile
[hasura Dockerfile]: ./packages/api-cardano-db-hasura/hasura/Dockerfile
[cardano-node-ogmios]: https://ogmios.dev/getting-started/docker/
[schema]: ./packages/api-cardano-db-hasura/schema.graphql
[TypeScript package for client-side static typing]: ./packages/client-ts/README.md
[Apollo Server]: https://www.apollographql.com/docs/apollo-server/
[GraphQL Code Generator]: https://graphql-code-generator.com
[available on npm]: https://www.npmjs.com/package/cardano-graphql-ts
[Ogmios]: https://ogmios.dev/
[releases]: https://github.com/cardano-foundation/cardano-graphql/releases
[Wiki :book:]: https://github.com/cardano-foundation/cardano-graphql/wiki
[Using Docker]: https://github.com/cardano-foundation/cardano-graphql/wiki/Docker
[Building]: https://github.com/cardano-foundation/cardano-graphql/wiki/Building
[API Documentation]: https://cardano-foundation.github.io/cardano-graphql
[Example Queries - Cardano DB Hasura]: ./packages/api-cardano-db-hasura/src/example_queries