First steps of gumanitarium in creating Subgraph.

Original p1
Original p2

The start of learning something new is to find a good guide to help you accelerate your journey.

In my opinion, a good start would be to use these 3 resources:

  1. The Graph Docs
  2. How to index and query Ethereum and IPFS data using The Graph
  3. ETHOnline 🛠️ The Graph: Building Subgraphs on The Graph

After reading the introduction, you will get a basic understanding of what Graph is and how it works.

In the next section you are given two ways of how to create Subgraph: by creating a local environment (more suitable for massive subgraphs and professional programmers) or using hosting service from The Graph team located in the cloud storage (this path is much easier for a beginner and David Kajpust in this video recommends using it).

In this article I will explain the second option.

To use The Graph team’s hosting, you need to authorize on their site (GitHub account is required). After this you will be able to add new Subgraphs.

Example from video “ETHOnline 🛠️ The Graph: Building Subgraphs on The Graph”

After clicking on the highlighted button, you will receive a window for adding Subgraph with a list of parameters.

After filling required fields and clicking the Create Subgraph button, you will go to the page of created, but not expanded Subgraph.

Under boxes number 1,2 and 3 are hidden commands that will need to be executed in terminal on your PC in order to:

  1. Install Graph CLI
  2. Create Subgraph
  3. Deploy Subgraph on The Graph’s node

Different terminals can be used for next steps.

The Graph team work on MacOS and use iTerm2.

For Windows users basic version of Windows PowerShell may be sufficient (or you can choose something from the offered iTerm analogues.

First, you will need to install Yarn. For Mac OS use this link.

For Windows you can check here.

FOR WINDOWS USERS:

Before execute next commands, do all the steps from this instruction. Start installers as Admin and install all additional atributes for Node.js.

Under the first block you can see message suggesting to install Graph CLI with npm or yarn right in you terminal:

$ npm install -g @graphprotocol/graph-cli$ yarn global add @graphprotocol/graph-cli

The command line log of executing this command in the terminal is shown below:

After successful installing Graph CLI we proceed to create Subgraph itself. This can be made in two ways:

1) From an existing Ethereum contract

2) From an existing The Graph team’s example

In this article we will try the second one. It is simple way to create Gravatar Subgraph, which will be useful for deploying your own Subgraph because of getting stock code to edit.

P.S. We did go by the second way at the end of this article. But I recommend to go through all steps in this guide at first.

After clicking on the second box, you will see following windows:

Copy command:

$ graph init — from-example <GITHUB_USERNAME>/<SUBGRAPH_NAME> <DIRECTORY>

And paste it into note, replase the following variables, and then paste the result in terminal:

<GITHUB_USERNAME> use your GitHub username

<SUBGRAPH_NAME> use your Subgraph’s name

<DIRECTORY> is optional: this is the name of directory in which your subgraph is created; by default, you should use subgraph’s name.

The implementation of the function above in terminal will look like this ( terminal will ask you to re-confirm name of your Subgraph and folder where you want to install it):

Example from video “ETHOnline 🛠️ The Graph: Building Subgraphs on The Graph”

After successfully creating Subgraph, you need to deploy it to The Graph hosting. This can be done using the commands that are hidden in the third box.

For the first command:

$ graph auth https://api.thegraph.com/deploy/ <ACCESS_TOKEN>

You need to use Subgraph’s access token, which is:

First command’s result:

Command has created a folder named identically like your Subgraph. In order to enter this folder, execute command “ cd <folder name> “. To see folder’s content, use “ ls ” command:

Inside you can see different files (License, abis, readme, etc), but for better understanding of the code, you can open this folder in Visual Studio (if installed). For this implement command

code .

The next step is implementing

$ yarn codegen

or

$ npm run codegen

command, which will create necessary files automatically.

What does this command do and why is she very useful? It takes data from abis smartcontract in Ethereum netwok, which looks so:

It creates more readable code, installs Setters and Getters, creates files and makes changes in Mappings, Schema and Subgraph.yaml (Manifest), facilitating working with Subgraph.

The final step of deploying our Subgraph on The Graph Hosting will be the deploy operation itself:

graph deploy \ 
— debug \
— node https://api.thegraph.com/deploy/ \
— ipfs https://api.thegraph.com/ipfs/ \
<SUBGRAPH_NAME>

Don’t forget to change <SUBGRAPH_NAME> on your Subgraph’s name

P.S. In discord, one curator suggested running the previous command together with access token and this solved problems of other users.

graph deploy — access-token <Ваш Access token>\ 
— debug \
— node https://api.thegraph.com/deploy/ \
— ipfs https://api.thegraph.com/ipfs/ \
<github/subgraph_name>

Since many people have the same error when implementing commands above, I advise you to write previous code in 1 line. The “\” sign must be removed (it just meant the continuity of the code). In total, your code will look like this:

As we can see, after completing implementation of the command, we received a link to the page of Subgraph we created, which is deployed to the hosting service The Graph and at the moment is probably indexed by it. By clicking on link, we will see the page already familiar to us:

So, once sync is complete, we will have PlayGround GraphQL in our dashboard in Graph Explorer, which is ready to execute queries using the new Subgraph we just created.

Next steps

It should be understood that so far we have just learned how to create and place a simple template Subgraph. In order to end up with Subgraph that performs the functions of particular interest to us, we will have to modify the code of this Subgraph, think over what exactly we want to get in the SchemaQL of our Subgraph and make changes to Mappings, Manifest, etc. The function “yarn codegen”, already studied and successfully applied by us, will become an important help here.

Also, instead of fixing created test Subgraph, you can leave it as it is and, with your experience, create a new Subgraph directly from Ethereum contract. You can read about creating Subgraph directly from an Ethereum contract in the next chapter below. If you still want to modify the already created Subgraph, and not create a new one, then you can continue reading this article.

Let’s imagine that we want to use data from Uniswap on pairs traded there. We can go to their GitHub page, download their ABI file from there, or just copy all the code from this page:

Then replase abi file Gravity.json by downloaded abi file (or just delete all the code and paste copyed from GitHub) in Visual Stidio of our Subgraph.

P.S. If you just change the code, you need to rename abi file. Write Gravity.json instead of Pair.json

After this you need to change Data Sourses in our Subgraph on new ABI’s name:

After that, we run the

yarn codegen

command, which will automatically rewrite Mappings, Manifest and other files of our Subgraph, taking into account the new input data.

To create a really good and useful Subgraph from the current template, you will have to spend some time studying GraphQL, Ethereum contract you are interested in and a deeper acquaintance with Graph documentation. But if you have successfully created and deployed this test Subgraph, then the above-mentioned “tasks with an star” are more than tough for you — so go for it!

2nd chapter

Let me remind you that after successful installation of the Graph CLI, we have 2 ways to create Subgraph:

1) from an existing Ethereum contract

2) from an existing example from The Graph team.

In this article, we will look at the second one.

Having decided on the idea that you want to implement using the subgraph, you find the address of the contract you are interested in on the Ethereum network from where you plan to index the data.

If you already chose the idea that you want to implement by your Subgraph, then find contract’s address that you will index.

Then use this command:

graph init \ 
— from-contract <CONTRACT_ADDRESS> \
[ — network <ETHEREUM_NETWORK>] \
[ — abi <FILE>] \
<GITHUB_USER>/<SUBGRAPH_NAME> [<DIRECTORY>]

<CONTRACT ADDRESS> — address of the contract that you would like to index.

<ETHEREUM_NETWOKR> — check all options here (unnecessary).

<FILE> — path to contract’s ABI file that is saved on you computer (unnecessary).

<GITHUB_USER> — your GitHub account name.

<SUBGRAPH_NAME> — your Subgraph name.

To simplify you can just use this command:
graph init — from-contract <CONTRACT_ADDRESS>
and answer all request step by step.

The result is a window with suggested next steps:

For the first command


graph auth https://api.thegraph.com/deploy/ <ACCESS_TOKEN>

Change <ACCESS_TOKEN> for your Subgraph’s token.

To enter the folder, use

cd <folder name>

To see it’s content use

ls 

Inside you can see different files, but for a better vision, open it in Visual Studio by “ code. “ command (Visual Studio should be installed already).

Further work with code is based on your idea, so only thing I can recommed is to insert the start block (when your contract was deployed in Ethereum network) into your Manifest.

You can find this block in the creation on etherscan.

The final step of deploying Subgraph on The Graph Hosting is “yearn deploy” operation:

We received a link to the page of Subgraph we created, which is deployed to The Graph’s hosting service and at the moment is probably indexed by it.

Author: Leopold #8689.

Translated by: Blump#9066.

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
ilya

ilya

I only write about what I’m really interested in