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
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
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.
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.
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.
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.
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.
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.
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!