Skip to main content

1. Initialise a New Project

SubQuery TeamAbout 3 min

1. Initialise a New Project

The goal of this quick start guide is to provide you with working SubQuery project in your chosen layer-1 network and a basic understanding of how SubQuery works, it should take around 10-15 minutes.

Prerequisites

Before you begin creating your first blockchain project with SubQuery, make sure you have installed the required supporting software applications. These are:

1. Install the SubQuery CLI

Install SubQuery CLI globally on your terminal by using NPM. We do not encourage the use of yarn global for installing @subql/cli due to its poor dependency management. This may lead to multiple errors.

# NPM
npm install -g @subql/cli

# Test that it was installed correctly
subql --help

2. Initialise a new SubQuery Project

Run the following command inside the directory that you want to create a SubQuery project in:

subql init

You'll be asked certain questions as you proceed ahead:

  • Project name: A project name for your SubQuery project.
  • Network family: The layer-1 blockchain network family that this SubQuery project will index. Use the arrow keys to select from the available options (scroll down as there are multiple pages).
  • Network: The specific network that this SubQuery project will index. Use the arrow keys to select from the available options (scroll down as there are multiple pages).
  • Template project: Select a SubQuery template project that will provide a starting point in the development. For some networks we provide multiple examples.
  • RPC endpoint: Provide an HTTP or websocket URL to a running RPC endpoint, which will be used by default for this project. You can use public endpoints for different networks, your own private dedicated node, or just use the default endpoint. This RPC node must have the entire state of the data that you wish to index, so we recommend an archive node.
  • Git repository: Provide a Git URL to a repo that this SubQuery project will be hosted in.
  • Authors: Enter the owner of this SubQuery project here (e.g. your name!) or accept the provided default.
  • Description: Provide a short paragraph about your project that describes what data it contains and what users can do with it, or accept the provided default.
  • Version: Enter a custom version number or use the default (1.0.0).
  • License: Provide the software license for this project or accept the default (MIT).

Let’s look at an example:

$ subql init
Project name [subql-starter]: test-subquery-project
? Select a network family Ethereum
? Select a network Ethereum
? Select a template project ethereum-starter     Starter project for Ethereum networks
RPC endpoint: [https://eth.api.onfinality.io/public]:
Git repository [https://github.com/subquery/ethereum-subql-starter]: https://github.com/jamesbayly/test-subquery-project  ^ Author [SubQuery Team]: James Bayly
Description [This project can be use as a starting po...]: A new example ethereum SubQuery project
Version [0.0.1]:
License [MIT]:
Preparing project... done
test-subquery-project is ready

Ethereum Project Scaffolding

You can generate a project from a JSON ABIs to save you time when creating your project in EVM chains. Please see EVM Project Scaffolding

After you complete the initialisation process, you will see a folder with your project name created inside the directory. Please note that the contents of this directory should be near identical to what's listed in the Directory Structure.

Finally, run the following command to install the new project’s dependencies from within the new project's directory.

yarn
cd PROJECT_NAME
yarn install

You have now initialised your first SubQuery project with just a few simple steps. Let’s now customise the standard template project for a specific blockchain of interest.

You may want to refer to the command line arguments used in SubQuery. It will help you understand the commands better.

3. Make Changes to Your Project

There are 3 important files that need to be modified. These are:

  1. The GraphQL Schema in schema.graphql.
  2. The Project Manifest in project.ts.
  3. The Mapping functions in src/mappings/ directory.

SubQuery supports various blockchain networks and provides a dedicated guide for each of them. Select your preferred blockchain under 2. Specific Chains and continue the quick start guide.

EVM Project Scaffolding

Scaffolding saves time during SubQuery project creation by automatically generating typescript facades for EVM transactions, logs, and types.

When you are initalising a new project using the subql init command, SubQuery will give you the option to set up a scaffolded SubQuery project based on your JSON ABI. If you have select an compatiable network type (EVM), it will prompt

? Do you want to generate scaffolding with an existing abi contract?

So for example, If I wanted to create the Ethereum Gravatar indexer, I would download the Gravity ABI contract JSON from Etherscanopen in new window, save it as Gravity.json, and then run the following.

Project Scaffolding EVM

Once completed, you will have a scaffold project structure from your chosen ABI functions/events.

You can read more about this feature in Project Scaffolding