gh-enviodev-envio-plugins-plugins-envio-hyperindex/commands/init.md

description, argument-hint, allowed-tools

description	argument-hint	allowed-tools
Initialize a new HyperIndex indexer project with guided setup	contract-address-or-type	Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion, WebSearch

Initialize a new Envio HyperIndex indexer project using envio init with non-interactive CLI flags.

IMPORTANT: The interactive CLI does not work well with agents. Always use the fully-specified command-line flags to avoid interactive prompts.

Step 1: Gather Required Information

Check $ARGUMENTS for:

• A contract address (starts with 0x)
• A template name (e.g., erc20, greeter)

If NO contract address or template provided:

1. Ask the user what protocol/contract they want to index
2. If they provide a name (e.g., "Uniswap V2", "Aave V3"), use WebSearch to find the contract address:
   • Search for: "[protocol name] [network] contract address"
   • Example: "Uniswap V2 Factory ethereum mainnet contract address"
3. Ask which network (default: eth for Ethereum mainnet)
4. Ask for project directory name (default: envio-indexer)

If contract address IS provided:

• Proceed directly to Step 2

Step 2: Initialize with Contract Import (Primary Method)

Use the fully non-interactive command with all flags specified:

pnpx envio init contract-import explorer \
  -c <CONTRACT_ADDRESS> \
  -b <NETWORK_ID> \
  -n <PROJECT_NAME> \
  -l typescript \
  -d <DIRECTORY_NAME> \
  --single-contract \
  --all-events \
  --api-token ""

Example - Uniswap V2 Factory on Ethereum:

pnpx envio init contract-import explorer \
  -c 0x5C69bEe701ef814a2B6a3EDD4B1652CB9cc5aA6f \
  -b ethereum-mainnet \
  -n uniswap-v2-indexer \
  -l typescript \
  -d uniswap-v2-indexer \
  --single-contract \
  --all-events \
  --api-token ""

CLI Flag Reference:

Flag	Description	Required
-c, --contract-address	Contract address to import	Yes
-b, --blockchain	Network ID (see network list below)	Yes
-n, --name	Project name	Yes
-l, --language	Handler language: typescript, javascript, rescript	Yes
-d, --directory	Output directory for the project	Yes
--single-contract	Skip prompt for additional contracts	Recommended
--all-events	Index all events without prompting	Recommended
--api-token	HyperSync API token (use "" for public access)	Recommended

Step 3: Fallback - Template Initialization

If contract import fails (e.g., unverified contract, network issues), use template initialization:

pnpx envio init template \
  -t erc20 \
  -n <PROJECT_NAME> \
  -l typescript \
  -d <DIRECTORY_NAME> \
  --api-token ""

Available Templates:

Template	Description	Use Case
erc20	ERC20 token transfers	Token tracking, balances
greeter	Simple example	Learning, testing

After template init, you'll need to manually update config.yaml with the actual contract address and network.

Step 4: Post-Initialization Setup

After init completes successfully:

cd <DIRECTORY_NAME>
pnpm install
pnpm codegen

Step 5: Verify Generated Files

Check that these files were created:

• config.yaml - Contract addresses, networks, events
• schema.graphql - GraphQL entity definitions
• src/EventHandlers.ts - Event handler stubs

Read and review each file to understand what was generated.

Step 6: Start Development

pnpm dev

This starts the indexer locally with hot reload and Hasura GraphQL console.

---

Network IDs

Use these values for the -b / --blockchain flag.

Mainnets

Network	CLI Value
Ethereum	ethereum-mainnet
Polygon	polygon
Arbitrum One	arbitrum-one
Arbitrum Nova	arbitrum-nova
Optimism	optimism
Base	base
Avalanche	avalanche
BSC	bsc
Gnosis	gnosis
Fantom	fantom
Linea	linea
Scroll	scroll
zkSync Era	zksync-era
Blast	blast
Mode	mode
Manta	manta
Mantle	mantle
Moonbeam	moonbeam
Celo	celo
Aurora	aurora
Harmony	harmony
Sonic	sonic
Berachain	berachain
Monad	monad
Abstract	abstract
Worldchain	worldchain
Unichain	unichain
Zora	zora

Testnets

Network	CLI Value
Sepolia	sepolia
Holesky	holesky
Base Sepolia	base-sepolia
Arbitrum Sepolia	arbitrum-sepolia
Optimism Sepolia	optimism-sepolia
Scroll Sepolia	scroll-sepolia
Linea Sepolia	linea-sepolia
Blast Sepolia	blast-sepolia
Mode Sepolia	mode-sepolia
Monad Testnet	monad-testnet
Polygon Amoy	amoy

Full List

Run pnpx envio init contract-import explorer --help to see all supported networks.

Common Contract Addresses

Ethereum Mainnet:

• Uniswap V2 Factory: 0x5C69bEe701ef814a2B6a3EDD4B1652CB9cc5aA6f
• Uniswap V3 Factory: 0x1F98431c8aD98523631AE4a59f267346ea31F984
• WETH: 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2
• USDC: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
• USDT: 0xdAC17F958D2ee523a2206206994597C13D831ec7
• DAI: 0x6B175474E89094C44Da98b954EescdeCB5BE3bE

Polygon:

• Uniswap V3 Factory: 0x1F98431c8aD98523631AE4a59f267346ea31F984
• QuickSwap Factory: 0x5757371414417b8C6CAad45bAeF941aBc7d3Ab32

Arbitrum:

• Uniswap V3 Factory: 0x1F98431c8aD98523631AE4a59f267346ea31F984
• GMX Vault: 0x489ee077994B6658eAfA855C308275EAd8097C4A

Base:

• Uniswap V3 Factory: 0x33128a8fC17869897dcE68Ed026d694621f6FDfD
• Aerodrome Factory: 0x420DD381b31aEf6683db6B902084cB0FFECe40Da

Always verify addresses with the user or official documentation before indexing.

---

Troubleshooting

Contract Import Fails

1. Check if the contract is verified on the block explorer
2. Try using a different block explorer or network
3. Fall back to template init and manually add the ABI

Network Not Found

• Check the full network list: pnpx envio init contract-import explorer --help
• Use the exact CLI value from the list (e.g., ethereum-mainnet, arbitrum-one)

ABI Not Available

Use local ABI import instead:

pnpx envio init contract-import local \
  -a ./path/to/abi.json \
  -c <CONTRACT_ADDRESS> \
  -b <NETWORK_ID> \
  --contract-name <NAME> \
  -n <PROJECT_NAME> \
  -l typescript \
  -d <DIRECTORY_NAME> \
  --single-contract \
  --all-events \
  --api-token ""