Tracking token total supply over millions of blocks: A guide to creating a subgraph and deploying to Chainstack
TLDR
- Demonstrates how to track a token’s total supply by capturing mint and burn events (transfers from/to the zero address) via a subgraph.
- Provides the configuration for subgraph manifest, schema, and mapping code to record each total supply change at the block level.
- Uses The Graph protocol on Chainstack Subgraphs for indexing large block ranges efficiently.
- Includes instructions for building, deploying, and querying the subgraph for historical total supply data.
Main article
In the evolving landscape of blockchain and cryptocurrency, tracking and analyzing data is crucial. One of the most insightful data points for ERC20 tokens is the total supply, which reflects the number of tokens in circulation. The Graph protocol offers an efficient way to query this data through a tool known as a “subgraph”. In this article, we will guide you through creating a subgraph that tracks and saves the totalSupply
of a specific token (e.g., USDT token on Ethereum - 0xdac17f958d2ee523a2206206994597c13d831ec7) over a million blocks.
Getting started with subgraph development
Setting up your environment
The first step in creating a subgraph is to set up your development environment. This involves installing the Graph CLI. Open your terminal and execute:
Initializing your subgraph
Once the Graph CLI is installed, you can initialize your subgraph project with the following command:
Answer the questions from the cli the following way:
The command line utility will create a subgraph template project for you. Here we’ve chosen the start block as a block of the smart contract deployment.
Crafting the subgraph manifest
The heart of your subgraph is the manifest file, named subgraph.yaml
. This file defines the data sources and how your subgraph interacts with the blockchain. For tracking an ERC20 token’s totalSupply
, your manifest file would be structured as follows:
Defining the GraphQL schema
Your subgraph will store and query data according to a GraphQL schema. In our case, the schema (schema.graphql
) for the total supply might look like this:
Implementing the mapping logic
The mapping file (mapping.ts
) contains the logic for processing blockchain events. Here’s an example of how you might handle Transfer
events to update the total supply:
Here we process each Transfer event and filtering by the transfers with zero address as a sender or receiver because these actions are related to mints and burns changing the actual total supply of the token.
Building and deploying your subgraph
After setting up these files, you can build and deploy your subgraph with the following commands.
Replace <ACCESS_TOKEN>
with your access token from Chainstack Subgraphs hosting. Also before this action you need to add a subgraph via the platform UI.
Querying the subgraph for the token total supply over a range of blocks
Once your subgraph is deployed and running, querying the data it indexes becomes a crucial part of extracting meaningful insights. Specifically, if you’re interested in analyzing the totalSupply
of a token over a range of blocks, you’ll utilize the Graph QL API provided by The Graph Protocol. This section will guide you through the process of querying your subgraph to retrieve totalSupply
data across a specified block range.
Understanding the query structure
To query a subgraph, you can choose from either of the following Subgraph query options in the subgraph details page:
- Query URL — use this URL to query in the CLI.
- GraphQL UI URL — use this URL to query in the GraphQL UI.
GraphQL queries are structured to allow you to request exactly what you need. In the context of our subgraph, we are interested in fetching the totalSupply
along with the blockNumber
for a range of blocks. The basic structure of such a query would be:
The response of the GraphQL interface will look like
So that one can see the totalSupplies for each block where it has been changed.
Conclusion
Creating a subgraph with Chainstack Subgraphs is a powerful way to access and analyze blockchain data efficiently. By following the steps outlined in this guide, you can track the total supply of an ERC20 token over a vast number of blocks, unlocking valuable insights into its distribution and circulation. This is just the beginning; the potential applications of subgraphs in blockchain data analysis are vast and varied, limited only by your imagination and the specifics of your project.
Tutorials you may like
This is a tutorials collection that will help you to use your subgraphs to the fullest. Before you start, make sure you learn the basics of Chainstack Subgraphs.
Explore how you can interact with subgraphs by following our series: