使用 Subgraph 获取 ERC20 代币持有人列表教程

GraphQL 是一种用于 API 的查询语言，Subgraph 是一种使用 GraphQL 构建的分布式 API 方式。在 Subgraph 中，我们可以定义数据模型和查询方法，并且 Subgraph 会自动处理数据的存储和访问。在本教程中，我们将学习如何使用 Subgraph 获取 ERC20 代币的持有人列表。

创建 Subgraph 项目

首先，我们需要创建一个 Subgraph 项目。我们可以使用 Graph CLI 工具来创建项目。

graph create <subgraph-name>

例如：

graph create demo-subgraph

定义数据模型

在 Subgraph 中，我们需要定义数据模型。我们将使用 ERC20 代币的标准数据模型，其中包含代币的符号、名称、总供应量和持有人地址。

定义数据模型的方式是编写 GraphQL schema。在 Subgraph 项目中，我们可以在 schema.graphql 文件中定义数据模型。以下是 ERC20 代币的数据模型：

type Token @entity {
  id: ID!
  symbol: String!
  name: String!
  totalSupply: BigInt!
  holders: [Address!]! @derivedFrom(field: 'token')
}

type Address @entity {
  id: ID!
  holdings: [TokenHolding!]!
}

type TokenHolding @entity {
  id: ID!
  token: Token!
  address: Address!
  balance: BigInt!
}

在这个数据模型中，我们定义了三个实体类型：Token、Address 和 TokenHolding。Token 实体表示代币本身，Address 实体表示代币的持有人地址，TokenHolding 实体表示持有人的代币余额。我们使用 @entity 指令告诉 Subgraph，这些类型是实体类型，需要进行数据存储和查询。

我们在 Token 类型中定义了一个 holders 字段，这个字段是一个 Address 类型的数组，表示持有该代币的地址列表。我们使用 @derivedFrom 指令告诉 Subgraph，这个字段是从 TokenHolding 实体中派生出来的，Subgraph 会自动处理这个字段的查询。

定义查询方法

在 Subgraph 中，我们可以定义查询方法来获取数据。查询方法的方式也是编写 GraphQL schema。我们将定义一个 getHodlers 查询方法来获取 ERC20 代币的持有人列表。

在 schema.graphql 文件中添加以下查询方法：

type Query {
  getHodlers(token: String!, first: Int!, skip: Int!): [Address!]!
}

这个查询方法接受三个参数：token、first 和 skip。token 参数是代币的符号，first 参数是要查询的第一个结果的数量，skip 参数是要跳过的结果数量。我们将使用这些参数来实现分页查询。

实现查询方法

现在我们需要实现 getHodlers 查询方法。在 Subgraph 中，我们可以使用 AssemblyScript 编写查询方法的实现。AssemblyScript 是一种与 TypeScript 类似的语言，可以编译为 WebAssembly 代码，可以在 Subgraph 中运行。

在 Subgraph 项目中创建一个 src 目录，并在其中创建一个 assembly 文件夹。在 assembly 文件夹中创建一个文件 getHodlers.ts，这个文件将包含 getHodlers 查询方法的实现。

在 getHodlers.ts 文件中添加以下代码：

import { Address, BigInt } from '@graphprotocol/graph-ts';
import { Token, TokenHolding } from '../generated/schema';

export function getHodlers(token: String, first: i32, skip: i32): Address[] {
  let tokenEntity = Token.load(token); // 获取代币实体
  let holdings = TokenHolding.query()
    .filter('token', token)
    .orderBy('balance', 'desc')
    .skip(skip)
    .take(first)
    .find(); // 查询代币持有人列表

  let hodlers: Address[] = [];
  for (let i = 0; i < holdings.length; i++) {
    let holding = holdings[i];
    let address = Address.fromString(holding.address);
    hodlers.push(address);
  }

  return hodlers;
}

这个查询方法首先获取代币实体，然后查询代币持有人列表，并返回持有人地址的数组。我们使用了 @graphprotocol/graph-ts 模块中的 Address 和 BigInt 类型，这些类型是用于 Subgraph 项目中的类型。我们还使用了 Token 和 TokenHolding 实体，这些实体是我们在数据模型中定义的。

部署 Subgraph 项目

现在我们需要将 Subgraph 项目部署到 Subgraph 节点上。我们可以使用 Graph CLI 工具来部署项目。

在 Subgraph 项目目录中运行以下命令：

graph deploy --node https://api.thegraph.com/deploy/ --ipfs https://api.thegraph.com/ipfs/ <subgraph-name>

例如：

graph deploy --node https://api.thegraph.com/deploy/ --ipfs https://api.thegraph.com/ipfs/ demo-subgraph

这个命令将会编译 Subgraph 项目，并将 Subgraph 部署到 Subgraph 节点上。

使用查询方法

现在我们可以使用 getHodlers 查询方法来获取 ERC20 代币的持有人列表。

在 Subgraph Explorer 中打开我们刚刚部署的 Subgraph 项目。在左侧的菜单中选择 GraphiQL 选项卡，这将打开 GraphiQL 查询编辑器。

在编辑器中编写以下查询：

{
  getHodlers(token: "DAI", first: 10, skip: 0) {
    id
  }
}

这个查询将获取 DAI 代币的前 10 个持有人的地址。

点击运行按钮，你应该可以看到查询结果，其中包含 10 个持有人的地址。

这就是使用 Subgraph 获取 ERC20 代币的持有人列表的方法。Subgraph 可以帮助我们快速构建分布式 API，让我们专注于查询方法的实现，而无需处理数据存储和访问。