Debugging Subgraphs with a local Graph node

• Learn how to run a local Graph Node using Docker Compose to debug subgraphs more thoroughly.
• Understand how to identify and fix errors by inspecting logs, adjusting schema requirements, and verifying entity data storage.
• Configure log levels in both local environments and Chainstack Subgraphs to pinpoint issues and streamline the debugging process.
• Finally, deploy your corrected subgraph to Chainstack Subgraphs for ongoing data indexing without disruptions.

​

Introduction

​

Before we begin

• This tutorial isn’t a beginner-friendly introduction to subgraph development. If you have never created a subgraph before, we have a beginner’s guide to subgraph development on our docs.
• In my experience, it is really difficult to manually spin up a Graph Node with Cargo, IPFS, and Postgres. You need to install a whole bunch of dependencies, and even then the source code may not compile due to OS-specific package dependency issues. If you want to try your hand at setting up a local Graph Node without Docker, you can refer to the repo’s README file.
• The author of this post, however, recommends you save yourselves a whole lot of hair-scratching and head-banging by setting up Docker on your machine. Docker is a tool that allows you to develop your applications in an isolated environment called a container. These containers can be replicated across different machines, ensuring a consistent and easy-to-set-up dev environment.
• Docker Compose, more specifically, can spin up a multi-container dev environment from a single YAML file that contains all the required configuration data.
• Before moving on with the tutorial, you need to install Docker Engine, Docker Desktop, and Docker Compose. This might seem tedious at first, but it will save you a lot of time and effort in the long run. With Docker set up, you don’t need to worry if a particular application isn’t well-suited to run on your OS.

​

What will we be doing?

1. Create a buggy subgraph.
2. Spin up a local Graph Node using Docker Compose.
3. Deploy a buggy subgraph on the said node and check for data availability.
4. Configure the environment variables in the YAML configuration file to tweak the exact data that is logged by our local node to check for errors.
5. Finally, deploy the debugged subgraph to Chainstack Subgraphs for long-term indexing.

​

Creating our subgraph

1. Install graph-cli on your machine.
2. Create a new directory and initialize a project in it by running:
   Copy

   graph init
   

3. Set up a subgraph with the following parameters:
   Copy

   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
   

4. Paste the following code in schema.graphql:
   Copy

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

   Explaining schema.graphql:
   • The Transfer entity will index data every time a Bored Ape NFT is transferred. It will log the transaction data, as well as the recipient and receiver addresses.
   • The BoredApe entity will index all the major information about an ape, including the original creator and the current owner.
   • The Property entity will index the IPFS metadata for all the apes. Each instance of this entity can be identified using the id field, which is nothing but the tokenID of the ape.
5. Delete everything inside subgraph.yaml, and paste the following code:
   Copy

   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
   

   Explaining subgraph.yaml:
   • In here, we declared the data source (address of the BAYC smart contract), the entities we want to index, and the events we want to look out for. For our use case, tracking the Transfer event from the smart contract will suffice.
   • For subgraphs that want to index IPFS data, ipfsOnEthereumContracts must be declared under features.
6. Run graph codegen in your terminal. You must run this command every time you edit the schema or YAML file.
7. Go to src/bayc.ts and delete everything inside it. Paste the following code:
   Copy

   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 {
   
     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()
   
     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();
   
     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;
   
       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;
                   }
   
                 }
   
               }
   
             }
   
           }
   
         }
       }
   
     }
   
   }
   

   Explaining src/bayc.ts:
   • We write the mapping logic for our entities under the handleTransfer function. This function will be automatically triggered every time the Transfer event is triggered in the BAYC smart contract. We configured this behavior inside the YAML file by creating the event-handler pair.
   • We get the data points we need for the Transfer and BoredApe entities straight from the logs emitted by the smart contract.
   • To index IPFS metadata, however, we use the [ipfs.cat](http://ipfs.cat) method from the graph-ts library by passing it the IPFS hash and the token URI for a specific ape.
   • We need to include a null check at every step while parsing the IPFS metadata, since an IPFS node may be unavailable at a given time, or the data we are querying may not exist at all.

​

Running a local Graph Node

1. If you have Docker and Docker Compose installed on your machine, the easiest way to set up a Graph Node locally:
   Copy

   git clone https://github.com/pranavdaa/Graph-Node-Local.git
   

   This will clone a repo onto your machine that just contains the YAML configuration file we need. Make sure that Docker Desktop is running on your machine.
2. Open the cloned directory, and then the docker-compose.yaml file in a code editor. Even the old and rusty Notepad++ will do. Docker will download the required dependencies using official images uploaded to it. Go to the image under IPFS, and change the line to the following:
   Copy

   image: ipfs/go-ipfs:v0.17.0
   

   This will result in Docker fetching a relatively recent version of IPFS. You can always check Docker hub for the latest available versions of an image. You can also skip specifying a particular version if you wish to work with the latest available versions.
3. To index subgraphs that index IPFS data using the .cat method, we need to configure an extra environment variable. Inside the environment object, add an environment variable like this:
   Copy

   GRAPH_ALLOW_NON_DETERMINISTIC_IPFS: 1
   

4. Lastly, we need to pass an RPC URL for an Ethereum archive mainnet node to the YAML file. You can set up an archive node using Chainstack. If you don’t know how to set up a node with Chainstack, refer to our blog. Edit the ethereum environment variable like this:
   Copy

   ethereum: 'mainnet:YOUR_CHAINSTACK_ENDPOINT'
   

5. Save the YAML file. Open a new terminal inside the cloned repo, and run:
   Copy

   docker-compose up
   

​

Deploying to a local Graph Node

1. Open a new terminal at the root of the subgraph project. To compile your subgraph, run:
   Copy

   graph codegen && graph build
   

2. To deploy your subgraph to the local Graph Node, run the following command by passing any random version number to the terminal:
   Copy

   npm run create-local && npm run deploy-local
   

​

First debugging iteration

1. Open the UI URL in your browser. For me, it is http://localhost:8000/subgraphs/name/BAYC/graphql. This URL may be different for you.
2. Run the following query in the interface:
   Copy

   {
     transfers(first:3) {
       id
       tokenId
       from
       to
       blockNumber
     }
     boredApes(first:3) {
       id
       creator
       newOwner
       tokenURI
       blockNumber
     }
     properties(first:3) {
       id
       image
       background
       clothes
       eyes
       fur
       mouth
       earring
       hat
     }
   }
   

1. Go to the terminal in your subgraph’s directory, and run:
   Copy

   npm run remove-local
   

   This command will remove the buggy subgraph from your node’s data store.
2. Go to the terminal running the local node, and stop the terminal (ctrl+c on my system, may be different on yours).
3. Go to src/bayc.ts in your subgraph code, and add this line to the file right before we invoke the ipfs.cat() method:
   Copy

   log.info('The fullURI is: {} ', [fullURI]);
   

4. Save the file.
5. Restart the Docker container using docker-compose up and re-deploy to the local node from the subgraph’s directory.

​

Second debugging iteration

property.save()

​

Third debugging iteration

Entity Property[0]: missing value for non-nullable field `hat`

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

{
  properties{
    id
    image
    background
    clothes
    eyes
    fur
    mouth
    earring
    hat
  }
}

​

Conclusion

​

About the author

Priyank Gupta

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