Token Subgraph Project

This project is a subgraph designed to index and query information about an ERC-20 token, including token holders, transfers, balance changes, and overall token metrics like total supply and volume. It uses The Graph to provide efficient data retrieval for on-chain token activity.

---

Features

• Holder Information:

  • Tracks token holders, their balances, and historical balance changes.

• Token Metrics:

  • Provides the total supply and the total volume of tokens transferred.

• Transfer Data:

  • Records all token transfers, including sender, receiver, value, timestamp, and transaction hash.

• Historical Data:

  • Captures balance changes and allows querying over specific time periods.

---

Technologies Used

• The Graph: Subgraph framework for indexing and querying blockchain data.
• GraphQL: Used for querying indexed data.
• AssemblyScript: For writing mapping functions.
• Ethereum: The blockchain network providing the data.

---

Schema

The following entities are indexed in the subgraph:

1. Holder

Represents a token holder.

type Holder @entity {
  id: ID!                  # Address of the token holder
  balance: BigInt!         # Current balance of the holder
  sentTransfers: [Transfer!]! @derivedFrom(field: "from") # Transfers sent by this holder
  receivedTransfers: [Transfer!]! @derivedFrom(field: "to") # Transfers received by this holder
  balanceChanges: [BalanceChange!]! @derivedFrom(field: "holder") # Historical balance changes
}

2. Transfer

Represents a single token transfer.

type Transfer @entity {
  id: ID!
  from: Holder!          # Sender address
  to: Holder!            # Receiver address
  value: BigInt!         # Token amount transferred
  timestamp: BigInt!     # Block timestamp
  transactionHash: String! # Transaction hash
}

3. Token

Represents the token and its overall metrics.

type Token @entity {
  id: ID!                # Token contract address
  totalSupply: BigInt!   # Total supply of the token
  volume: BigInt!        # Total volume of tokens transferred
  holders: [Holder!]     # List of unique holders
}

4. BalanceChange

Represents a balance change for a holder.

type BalanceChange @entity {
  id: ID!
  holder: Holder!
  balance: BigInt!
  timestamp: BigInt!
}

---

Setup Instructions

1. Prerequisites

• Node.js (v16+)
• Yarn (v1.22+)
• The Graph CLI (@graphprotocol/graph-cli)

Install The Graph CLI globally:

yarn global add @graphprotocol/graph-cli

2. Clone the Repository

git clone <repository-url>
cd <repository-folder>

3. Install Dependencies

yarn install

4. Generate Types

Run the following command to generate TypeScript types for the smart contract and schema:

graph codegen

5. Build the Subgraph

Compile the subgraph mappings:

graph build

6. Deploy the Subgraph

Deploy the subgraph to The Graph Hosted Service or Subgraph Studio:

graph deploy --studio <subgraph-name>

Replace <subgraph-name> with your desired subgraph name.

---

Queries

1. Fetch Token Data

Retrieve information about the token, including total supply and volume:

query {
  token(id: "1") {
    totalSupply
    volume
    holders {
      id
      balance
    }
  }
}

2. Fetch Transfers

Retrieve recent token transfers:

query {
  transfers(first: 10, orderBy: timestamp, orderDirection: desc) {
    id
    from {
      id
    }
    to {
      id
    }
    value
    timestamp
  }
}

3. Fetch Balance Changes for a Holder

Retrieve the historical balance changes for a specific holder:

query GetBalanceChanges($id: ID!) {
  holder(id: $id) {
    balanceChanges(orderBy: timestamp, orderDirection: asc) {
      balance
      timestamp
    }
  }
}

---

File Structure

.
├── abis/                   # ABI files for the token contract
│   └── Token.json
├── generated/              # Auto-generated files (after codegen)
├── src/                    # Mapping functions
│   └── mapping.ts          # Business logic for handling events
├── schema.graphql          # GraphQL schema for entities
├── subgraph.yaml           # Subgraph manifest file
└── package.json            # Project dependencies and scripts

---

Deployment Notes

1. Smart Contract Address: Update the address field in subgraph.yaml with your token contract address.

2. Start Block: Set the startBlock field in subgraph.yaml to the block number where the token contract was deployed.

---

Future Enhancements

• Add support for multiple tokens.
• Include event handlers for Approval events.
• Index additional metrics such as staking or liquidity data.

---

Support

If you encounter issues, feel free to open an issue on the repository or contact the project maintainers.

---

License

This project is licensed under the MIT License. See LICENSE for details.