name: indexer
description: 此技能包含设置 Envio HyperIndex 索引器的说明，用于捕获链上智能合约事件。当用户希望在其应用中实现历史数据流、活动流或类似跟踪信息/功能，或者希望捕获链上智能合约事件以作为触发其他操作的触发器时，可使用此技能。此技能同样适用于用户想要调试、重启、升级或删除已部署在 Envio Cloud 上的现有 Envio 索引器。

索引器

本技能涵盖初始化 HyperIndex 索引器以及使用 envio-cloud CLI 将其部署/管理到 Envio Cloud。

何时使用本技能

• 用户想要为 Monad 合约初始化一个新的索引器。
• 用户想要将一个索引器部署到 Envio Cloud。
• 用户想要检查、升级、重启或删除现有部署。
• 用户想要管理索引器的环境变量或 IP 白名单。
• 用户想要调试一个部署或同步失败的索引器。
• 用户想要获取索引器的 GraphQL API URL（例如，用于前端或 curl 调用）。

初始化新索引器

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

硬性前提：合约必须先部署并在 Monad 浏览器上验证通过，然后才能运行此命令。 contract-import 会从浏览器拉取 ABI — 未验证的合约会导致导入失败。如果用户尚未验证合约，请先停止并完成验证（参见 scaffold/ 技能中的验证 API）。

Monad 主网

mkdir -p indexer && cd indexer
pnpx envio@3.0.0-alpha.21 init contract-import explorer \
  -b monad \
  -c <合约地址> \
  -n <合约名称> \
  -l typescript \
  -d ./ -o ./ \
  --all-events --single-contract --api-token ""

Monad 测试网

mkdir -p indexer && cd indexer
pnpx envio@3.0.0-alpha.21 init contract-import explorer \
  -b monad-testnet \
  -c <合约地址> \
  -n <合约名称> \
  -l typescript \
  -d ./ -o ./ \
  --all-events --single-contract --api-token ""

注意事项：

• <合约地址> — 已部署且已验证的合约地址。
• <合约名称> — 合约名称（与 Solidity 合约一致，例如 MyToken）。
• --all-events 导入 ABI 中的所有事件。如果用户只需要特定事件，稍后可以编辑 config.yaml 缩小范围。
• --single-contract 为单个合约搭建骨架。如需为其他合约重复执行该命令，或手动编辑配置。
• --api-token "" 是有意为之的 — 请保持为空。
• -l typescript 是一个标志参数，不是位置参数 — envio CLI 不接受 typescript 作为裸位置参数。
• 版本固定为 envio@3.0.0-alpha.21（请精确使用此版本）。

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

在编写处理程序之前选择接收交易字段

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

在 config.yaml 中添加 field_selection：

field_selection:
  transaction_fields:
    - hash

将其放在 config.yaml 的顶层（与 networks:、contracts: 等并列），不要嵌套在网络或合约下。编辑后，重新运行 pnpm codegen（或 pnpx envio@3.0.0-alpha.21 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 部署 — 索引器仓库必须先推送到 GitHub，而 gh 正是执行此操作的工具。

⚠️ 注意事项

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

如果你尝试执行某个 envio-cloud 命令但未满足这些前提条件，monskills 钩子会拒绝该工具调用并返回一条指向缺失项的消息。这是预期行为 — 请将消息展示给用户，等待他们解决。

下一步查阅

本技能分布在多个参考文件中。请按需获取：

• 工作流指南 — 针对常见任务（首次部署、调试部署失败、轮换环境变量、IP 白名单）提供推荐的操作序列。
• CLI 参考 — 每个 envio-cloud 命令，按功能分组（身份验证、上下文、索引器生命周期、部署、环境、安全）。

首先找到与用户目标匹配的工作流指南。仅在需要该指南未覆盖的标志或子命令时，再查阅 CLI 参考。

退出码约定

每个 envio-cloud 命令都遵循相同的退出码约定 — 请通过退出码（而非仅 stdout）来判断步骤是否成功：

官方文档

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