Templates for EVM squids

This repository is a collection of templates for developing Subsquid-based indexers ("squids") that work with EVM-based chains such as Ethereum, Polygon, Arbitrum etc. Available templates:

• erc20 - a complete squid for indexing all standard events and function calls of an arbitrary ERC20 token contract.
• abi - a template for autogenerating squids that index events and function calls within the ABI of a given contract.
• evm - a minimal squid indexing all Ethereum transactions that send ETH to the null address (a.k.a. "burns").
• gravatar - a squid migrated from the Gravatar subgraph.
• multichain - a template for indexing multiple chains at once. Captures ERC20 Transfer events of USDC on Ethereum and BSC.

To begin using the templates, install the sqd excutable:

npm install -g @subsquid/cli@latest

Next, fetch the chosen template to a new project folder using sqd init:

sqd init <new-project-name> -t <erc20|abi|evm|gravatar|multichain>

You now have a copy of the chosen squid template sitting at the <new-project-name> folder.

Note: at the moment of this writing, the erc20 template is not yet made available in sqd init. If you encounter any issues fetching it, use the following command instead: sqd init <new-project-name> -t https://github.com/subsquid-labs/squid-erc20-template.

Note: for chains that implement EVM with Substrate such as Moonbean, Astar or Acala you may want to use one of the Substrate squid templates.

Configuring the template

erc20: open the .env file in the squid project folder and set the CONTRACT_ADDRESS and CONTRACT_DEPLOYED_AT variables to the address of the token contract you want to index and the block height at which it was deployed, correspondingly.

abi: enter the squid project folder and generate the squid code with sqd generate. See sqd generate --help for further instructions. The Archives overview page of Subsquid documentation may also be helpful.

evm, gravatar, multichain: no configuration required.

Starting the squid

All EVM squid templates, once configured, are complete squids. They can run locally, provided that sqd and Docker are available.

The "processor" process is present in all squids. It downloads pre-filtered blockchain data from Subsquid Archives, applies any necessary transformations and saves the result in an application-appropriate storage. Currently, all template squids store their data to a Postgresql database and provide a way to access it via a GraphQL API.

To start the processor, run

cd <new-project-name>
npm ci
sqd build
sqd up # starts a Postgres database in a Docker container
sqd migration:apply # optional for all squids except multichain
sqd run .

Processor(s) and the GraphQL server should now be running in foreground, printing messages like

01:02:37 INFO  sqd:processor 234354 / 16519081, rate: 17547 blocks/sec, mapping: 2420 blocks/sec, 2945 items/sec, ingest: 794 blocks/sec, eta: 16m

The extracted data will begin accumulating in the database available at localhost:23798. Log in using the container default credentials:

PGPASSWORD=postgres psql -U postgres -p 23798 -h localhost squid

Graphical GraphQL query builder will be available at http://localhost:4350/graphql.

Further reading

• Quickstart guides at Subsquid docs: a more detailed version of this README that gets updated before this file does. In particular:
  • ABI template page
  • EVM template page
• Squid development flow: a guide to reshaping a template into your own squid.
• EVM indexing: the comprehensive documentation section on indexing EVM chains.
• Tutorials and examples.