Quickstart: generate from ABI
With the abi
template you can generate ready-to-use squids from EVM contract ABIs. Here we make a simple squid that decodes and indexes EVM logs and transactions of a single contract into a local Postgres database. Additionally, it serves the indexed data with a rich GraphQL API supporting pagination and filtering.
It is also possible to generate squids that handle data from multiple contracts and/or save the output to a file-based dataset.
Squid generation tools are fully documented on this page.
Pre-requisites
Before getting to work on your very first squid, verify that you have installed the following software:
- Node v16.x or newer
- Squid CLI v2.1.0 or newer
- Docker
With the exception of sqd init
, sqd
commands mentioned here are just scripts defined in commands.json
that the sqd
executable automatically discovers. Take a look at the contents of this file to learn more about how squids work under the hood.
Please note:
- Squid templates are not compatible with
yarn
. Usenpm
instead.
Step 1: Scaffold from a template
Come up with a new memorable name for your squid and scaffold from squid-abi-template using sqd init
:
sqd init my-awesome-squid --template abi
cd my-awesome-squid
# install the dependencies
npm ci
Step 2: Generate the squid
- Consult the supported EVM networks page and find an archive endpoint for your network in the list.
- Prepare the contract ABI and save it into the
abi
folder, e.g. asabi/usdc.json
.
For public contracts the ABI can be fetched automatically using an Etherscan-like API. To do so omit the --abi
flag or, if your contract is a proxy, supply its address via --proxy
and the address of the implentation via --address
. For a full list of supported CLI options see
sqd generate --help
Generate the squid with
sqd generate \
--address <address> \
--abi <path to contract ABI> \ # optional
--archive <network archive alias or endpoint URL> \
--event '*' \
--function '*' \
--from <starting block>
The tool will attempt to grab the ABI from Etherscan API if --abi
is omitted. Other compatible APIs can be used; for example, BSC contracts' ABIs can be retreved from BscScan with --etherscan-api https://api.bscscan.com/
.
Example
sqd generate \
--address 0x6B175474E89094C44Da98b954EedeAC495271d0F \
--archive eth-mainnet \
--event '*' \
--function '*' \
--from 1000000
Squid generation tools can also be configured with YAML files. This mode unlocks advanced features such as working with multiple contracts and saving the squid data to file-based datasets.
Step 3: Launch Postgres in a detached Docker container
sqd up
Step 4: Generate the schema migrations
sqd migration:generate
Step 5: Run the squid processor
Run the processor with
sqd process
The squid now ingests the contract transactions and event log data, decodes it and stores it in the database.
Step 6: Start the GraphQL server
In a separate terminal window, run
sqd serve
This starts a GraphQL server serving the indexed events and transactions from the local database. The GraphQL playground is available at http://localhost:4350/graphql
. Open it in a browser and run sample queries by applying filters and data selections in the panel to the left.
query MyQuery {
contractEventTransfers(limit: 10) {
id
src
dst
}
}
What's next?
- Deploy the squid to the Aquarium hosted service
- Migrate your existing subgraphs to Subsquid
- Explore examples of squids for EVM networks, from simple transfer indexing to DEX analytics
- Develop a custom EVM squid from scratch
- Define your own data schema
- Deeper dive into
EvmBatchProcessor
- Explore how to enhance the GraphQL API with custom SQL, caching and limits