Nifty Notes: Building with TheGraph

Adam Fuller
4 min readOct 16, 2020

Today we are talking about The Graph. If you have ever battled in vain to get data out of a smart contract, The Graph is the magical middleware you were searching for. In this post we will cover:

  • What The Graph is and why it is cool 🆒
  • Our experience adding it into 🖌️
  • A lightweight demo that lets you spin up your own subgraph 👷

What is The Graph? 🆒

While blockchains are great in lots of ways (not now Dad), one thing they are not so good at is returning nice structured data for your user interface. Extracting data from Ethereum can be EXCEPTIONALLY CONVOLUTED, which means that as much time is spent wrangling eth_call as is spent actually creating a good user experience.

The smart-brains at The Graph identified this problem, and built a really excellent way for users to aggregate blockchain events into easily accessible graphQL (a “subgraph”). As a result your contract data is a single API call away, no wallet permissions required. If you’re not excited, you’ve never iterated through a mapping in a smart contract (that was a joke because you can’t!)

The creation of a subgraph can be broken down into three steps:

  1. Define your schema
  2. Create event handlers to update the subgraph when a certain event takes place
  3. Create a manifest file that combines the schema & the handlers with the meta-data required (e.g. the chain, the contract addresses)

And that’s it! Once these three files are defined, you are three CLI commands away from a production-ready graphQL backend for your Dapp.

TheGraph <> 🖌️ v0 was built as a proof-of-concept elaboration of a few cool technologies (ipfs! meta-transactions! cross-chain transfers!) We definitely considered using The Graph, but decided that we didn’t want to over-optimise for our initial release.

This was a mistake!

While a subgraph is maybe overkill for a very simple app, as soon as you find yourself making multiple contract calls, you may want to consider building a subgraph — it might even be quicker and easier! In addition you get a huge amount of flexibility out of the box (filtering, sorting etc.) and you can worry less about how you get the data back from the chain, and more about how you present it to your users. Creating your graphQL schema also makes sure you think about use-cases for your Dapp’s data, beyond the MVP.

A few graph-powered Inks

Which is a long-winded way of saying is now powered by The Graph! Many kudos to Osama for jumping in on this project. It wasn’t all plain sailing — while we got the the initial subgraph spun up in a matter of hours, we hit a bit of a speed-bump as we hadn’t emitted events on every function of interest. There is a workaround, we just needed to rely on calldata instead, but this wasn’t enabled on xDai (the side-chain is primarily built on). Enormous credit to The Graph’s team, who were responsive and exceptionally helpful in getting this up and going, in collaboration with the xDai team

We had some other interesting challenges — is a two-chain app, so we needed two subgraphs as we can’t (currently) merge data from xDai and mainnet contracts. But all in all, I wish we had built on top of a subgraph from the get-go — check out, which is smoother than ever, and watch out for some new subgraph enabled features coming down the pipe!

A happy little subgraph

> And if you can spare the gas cost, make sure that you add events everywhere when you’re developing your smart contracts. You won’t regret it.

Trying it out! 👷

The best way to get a feel for a new technology is to try it out, so with that in mind we invite you to check out the graph-dev branch on scaffold-eth. This demonstrates:

  • How to run a local graph node (in a Docker container)
  • Deploying a stripped-back version of our nifty-ink subgraph
  • A react-app using Apollo to pull out data from the subgraph
Local graph node, working hard.

Check out the README for a step-by-step walkthrough, and do get in touch on Twitter or Telegram — we’d love to hear how you get on.

Many thanks to all those who helped move onto The Graph: Leo, Martin, Ford from The Graph; Igor & team from xDai, and Osama & Austin from

It is hard to do screenshots for API features