Chaingraph

A multi-node blockchain indexer and GraphQL API.

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

Quick Start

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.

Create a Cluster

As of 2023, 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 $200 credit (supports demo.chaingraph.cash); this should cover a basic, production-ready BCH mainnet deployment for ~60 days (approximately $85/month for SSD storage, one $12/month droplet, and $12/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.

Add the Chart Repo

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.

Deploy a Release

Using the default configuration, Chaingraph will be installed with one chipnet and one 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
      }
    }
  }
}

More details

This subscription returns the list of nodes connected to Chaingraph, their version information, and the hash, height, size, and transaction count of the most recently saved block accepted by that node.

Note, Chaingraph saves blocks asynchronously, and large blocks can take longer to save to the database. During initial sync, this may cause the subscription to occasionally update its result with lower-height (more recently saved) blocks. Regardless, this subscription will roughly track sync progress for each connected node.

This query could also be ordered by block height, but because non-primary indexes are created after initial sync (to reduce time required), ordering by block height can be slow until after the initial sync is complete.

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.

Upgrade Chaingraph

These instructions upgrade the my-chaingraph cluster created in the Quick Start to the latest version of Chaingraph:

helm repo update # Pull the latest bitauth/chaingraph helm chart
helm get values my-chaingraph -o yaml > my-values.yaml
helm upgrade my-chaingraph bitauth/chaingraph --reset-values --values my-values.yaml

As a best practice, consider preserving the my-values.yaml file for future reference. You can also preserve the latest deployment status and notes at any time:

helm status my-chaingraph > status.txt

Architecture

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 →

Schema

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 →

New Developers

New developers to Chaingraph, Bitcoin Cash or blockchain development generally may benefit from some initial introductory information. See Helpful Tips.

Contributing

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