Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/bitauth/chaingraph
A multi-node blockchain indexer and GraphQL API
https://github.com/bitauth/chaingraph
bitcoin bitcoin-cash blockchain cryptocurrency graphql helm-chart indexer kubernetes
Last synced: about 1 month ago
JSON representation
A multi-node blockchain indexer and GraphQL API
- Host: GitHub
- URL: https://github.com/bitauth/chaingraph
- Owner: bitauth
- License: mit
- Created: 2021-09-30T04:42:10.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2023-12-13T15:47:34.000Z (7 months ago)
- Last Synced: 2024-05-17T04:51:57.572Z (about 1 month ago)
- Topics: bitcoin, bitcoin-cash, blockchain, cryptocurrency, graphql, helm-chart, indexer, kubernetes
- Language: TypeScript
- Homepage: https://chaingraph.cash/
- Size: 1.81 MB
- Stars: 44
- Watchers: 4
- Forks: 15
- Open Issues: 54
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
Lists
- Blockchain-Guide - Chaingraph - node blockchain indexer and GraphQL API. (Blockchain Playgrounds / E-Books)
- awesome-bitcoin - Chaingraph - node blockchain indexer and GraphQL API. (Blockchain dump)
README
[](https://github.com/bitauth/chaingraph/actions/workflows/ci.yaml)
[](https://app.codecov.io/gh/bitauth/chaingraph/)
[](https://twitter.com/ChaingraphCash)
[](https://t.me/chaingraph_dev)
[](https://hub.docker.com/u/chaingraph)
[](https://github.com/bitauth/chaingraph)
# Chaingraph
A multi-node blockchain indexer and GraphQL API.
For more information, and for examples of live subscriptions and complex queries, see [**chaingraph.cash**](https://chaingraph.cash/).
## Quick Start
Chaingraph runs on [Kubernetes](https://kubernetes.io/), 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](.github/CONTRIBUTING.md). For details about other configurations, see the [chart documentation](./charts/chaingraph/readme.md).
### 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](https://m.do.co/c/cb25573fbfe7)** (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](https://helm.sh), then add the `bitauth` repo:
```sh
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](https://gitlab.com/bitcoin-cash-node/bitcoin-cash-node) 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](./charts/chaingraph/readme.md) 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](https://github.com/hasura/graphqurl#graphiql) 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:
```gql
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**](https://chaingraph.cash).
### Upgrade Chaingraph
These instructions upgrade the `my-chaingraph` cluster created in the [Quick Start](#quick-start) to the latest version of Chaingraph:
```sh
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:
```sh
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 →](./docs/architecture.md)
## 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](https://blog.bitjson.com/defensive-consensus-getting-to-a-multi-implementation-bitcoin-network/) strategies.
Learn more about [Chaingraph's API Schema →](./docs/schema.md)
## New Developers
New developers to Chaingraph, Bitcoin Cash or blockchain development generally may benefit from some initial introductory information. See [Helpful Tips](./docs/helpful-tips.md).
## Contributing
To set up a local cluster for development, please see the [Contributing Guide](./.github/CONTRIBUTING.md).