Integrating New Networks
Graph Node can currently index data from the following chain types:
- Ethereum, via EVM JSON-RPC and Ethereum Firehose
- NEAR, via a NEAR Firehose
- Cosmos, via a Cosmos Firehose
- Arweave, via an Arweave Firehose
If you are interested in any of those chains, integration is a matter of Graph Node configuration and testing.
If you are interested in a different chain type, a new integration with Graph Node must be built. Our recommended approach is developing a new Firehose for the chain in question and then the integration of that Firehose with Graph Node. More info below.
1. EVM JSON-RPC
If the blockchain is EVM equivalent and the client/node exposes the standard EVM JSON-RPC API, Graph Node should be able to index the new chain. For more information, refer to Testing an EVM JSON-RPC.
For non-EVM-based chains, Graph Node must ingest blockchain data via gRPC and known type definitions. This can be done via Firehose, a new technology developed by StreamingFast that provides a highly-scalable indexing blockchain solution using a files-based and streaming-first approach. Reach out to the StreamingFast team if you need help with Firehose development.
While the two are suitable for subgraphs, a Firehose is always required for developers wanting to build with Substreams, like building Substreams-powered subgraphs. In addition, Firehose allows for improved indexing speeds when compared to JSON-RPC.
New EVM chain integrators may also consider the Firehose-based approach, given the benefits of substreams and its massive parallelized indexing capabilities. Supporting both allows developers to choose between building substreams or subgraphs for the new chain.
NOTE: A Firehose-based integration for EVM chains will still require Indexers to run the chain's archive RPC node to properly index subgraphs. This is due to the Firehose's inability to provide smart contract state typically accessible by the
eth_call RPC method. (It's worth reminding that eth_calls are not a good practice for developers)
For Graph Node to be able to ingest data from an EVM chain, the RPC node must expose the following EVM JSON RPC methods:
eth_call_(for historical blocks, with EIP-1898 - requires archive node):
eth_getTransactionReceipt, in a JSON-RPC batch request
trace_filter(optionally required for Graph Node to support call handlers)
Start by preparing your local environment
- Clone Graph Node
- Modify this line to include the new network name and the EVM JSON RPC compliant URL
Do not change the env var name itself. It must remain
ethereumeven if the network name is different.
- Run an IPFS node or use the one used by The Graph: https://api.thegraph.com/ipfs/
Test the integration by locally deploying a subgraph
- Install graph-cli
- Create a simple example subgraph. Some options are below:
- Adapt the resulting
dataSources.networkto the same name previously passed on to Graph Node.
- Create your subgraph in Graph Node:
graph create $SUBGRAPH_NAME --node $GRAPH_NODE_ENDPOINT
- Publish your subgraph to Graph Node:
graph deploy $SUBGRAPH_NAME --ipfs $IPFS_ENDPOINT --node $GRAPH_NODE_ENDPOINT
Graph Node should be syncing the deployed subgraph if there are no errors. Give it time to sync, then send some GraphQL queries to the API endpoint printed in the logs.
Integrating a new chain is also possible using the Firehose approach. This is currently the best option for non-EVM chains and a requirement for substreams support. Additional documentation focuses on how Firehose works, adding Firehose support for a new chain and integrating it with Graph Node. Recommended docs for integrators: