> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainstack.com/llms.txt
> Use this file to discover all available pages before exploring further.
## Submitting Feedback
If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:
POST https://docs.chainstack.com/feedback
```json
{
"path": "/docs/tracking-token-total-supply-over-millions-of-blocks-a-guide-to-creating-a-subgraph-and-deploying-to-chainstack",
"feedback": "Description of the issue"
}
```
Only submit feedback when you have something specific and actionable to report.
# Track token supply with subgraphs on Chainstack
> Track ERC-20 token total supply across millions of blocks with subgraphs. Index mint/burn events, deploy to Chainstack, and query historical data efficiently.
**Chainstack Subgraphs is transitioning to Ormi**
Chainstack is sunsetting its Subgraphs service and partnering with [Ormi](https://ormilabs.com/), a next-generation subgraph indexer built for real-time production workloads, to support existing subgraphs. Your data and schemas remain unchanged—your only action is to swap the endpoint.
* No new subgraphs after January 5, 2026
* Service disabled on February 1, 2026
* Ormi provides one free month (Feb 1 – March 1, 2026)
For migration assistance, join the dedicated Telegram support group (check your email for the invitation).
See the [Ormi–Chainstack transition guide](https://docs.ormilabs.com/subgraphs/tutorials/migrate-chainstack-subgraphs) for full details.
**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](https://etherscan.io/address/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:
```bash Bash theme={"system"}
npm install -g @graphprotocol/graph-cli
```
### **Initializing your subgraph**
Once the Graph CLI is installed, you can initialize your subgraph project with the following command:
```bash Bash theme={"system"}
graph init --allow-simple-name
```
Answer the questions from the cli the following way:
```bash Bash theme={"system"}
✔ Protocol · ethereum
✔ Product for which to initialize · hosted-service
✔ Subgraph name · erc20_historical_total_supply
✔ Directory to create the subgraph in · erc20_historical_total_supply
? Ethereum network …
✔ Ethereum network · mainnet
✔ Contract address · 0xdac17f958d2ee523a2206206994597c13d831ec7
✔ Fetching ABI from Etherscan
✖ Failed to fetch Start Block: Failed to fetch contract creation transaction hash
✔ Start Block · 4634747
✔ Contract Name · Contract
✔ Index contract events as entities (Y/n) · true
```
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:
```yaml YAML theme={"system"}
specVersion: 0.0.5
schema:
file: ./schema.graphql
dataSources:
- kind: ethereum
name: Contract
network: mainnet
source:
address: "0xdac17f958d2ee523a2206206994597c13d831ec7"
abi: Contract
startBlock: 17640663
mapping:
kind: ethereum/events
apiVersion: 0.0.7
language: wasm/assemblyscript
entities:
- TotalSupply
abis:
- name: Contract
file: ./abis/Contract.json
eventHandlers:
- event: Transfer(indexed address,indexed address,uint256)
handler: handleTransfer
file: ./src/contract.ts
```
## **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:
```graphql GraphQL theme={"system"}
type TotalSupply @entity(immutable: true) {
id: Bytes!
value: BigInt!
blockNumber: BigInt!
}
```
## **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:
```tsx tsx theme={"system"}
import { Transfer } from "../generated/Contract/Contract"
import { TotalSupply } from "../generated/schema"
import { BigInt, Address } from "@graphprotocol/graph-ts"
import { Contract } from "../generated/Contract/Contract"
export function handleTransfer(event: Transfer): void {
let zeroAddress = Address.fromString("0x0000000000000000000000000000000000000000")
if (event.params.from.equals(zeroAddress) || event.params.to.equals(zeroAddress)) {
let totalSupply = new TotalSupply(event.transaction.hash.concatI32(event.logIndex.toI32()))
let contract = Contract.bind(event.address)
let totalSupplyResult = contract.try_totalSupply()
if (!totalSupplyResult.reverted) {
totalSupply.value = totalSupplyResult.value
totalSupply.blockNumber = event.block.number
totalSupply.save()
}
}
}
```
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.
```bash Bash theme={"system"}
graph codegen
graph build
graph deploy --node https://api.graph-ams.p2pify.com/940a577dc77637743ce420baed763b62/deploy --ipfs https://api.graph-ams.p2pify.com/940a577dc77637743ce420baed763b62/ipfs erc20_subgraph
```
Replace **``** 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:
```bash Bash theme={"system"}
{
totalSupplies(
orderBy: blockNumber,
orderDirection: desc
) {
value
blockNumber
}
}
```
The response of the GraphQL interface will look like
```bash Bash theme={"system"}
{
"data": {
"totalSupplies": [
{
"value": "60109970000000",
"blockNumber": "5747917"
},
{
"value": "60109502104300",
"blockNumber": "5839244"
},
{
"value": "60109502104300",
"blockNumber": "5869105"
},
{
"value": "60109502104300",
"blockNumber": "6125686"
},
{
"value": "60109502104300",
"blockNumber": "6906187"
},
{
"value": "60109502104300",
"blockNumber": "6941942"
}
]
}
}
```
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](/docs/subgraphs-introduction).
Explore how you can interact with subgraphs by following our series:
### About the author
Product Lead @ Chainstack
BUIDLs on Ethereum and Graph protocol
Majored in Data Science and Product Management