用途
indexer 技能用于为 Monad 智能合约搭建链上事件索引器:初始化一个 Envio HyperIndex 索引器项目,并将其部署、管理在 Envio Cloud 上。适合需要历史事件流或活动数据、并希望通过 GraphQL API 对外提供查询的场景。
主要能力
- 初始化新的 Monad 合约索引器(支持 Monad 主网与测试网)。
- 通过 contract-import 从区块浏览器拉取已验证合约的 ABI,并生成 config.yaml、schema.graphql 与处理函数存根。
- 在 Envio Cloud 上部署新索引器。
- 检查、提升(promote)、重启或删除已有部署。
- 管理索引器环境变量与 IP 允许列表。
- 排查部署或同步失败的索引器。
- 提供索引器的 GraphQL API URL,供前端或 curl 调用。
使用方式
在项目根目录的 indexer/ 文件夹内运行初始化命令。硬性前置条件:合约必须先完成部署并在 Monad 浏览器上验证,否则 contract-import 拉取 ABI 会失败。
Monad 主网:
mkdir -p indexer && cd indexer
pnpx envio@3.0.0-alpha.21 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 envio@3.0.0-alpha.21 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> 为合约名称(如 MyToken);--all-events 导入 ABI 中的全部事件,之后可在 config.yaml 中收窄;--single-contract 为单合约生成脚手架,多合约可重复运行或手动编辑配置;--api-token "" 有意留空;-l typescript 是标志而非位置参数;版本固定为 envio@3.0.0-alpha.21。
初始化完成后,需编辑处理函数以决定存入数据库的内容;代码就绪并推送到 GitHub 后,再部署到 Envio Cloud。
在编写处理函数前启用交易字段
默认情况下,生成的处理器中 event.transaction.* 类型为 never,访问 event.transaction.hash 等会报 TypeScript 错误。若需要交易哈希(如区块浏览器链接、去重),应在 config.yaml 顶层(与 networks、contracts 同级)添加:
field_selection:
transaction_fields:
- hash
修改后需重新运行 pnpm codegen(或 pnpx envio@3.0.0-alpha.21 codegen)以重新生成类型。其他需要的字段(from、to、value、gasUsed、input 等)可加入同一列表,Envio 只拉取并键入此处列出的字段,应保持最小化。
前置条件
- 全局安装 envio-cloud:
npm install -g envio-cloud - 登录 envio-cloud:
envio-cloud login(浏览器流程,30 天会话) - 安装 GitHub CLI(macOS:
brew install gh,或参见 https://cli.github.com/) - 登录 GitHub CLI:
gh auth login
gh 之所以必需,是因为 Envio Cloud 从 GitHub 部署,索引器仓库需先推送至 GitHub。
注意:不要替用户安装 CLI 或执行登录;若缺失,应告知确切命令并等待用户自行完成。缺少前置条件时执行 envio-cloud 命令会被 monskills 钩子拒绝并提示缺失项,这属于预期行为,应将提示转达用户并等待处理。
退出码约定
所有 envio-cloud 命令统一遵循退出码约定,判断步骤是否成功时应检查退出码而非仅看 stdout:
- 0:成功,继续。
- 1:用户错误(参数错误、未知索引器、未登录),读取 stderr,修正输入后重试。
- 2:API/服务器错误,非用户问题;重试一次,若持续则告知用户并停止。
延伸参考与官方文档
技能拆分为多个参考文件,可按需获取:工作流配方(首次部署、调试失败部署、轮换环境变量、IP 允许列表等常见任务的推荐流程)与 CLI 参考(按认证、上下文、索引器生命周期、部署、环境变量、安全分组的全部 envio-cloud 命令)。建议先看与目标匹配的工作流配方,仅在需要未覆盖的标志或子命令时查阅 CLI 参考。
官方文档:https://docs.envio.dev/docs/HyperIndex/envio-cloud-cli