Integrating New Networks

Reading time: 3 min

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.

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.

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.

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)

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: https://api.thegraph.com/ipfs/

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 dataSources.network 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 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