Publishing your SubQuery Project

Benefits of hosting your project with OnFinality’s Indexing Service

Subgraphs are now supported in OnFinality’s Indexing Service

Run your projects side by side together with OnFinality’s Subgraph hosting. One hosting provider for all your data indexing needs. Read more about how to quickly deploy and host your Subgraphs in the OnFinality’s Indexing Service Publishing your Subgraph Project

The biggest dApps depend on OnFinality’s enterprise level Indexing Service. With 100's of millions of daily requests and hundreds of active projects, OnFinality’s Indexing Service provides industry leading hosting for our customers.

We'll run your SubQuery and Subgraph projects for you in a high performance, scalable, and managed public service.
This service is being provided to the community with a generous free tier! You can host your first two projects for absolutely free!

You can upgrade to take advantage of the following paid services:

Production ready hosting for mission critical data with zero-downtime blue/green deployments
Dedicated databases
Multiple geo-redundant clusters and intelligent routing
Advanced monitoring and analytics.

Publish your SubQuery project to IPFS

When deploying to OnFinality’s Indexing Service, you must first host your codebase in IPFS. Hosting a project in IPFS makes it available for everyone and reduces your reliance on centralised services like GitHub.

Requirements

@subql/cli version 0.21.0 or above.
Manifest specVersion 1.0.0 and above.
Get your SUBQL_ACCESS_TOKEN ready.
To make sure your deployment is successful, we strongly recommend that you build your project with the subql build command, and test it locally before publishing.

Prepare your SUBQL_ACCESS_TOKEN

Step 1: Go to OnFinality Indexing Service (https://indexing.onfinality.io) and log in.
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)

How to publish a project

Run the following command, which will read the project's default manifest project.ts for the required information.

If you have @subql/cli version 5.0.0 or above, you will need to install @subql/common-<network> package in the dependencies before execute this command.

BASH

// Publish it from your project's root directory
subql publish

// OR point to your project root
subql publish -f ~/my-project/

Alternatively, if your project has multiple manifest files, for example you support multiple networks but share the same mapping and business logic, and have a project structure as follows:

CODE

L projectRoot
 L src/
 L package.json
 L polkadot.yaml (Manifest for Polkadot network)
 L kusama.yaml   (Manifest for Kusama network)
 ...

You can always publish the project with your selected manifest file.

BASH

// This will publish project support indexing Polkadot network
subql publish -f ~/my-projectRoot/polkadot.yaml

// This will publish project support indexing Polkadot network
subql publish -f ~/my-projectRoot/polkadot.yaml

After successfully publishing the project, the logs below indicate that the project was created on the IPFS cluster and have returned its CID (Content Identifier). Please note down this CID.

CODE

Building and packing code... done
Uploading SupQuery project to IPFS
SubQuery Project uploaded to IPFS: QmZ3q7YZSmhwBiot4PQCK3c7Z6HkteswN2Py58gkkZ8kNd  //CID

Note:

With @subql/cli version 5.0.0 or above, you will need to install @subql/common-<network> package in the dependencies before execute this command. For example, for substrate project, please make sure @subql/common-substrate 4.0.0 is installed

What happens during an IPFS deployment?

IPFS deployment represents an independent and unique existence of a SubQuery project on a decentralised network. Therefore, any changes with the code in the project will affect its uniqueness. If you need to adjust your business logic, e.g. change the mapping function, you must republish the project, and the CID will change.

For now, to view the project you have published, use a REST API tool such as Postman, and use the POST method with the following example URL to retrieve it: https://ipfs.subquery.network/ipfs/api/v0/cat?arg=<YOUR_PROJECT_CID>.

You should see the example project deployment as below.

This deployment looks very similar to your manifest file. You can expect those descriptive fields, and the network and dictionary endpoint has been removed as they did not directly affect the outcome of project execution.

Those files been used in your local project has been packed and published to IPFS as well.

YAML

dataSources:
  - kind: substrate/Runtime
    mapping:
      file: ipfs://QmTTJKrMVzCZqmRCd5xKHbKymtQQnHZierBMHLtHHGyjLy
      handlers:
        - handler: handleBlock
          kind: substrate/BlockHandler
        - filter:
            method: Deposit
            module: balances
          handler: handleEvent
          kind: substrate/EventHandler
        - handler: handleCall
          kind: substrate/CallHandler
    startBlock: 8973820
network:
  genesisHash: "0x91b171bb158e2d3848fa23a9f1c25182fb8e20313b2c1eb49219da7a70ce90c3"
schema:
  file: ipfs://QmTP5BjtxETVqvU4MkRxmgf8NbceB17WtydS6oQeHBCyjz
specVersion: 0.2.0

Login to OnFinality Indexing Service

To create your first project, head to OnFinality Indexing Service. You'll need to authenticate with your GitHub account to login.

On first login, you will be asked to authorise OnFinality’s Indexing Service. We only need your email address to identify your account, and we don't use any other data from your GitHub account for any other reasons. In this step, you can also request or grant access to your GitHub Organisation account so you can post SubQuery projects under your GitHub Organisation instead of your personal account.

OnFinality Indexing Service is where you manage all your hosted projects uploaded to the OnFinality Indexing Service platform. You can create, delete, and even upgrade projects all from this application.

If you have a GitHub Organisation accounts connected, you can use the switcher on the header to change between your personal account and your GitHub Organisation account. Projects created in a GitHub Organisation account are shared between members in that GitHub Organisation. To connect your GitHub Organisation account, you can follow the steps here.

Create Your First Project

Before starting, please make sure that your SubQuery project codebase is published to IPFS.

There are two methods to create a project in the OnFinality Indexing Service: you can use the UI or directly via the subql cli tool

Using the UI

Start by clicking on "Create Project". You'll be taken to the new project form. Start by selecting what project type you would like to deploy (SubQuery), and then follow the steps and enter the following (you can change this in the future):

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@onfinality.io to have this setting enabled.
Visible in Explorer: If selected, this will show the project from the public explorer to share with the community.

Create your project and you'll see it on your OnFinality’s Indexing Project's list. Next, we just need to deploy a new version of it.

Using the CLI

You can also use @subql/cli to create a new deployment of your project to our Indexing Service. Please follow the guide on how to create a new project on the OnFinality’s Indexing Service in the CLI documentation.

Deploy your First Version

There are three methods to deploy a new version of your project to the OnFinality Indexing Service, you can use the UI or directly, via the subql cli tool, or using an automated GitHub Action.

Using the UI

While creating a project will setup the display behaviour of the project, you must deploy a version of it before it becomes operational. Deploying a version triggers an indexing operation to start, and sets up the required query service to start accepting GraphQL requests. You can also deploy new versions to existing projects here.

With your new project, you'll see a "Deploy your first version" button. Click this, and fill in the required information about the deployment:

CID: Provide your IPFS deployment CID. Retrieve this by following the steps above.
Manifest: The details are obtained from the contents of the provided CID.
Override Network and Dictionary Endpoints: You can override the endpoints in your project manifest here.
Indexer Version: This is the version of SubQuery's node service that you want to run this SubQuery on. See @subql/node (https://www.npmjs.com/package/@subql/node).
Query Version: This is the version of SubQuery's query service that you want to run this SubQuery on. See @subql/query (https://www.npmjs.com/package/@subql/query).
Advanced Settings: There are numerous advanced settings which are explained via the in built help feature.

If deployed successfully, you'll see the indexer start working and report back progress on indexing the current chain. This process may take time until it reaches 100%.

Using the CLI

You can also use @subql/cli to create a new deployment of your project to our Indexing Service. Please follow the guide on how to deploy to an existing project on the Indexing Service in the CLI documentation.

Next Steps - Connect to your Project

Once your deployment has successfully completed and our nodes have indexed your data from the chain, you'll be able to connect to your project via the displayed GraphQL Query endpoint.

Alternatively, you can click on the three dots next to the title of your project, and view it on SubQuery Explorer. There you can use the in browser playground to get started.

Upgrade to the Latest Indexer and Query Service

If you just want to upgrade to the latest indexer @subql/node (https://www.npmjs.com/package/@subql/node) or query service @subql/query(https://www.npmjs.com/package/@subql/query) to take advantage of our regular performance and stability improvements, just select a newer versions of our packages and save. This will cause only a few minutes of downtime as the services running your project are restarted.