Chaingraph: Multi-Node Bitcoin Cash Indexer

Jason Dreyzehner -

Chaingraph is an open source blockchain indexer and API backend for Bitcoin Cash apps and businesses. It supports multiple nodes and chains, allowing your software to gracefully handle network splits or node instability.

The code is available on GitHub, and examples of live subscriptions and complex, nested queries can be found on the project website: chaingraph.cash.

Universal Node Support

Chaingraph connects to nodes using the standard P2P interface, so it can connect to any node, written in any language, for any platform. It tracks all transactions and blocks accepted by each node, allowing apps to query or subscribe to activity over a GraphQL API.

Since there’s no reliance on RPC or other non-standard backend interfaces, it’s easy to swap or add new node implementations without modifying Chaingraph or your business logic. This makes your app more resilient and the ecosystem more censorship resistant.

Chaingraph can connect to nodes already running in your infrastructure, and it can also spin up, configure, and manage a set of nodes itself. Initial support already includes the latest mainnet and testnet BCHN nodes, and future versions may support automatic deployment of other popular node implementations.

Multi-node, Multi-chain

While many indexers are designed to support only one node implementation (or are themselves a unique, possibly-incompatible 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.

Despite this additional data, nodes running on the same network require very little additional storage (less than 100 MB per node). With such low requirements, it’s even reasonable to run multiple versions of the same implementation simultaneously (particularly for implementations which support pruning).

Nodes which share a common history (i.e. running on each side of a chain split) also save significant storage, as pre-split blocks and transactions are not duplicated in the database. This makes supporting network splits surprisingly fast and cheap for businesses: only the post-split tip needs to be synced, and if Chaingraph is already running at the time of the split, it’s possible to keep Chaingraph synchronized on both tips with only pruned node implementations.

Powerful GraphQL API

Chaingraph’s GraphQL API is served by the open source Hasura engine, enabling rapid development without sacrificing production performance. Hasura supports complex, nested queries and live subscriptions that can horizontally scale to millions of subscribers.

Using Hasura both decreases the maintenance surface of Chaingraph and simplifies extending the indexer with new functionality. Developers can add new Postgres views, tables, functions, triggers, etc. to the database without modifying Chaingraph’s Typescript code, and Hasura automatically provides API access to those custom database objects. Other Hasura features – like REST API support, webhooks, and event triggers – are also valuable for extending Chaingraph with more complex functionality.

Customize and Extend with SQL

All Chaingraph data is normalized in a PostgreSQL database, making it possible for developers to get raw access, build new features and indexes, or run complex blockchain analysis queries, all without having to patch or maintain a fork of Chaingraph.

Chaingraph also ships with several built-in blockchain analysis features:

  • Unlocking, locking, and P2SH redeem bytecode decoding and pattern extraction
  • Cumulative input, output, and fee calculations for transactions and blocks
  • Recursive Bitauth identity resolution
  • Broadcast timing information for all transactions and blocks
  • A locking bytecode prefix index, which enables searching both by address and by the first 26 bytes of OP_RETURN data carrier outputs (sufficient for most OP_RETURN protocols)

To reduce storage requirements, a standard Chaingraph instance only maintains the minimum required indexes for typical wallet applications, but even custom queries requiring very expensive computations can be accelerated by precomputing results using Postgres expression indexes, materialized views, or custom tables and triggers.

Researchers interested in blockchain analysis features not yet included in Chaingraph are encouraged to open an issue on GitHub. Several features are planned for future releases, including address clustering, privacy leak analysis, coin-days destroyed, and other monetary measurements.

Most analysis features can be enabled by default without a performance penalty, and features requiring increased runtime requirements can be made configurable during installation.

Simple Deployment and Configuration

Helm makes installation and configuration a breeze. Running helm install <deployment-name> bitauth/chaingraph [options] on any Kubernetes cluster will provision storage, spin up node(s), create and connect the database, start the API server, etc.

See the video demo:

By default, Chaingraph spins up and connects to a single testnet BCHN node (testnet4). This makes experimenting with Chaingraph fast, even on inexpensive, shared, cloud computing resources. Mainnet support can be enabled by simply including bitcoinCashNode.enable=true during helm chart installation or upgrade.

Chart options also enable customization of many other deployment properties, including which container images should be used for each software component. This generally allows deep customization of Chaingraph (or use of pre-release component versions) without having to modify the Helm chart.

Built To Last

Chaingraph is designed to be maximally-maintainable: less than 5000 lines of TypeScript manage a reliable, open source stack, and the project includes thorough unit and end-to-end tests (including simulation of unintended and long-lasting chain splits). Additionally, the primary Typescript application (chaingraph-agent) requires only a few, well-vetted, SHA256 digest-locked dependencies.

All Chaingraph component images are built automatically by continuous integration when pull requests are merged, so reliable images for pre-release features are available immediately. Versioned releases of the Chaingraph Helm chart are also automatically deployed from the repo, with all components strictly versioned by SHA256 digest.

Get Started

For sample queries and subscriptions, see the Chaingraph website. To try out a demo instance, check out try.chaingraph.cash.

To get involved, ask questions, or contribute code, please join the Chaingraph Telegram group. More information is also available in the Contributor’s Guide.