A multi-node blockchain indexer and GraphQL API.

For more information, and for examples of live subscriptions and complex queries, see chaingraph.cash.

Chaingraph runs on Kubernetes, making it easy to deploy for production usage across many cloud providers or on self-managed hardware.

This guide describes a simple testnet deployment to a production Kubernetes cluster.

To deploy Chaingraph locally, see the instructions in the Contributing Guide. For details about other configurations, see the chart documentation.

As of late 2021, DigitalOcean is the most cost-effective cloud provider for Chaingraph deployments (differentiated primarily by pricing of egress bandwidth and persistent volume SSD storage).

To set up a new cluster, consider using Chaingraph's referral code for a $100 credit (supports demo.chaingraph.cash); this should cover a production-ready BCH mainnet deployment for ~30 days (approximately $85/month for SSD storage, one $10/month droplet, and $10/month for the load balancer and egress bandwidth).

Whichever cloud provider you choose, for the below testnet deployment, provision at least 1 Kubernetes node of the least expensive type.

Typically, providers offer setup commands which add cluster authentication information to your local kubectl settings. Once your cluster is created, follow the provider's instructions for connecting to the cluster from your machine.

To deploy Chaingraph to your cluster, first install Helm, then add the bitauth repo:

helm repo add bitauth https://charts.bitauth.com/

If you have previously added the bitauth repo, run helm repo update to fetch the latest charts.

Using the default configuration, Chaingraph will be installed with a single testnet4 BCHN full node, an internally-managed Postgres instance, and no load balancer.

This is an ideal configuration for experimenting with Chaingraph, as it can be deployed on very low-powered clusters (often even within the free tier provided by many cloud Kubernetes providers). See the chart readme for information about other options.

helm install my-chaingraph bitauth/chaingraph

Review the notes which are logged after installation for more information about your deployment. You'll find an API section with instructions for exposing Chaingraph's GraphQL API.

Once the API is public, you're ready to start using Chaingraph. We recommend graphqurl for exploring the API. Use -i to open the interactive GraphiQL UI:

npm install -g graphqurl
gq -i http://YOUR_IP:PORT/v1/graphql

Chaingraph's API is available during the initial sync. Try monitoring it with a subscription:

subscription MonitorSyncTips {
  node {
    name
    user_agent
    latest_tip: accepted_blocks(
      limit: 1
      order_by: { block_internal_id: desc }
    ) {
      block {
        hash
        height
        transaction_count
        size_bytes
      }
    }
  }
}

Mainnet Chaingraph deployments may take 10 hours or more to sync fully and build all indexes (depending primarily on the performance of configured nodes and the write speed of the database volume). Testnet deployments typically finish in a few minutes.

To continue exploring the Chaingraph API, check out the example queries on chaingraph.cash.

Chaingraph is a Kubernetes application which manages a stack of open source software including one or more Bitcoin Cash full nodes, a syncing agent, a Postgres SQL database, and a Hasura instance.

Learn more about Chaingraph's Architecture →

While many indexers are designed to support only one node implementation, Chaingraph is designed from the ground up to support multiple nodes.

Rather than assuming a single-node source-of-truth view of the network, the Chaingraph database schema and GraphQL API differentiate which nodes have acknowledged any particular transaction or block, and a full timeline is maintained for transaction validation, block acceptance, observed double-spends, and block re-organizations.

This additional information makes it possible for businesses to handle unusual network behavior without manual intervention by employing defensive consensus strategies.

Learn more about Chaingraph's API Schema →

To set up a local cluster for development, please see the Contributing Guide.