Integrating New Networks

Reading time: 3 min

Graph Node can currently index data from the following chain types:

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.


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.

2. Firehose

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.

Difference between EVM JSON-RPC & Firehose

Link to this section

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)

Testing an EVM JSON-RPC

Link to this section

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_getLogs
  • eth_call _(for historical blocks, with EIP-1898 - requires archive node):
  • eth_getBlockByNumber
  • eth_getBlockByHash
  • net_version
  • eth_getTransactionReceipt, in a JSON-RPC batch request
  • trace_filter (optionally required for Graph Node to support call handlers)

Graph Node Configuration

Link to this section

Start by preparing your local environment

  1. Clone Graph Node
  2. 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 ethereum even if the network name is different.

  3. Run an IPFS node or use the one used by The Graph:

Test the integration by locally deploying a subgraph

  1. Install graph-cli
  2. Create a simple example subgraph. Some options are below:
    1. The pre-packed Gravitar smart contract and subgraph is a good starting point
    2. Bootstrap a local subgraph from any existing smart contract or solidity dev environment using Hardhat with a Graph plugin
  3. Adapt the resulting subgraph.yaml by changing to the same name previously passed on to Graph Node.
  4. Create your subgraph in Graph Node: graph create $SUBGRAPH_NAME --node $GRAPH_NODE_ENDPOINT
  5. 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 Firehose-enabled chain

Link to this section

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:

  1. General docs on Firehose
  2. Adding Firehose support for a new chain
  3. Integrating Graph Node with a new chain via Firehose
Edit page

Supported Network Requirements
Edit page