indexer

インデクサー

このスキルでは、envio-cloud CLI を使用して HyperIndex インデクサーを初期化し、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 は 1 つのコントラクト用のスキャフォールドを生成します。追加のコントラクトにはコマンドを再実行するか、手動で設定を編集してください。
• --api-token "" は意図的な指定です。空のままにしてください。
• -l typescript はフラグであり、位置引数ではありません。Envio CLI は typescript を単独の位置引数として指定すると拒否します。
• バージョンは [email protected] に固定されています（必ずこのバージョンを使用してください）。

初期化後、indexer/ フォルダーには config.yaml、schema.graphql、ハンドラーのスタブが作成されます。データベースに保存する内容は、ユーザーがハンドラーを編集して決定します。コードの準備が整い、GitHub にプッシュされたら、Envio Cloud にデプロイします（以下を参照）。

ハンドラーを書く前にトランザクションフィールドを有効にする

デフォルトでは、生成されたハンドラー内で event.transaction.* は never 型です。そのため、event.transaction.hash（またはその他のトランザクションフィールド）にアクセスすると TypeScript エラーになります。多くのフロントエンドではトランザクションハッシュ（エクスプローラーへのリンクや重複排除などに使用）が必要なので、ハンドラーのコードを書く前に明示的に有効にしてください。

config.yaml に field_selection を追加します。

field_selection:
  transaction_fields:
    - hash

field_selection は config.yaml のトップレベル（networks:、contracts: などと同じ階層）に配置し、ネットワークやコントラクトの下にネストしないでください。編集後、型を再生成するために pnpm codegen（または pnpx [email protected] codegen）を再実行してください。そうしないと、event.transaction.hash は引き続き never 型になります。

ハンドラーで必要なその他のフィールド（from、to、value、gasUsed、input など）も同じリストに追加します。Envio はここに記載されたフィールドのみを取得して型付けするため、必要最小限にしてください。使用可能なフィールドの全一覧については、Envio のフィールド選択に関するドキュメントを参照してください。

前提条件

インデクサーのコマンドを実行するには、以下の 4 つすべてを事前に用意しておく必要があります。

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

Envio Cloud は GitHub からデプロイするため、gh が必要です。インデクサーのリポジトリを GitHub にプッシュする必要があり、その操作には gh を使用します。

してはいけないこと

• どちらの CLI もユーザーに代わってインストールしないでください。 いずれかが見つからない場合は、正確なコマンドを伝え、待機してください。
• envio-cloud login や gh auth login をユーザーに代わって実行しないでください。 どちらもブラウザーを開き、ユーザー自身でフローを完了する必要があります。

これらの前提条件を満たさずに envio-cloud コマンドを実行すると、monskills フックが不足している項目を正確に示すメッセージとともにツール呼び出しを拒否します。これは想定どおりの動作です。そのメッセージをユーザーに伝え、ユーザーが解決するまで待機してください。

次に確認する場所

このスキルは複数のリファレンスファイルに分かれています。必要に応じて取得してください。

• ワークフローのレシピ — 一般的なタスク（初回デプロイ、失敗したデプロイのデバッグ、環境変数のローテーション、IP の許可リストへの追加）向けの推奨手順です。
• CLI リファレンス — envio-cloud の全コマンドを、分野別（認証、コンテキスト、インデクサーのライフサイクル、デプロイ、環境、セキュリティ）にまとめています。

ユーザーの目的に合うワークフローのレシピから始めてください。そこに記載のないフラグやサブコマンドが必要な場合にのみ、CLI リファレンスを確認してください。

終了コードの規約

すべての envio-cloud コマンドは同じ終了コードの規約に従います。手順が成功したかどうかを判断する際は、標準出力だけでなく、終了コードも確認してください。

終了コード	意味	対応方法
0	成功	続行します
1	ユーザーエラー（不正な引数、不明なインデクサー、未ログイン）	標準エラーを確認し、入力を修正して再試行します
2	API／サーバーエラー	ユーザーに責任はありません。一度再試行し、解決しない場合はユーザーに伝えて停止します。

公式ドキュメント

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