Ethereum / EVM indexer template (Squid SDK)

This is a starter template of a squid indexer for EVM networks (Ethereum, Polygon, BSC, etc.). See Squid SDK docs for a complete reference.

Documentation: docs.sqd.dev | sqd.dev

The data source streams pre-filtered data from a public SQD Network Portal dataset — no API key or RPC endpoint is required, and it covers real-time unfinalized blocks. To extract EVM logs and transactions by a topic or a contract address, use .addLog(), .addTransaction(), .addTrace() or .addStateDiff() methods of the DataSourceBuilder defined in src/main.ts. Select data fields with .setFields().

The requested data is transformed in batches by a single handler provided to the run() function.

For a full list of supported networks and config options, check the EVM Portal stream overview.

For a step-by-step migration guide from TheGraph, see the dedicated docs page.

Dependencies: Node.js 20 or newer, Git, Docker.

Quickstart

# 0. Install @subsquid/cli a.k.a. the sqd command globally
npm i -g @subsquid/cli

# 1. Retrieve the template
sqd init my_squid_name -t evm
cd my_squid_name

# 2. Install dependencies
npm i

# 3. Start a Postgres database container and detach
sqd up

# 4. Build the squid
sqd build

# 5. Start both the squid processor and the GraphQL server
sqd run .

A GraphiQL playground will be available at localhost:4350/graphql.

You can also start squid services one by one:

sqd process
sqd serve

Dev flow

1. Define database schema

Start development by defining the schema of the target database via schema.graphql. Schema definition consists of regular graphql type declarations annotated with custom directives. Full description of schema.graphql dialect is available here.

2. Generate TypeORM classes

Mapping developers use TypeORM EntityManager to interact with target database during data processing. All necessary entity classes are generated by the squid framework from schema.graphql. This is done by running sqd codegen command.

3. Generate database migrations

All database changes are applied through migration files located at db/migrations. squid-typeorm-migration(1) tool provides several commands to drive the process.

## drop create the database
sqd down
sqd up

## replace any old schemas with a new one made from the entities
sqd migration:generate

See docs on database migrations for more details.

4. Import ABI contract and generate interfaces to decode events

It is necessary to import the respective ABI definition to decode EVM logs. One way to generate a type-safe facade class to decode EVM logs is by placing the relevant JSON ABIs to ./abi, then using squid-evm-typegen(1) via an sqd script:

sqd typegen

See more details on the squid-evm-typegen doc page.

Project conventions

Squid tools assume a certain project layout:

• All compiled js files must reside in lib and all TypeScript sources in src. The layout of lib must reflect src.
• All TypeORM classes must be exported by src/model/index.ts (lib/model module).
• Database schema must be defined in schema.graphql.
• Database migrations must reside in db/migrations and must be plain js files.
• sqd(1) and squid-*(1) executables consult .env file for environment variables.