A beginner’s guide to getting started with The Graph

• The Graph is used to index and query blockchain data with a custom GraphQL API, making retrieval of on-chain data more efficient.
• In this tutorial, we create a subgraph for the Bored Ape NFT contract and fetch IPFS-based metadata alongside ownership data.
• We define schema entities (e.g. Transfer, BoredApe, Property), map them via AssemblyScript to on-chain events, and handle mint or transfer events to store relevant NFT and metadata details.
• Deploying the subgraph (e.g. on Chainstack Subgraphs) gives a powerful, real-time GraphQL endpoint for querying historical NFT data, including IPFS metadata.

​

Introduction

​

What is The Graph

​

Indexing blockchain data

​

The Graph network

1. The Graph’s hosted service. The hosted service is The Graph protocol’s centralized solution for hosting subgraphs. Hosted service supports a multitude of different blockchains. However, The Graph will disable this service entirely in the future.
2. Subgraph Studio. The Graph allows you to publish subgraphs on the decentralized graph network. This network however only supports the Ethereum Mainnet for now. Furthermore, to publish and maintain your subgraphs on the studio, you need to be well-versed in the tokenomics of the Graph network, which is split into many different roles like indexers, delegators, and curators. You can read about these roles in more detail on The Graph’s docs.
3. Chainstack Subgraphs. Chainstack Subgraphs is a super-fast, production-level solution to deploy your subgraphs that you can use without having to go through the hassle of staking, delegating, and/or incentivizing the indexing of your subgraph. With Chainstack, you can be assured of fast indexing and consistent availability of data.

​

Setting up a subgraph project on your machine

​

Installing the Graph CLI

npm install -g @graphprotocol/graph-cli

graph

​

Creating a subgraph project

graph init

Protocol: Ethereum
Product for which to initialize: subgraph-studio
Subgraph Slug: BAYC
Directory to create the subgraph in: ChainstackSubgraph
Ethereum network: mainnet
Contract address: 0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D
Contract Name: BAYC
Index contract events as entities: true

1. We initialize a new subgraph project using graph init, but to do that we need to pass it a bunch of parameters.
2. The network and the contract address are the two main configurations to take note of. The Graph protocol supports a number of different chains, but the Bored Ape smart contract is deployed on the Ethereum Mainnet. Hence, we choose ‘mainnet’ as our network.
3. We need to pass the correct address to the CLI, since that is what is used to fetch the latest ABI for the smart contract we want to index.
4. When we choose to index the contract events as entities, The Graph automatically tries to generate some helper code for us. We will go into more detail on this below.

​

Understanding the project layout

• The manifest file. The subgraph.yaml at the root defines all the major parameters of a subgraph project. It contains a list of all the smart contracts being indexed, as well as a list of entities and their corresponding handler functions. We will be adding more properties like startBlock and description to the YAML file in the tutorial. You can read about all the specifications in detail in the Graph docs, though that is not necessary to go through this tutorial.
• The schema file. At its core, a subgraph is a GraphQL API that indexes data from the blockchain. It is important to understand the difference between a REST API and a GraphQL API. You can watch this video for a brief explanation. The schema.graphql file at the root of our project contains all our entities. These entities define what data our subgraph indexes. Here is what an entity could look like:
  schema.graphql

  Copy

  type BoredApe @entity {
    id: ID!
    creator: Bytes!
    newOwner: Bytes!
    tokenURI: String!
    blockNumber: BigInt!
  }
  

• The mappings file. A mappings file contains functions that take the data from a blockchain, and convert it into manageable data along the lines of our GraphQL entities. It is written in AssemblyScript, which is a TypeScript-like language with a stricter syntax. This file contains the logic that dictates how data should be retrieved and stored when someone interacts with the smart contracts we intend to index. The Graph CLI creates a mapping file by default inside the src folder. If you followed the instructions above, you should see a file named bayc.ts inside the src folder.

​

Indexing data from events in subgraphs

• Event handlers run whenever a specific event is triggered.
• Call handlers run when a specific function is called by an account other than the contract itself.
• Block handlers run every time a new block is added to the chain, although it is possible to define filters such that the handler function runs only if the new block fulfills certain criteria.

​

Configuring subgraph.yaml

​

Entities and event handlers

specVersion: 0.0.5
description: A subgraph to index data on the Bored Apes contract
features:
  - ipfsOnEthereumContracts
schema:
  file: ./schema.graphql
dataSources:
  - kind: ethereum
    name: BAYC
    network: mainnet
    source:
      address: "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D"
      abi: BAYC
      startBlock: 12287507
    mapping:
      kind: ethereum/events
      apiVersion: 0.0.7
      language: wasm/assemblyscript
      entities:
        - Transfer
        - BoredApe
        - Property
      abis:
        - name: BAYC
          file: ./abis/BAYC.json
      eventHandlers:
        - event: Transfer(indexed address,indexed address,indexed uint256)
          handler: handleTransfer
      file: ./src/bayc.ts

• We need to define event-handler pairs inside the eventHandlers object. In practice, what this means is that a function named handleTransfer will run every time an event named Transfer is triggered from the smart contract we are indexing. We are indexing the Bored Apes smart contract, and the transfer event is emitted every time a Bored Ape NFT is transferred from one address to another. You can check out the code on Etherscan.
• Recent versions of The Graph API require us to declare some features under the features object. Since we will be using The Graph’s IPFS API, we need to declare it as such within the features object.
• We will be defining three entities inside our schema file, and they too must be declared inside the subgraph manifest, within the entities object.

​

Start block

1. Go to the smart contract address on Etherscan.
2. Above the table, click the filter icon > View Contract Creation.

​

Defining schemas

type Transfer @entity(immutable: true) {
  id: Bytes!
  from: Bytes!
  to: Bytes!
  tokenId: BigInt!
  blockNumber: BigInt!
  transactionHash: Bytes!
}

type Transfer @entity(immutable: true) {
  id: Bytes!
  from: Bytes!
  to: Bytes!
  tokenId: BigInt!
  blockNumber: BigInt!
  transactionHash: Bytes!
}

event Transfer(address indexed from, address indexed to, uint256 indexed tokenId);

• This event is emitted whenever an NFT is transferred from one address to another. It logs the previous owner, the new owner, and the token ID of the NFT that was just transferred. We want the Transfer entity to store all of this data whenever the Transfer event is triggered so that we have a complete history of ownership for all the Bored Ape NFTs.
• Note that all Transfer events will have a unique transaction hash. Also, the id field needs to be unique for all instances of the Transfer entity. Thus, we can use the transaction hash of every transfer event to generate a unique ID every time.
• Also, since all instances of the Transfer entity will have unique IDs, we will never need to overwrite an existing instance of the Transfer entity. Thus, we should mark the entity as immutable. Entities marked immutable are faster to query, and should be marked as such unless we expect our entities to be overwritten with new values.

type BoredApe @entity {
  id: ID!
  creator: Bytes!
  newOwner: Bytes!
  tokenURI: String!
  blockNumber: BigInt!
}

• We want this entity to store some data about all the Bored Ape NFTs. We want to be able to query the creator, current owner, and tokenURI of an NFT from its tokenID, along with the block in which it last changed ownership.
• Each instance of the BoredApe entity will be distinguished by the tokenID, which we will use as the ID for the entity. Since an NFT can be transferred multiple times, the entity will have to be mutable to reflect this fact.
• But the Transfer event is emitted only when an ape is transferred from one address to another. How will we find out the creator of an NFT with its help?

function _mint(address to, uint256 tokenId) internal virtual {
  require (to != address (0),
  "ERC721: mint to the zero address");
  require(!_exists (tokenId), "ERC721: token already minted");
  _beforeTokenTransfer (address (0), to, tokenId) ;
  holderTokens [to].add(tokenId);
  tokenOwners. set (tokenId, to);
  emit Transfer(address (0), to, tokenId);
}

type Property @entity {
  id: ID!
  image: String
  background: String
  clothes: String
  earring: String
  eyes: String
  fur: String
  hat: String
  mouth: String
}

• The image object is an IPFS address that leads directly to the bored ape image.
• The attributes array is a list of properties, up to 7 properties in length. Check what a random ape with token ID 1065 looks like on Opensea.
• We want our Property entity to store valid values for all the attributes that actually have a value. We want it to store null for all the others.
• You might notice that, unlike the first two entities, most fields of the Property entity are not suffixed with an exclamation mark (!). This is because fields marked with an ! must have a valid value. They cannot be null. We, however, expect many of our NFTs to have multiple attributes with the value null. Moreover, sometimes an IPFS node is not available, and we might thus not receive a response at all. Thus, we must ensure that all fields that store our metadata can store null as a valid value.

type Transfer @entity(immutable: true) {
  id: Bytes!
  from: Bytes!
  to: Bytes!
  tokenId: BigInt!
  blockNumber: BigInt!
  transactionHash: Bytes!
}

type BoredApe @entity {
  id: ID!
  creator: Bytes!
  newOwner: Bytes!
  tokenURI: String!
  blockNumber: BigInt!
}

type Property @entity {
  id: ID!
  image: String
  background: String
  clothes: String
  earring: String
  eyes: String
  fur: String
  hat: String
  mouth: String
}

​

Mapping functions to schemas

graph codegen

• You must run this command every time after editing the schema or YAML file.
• The Graph will look into our entities and the events we want to index. Using the files and the ABI file, it will generate some classes for the entities and events in our subgraph in the generated directory. You should not change any files inside the generated directory, unless you know exactly what you are doing.

import {
  Transfer as TransferEvent,
  BAYC,
} from "../generated/BAYC/BAYC"
import {
  BoredApe,
  Transfer,
  Property
} from "../generated/schema"

import { ipfs, json, JSONValue, log } from '@graphprotocol/graph-ts'

• The generated directory has two files, schema.ts and BAYC.ts
• schema.ts contains AssemblyScript types generated from our schema file. We import AssemblyScript classes for our entities directly from this file.
• BAYC.ts contains AssemblyScript types generated from our contract ABI. The TransferEvent class allows us to work with the Transfer event from the smart contract, while the BAYC class is an abstraction of the smart contract itself. We can use this latter class to read data and call functions from the smart contract.

export function handleTransfer(event: TransferEvent): void {

}

• For each event handler that is defined in subgraph.yaml, we need to create an exported function of the same name in our mapping file. Each event handler should accept a parameter called event with a type corresponding to the name of the event which is being handled. In our case, we are handling the Transfer event.
• This function will trigger every time the Transfer event is emitted.
• The mapping function contains the logic that powers our API. This is where we manipulate blockchain data to index it according to our requirements.

let transfer = new Transfer(event.transaction.hash.concatI32(event.logIndex.toI32()))
  transfer.from = event.params.from
  transfer.to = event.params.to
  transfer.tokenId = event.params.tokenId
  transfer.blockNumber = event.block.number
  transfer.transactionHash = event.transaction.hash
  transfer.save()

• First, we create a new instance of the Transfer entity. We ensure that each instance of the Transfer entity has a unique ID by concatenating the transaction hash with the log index of the event. This is what will be returned as the id when we query the Transfer entity.
• The next three fields are available directly from the parameters of the Transfer event.
• event.block and event.transaction are part of the Ethereum API of the graph-ts library. You can refer to this page for a complete reference. We can leverage this library to get back all sorts of data.
• The store API, again part of the graph-ts library, gives us access to the save() method. Using this method, we can save new instances of the Transfer entity to our database.

let contractAddress = BAYC.bind(event.address);
let boredApe = BoredApe.load(event.params.tokenId.toString());

  if(boredApe==null){
  boredApe = new BoredApe(event.params.tokenId.toString());
  boredApe.creator=event.params.to;
  boredApe.tokenURI=contractAddress.tokenURI(event.params.tokenId);
  }

  boredApe.newOwner=event.params.to;
  boredApe.blockNumber=event.block.number;
  boredApe.save();

• The bind method allows us to access the address of the smart contract that emitted the event, which in our case is the address of the BAYC smart contract. This will come in handy later on.
• Recall that we use the token ID of an NFT as a unique identifier for every instance of the BoredApe entity. Let us say our subgraph comes across a Transfer event for a particular token ID. We can then use the load method to check if any instance of the BoredApe entity exists with that particular ID.
• If no instance with that ID exists, we create a new one. If we are encountering that token ID for the first time, then it means it has just been minted. We populate the creator field, and we get the token URI of the particular NFT by using the contractAddress object.
• Now every time that NFT is transferred, we will simply update the owner field and the blockNumber field. We don’t have to change the other fields because they will remain constant. After that, we save the entity to our database.

const ipfshash = "QmeSjSinHpPnmXmspMjwiXyN6zS4E9zccariGR3jxcaWtq"
  let tokenURI = "/" + event.params.tokenId.toString();
  log.debug('The tokenURI is: {} ', [tokenURI]);

  let property = Property.load(event.params.tokenId.toString());

  if (property == null) {
    property = new Property(event.params.tokenId.toString());

    let fullURI = ipfshash + tokenURI;
    log.debug('The fullURI is: {} ', [fullURI]);

    let ipfsData = ipfs.cat(fullURI);

    if (ipfsData) {
      let ipfsValues = json.fromBytes(ipfsData);
      let ipfsValuesObject = ipfsValues.toObject();

      if (ipfsValuesObject) {
        let image = ipfsValuesObject.get('image');
        let attributes = ipfsValuesObject.get('attributes');

        let attributeArray: JSONValue[];
        if (image) {
          property.image = image.toString();
        }
        if (attributes) {

          attributeArray = attributes.toArray();

          for (let i = 0; i < attributeArray.length; i++) {

            let attributeObject = attributeArray[i].toObject();

            let trait_type = attributeObject.get('trait_type');
            let value_type = attributeObject.get('value');

            let trait: string;
            let value: string;

            if (trait_type && value_type) {

              trait = trait_type.toString();
              value = value_type.toString();

              if (trait && value) {

                if (trait == "Background") {
                  property.background = value;
                }

                if (trait == "Clothes") {
                  property.clothes = value;
                }

                if (trait == "Earring") {
                  property.earring = value;
                }

                if (trait == "Eyes") {
                  property.eyes = value;
                }

                if (trait == "Fur") {
                  property.fur = value;
                }

                if (trait == "Hat") {
                  property.hat = value;
                }

                if (trait == "Mouth") {
                  property.mouth = value;
                }

              }

            }

          }

        }

      }
    }

  }

  property.save();

• You can get the main IPFS hash that stores all the metadata by calling the baseURI function on the bored apes smart contract.
• We only need to index all the IPFS metadata for a particular entity once. The handleTransfer function however will run every time the transfer event is emitted. Thus, we run the entire metadata indexing procedure only if that particular instance of the Property entity doesn’t exist.
• The .cat() method can be used to retrieve the entire metadata of an NFT by passing the complete IPFS hash path to it. Please note that you need to perform a null check at every step while querying IPFS data.
• We use The Graph’s JSON API to convert the retrieved data to a parable JSON object. We retrieve the image link and store it to the Property entity directly after converting it to a string.
• Lastly, we iterate through the entire attributes array to store those values to the respective fields. The attributes that don’t return a value will be marked null, since that is the default value.
• After everything is queried and indexed, we update our subgraph’s store again by calling the .save() method.

import {
  Transfer as TransferEvent,
  BAYC,
} from "../generated/BAYC/BAYC"
import {
  BoredApe,
  Transfer,
  Property
} from "../generated/schema"

import { ipfs, json, JSONValue, log } from '@graphprotocol/graph-ts'

export function handleTransfer(event: TransferEvent): void {

  //Here we write the handler code for the Transfer entity
  let transfer = new Transfer(event.transaction.hash.concatI32(event.logIndex.toI32()))
  transfer.from = event.params.from
  transfer.to = event.params.to
  transfer.tokenId = event.params.tokenId
  transfer.blockNumber = event.block.number
  transfer.transactionHash = event.transaction.hash
  transfer.save()
  //The transfer entity handler code ends here

  //Here we write the handler code for the BoredApe entity
  let contractAddress = BAYC.bind(event.address);

  let boredApe = BoredApe.load(event.params.tokenId.toString());
  if (boredApe == null) {
    boredApe = new BoredApe(event.params.tokenId.toString());
    boredApe.creator = event.params.to;
    boredApe.tokenURI = contractAddress.tokenURI(event.params.tokenId);
  }
  boredApe.newOwner = event.params.to;
  boredApe.blockNumber = event.block.number;
  boredApe.save();
  //The BoredApe entity handler code ends here

  //Here we write the handler code for the metadata

  const ipfshash = "QmeSjSinHpPnmXmspMjwiXyN6zS4E9zccariGR3jxcaWtq"
  let tokenURI = "/" + event.params.tokenId.toString();

  let property = Property.load(event.params.tokenId.toString());

  if (property == null) {
    property = new Property(event.params.tokenId.toString());

    let fullURI = ipfshash + tokenURI;
    log.debug('The fullURI is: {} ', [fullURI]);

    let ipfsData = ipfs.cat(fullURI);

    if (ipfsData) {
      let ipfsValues = json.fromBytes(ipfsData).toObject();

      if (ipfsValues) {
        let image = ipfsValues.get('image');
        let attributes = ipfsValues.get('attributes');

        let attributeArray: JSONValue[];
        if (image) {
          property.image = image.toString();
        }
        if (attributes) {

          attributeArray = attributes.toArray();

          for (let i = 0; i < attributeArray.length; i++) {

            let attributeObject = attributeArray[i].toObject();

            let trait_type = attributeObject.get('trait_type');
            let value_type = attributeObject.get('value');

            let trait: string;
            let value: string;

            if (trait_type && value_type) {

              trait = trait_type.toString();
              value = value_type.toString();

              if (trait && value) {

                if (trait == "Background") {
                  property.background = value;
                }

                if (trait == "Clothes") {
                  property.clothes = value;
                }

                if (trait == "Earring") {
                  property.earring = value;
                }

                if (trait == "Eyes") {
                  property.eyes = value;
                }

                if (trait == "Fur") {
                  property.fur = value;
                }

                if (trait == "Hat") {
                  property.hat = value;
                }

                if (trait == "Mouth") {
                  property.mouth = value;
                }

              }

            }

          }

        }

      }
    }

  }

  property.save();

  //The Metadata entity handler code ends here

}

graph build

​

Deploying the subgraph

1. Go to Chainstack and create a subgraph under your project.
2. Open your subgraph details in the console and scroll down till you see the subgraph deployment command.
3. Copy the command and run it in your terminal.

​

Querying subgraphs

​

Using the GraphQL UI URL

{
  transfers{
    id
    from
    to
    tokenId
    blockNumber
    transactionHash
  }
}

{
  transfers(orderBy: tokenId, orderDirection: asc){
    id
    from
    to
    tokenId
  }
}

{
  transfers(orderBy: tokenId,
    orderDirection: asc,
    where: {from: "0x0000000000000000000000000000000000000000"})
  {
    tokenId
    to
    transactionHash
  }
}

1. Fetches the complete transfer history of the NFT with token ID 1065.
2. Fetches the data and metadata for that NFT.

{
  transfers(where :{tokenId: "1065"}, orderBy:blockNumber, orderDirection:asc) {
    id
    tokenId
    from
    to
    blockNumber
  }
  boredApes(where :{id: "1065"}) {
    id
    creator
    newOwner
    tokenURI
    blockNumber
  }
  properties(where:{id: "1065"}) {
    id
    image
    background
    clothes
    eyes
    fur
    mouth
    earring
    hat
  }
}

​

Using the query URL

curl --version

curl -g \-X POST \-H "Content-Type: application/json" \-d '{"query":"{transfers(orderBy: tokenId,orderDirection: asc,first:5){tokenId to transactionHash}}"}' \<YOUR_QUERY_URL>

​

Conclusion

​

About the author

Priyank Gupta

Developer Advocate @ Chainstack BUIDLs on Ethereum, zkEVMs, The Graph protocol, and IPFS Part-time Rust aficionado