Hardhat graph plugin

Hello everyone, this is Petko (Axiomatic Aardvark on Discord) from LimeChain. I would like to bring to your attention an idea that we’ve been tossing around for a bit with folks from The Graph Foundation (namely @Pedro).

In a nutshell
It would be awesome to have a plugin for Hardhat, which smart contract developers (and subgraph developers of course) can utilise in order to automate away some of the manual tasks associated with subgraph development.

The pitch
Hardhat has been around for a while and has become one of the most widely used (if not the most widely used) framework for developing smart contracts on Ethereum. Given The Graph’s exponential popularity growth we can assume that a lot of new contracts being developed will incorporate subgraphs early on in their architecture. We expect to see a rise of something like subgraph-driven development of smart contracts. Meaning that smart contract devs will consciously strive to write their contracts in an event-first fashion, using little functions to none at all. This creates a need for a Hardhat plugin, which can abstract away the manual tasks related to creating and updating your subgraph.

How the plugin will work
Let’s imagine that a developer sits down to write a smart contract using Hardhat. They initialise their project from a Hardhat template and then update the template contract accordingly. After the initial setup is complete and they have a basci contract in place, they can run the following:

npx hardhat graph

which will automatically create a subgraph folder in the root of their Hardhat project, and populate it with a basic structure (copied from the Example Subgraph, for instance). The command would also generate the schema.json, subgraph.yaml, mapping.ts, and other files files accordingly, based on the contents of Hardhat’s artifacts build folder.

If however there’s already a subgraph folder, the plugin/tool will update only the bits that have changed.

Request for feedback
Now that we’ve gone over the basics of the Hardhat plugin concept, there is so much room for other functionality that can be added to further automate the process of subgraph development, based on the developers needs. All questions, comments and functionality requests are more than welcome!

PS the POC repo for this idea is located here. We will be using it to track progress, receive feedback in the form of Issues, etc.


Similar thing can be currently achieved with graph-cli init command.

It would be great, if subgraph can be included in testing of smart contracts…

Something like on running contract test cases, graph node will run and generated subgraph will be deployed.
Test cases assertions can be done by querying subgraph.

1 Like

Hey @AxiomaticAardvark, thanks for this! I definitely agree that it’s helpful to have Hardhat and Subgraphs working closely together. Previously I have worked on the subgraph package in scaffold-eth, where a few things happen whenever contracts are deployed:

This reduces the need for manual copy pasting so you can iterate pretty quickly.

That is slightly different to the proposal above, which is focused on scaffolding a subgraph from an ABI. I think that is because there are a couple of use-cases here:

  • Initialising a subgraph based on an ABI: simple
  • Iterating on a contract and a subgraph in tandem: in this case you likely don’t want to edit or update the mappings / schema, you might just want to update the deployed address & ABI (as in scaffold-eth)

I think it’s also interesting to think about the flow - while a hardhat CLI command might work well in some cases, developers may want to always update their subgraph config whenever they deploy, in which case a function (hh.graph.update("contractName")) that can be called as part of a hardhat task (or in a hardhat-deploy execution) might be preferable.

There is obviously a pretty broad problem / solution space here. Other things that I think are interesting:

  • Using the deploy network to identify what the network should be in the subgraph.yaml
  • Handling & iterating on multiple contracts / networks at a time
  • Should this facilitate testing with a local graph-node? (that is the recommended setup in scaffold-eth)
  • How might this tie in with testing frameworks (for the smart contract, and for the subgraph) as mentioned by @steve-pro

Definitely interested in hearing other perspectives and thoughts from other Hardhat / Subgraph users! cc @ariel @davekaj

1 Like

Hi! I wanted to share a related proposal, adding functionality to graph-cli:

  • Add an easy networks.json standard for updating the contract addresses & network for a subgraph as part of graph build
    • e.g. during local development, or when deploying the same subgraph to multiple networks
  • Let developers graph add dataSources to a subgraph programmatically (based on deployed contracts), in the same way they can currently use graph init

More detailed write up:

These interfaces will be useful for development of a Hardhat graph plugin. Feedback welcome!


Plus 1 this to infinity



The Hardhat Plugin is now being worked on in GitHub - graphprotocol/hardhat-graph. A loose initial spec is here: Hardhat Graph plugin - HackMD, but looking forward to discussions & feedback from the community as this develops.

Also drawing developers’ attention to the new networks.json file that is generated by graph init, and which can be used at build time to easily switch the same subgraph to be deployed to a different network (with different contract addresses and startblock!) - Deploy a Subgraph to the Hosted Service - The Graph Docs.

I integrated this with the master branch of scaffold-eth, which now populates the networks.json file during contract deployment

This is a useful new feature built by Limechain in preparation for the hardhat-graph workstream, and feedback is welcome!

1 Like