Manifest File

... 2022-12-1 About 7 min

# Manifest File

Il file Manifest project.yaml può essere visto come un punto di ingresso del tuo progetto e definisce la maggior parte dei dettagli su come SubQuery indicizzerà e trasformerà i dati della catena.

Il manifesto può essere in formato YAML o JSON. In questo documento useremo YAML in tutti gli esempi. Di seguito è riportato un esempio standard di un project.yaml di base.

# Migrating from v0.0.1 to v0.2.0 upgrade

If you have a project with specVersion v0.0.1, you can use subql migrate to quickly upgrade. See here for more information

Under network:

  • There is a new required genesisHash field which helps to identify the chain being used.
  • Per v0.2.0 e versioni successive, puoi fare riferimento a un chaintype file esterno se stai facendo riferimento a una catena personalizzata.

Under dataSources:

  • Può collegare direttamente un punto di ingresso index.js per i gestori di mappatura. Per impostazione predefinita, questo index.js verrà generato da index.ts durante il processo di compilazione.
  • Le origini dati ora possono essere una normale origine dati di runtime o custom data sourc.

# CLI Options

By default the CLI will generate SubQuery projects for spec verison v0.2.0. This behaviour can be overridden by running subql init --specVersion 0.0.1 PROJECT_NAME, although this is not recommended as the project will not be supported by the SubQuery hosted service in the future

subql migrate can be run in an existing project to migrate the project manifest to the latest version.

USAGE $ subql init [PROJECTNAME]

ARGUMENTS PROJECTNAME Give the starter project name

Options Description
-f, --force
-l, --location=location local folder to create the project in
--install-dependencies Install dependencies as well
--npm Force using NPM instead of yarn, only works with install-dependencies flag
--specVersion=0.0.1 0.2.0 [default: 0.2.0]

# Overview

# Top Level Spec

Field v0.0.1 v0.2.0 Description
specVersion String String 0.0.1 or 0.2.0 - the spec version of the manifest file
name 𐄂 String Name of your project
version 𐄂 String Version of your project
description String String Discription of your project
repository String String Git repository address of your project
schema String Schema Spec The location of your GraphQL schema file
network Network Spec Network Spec Detail of the network to be indexed
dataSources DataSource Spec DataSource Spec

# Schema Spec

Field v0.0.1 v0.2.0 Description
file 𐄂 String The location of your GraphQL schema file

# Network Spec

Field v0.0.1 v0.2.0 Description
genesisHash 𐄂 String The genesis hash of the network
endpoint String String Cartella locale in cui eseguire la migrazione (deve project. yaml). Puoi recuperare gli endpoint per tutte le paracatene gratuitamente da OnFinality (opens new window)
dictionary String String Si suggerisce di fornire l'endpoint HTTP di un dizionario a catena completa per velocizzare l'elaborazione: leggi come funziona un dizionario di sottoquery.
chaintypes 𐄂 {file:String} Path to chain types file, accept .json or .yaml format

# Datasource Spec

Defines the data that will be filtered and extracted and the location of the mapping function handler for the data transformation to be applied.

Field v0.0.1 v0.2.0 Description
name String 𐄂 Name of the data source
kind substrate/Runtime substrate/Runtime, substrate/CustomDataSource We supports data type from default substrate runtime such as block, event and extrinsic(call).
From v0.2.0, we support data from custom runtime, such as smart contract.
startBlock Integer Integer This changes your indexing start block, set this higher to skip initial blocks with less data
mapping Mapping Spec Mapping Spec
filter network-filters 𐄂 Filter the data source to execute by the network endpoint spec name

# Mapping Spec

Field v0.0.1 v0.2.0 Description
file String 𐄂 Path to the mapping entry
handlers & filters Default handlers and filters Default handlers and filters,
Custom handlers and filters
Elenca tutte le mapping functions e i relativi tipi di gestori, con filtri di mappatura aggiuntivi.

For custom runtimes mapping handlers please view Custom data sources

# Data Sources and Mapping

In this section, we will talk about the default substrate runtime and its mapping. Here is an example:

dataSources:
  - kind: substrate/Runtime # Indicates that this is default runtime
    startBlock: 1 # This changes your indexing start block, set this higher to skip initial blocks with less data
    mapping:
      file: dist/index.js # Entry path for this mapping
1
2
3
4
5

# Mapping handlers and Filters

The following table explains filters supported by different handlers.

Your SubQuery project will be much more efficient when you only use event and call handlers with appropriate mapping filters

Handler Supported filter
BlockHandler specVersion
EventHandler module,method
CallHandler module,method ,success

Default runtime mapping filters are an extremely useful feature to decide what block, event, or extrinsic will trigger a mapping handler.

Only incoming data that satisfy the filter conditions will be processed by the mapping functions. Mapping filters are optional but are highly recommended as they significantly reduce the amount of data processed by your SubQuery project and will improve indexing performance.

# Example filter from callHandler
filter:
  module: balances
  method: Deposit
  success: true
1
2
3
4
5
  • I filtri di modulo e metodo sono supportati su qualsiasi catena basata su substrato.
  • Il filtro success assume un valore booleano e può essere utilizzato per filtrare l'estrinseco in base al suo stato di successo.
  • The specVersion filter specifies the spec version range for a substrate block. Gli esempi seguenti descrivono come impostare gli intervalli di versioni.
filter:
  specVersion: [23, 24]   # Index block with specVersion in between 23 and 24 (inclusive).
  specVersion: [100]      # Index block with specVersion greater than or equal 100.
  specVersion: [null, 23] # Index block with specVersion less than or equal 23.
1
2
3
4

# Custom Chains

# Network Spec

When connecting to a different Polkadot parachain or even a custom substrate chain, you'll need to edit the Network Spec section of this manifest.

The genesisHash must always be the hash of the first block of the custom network. You can retireve this easily by going to PolkadotJS (opens new window) and looking for the hash on block 0 (see the image below).

Genesis Hash

Additionally you will need to update the endpoint. This defines the wss endpoint of the blockchain to be indexed - This must be a full archive node. Puoi recuperare gli endpoint per tutte le paracatene gratuitamente da OnFinality (opens new window)

# Chain Types

You can index data from custom chains by also including chain types in the manifest.

We support the additional types used by substrate runtime modules, typesAlias, typesBundle, typesChain, and typesSpec are also supported.

In the v0.2.0 example below, the network.chaintypes are pointing to a file that has all the custom types included, This is a standard chainspec file that declares the specific types supported by this blockchain in either .json, .yaml or .js format.

To use typescript for your chain types file include it in the src folder (e.g. ./src/types.ts), run yarn build and then point to the generated js file located in the dist folder.

network:
  chaintypes:
    file: ./dist/types.js # Will be generated after yarn run build
1
2
3

Things to note about using the chain types file with extension .ts or .js:

  • La tua versione manifest deve essere v0.2.0 o successiva.
  • Solo l'esportazione predefinita verrà inclusa nell'polkadot api (opens new window) durante il recupero dei blocchi.

Here is an example of a .ts chain types file:

# Custom Data Sources

Custom Data Sources provide network specific functionality that makes dealing with data easier. They act as a middleware that can provide extra filtering and data transformation.

A good example of this is EVM support, having a custom data source processor for EVM means that you can filter at the EVM level (e.g. filter contract methods or logs) and data is transformed into structures farmiliar to the Ethereum ecosystem as well as parsing parameters with ABIs.

Custom Data Sources can be used with normal data sources.

Here is a list of supported custom datasources:

Kind Supported Handlers Filters Description
substrate/Moonbeam substrate/MoonbeamEvent, substrate/MoonbeamCall See filters under each handlers Provides easy interaction with EVM transactions and events on Moonbeams networks

# Network Filters

Network filters only applies to manifest spec v0.0.1.

Usually the user will create a SubQuery and expect to reuse it for both their testnet and mainnet environments (e.g Polkadot and Kusama). Between networks, various options are likely to be different (e.g. index start block). Therefore, we allow users to define different details for each data source which means that one SubQuery project can still be used across multiple networks.

Users can add a filter on dataSources to decide which data source to run on each network.

Below is an example that shows different data sources for both the Polkadot and Kusama networks.

Last update: December 1, 2022 23:29