SubQuery is a fast, flexible, and reliable open-source data decentralised infrastructure network, providing both RPC and indexed data to consumers around the world.
In this guide, we will walk through the steps required to set up an indexer using SubQuery on AssetChain.
Prerequisites
Before starting, ensure the following tools are installed on your machine:
Node.js: Install Node.js (LTS version recommended) from the official site.
Docker: Required for running SubQuery locally. Install from the Docker website.
SubQuery CLI: Install using the command
# NPM
npm install -g @subql/cli
# Test that it was installed correctly
subql --help
Getting Started
Once you're done installing the Subquery CLI, Initializea 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: Choose a name for your SubQuery project.
Network Family: Select the EVM . Use the arrow keys to browse the available options (there may be multiple pages to scroll through).
Network: Pick the specific network(i.e Asset Chain Testnet) to be indexed by this SubQuery project. Use the arrow keys to scroll through the available networks.
Template Project: Select a template project to kickstart the development process(asset-chain-testnet-starter ).
RPC Endpoint: Provide the HTTP or websocket URL for a running RPC endpoint. This can be a public endpoint, a private node, or the default endpoint. Ensure the node has the full state of the data you wish to index—archive nodes are recommended.
Git Repository: Enter the Git URL for the repository where your SubQuery project will be hosted.
Authors: Specify the owner or author of this project (e.g., your name) or use the default provided.
Description: Write a brief description explaining the data your project indexes and what users can do with it, or use the provided default.
Version: Enter a custom version number or keep the default.
License: Provide a software license for the project or leave it as the default (MIT).
Let's look at an example
subql init
? Project name indexer-tutorial
? Select a network family EVM
? Select a network Asset Chain Testnet
? Select a template project asset-chain-testnet-starter This SubQuery project indexes all transfers and approval events for the WRWA Token on Asset Chain Test Network
? RPC endpoint: https://enugu-rpc.assetchain.org
? Author KodeSage
? Description This is my subquery tutorial
indexer-tutorial is ready
? Do you want to generate scaffolding from an existing contract abi? no
Finally, run the following command to install the new project’s dependencies from within the new project's directory
cd indexer-tutorial // Replace with you project name
yarn install
You have now initialised your first SubQuery project with just a few simple steps. Let’s now customise the asset-chain-testnet template for our project.
Building the Project
For this Project, we are going to be indexing this MultitokenLauncher Contract. Specifically, we will be indexing the TokenCreatedEvent.
Inside your Project, you abis directory and rename the erc20.abi.json file to multitokenlauncher.abi.json and replace the file content with this content below
In the mappings/mappingHandlers.tsfile, replace the content with this:
export async function handleTokenCreated(): Promise<void> {
}
In the project.tsfile, replace the content with this:
import {
EthereumProject,
EthereumDatasourceKind,
EthereumHandlerKind,
} from "@subql/types-ethereum";
import * as dotenv from 'dotenv';
import path from 'path';
const mode = process.env.NODE_ENV || 'production';
// Load the appropriate .env file
const dotenvPath = path.resolve(__dirname, `.env${mode !== 'production' ? `.${mode}` : ''}`);
dotenv.config({ path: dotenvPath });
// Can expand the Datasource processor types via the generic param
const project: EthereumProject = {
specVersion: "1.0.0",
version: "0.0.1",
name: "indexer tutorials",
description: "This is a sample implementation of the indexer tutorials",
runner: {
node: {
name: "@subql/node-ethereum",
version: ">=3.0.0",
},
query: {
name: "@subql/query",
version: "*",
},
},
schema: {
file: "./schema.graphql",
},
network: {
/**
* chainId is the EVM Chain ID, for Asset Chain Testnet this is 42421
* https://chainlist.org/chain/42421
*/
chainId: process.env.CHAIN_ID!,
/**
* These endpoint(s) should be public non-pruned archive node
* We recommend providing more than one endpoint for improved reliability, performance, and uptime
* Public nodes may be rate limited, which can affect indexing speed
* When developing your project we suggest getting a private API key
* If you use a rate limited endpoint, adjust the --batch-size and --workers parameters
* These settings can be found in your docker-compose.yaml, they will slow indexing but prevent your project being rate limited
*/
endpoint: process.env.ENDPOINT!?.split(",") as string[] | string,
},
dataSources: [
{
kind: EthereumDatasourceKind.Runtime,
startBlock: 141381, //The Block Number where your contract was created
options: {
abi: "multitokenlauncher",
// This is the contract address for MultiTokenlauncher
address: "0x6fCc46E73E5B96479F6fA731893534b6Ec6bf5E1",
},
assets: new Map([
["multitokenlauncher", { file: "./abis/multitokenlauncher.abi.json" }],
]),
mapping: {
file: "./dist/index.js",
handlers: [
{
kind: EthereumHandlerKind.Event,
handler: "handleTokenCreated",
filter: {
/**
* Follows standard log filters https://docs.ethers.io/v5/concepts/events/
* address: "0x6fCc46E73E5B96479F6fA731893534b6Ec6bf5E1"
*/
topics: [
"TokenCreated(address indexed tokenAddress, address indexed deployer, string tokenname, string tokensymbol)",
],
},
},
],
},
},
],
repository: "https://github.com/subquery/ethereum-subql-starter", // Replace with your own repository
};
// Must set default to the project instance
export default project;
Afterwards , Then Open your terminal and run the following code below
yarn codegen
This Generates types from the GraphQL schema definition and contract ABIs and saves them in the /src/types directory. This must be done after each change to the schema.graphql file or the contract ABIs and Updating the project.tsfile.
Update mappings/mappingHandlers.ts file with this content below:
import { TokenCreated } from "../types";
import { TokenCreatedLog } from "../types/abi-interfaces/MultitokenlauncherAbi";
import assert from "assert";
export async function handleTokenCreated(log: TokenCreatedLog): Promise<void> {
logger.info(`New TokenCreated event log at block ${log.blockNumber}`);
assert(log.args, "No log.args");
const token = TokenCreated.create({
id: log.transactionHash,
tokenAddress: log.args.tokenAddress,
owner: log.args.deployer,
name: log.args.tokenname,
symbol: log.args.tokensymbol,
});
await token.save();
}
// This handles the Transformation Logic and make the data's indexed.
Now that our Project is Completed, we need to build out the dist file and test it.
in your terminal, run the following command:
yarn build
Once the Build Passes, Kudos your Subgraph Project is Ready.
Testing
You need to test the project locally and make sure it is working before deploying.
To Test, make sure you have your Docker Environment is running.
Step 2: Click on your profile at the top right of the navigation menu, then click on Refresh Token.
Step 3: Copy the generated token.
Step 4: To use this token:
Add SUBQL_ACCESS_TOKEN in your environment variables. EXPORT SUBQL_ACCESS_TOKEN=<token> (Windows) or export SUBQL_ACCESS_TOKEN=<token> (Mac/Linux)
Publish your project
In your project directory, run the following command
subql publish
you should then see a similar output below
SubQuery Project project.yaml uploaded to IPFS: QmPWDhbqBqN4peb5BQKuFZPFt1qfAP6b6aQNmzEYzaWg9M
Deploying Our Project to The Network
To create your first project, head to SubQuery Managed Service. You'll need to authenticate with your GitHub account to login.
SubQuery Projects is where you manage all your hosted projects uploaded to the SubQuery platform. You can create, delete, and even upgrade projects all from this application.
Click on the Create Project Buttton to Create your Project, A Modal will pop up, then you Click on the Subquery Project and click the Next Button.
and then follow the steps and enter the following:
The information you are filling should tally with the same information you used while setting up the project using the CLI
Project Name: Name your project.
Description: Provide a description of your project.
Database: Premium customers can access dedicated databases to host production SubQuery projects from. If this interests you, you can contact sales@subquery.network to have this setting enabled.
Visible in Explorer: If selected, this will show the project from the public SubQuery explorer to share with the community.\