Overview of solutions for querying Ethereum with GraphQL

Have you heard of GraphQL? That’s an alternative to REST apis that was created by Facebook. With GraphQL, clients specify the shape of the data they want, and backends figure out how to provide the desired data. No need to juggle with countless REST endpoints. GraphQL is becoming super popular this year, and web developers should absolutely learn it.

And now you can start using GraphQL with Ethereum too. Using the power of the GraphQL Standard Definition Language (SDL) and, you can easily make complex queries to the Ethereum blockchain and its smart contract. Let’s see what are the options for using GraphQL with Ethereum.

EthQL

EthQL is a NodeJS library that provides a GraphQL api on top of the REST api of Ethereum.

It uses an Infura backend. If you have never heard of Infura, that is a service that save you the pain of running your own Ethereum nodes by providing publicly-accessible Ethereum nodes. To use EthQL, you need to first create an account on Infura, create a project in their dashboard, and put your Infura project ID in an environment variable.

Then, you run your EthQL server, and you can send it GraphQL requests. The EthQL API covers:

• Block
• Account
• Transaction
• Log
• Decoded transaction

For example, this is a query for finding block info:

{
  block(number: 5450945) {
    number
    hash
    parent {
      number
    }
    nonce
    transactionsRoot
    transactionCount
    ...
}

On the frontend, you can use any GraphQL client that you want (Apollo, raw Graphql, etc…). All that matters is that you send your EthQL server queries it can understand. If you want to know more what the type of query you can send, check out this document.

TheGraph

TheGraph is a GraphQL api for Ethereum, available as a service. Contrary to EthQL, you don’t need to run any GraphQL server yourself. You only need to write Graphql queries, and send them to TheGraph server. Another difference is that TheGraph is focused on providing an interface for smart contracts, instead of the whole Ethereum API. And a last difference is that Dapp developers need to upload a description of the GraphQL interface of their smart contract (a “subgraph”) to TheGraph before it can add the contract to its public API.

If you want to know more about TheGraph, you can check this introduction in their documentation. And if you want to add a subgraph for your smart contract, you can check out this step-by-step tutorial. One interesting part is that they have CLI tools to speed-up the generation of a subgraph for a contract.

Ethereum-to-Graphql

This project is an NodeJS tool to dynamically create a GraphQL schema of your smart contract. It will map a GraphQL Query or Mutation to all your Solidity functions, depending on whether they are read-only (view and pure) or not. You can use the GraphQL schema in any GraphQL server.

When you use this tool, you need to provide it with an url to an Ethereum node. You can run your own, or specify the url of a public node, like Infura.

EIP 1767

All of the projects I showed you before are great but you might wonder whether Ethereum itself has plans for GraphQL. Wouldn’t it be great if Ethereum clients themselves had a GraphQL API?

A team of volunteer have been working on a specification just for that. That’s the EIP 1767. If you are not familiar with EIPs (Ethereum Improvement Proposals), that is basically the Ethereum equivalent of internet RFCs (Request For Proposal), a collaborative process to create new standards.

When EIP 1167 will be finalized, Ethereum clients will start adding a GraphQL API. I dont think it will replace the REST api, but at least it will be a nice alternative way of fetching Ethereum data.

Lastly, there was also a project called Cleargraph to query Ethereum with GraphQL, but there were bought by another company, and it’s not clear whether or not the project is still active, so I just mention it for reference.

If you are a user of GraphQL or just curious, do try to use it in your future projects. The easiest way to get started and start playing around is to use TheGraph GraphQL api.