Skip to main content

The Graph

Introductionโ€‹

The Graph is an indexing service which collects Ethereum events and exports them through GraphQL endpoints. It is widely used in the Ethereum ecosystem which supports fast and cheap queries for DApps.

This tutorial covers the following topics:

  • Running a Graph node on Aurora.
  • Creating and deploying a subgraph.
  • Querying events from the subgraph.

Prerequisitesโ€‹

Before delving into the tutorial, you need to make sure that you have setup the following tools on you machine:

Running Graph Nodeโ€‹

Cloneโ€‹

Clone the graph node source code

git clone https://github.com/graphprotocol/graph-node.git
cd graph-node

Configureโ€‹

In order wire your local graph node with Aurora Testnet RPC, you should change the value of ethereum section in docker/docker-compose.yaml file from mainnet:http://host.docker.internal:8545 to 'aurora:https://testnet.aurora.dev'.

....
environment:
postgres_host: postgres
postgres_user: graph-node
postgres_pass: let-me-in
postgres_db: graph-node
ipfs: 'ipfs:5001'
ethereum: 'aurora:https://testnet.aurora.dev'
GRAPH_LOG: info
...

Startโ€‹

The following commands will setup the environment and start the graph indexer. The indexing process might take long time to have 100% sync with the chain. This has nothing to do with our tutorial but keep this process running in a separate terminal.

cd graph-node/docker
./setup.sh
docker-compose up

Create a subgraphโ€‹

Now we are done with starting our graph node, the next step is to create and deploy a subgraph. The subgraph defines how the data on Ethereum will be indexed and stored on the graph node.

In this tutorial, we are going to use the subgraph example called GravatarRegistry (a simple on-chain Gravatar). The GravatarRegistry contract has two events:

event NewGravatar(uint id, address owner, string displayName, string imageUrl);
event UpdatedGravatar(uint id, address owner, string displayName, string imageUrl);

The contract was already deployed on Aurora Testnet. The deployed GravatarRegistry contract address is 0x8773e6832f44b2C17AC78592ffCe407C62d8c36E and the start block number is 74885768.

Clone subgraphโ€‹

Clone subgraph example repo.

git clone https://github.com/aurora-is-near/example-subgraph.git
cd example-subgraph

Installโ€‹

yarn install

Configure the Subgraphโ€‹

Update the address and (the startBlock optional) in subgraph.yaml as follows:

    ...
network: aurora
source:
address: '0x8773e6832f44b2C17AC78592ffCe407C62d8c36E'
abi: Gravity
startBlock: 74885768
...

Also make sure you are pointing into aurora as a network.

Generating typesโ€‹

yarn codegen
Skip migration: Bump mapping apiVersion from 0.0.1 to 0.0.2
Skip migration: Bump mapping apiVersion from 0.0.2 to 0.0.3
Skip migration: Bump mapping apiVersion from 0.0.3 to 0.0.4
Skip migration: Bump mapping apiVersion from 0.0.4 to 0.0.5
Skip migration: Bump mapping specVersion from 0.0.1 to 0.0.2
โœ” Apply migrations
โš  Warnings while loading subgraph from subgraph.yaml: Warnings in subgraph.yaml:

Path: repository
The repository is still set to https://github.com/graphprotocol/example-subgraph.
Please replace it with a link to your subgraph source code.

Path: description
The description is still the one from the example subgraph.
Please update it to tell users more about your subgraph.

โœ” Load subgraph from subgraph.yaml
Load contract ABI from abis/Gravity.json
โœ” Load contract ABIs
Generate types for contract ABI: Gravity (abis/Gravity.json)
Write types to generated/Gravity/Gravity.ts
โœ” Generate types for contract ABIs
โœ” Generate types for data source templates
โœ” Load data source template ABIs
โœ” Generate types for data source template ABIs
โœ” Load GraphQL schema from schema.graphql
Write types to generated/schema.ts
โœ” Generate types for GraphQL schema

Types generated successfully

โœจ Done in 3.38s.

Mappingsโ€‹

Maps Ethereum event data to the data that has been defined in the schema.graphql. For example handleNewGravatar parses the new event parameters, and save them in gravatar.

export function handleNewGravatar(event: NewGravatar): void {
let gravatar = new Gravatar(event.params.id.toHex())
gravatar.owner = event.params.owner
gravatar.displayName = event.params.displayName
gravatar.imageUrl = event.params.imageUrl
gravatar.save()
}

Deploy the Subgraphโ€‹

First, we need to register the subgraph name on the graph node. To do that run yarn create-local.

$ yarn create-local
Created subgraph: example
โœจ Done in 2.12s.

Once the subgraph is registered, now you can deploy it by executing the following command:

$ yarn deploy-local
โœ” Version Label (e.g. v0.0.1) ยท
Skip migration: Bump mapping apiVersion from 0.0.1 to 0.0.2
Skip migration: Bump mapping apiVersion from 0.0.2 to 0.0.3
Skip migration: Bump mapping apiVersion from 0.0.3 to 0.0.4
Skip migration: Bump mapping apiVersion from 0.0.4 to 0.0.5
Skip migration: Bump mapping specVersion from 0.0.1 to 0.0.2
โœ” Apply migrations
โš  Warnings loading subgraph from subgraph.yaml: Warnings in subgraph.yaml:

Path: repository
The repository is still set to https://github.com/graphprotocol/example-subgraph.
Please replace it with a link to your subgraph source code.

Path: description
The description is still the one from the example subgraph.
Please update it to tell users more about your subgraph.

โœ” Load subgraph from subgraph.yaml
Compile data source: Gravity => build/Gravity/Gravity.wasm
โœ” Compile subgraph
Copy schema file build/schema.graphql
Write subgraph file build/Gravity/abis/Gravity.json
Write subgraph manifest build/subgraph.yaml
โœ” Write compiled subgraph to build/
Add file to IPFS build/schema.graphql
.. QmbSFRGGvHM7Cn8YSjDL41diDMxN4LQUDEMqaa5VVc5sC4
Add file to IPFS build/Gravity/abis/Gravity.json
.. QmajZTadknSpgsCWRz9fG6bXFHdpVXPMWpx9yMipz3VtMQ
Add file to IPFS build/Gravity/Gravity.wasm
.. QmbK8QL1GWmsdTsgFYawvxFCjLEFwBsPjMGWpeRh6yaXEk
โœ” Upload subgraph to IPFS

Build completed: QmUiu7NRW7Lc89rxfacqUViaFLYwftrGUn54segMFgWggu

Deployed to http://127.0.0.1:8000/subgraphs/name/example/graphql

Subgraph endpoints:
Queries (HTTP): http://127.0.0.1:8000/subgraphs/name/example
Subscriptions (WS): http://127.0.0.1:8001/subgraphs/name/example

โœจ Done in 10.23s.

Now, you should be able to access your subgraph endpoint through http://127.0.0.1:8000/subgraphs/name/example.

Publish Events (optional)โ€‹

There were already published events starting from block number 74885768, So you can skip this step.

Query Eventsโ€‹

To query events, TheGraph protocol provides a GraphQL endpoint for your local graph node. Go to http://127.0.0.1:8000/subgraphs/name/example, it automatically will show up a predefined GraphQL query. Run this query to get the results as shown below:

image

Summaryโ€‹

In this tutorial, we started a Graph node locally, then we wired our node to Aurora Testnet RPC. We also configured a subgraph example and deployed that subgraph on our local graph node. Finally the graph node was able to collect and index the subgraph example (GravatarRegistry) events from Aurora Testnet.