Learn How To Evaluate The Graph Subgraphs Like A Pro Curator

This article is for people already familiar with The Graph protocol. It will be of the most interest to the reader who is most likely a subgraph curator and who want to learn the initial steps needed to evaluate a subgraph. In the paragraphs below, I will provide a simple algorithm for evaluating a subgraph. Please note, I do not intend to provide a complete not only solution. Merely, this guide should be seen as a starting point for developing your approach to the analysis of the subgraphs. I also assume that the reader has at least some understanding of how the subgraph works. If you are completely new, I would suggest to read The Graph docs first and then coming back to this guide.

The Starting Ground

The Graph Explorer. You can see the url, GitHub, and ID of the project.

First of all, you need to find the subgraph that you will be evaluating. The simplest way to do that is to go to the URL bar and paste the following link: https://thegraph.com/explorer/subgraph/[subgraph_name] Please replace [subgraph_name] with the subgraph name you are searching for. If you do not have a subgraph name then just go The Graph Explorer and search for anything that interests you.

I chose the following graph as an example: https://thegraph.com/explorer/subgraph/ianlapham/tokenholders

Once you are on the subgraph page, look at the description. Does it well describe what data the subgraph provides? Then, check if the subgraph has a Github account. If it does, open it and check if it has a README file. Read the description there. Note, if there is no GitHub link and you can not find it on GitHub by searching for repositories with similar names that match the subgraph name, you would not be able to perform an analysis of its handlers. You would have to take a guess at the subgraph implementation. There is no way to pull out mappings file because it would be stored in a compiled form once deployed.

Then, you can use The Explorer Playground to interact with the subgraph data. Check what sort of queries are possible there and what sort of data you can receive.

Get A Detailed Sense Of What The Subgraph Does

The subgraph manifest found at ipfs.io. Take a note of the URL and contract addresses from where the subgraph is watching for events. In this subgraph there are two contracts. There could be one or more. Copy the contract address.

Now, it’s time to look at the subgraph manifest. The manifest will tell you what contracts the subgraph is watching and what events it is tracking.

First, go to https://ipfs.io/ipfs/[ID] and replace [ID] with the subgraph ‘ID’ found in The Explorer. Then find what contracts the subgraph is tracking. To do that, look at the following keys in the manifest: dataSources => mapping => source. Copy the contract address from the source, go to Etherscan and find that contract. See what project it belongs to and what sort of transactions are occurring there. Note, a subgraph can contain multiple contracts. In this case, check each one of them.

Overview of the contract that the subgraph is tracking. Check what project it belongs to and what transactions are there.

Note, you can also go to ‘subgraph.yaml’ (it’s the manifest file) on the subgraph Github page and compare it to the data obtained from https://ipfs.io. These two should be the same. Then you can also check ‘schema.graphql’ file to see what sort of graphql types are defined there. These typing define the structure of the data that you can query in The Explorer Playground.

Subgraph manifest in ‘subgraph.yaml’ file in the GitHub repository. It should match the manifest on https://ipfs.io

Subgraph GraphQL type definitions found in ‘schema.graphql’ in the GitHub repository. The types defined there give structure to the queries. They should match the types that you can query in The Explorer Playgound.

If you have some knowledge of Solidity, you can skim over the contract on Etherscan to see what sort of functions, with what data are being called there.

Contract source code on Etherscan found under the ‘Contract’ tab.

At this point you should be able to answer what the subgraph does and if it’s production-ready.

Get To Know The Subgraph In Action

In this step, you are going to find out what sort of events the subgraph is watching, and what handlers it is calling to extract the data.

Events and handlers in the subgraph manifest. Events will match function names in the contracts they are associated with. These are the events the subgraph is ‘watching’. Handlers are functions defined in ‘mappings’ in the subgraph repository. These are the functions called by the subgraph upon each event above in the contract.

Look at the contract events that the subgraph is watching by looking in the manifest file (subgraph.yaml) dataSources => mapping => eventHandlers => event. These are the functions that the ethereum contract is calling. Each time the function is called, the subgraph is going to take a note and call a handler defined in the manifest below the event: dataSources => mapping => eventHandlers => handler.

ABI file in the subgraph repository. Each ‘name’ field will match a function name in the contract. Each input filed will match inputs that function takes.

ABI file on Etherscan in the project contract. You can export it into a JSON file to make it more readable. Or paste it in any JSON formatter tool online.

Then, open up an ABIs for the contracts defined in the manifest. (Note, ABI is a list of the contract’s functions and arguments (in JSON format)). The ABIs can either be found in the subgraph GitHub (in ‘abis’ folder) or on etherscan contract address under ‘Contract’ tab below the Ethereum contract. Go over the ‘name’ fields to see what functions are in the ABIs — these are essentially events that that happen, they are usually self-descriptive and by the name, you can take a guess at what that function does. Take a note of the function names that match eventHandlers in the subgraph manifest. Pay attention to what arguments these functions are taking too.

Subgraph mappins file in the GitHub repository. There should be function names that match ‘eventHandlers’ in the manifest file. Other functions are helper functions. Look at the names to guess what sort of transofmations they do. Then look at the function implemntation to see what sort of data modifications the handlers perform before saving data in The Graph store. This will tell you exactly what a subgraph does.

Then, go to mappings files in the subgraph github account (/src/mappings/) check out the files there and look for function names that match handlers in ‘eventHandlers’ in the manifest. Try to get a sense of what sort of data extraction this handler does.

Evaluate The Subgraph

At this point you should have a pretty good understanding of what events the subgraph is recording from the contract and what data it is recording from these events. Now it’s time to think about what you found so far. Evaluate the graph and ask the following questions:

• What changes would you make to the schema including additions or modifications to entities, fields, field types, relationships, or any other improvements?
• Are there any other subgraphs that do similar things? How does this one compare?
• Identify the degree of completeness, complexity and accuracy of the implementation.
• Is the data provided by the subgraph is useful?
• Is there a way to improve it?

Make It Better

After that analysis of the subgraph, see what could be improved. Go over the existing entities in the ‘schema.graphql’ file and think about what other data could be useful to add.

Then go over the ABIs again and based on the function names, think about what other events could be tracked and what sort of valuable data could be extracted from that.

If you find there’s an opportunity to add more value or extract more data, take a record of that. These are the future points for further development of that subgraph.

Congratulations The Graph Master

Ok, maybe not a master yet. But the above steps should give you a very good starting point for evaluating the subgraphs.

One additional suggestion I would make is to start with very small subgraphs. These usually do not have much information and are easier to grasp. After you are confident with the overall structure and implementation of subgraphs, you can move onto more complex ones. Good luck!