indexer

索引器

此技能介绍如何初始化 HyperIndex 索引器，以及如何使用 envio-cloud CLI 在 Envio Cloud 上部署和管理索引器。

何时获取此技能

• 用户想为 Monad 合约初始化一个新的索引器。
• 用户想将新的索引器部署到 Envio Cloud。
• 用户想检查、提升、重启或删除现有部署。
• 用户想管理索引器环境变量或 IP 允许列表。
• 用户想排查部署或同步失败的索引器。
• 用户想获取索引器的 GraphQL API URL（例如，供前端或 curl 使用）。

初始化新索引器

在项目根目录下的 indexer/ 文件夹中运行 init 命令。如果该文件夹不存在，请先创建。

硬性前提：运行此命令前，合约必须已部署并在 Monad 区块浏览器上完成验证。 contract-import 会从区块浏览器获取 ABI，未验证的合约无法导入。如果用户尚未完成验证，请先暂停并完成验证（验证 API 请参阅 scaffold/ 技能）。

Monad 主网

mkdir -p indexer && cd indexer
pnpx [email protected] init contract-import explorer \
  -b monad \
  -c <CONTRACT_ADDRESS> \
  -n <CONTRACT_NAME> \
  -l typescript \
  -d ./ -o ./ \
  --all-events --single-contract --api-token ""

Monad 测试网

mkdir -p indexer && cd indexer
pnpx [email protected] init contract-import explorer \
  -b monad-testnet \
  -c <CONTRACT_ADDRESS> \
  -n <CONTRACT_NAME> \
  -l typescript \
  -d ./ -o ./ \
  --all-events --single-contract --api-token ""

说明：

• <CONTRACT_ADDRESS> — 已部署并验证的合约地址。
• <CONTRACT_NAME> — 合约名称（与 Solidity 合约一致，例如 MyToken）。
• --all-events 会导入 ABI 中的所有事件。如果用户只需要特定事件，之后可编辑 config.yaml 进行筛选。
• --single-contract 会为单个合约生成脚手架。若要添加其他合约，请重新运行命令，或手动编辑配置。
• --api-token "" 是有意设置的，请保持为空。
• -l typescript 是一个标志，而非位置参数 — envio CLI 会拒绝将 typescript 作为单独的位置参数。
• 版本固定为 [email protected]（必须使用此版本）。

初始化后，indexer/ 文件夹中会包含 config.yaml、schema.graphql 和处理程序存根。用户可编辑处理程序，以决定将哪些内容存入数据库。代码准备就绪并推送到 GitHub 后，即可部署到 Envio Cloud（见下文）。

编写处理程序前启用事务字段

默认情况下，生成的处理程序中 event.transaction.* 的类型为 never — 访问 event.transaction.hash（或任何其他事务字段）会导致 TypeScript 错误。大多数前端都需要事务哈希（用于区块浏览器链接、去重等），因此请在编写处理程序代码前显式启用。

将 field_selection 添加到 config.yaml：

field_selection:
  transaction_fields:
    - hash

将其放在 config.yaml 的顶层（与 networks:、contracts: 等并列），不要嵌套在网络或合约下。编辑后，重新运行 pnpm codegen（或 pnpx [email protected] codegen）以重新生成类型，否则 event.transaction.hash 仍会被标记为 never。

将处理程序所需的其他字段（from、to、value、gasUsed、input 等）添加到同一列表中。Envio 只会提取并声明此处列出的字段类型，因此请尽量精简。可用字段的完整列表请参阅 Envio 字段选择文档。

前提条件

要运行任何索引器命令，用户必须具备以下全部四项条件：

1. 已全局安装 envio-cloud：npm install -g envio-cloud
2. 已登录 envio-cloud：envio-cloud login（通过浏览器登录，会话有效期为 30 天）
3. 已安装 GitHub CLI（gh）：macOS 上运行 brew install gh，或访问 https://cli.github.com/
4. 已登录 GitHub CLI：gh auth login

gh 是必需的，因为 Envio Cloud 从 GitHub 部署 — 索引器仓库必须先推送到那里，而 gh 用于完成此操作。

不要做的事

• 不要替用户安装任何一个 CLI。 如果缺少其中一个，请告知用户准确的命令并等待。
• 不要替用户运行 envio-cloud login 或 gh auth login。 这两条命令都会打开浏览器，需要用户自行完成流程。

如果在未满足这些前提条件的情况下尝试运行 envio-cloud 命令，monskills hook 会拒绝该工具调用，并指出具体缺少的内容。这是预期行为——将提示消息告知用户，然后等待他们解决问题。

接下来查看

此技能分为多个参考文件。按需获取：

• 工作流方案 — 常见任务的建议步骤（首次部署、调试失败的部署、轮换环境变量、将某个 IP 加入允许列表）。
• CLI 参考 — 所有 envio-cloud 命令，按类别分组（身份验证、上下文、索引器生命周期、部署、环境、安全）。

从与用户目标匹配的工作流方案开始。只有在需要该方案未涵盖的标志或子命令时，才查阅 CLI 参考。

退出码约定

每条 envio-cloud 命令都遵循相同的退出码约定——判断某个步骤是否成功时，请检查退出码，而不只是标准输出：

退出码	含义	应对方式
0	成功	继续
1	用户错误（参数错误、索引器未知、未登录）	阅读标准错误，修正输入后重试
2	API/服务端错误	并非用户的问题。重试一次；如果仍然失败，告知用户并停止。

官方文档

https://docs.envio.dev/docs/HyperIndex/envio-cloud-cli