indexer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Indexer

索引器

This skill covers initializing a HyperIndex indexer and deploying/managing it on Envio Cloud using the

envio-cloud

CLI.

本技能涵盖使用

envio-cloud

CLI初始化HyperIndex索引器并在Envio Cloud上部署/管理索引器的操作。

When to fetch this skill

何时调用本技能

The user wants to initialize a new indexer for a Monad contract.
The user wants to deploy a new indexer to Envio Cloud.
The user wants to inspect, promote, restart, or delete an existing deployment.
The user wants to manage indexer environment variables or IP allowlists.
The user wants to debug an indexer that is failing to deploy or sync.
The user wants the GraphQL API URL for an indexer (e.g. to point a frontend or curl at it).

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

Initialize a new indexer

初始化新索引器

Run the init command inside an

indexer/

folder at the project root. Create the folder first if it doesn't exist.

Hard prereq: the contract must be both deployed AND verified on a Monad explorer before you run this.

contract-import

pulls the ABI from the explorer — an unverified contract will fail the import. If the user hasn't verified yet, stop and do that first (see

scaffold/

skill for the verification API).

在项目根目录的

indexer/

文件夹内运行初始化命令。如果该文件夹不存在，请先创建。

硬性前提：在运行此命令前，合约必须已部署并在Monad浏览器上完成验证。

contract-import

会从浏览器拉取ABI——未验证的合约会导致导入失败。如果用户尚未完成验证，请先停止操作并完成验证（可参考

scaffold/

技能中的验证API）。

Monad mainnet

Monad主网

bash

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 ""

bash

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 testnet

Monad测试网

bash

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 ""

Notes:

```
<CONTRACT_ADDRESS>
```
— the deployed, verified contract address.
```
<CONTRACT_NAME>
```
— the contract name (matches the Solidity contract, e.g.
```
MyToken
```
).
```
--all-events
```
imports every event in the ABI. Narrow this later by editing
```
config.yaml
```
if the user wants only specific events.
```
--single-contract
```
scaffolds for one contract. Re-run the command for additional contracts, or edit the config by hand.
```
--api-token ""
```
is intentional — leave it empty.
```
-l typescript
```
is a flag, not a positional — the envio CLI rejects
```
typescript
```
as a bare positional arg.
The version is pinned to
```
envio@3.0.0-alpha.21
```
(use exactly this).

After init, the

indexer/

folder will contain

config.yaml

schema.graphql

, and handler stubs. The user edits the handlers to decide what gets stored in the database. Once the code is ready and pushed to GitHub, deploy to Envio Cloud (see below).

bash

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>
```
——合约名称（与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（见下文）。

Opt into transaction fields before writing handlers

编写处理程序前选择交易字段

By default,

event.transaction.*

is typed

never

in generated handlers — accessing

event.transaction.hash

(or any other tx field) is a TypeScript error. Most frontends want the tx hash (for explorer links, dedup, etc.), so opt in explicitly before writing handler code.

Add

field_selection

config.yaml

yaml

field_selection:
  transaction_fields:
    - hash

Place it at the top level of

config.yaml

(sibling of

networks:

contracts:

, etc.), not nested under a network or contract. After editing, re-run

pnpm codegen

(or

pnpx envio@3.0.0-alpha.21 codegen

) so the types regenerate — otherwise

event.transaction.hash

will still be typed

never

Add other fields the handlers need (

from

to

value

gasUsed

input

, etc.) to the same list. Envio only pulls and types the fields listed here, so keep it minimal. The full set of available fields is in the Envio field selection docs.

默认情况下，生成的处理程序中

event.transaction.*

的类型为

never

——访问

event.transaction.hash

（或其他任何交易字段）会触发TypeScript错误。大多数前端需要交易哈希（用于浏览器链接、去重等），因此在编写处理程序代码前需明确开启该选项。

在

config.yaml

中添加

field_selection

：

yaml

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字段选择文档。

Prerequisites

前置条件

Before any indexer command will work, the user must have all four of these in place:

```
envio-cloud
```
installed globally:
```
npm install -g envio-cloud
```
```
envio-cloud
```
logged in:
```
envio-cloud login
```
(browser flow, 30-day session)
GitHub CLI (
```
gh
```
) installed:
```
brew install gh
```
on macOS, or see https://cli.github.com/
GitHub CLI logged in:
```
gh auth login
```

gh

is required because Envio Cloud deploys from GitHub — the indexer repo has to be pushed there, and

gh

is how that's done.

在运行任何索引器命令前，用户必须完成以下四项准备工作：

全局安装
```
envio-cloud
```
：
```
npm install -g envio-cloud
```
登录
```
envio-cloud
```
：
```
envio-cloud login
```
（浏览器流程，会话有效期30天）
安装GitHub CLI（
```
gh
```
）：macOS系统可使用
```
brew install gh
```
，或参考https://cli.github.com/
登录GitHub CLI：
```
gh auth login
```

需要

gh

是因为Envio Cloud从GitHub部署——索引器仓库必须推送到GitHub，而

gh

是完成该操作的工具。

What NOT to do

禁止操作

Do not install either CLI for the user. If one is missing, tell them the exact command and wait.
Do not run
envio-cloud login
or
gh auth login
for the user. Both open a browser and require the user to complete the flow themselves.

If you attempt an

envio-cloud

command without these prereqs, the monskills hook will deny the tool call with a message pointing to the exact missing piece. That's expected — surface the message to the user and wait for them to resolve it.

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

如果在未满足前置条件的情况下尝试运行

envio-cloud

命令，monskills钩子会拒绝工具调用并提示具体缺少的内容。这属于预期情况——请将提示信息告知用户并等待其解决问题。

Where to look next

后续参考

This skill is split across reference files. Fetch them on demand:

Workflow recipes — opinionated sequences for common tasks (first deploy, debug a failing deploy, rotate env vars, allowlist an IP).
CLI reference — every
```
envio-cloud
```
command, grouped by area (auth, context, indexer lifecycle, deployment, env, security).

Start with the workflow recipe that matches the user's goal. Drop into the CLI reference only when you need a flag or subcommand not covered there.

本技能的内容分散在多个参考文件中，可按需调用：

工作流指南——针对常见任务的标准化流程（首次部署、调试部署失败、轮换环境变量、添加IP白名单等）。
CLI参考——所有
```
envio-cloud
```
命令，按功能分类（认证、上下文、索引器生命周期、部署、环境、安全）。

请先选择与用户目标匹配的工作流指南。仅当需要指南中未覆盖的标志位或子命令时，再查看CLI参考。

Exit-code contract

退出码约定

Every

envio-cloud

command follows the same exit code convention — check this, not just stdout, when deciding whether a step succeeded:

Exit code	Meaning	How to react
`0`	Success	Continue
`1`	User error (bad args, unknown indexer, not logged in)	Read stderr, fix the input, retry
`2`	API/server error	Not the user's fault. Retry once; if it persists, tell the user and stop.

每个

envio-cloud

命令都遵循相同的退出码规则——判断步骤是否成功时，请检查退出码而非仅查看标准输出：

退出码	含义	应对方式
`0`	成功	继续执行
`1`	用户错误（参数错误、索引器不存在、未登录等）	读取标准错误输出，修正输入后重试
`2`	API/服务器错误	非用户问题。重试一次；如果问题持续，请告知用户并停止操作。

Official docs

官方文档

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