如何使用 Envio HyperSync 查询代币数据

在本指南中，您将学习如何使用 Envio HyperSync 加速这一过程，为 Monad 上的 ERC-721、ERC-20 和 ERC-1155 合约高效计算代币归属情况。

背景

EVM 开发者经常遇到的问题是”历史余额问题” —— 恢复某个 ERC-20、ERC-721 或 ERC-1155 代币账户到余额的完整映射。Solidity 不会追踪 mapping 中的键；值在对键进行哈希后存储到相应的存储槽中。因此，要恢复余额，常见策略是重放该代币的所有转账事件并计算滚动累加。 Envio HyperSync 是一个索引器，允许开发者在几秒钟内查询数百万个区块链事件。在本指南中，我们将使用来自 HyperSync 的数据重建代币的历史余额。

前置条件

Node.js 18+
从 envio.dev/app/api-tokens 获取的免费 HyperSync API 密钥

HyperSync 端点

网络	URL
测试网
主网

组件

本指南概述如何重建三种最流行代币标准（ERC-20、ERC-721 和 ERC-1155）的余额。每种都使用一些通用组件，但需要不同的逻辑来组合出最终结果。

查询 Transfer 事件

首先，让我们编写代码来查询合约的所有 Transfer 事件，并按适当的签名过滤。 ERC-20 和 ERC-721 使用下面的 Transfer 事件，而 ERC-1155 使用 TransferSingle 和 TransferBatch 事件：

Event	Signature
`Transfer(address,address,uint256)`	`0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef`
`TransferSingle(address,address,address,uint256,uint256)`	`0xc3d58168c5ae7397731d063d5bbf3d657854427343f4c083240f7aacaa2d0f62`
`TransferBatch(address,address,address,uint256[],uint256[])`	`0x4a39dc06d4c0dbc64b70af90fd698a233a518aa5d07e595d983b8c0526c8f7fb`

lib/signatures.ts

// ERC-20 and ERC-721 share the same Transfer signature
const TRANSFER_EVENT = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";

// ERC-1155 events
const TRANSFER_SINGLE = "0xc3d58168c5ae7397731d063d5bbf3d657854427343f4c083240f7aacaa2d0f62";
const TRANSFER_BATCH = "0x4a39dc06d4c0dbc64b70af90fd698a233a518aa5d07e595d983b8c0526c8f7fb";

以下是查询 ERC-20 合约事件的代码：

lib/hypersync.ts

const HYPERSYNC_URL = "https://monad-testnet.hypersync.xyz";

// keccak256("Transfer(address,address,uint256)") - same for ERC-20 and ERC-721
const TRANSFER_SIGNATURE = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";

async function queryTransfers(contractAddress: string, apiKey: string) {
  const response = await fetch(`${HYPERSYNC_URL}/query`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${apiKey}`,
    },
    body: JSON.stringify({
      from_block: 0,
      logs: [
        {
          address: [contractAddress],
          topics: [[TRANSFER_SIGNATURE]],
        },
      ],
      field_selection: {
        log: ["topic0", "topic1", "topic2", "topic3", "data"],
      },
    }),
  });

  return response.json();
}

字段选择

为了优化查询，我们只请求实际需要的字段。这可以减少响应大小并显著加快查询速度。不同代币标准将数据编码在不同的 topic 中： ERC-721（tokenId 位于 topic3）：

{ "log": ["topic0", "topic2", "topic3"] }

ERC-20（value 位于 data）：

{ "log": ["topic0", "topic1", "topic2", "data"] }

ERC-1155（id 和 value 位于 data）：

{ "log": ["topic0", "topic1", "topic2", "topic3", "data"] }

解析日志数据

现在我们有了原始事件数据，需要将其解析为可用的值。Topics 是 32 字节的十六进制字符串，其中地址左侧填充零，占据最后 20 字节：

lib/parse.ts

function parseAddress(topic: string): string {
  return "0x" + topic.slice(-40).toLowerCase();
}

function parseTokenId(topic: string): string {
  return BigInt(topic).toString();
}

function parseValue(data: string): bigint | null {
  if (!data || data === "0x") return null;
  return BigInt(data);
}

注意： parseValue 返回原始代币值作为 bigint。ERC-20 代币具有 decimals 属性（通常为 18）—— 除以 10n ** BigInt(decimals) 以转换为人类可读的数量。

分页

HyperSync 返回分页结果以高效处理大型数据集。我们需要持续查询，直到 next_block 为 undefined，以获取所有转账：

lib/paginate.ts

async function fetchAllTransfers(contractAddress: string, apiKey: string) {
  const ownership = new Map<string, string>();
  let fromBlock = 0;
  let hasMore = true;

  while (hasMore) {
    const response = await queryHypersync(contractAddress, fromBlock, apiKey);

    // Process logs
    for (const block of response.data) {
      for (const log of block.logs) {
        const to = parseAddress(log.topic2);
        const tokenId = parseTokenId(log.topic3);
        ownership.set(tokenId, to);
      }
    }

    // Check for more pages
    if (response.next_block && response.next_block > fromBlock) {
      fromBlock = response.next_block;
    } else {
      hasMore = false;
    }
  }

  return ownership;
}

现在我们可以把所有内容整合起来。

ERC-721 余额快照

对于 ERC-721，我们通过重放所有 Transfer 事件重建当前的持有状态。对于 NFT，每个 token ID 的最后一次转账决定了当前的所有者：

app/api/snapshot/route.ts

import { NextRequest, NextResponse } from "next/server";

const HYPERSYNC_URL = "https://monad-testnet.hypersync.xyz";

// keccak256("Transfer(address,address,uint256)") - same for ERC-20 and ERC-721
const TRANSFER_SIGNATURE = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";

const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";

function parseAddress(topic: string): string {
  return "0x" + topic.slice(-40).toLowerCase();
}

function parseTokenId(topic: string): string {
  return BigInt(topic).toString();
}

interface HypersyncLog {
  topic0: string;
  topic2: string;
  topic3: string;
}

interface HypersyncResponse {
  data: { logs: HypersyncLog[] }[];
  next_block?: number;
}

async function queryHypersync(
  contractAddress: string,
  fromBlock: number,
  apiKey: string
): Promise<HypersyncResponse> {
  const response = await fetch(`${HYPERSYNC_URL}/query`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${apiKey}`,
    },
    body: JSON.stringify({
      from_block: fromBlock,
      logs: [{ address: [contractAddress], topics: [[TRANSFER_SIGNATURE]] }],
      field_selection: { log: ["topic0", "topic2", "topic3"] },
    }),
  });

  if (!response.ok) {
    throw new Error(`HyperSync error: ${response.status}`);
  }

  return response.json();
}

export async function GET(request: NextRequest) {
  const contract = request.nextUrl.searchParams.get("contract");
  const apiKey = process.env.HYPERSYNC_BEARER_TOKEN;

  if (!contract || !apiKey) {
    return NextResponse.json({ error: "Missing parameters" }, { status: 400 });
  }

  // Track current owner for each tokenId
  const ownership = new Map<string, string>();
  let fromBlock = 0;
  let hasMore = true;

  while (hasMore) {
    const response = await queryHypersync(contract, fromBlock, apiKey);

    for (const block of response.data) {
      for (const log of block.logs) {
        const to = parseAddress(log.topic2);
        const tokenId = parseTokenId(log.topic3);
        ownership.set(tokenId, to); // Last transfer wins
      }
    }

    if (response.next_block && response.next_block > fromBlock) {
      fromBlock = response.next_block;
    } else {
      hasMore = false;
    }
  }

  // Filter out burned tokens
  const snapshot = Array.from(ownership.entries())
    .filter(([, owner]) => owner !== ZERO_ADDRESS)
    .map(([tokenId, owner]) => ({ tokenId, owner }));

  return NextResponse.json({ snapshot });
}

ERC-20 余额快照

对于 ERC-20 代币，我们需要累加所有转账以计算当前余额。与 NFT 追踪所有权不同，ERC-20 余额需要为每个地址累加所有转入和转出的转账。首先，用正确的字段选择查询 ERC-20 转账（topic1 为 from，topic2 为 to，data 为值）：

lib/erc20.ts

async function queryERC20Transfers(
  contractAddress: string,
  fromBlock: number,
  apiKey: string
): Promise<HypersyncResponse> {
  const response = await fetch(`${HYPERSYNC_URL}/query`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${apiKey}`,
    },
    body: JSON.stringify({
      from_block: fromBlock,
      logs: [{ address: [contractAddress], topics: [[TRANSFER_SIGNATURE]] }],
      field_selection: { log: ["topic0", "topic1", "topic2", "data"] },
    }),
  });

  if (!response.ok) {
    throw new Error(`HyperSync error: ${response.status}`);
  }

  return response.json();
}

然后通过累加所有转账重建余额：

lib/erc20.ts

async function getERC20Balances(contractAddress: string, apiKey: string) {
  const balances = new Map<string, bigint>();
  let fromBlock = 0;
  let hasMore = true;

  while (hasMore) {
    const response = await queryERC20Transfers(contractAddress, fromBlock, apiKey);

    for (const block of response.data) {
      for (const log of block.logs) {
        const from = parseAddress(log.topic1);
        const to = parseAddress(log.topic2);
        const value = parseValue(log.data);

        if (value === null) continue;

        // Subtract from sender
        if (from !== ZERO_ADDRESS) {
          const current = balances.get(from) || 0n;
          balances.set(from, current - value);
        }

        // Add to receiver
        if (to !== ZERO_ADDRESS) {
          const current = balances.get(to) || 0n;
          balances.set(to, current + value);
        }
      }
    }

    if (response.next_block && response.next_block > fromBlock) {
      fromBlock = response.next_block;
    } else {
      hasMore = false;
    }
  }

  // Filter positive balances, sort descending
  return Array.from(balances.entries())
    .filter(([, balance]) => balance > 0n)
    .sort((a, b) => (b[1] > a[1] ? 1 : -1))
    .map(([address, balance]) => ({ address, balance: balance.toString() }));
}

ERC-1155 余额快照

ERC-1155 代币与 ERC-20 和 ERC-721 的工作方式不同。它们将 id 和 value 存储在 data 字段而不是 topic 中，需要更复杂的解析：

lib/erc1155.ts

// TransferSingle: data = id (32 bytes) + value (32 bytes)
function parseTransferSingle(data: string): { tokenId: string; value: bigint } | null {
  if (!data || data.length < 130) return null;
  const tokenId = BigInt("0x" + data.slice(2, 66)).toString();
  const value = BigInt("0x" + data.slice(66, 130));
  return { tokenId, value };
}

// TransferBatch: ABI-encoded arrays
function parseTransferBatch(data: string): { tokenId: string; value: bigint }[] | null {
  if (!data || data.length < 258) return null;

  // Decode offsets
  const idsOffset = Number(BigInt("0x" + data.slice(2, 66)));
  const valuesOffset = Number(BigInt("0x" + data.slice(66, 130)));

  // Read array lengths
  const idsLengthStart = 2 + idsOffset * 2;
  const idsLength = Number(BigInt("0x" + data.slice(idsLengthStart, idsLengthStart + 64)));

  const valuesLengthStart = 2 + valuesOffset * 2;
  const valuesLength = Number(BigInt("0x" + data.slice(valuesLengthStart, valuesLengthStart + 64)));

  if (idsLength !== valuesLength || idsLength === 0) return null;

  // Parse each id/value pair
  const results: { tokenId: string; value: bigint }[] = [];
  for (let i = 0; i < idsLength; i++) {
    const idStart = idsLengthStart + 64 + i * 64;
    const valueStart = valuesLengthStart + 64 + i * 64;
    const tokenId = BigInt("0x" + data.slice(idStart, idStart + 64)).toString();
    const value = BigInt("0x" + data.slice(valueStart, valueStart + 64));
    results.push({ tokenId, value });
  }

  return results;
}

查询多种事件类型

在处理 ERC-1155 代币时，我们可以通过在单个请求中同时查询 TransferSingle 和 TransferBatch 事件来优化：

lib/multi-event.ts

const query = {
  from_block: 0,
  logs: [
    {
      address: [contractAddress],
      topics: [[TRANSFER_SINGLE, TRANSFER_BATCH]], // Both ERC-1155 events
    },
  ],
  field_selection: {
    log: ["topic0", "topic1", "topic2", "topic3", "data"],
  },
};

然后根据 topic0 路由：

for (const log of block.logs) {
  if (log.topic0 === TRANSFER_SINGLE) {
    const parsed = parseTransferSingle(log.data);
    // handle single transfer...
  } else if (log.topic0 === TRANSFER_BATCH) {
    const parsed = parseTransferBatch(log.data);
    // handle batch transfer...
  }
}

获取最新区块

要验证您已同步所有可用数据，您可以检查当前链的高度：

lib/height.ts

async function getLatestBlock(apiKey: string): Promise<number> {
  const response = await fetch(`${HYPERSYNC_URL}/height`, {
    headers: { "Authorization": `Bearer ${apiKey}` },
  });
  const data = await response.json();
  return data.height;
}

常见错误

1. 忘记分页

HyperSync 返回的是部分结果。请始终检查 next_block：

// Wrong - only gets first page
const response = await queryHypersync(contract, 0);

// Right - loop until done
while (response.next_block) {
  // continue querying...
}

2. 请求未使用的字段

每个字段都会增加响应大小。请显式指定：

// Wrong - fetches everything
field_selection: { log: ["*"] }

// Right - only what you need
field_selection: { log: ["topic0", "topic2", "topic3"] }

3. 使用库进行简单解析

HyperSync 返回原始十六进制。原生 BigInt 可以处理它：

// Unnecessary - adds dependency
import { decodeAbiParameters } from "viem";

// Sufficient - native JS
const value = BigInt("0x" + data.slice(2, 66));

4. 未过滤已销毁的代币

地址 0x000...000 表示已销毁：

const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";

// Filter them out
const active = ownership.filter(([, owner]) => owner !== ZERO_ADDRESS);

API 参考

POST /query

查询事件日志。 请求体：

字段	类型	说明
`from_block`	number	起始区块（包含）
`to_block`	number	结束区块（可选）
`logs`	array	日志过滤器
`logs[].address`	string[]	要过滤的合约地址
`logs[].topics`	string[][]	Topic 过滤器（数组内为 OR，跨数组为 AND）
`field_selection.log`	string[]	要返回的字段

响应：

字段	类型	说明
`data`	array	包含匹配日志的区块
`data[].logs`	array	区块中的匹配日志
`next_block`	number	下一个要查询的区块（分页）

GET /height

获取当前链的高度。 响应：

字段	类型	说明
`height`	number	最新区块号

总结

Envio HyperSync 让您可以通过单个分页 API 查询 Monad 上任何合约的事件历史 —— 无需运行节点，也无需维护索引器。 /query 端点接受 topic 和地址过滤器，/height 会给您当前链的高度。请查看完整 HyperSync 文档以了解更多查询类型和选项。在此基础上，您可以扩展此模式以构建空投资格检查器、治理投票权快照或多代币组合追踪器。

后续步骤

Envio 文档 - 完整的 HyperSync 文档
API tokens - 获取您的免费 API 密钥

简介

开发者要点

工具和基础设施

JSON-RPC

指南

资源

面向 AI 智能体

如何使用 Envio HyperSync 查询代币数据

背景

前置条件

HyperSync 端点

组件

查询 Transfer 事件

字段选择

解析日志数据

分页

ERC-721 余额快照

ERC-20 余额快照

ERC-1155 余额快照

查询多种事件类型

获取最新区块

常见错误

1. 忘记分页

2. 请求未使用的字段

3. 使用库进行简单解析

4. 未过滤已销毁的代币

API 参考

POST /query

GET /height

总结

后续步骤

​背景

​前置条件

​HyperSync 端点

​组件

​查询 Transfer 事件

​字段选择

​解析日志数据

​分页

​ERC-721 余额快照

​ERC-20 余额快照

​ERC-1155 余额快照

​查询多种事件类型

​获取最新区块

​常见错误

​1. 忘记分页

​2. 请求未使用的字段

​3. 使用库进行简单解析

​4. 未过滤已销毁的代币

​API 参考

​POST /query

​GET /height

​总结

​后续步骤

背景

前置条件

HyperSync 端点

组件

查询 Transfer 事件

字段选择

解析日志数据

分页

ERC-721 余额快照

ERC-20 余额快照

ERC-1155 余额快照

查询多种事件类型

获取最新区块

常见错误

1. 忘记分页

2. 请求未使用的字段

3. 使用库进行简单解析

4. 未过滤已销毁的代币

API 参考

POST /query

GET /height

总结

后续步骤