マニフェストファイル

マニフェストファイル project.yaml は、プロジェクトのエントリーポイントと見なすことができ、SubQuery がどのようにインデックスを作成し、チェーンデータを変換するかについて詳細を定義します。

マニフェストは YAML または JSON 形式で使用できます。 このドキュメントでは、すべての例で YAML を使用します。 以下は、基本的な project.yaml の例です。

::: code-tabs @tab v0.2.0 yml specVersion: 0.2.0 name: example-project # Provide the project name version: 1.0.0 # Project version description: '' # Description of your project repository: 'https://github.com/subquery/subql-starter' # Git repository address of your project schema: file: ./schema.graphql # The location of your GraphQL schema file network: genesisHash: '0x91b171bb158e2d3848fa23a9f1c25182fb8e20313b2c1eb49219da7a70ce90c3' # Genesis hash of the network endpoint: 'wss://polkadot.api.onfinality.io/public-ws' # Optionally provide the HTTP endpoint of a full chain dictionary to speed up processing dictionary: 'https://api.subquery.network/sq/subquery/dictionary-polkadot' dataSources: - kind: substrate/Runtime startBlock: 1 # This changes your indexing start block, set this higher to skip initial blocks with less data mapping: file: "./dist/index.js" handlers: - handler: handleBlock kind: substrate/BlockHandler - handler: handleEvent kind: substrate/EventHandler filter: #Filter is optional module: balances method: Deposit - handler: handleCall kind: substrate/CallHandler ```` @tab v0.0.1 yml specVersion: "0.0.1" description: '' # Description of your project repository: 'https://github.com/subquery/subql-starter' # Git repository address of your project schema: ./schema.graphql # The location of your GraphQL schema file network: endpoint: 'wss://polkadot.api.onfinality.io/public-ws' # Optionally provide the HTTP endpoint of a full chain dictionary to speed up processing dictionary: 'https://api.subquery.network/sq/subquery/dictionary-polkadot' dataSources: - name: main kind: substrate/Runtime startBlock: 1 # This changes your indexing start block, set this higher to skip initial blocks with less data mapping: handlers: - handler: handleBlock kind: substrate/BlockHandler - handler: handleEvent kind: substrate/EventHandler filter: #Filter is optional but suggested to speed up event processing module: balances method: Deposit - handler: handleCall kind: substrate/CallHandler ```` :::

v0.0.1 から v0.2.0 への移行 upgrade

specVersion v0.0.1 のプロジェクトがあれば、subql migrateを使って素早くアップグレードすることができます。 詳細は こちら を参照

network :

• 使用されているチェーンを識別するのに役立つ genesisHash フィールドが新たに必須となりました。
• v0.2.0 以上では、カスタムチェーンを参照している場合、外部 チェーンタイプ ファイル を参照できます。

dataSources :

• マッピングハンドラの index.js エントリポイントを直接リンクすることができます。 デフォルトでは、この index.js は、ビルド プロセス中に index.ts から生成されます。
• データソースは、通常のランタイムデータソースまたは カスタムデータソースのいずれかになります。

コマンドラインオプション

デフォルトでは、CLI は verison v0.2.0 の SubQuery プロジェクトを生成します。 この動作は subql init --specVersion 0.0.1 PROJECT_NAME を実行することで上書きできますが、これは将来的に SubQuery ホストサービスでサポートされないプロジェクトになるためお勧めしません。

subql migration は既存のプロジェクトで実行して、プロジェクトマニフェストを最新バージョンに移行できます。

使い方 $ subql init [PROJECTNAME]

引数 PROJECTNAME プロジェクト名を指定する

| オプション | 説明 | | ----------------------- | ------------------------------------------------------------------------------------------ | -------------------------------- | | -f, --force | | | -l, --location=location | プロジェクトを作成するローカルフォルダ | | --install-dependencies | 依存関係をインストールする | | --npm | yarn の代わりに NPM を強制的に使用し、install-dependenciesフラグでのみ機能するようにする | | --specVersion=0.0.1 | 0.2.0 [デフォルト: 0.2.0] | プロジェクトで使用するバージョン |

概要

最上位の仕様

フィールド	v0.0.1	v0.2.0	説明
specVersion	String	String	0.0.1 または 0.2.0 - マニフェストファイルバージョン
name	𐄂	String	プロジェクト名
version	𐄂	String	プロジェクトのバージョン
description	String	String	あなたのプロジェクトの説明
repository	String	String	プロジェクトの Git リポジトリアドレス
schema	String	Schema Spec	GraphQL スキーマファイルの場所
network	Network Spec	Network Spec	インデックスを作成するネットワークの詳細
dataSources	DataSource Spec	DataSource Spec

Schema の仕様

フィールド	v0.0.1	v0.2.0	説明
file	𐄂	String	GraphQL スキーマファイルの場所

Network の仕様

フィールド	v0.0.1	v0.2.0	説明
genesisHash	𐄂	String	ネットワークの生成ハッシュ
endpoint	String	String	インデックスを生成するブロックチェーンの wss または ws エンドポイントを定義します - これはフルアーカイブノード でなければなりません。 OnFinalityでは、すべてのパラチェーンのエンドポイントを無料で取得できます。
dictionary	String	String	処理を高速化するために、フルチェーンディクショナリの HTTP エンドポイントを提供することが推奨されます。 SubQuery Dictionary の仕組みを参照してください。
chaintypes	𐄂	{file:String}	チェーンタイプファイルへのパス。 .json または .yaml 形式を使用してください。

Datasource の仕様

フィルターされ抽出されるデータと、適用されるデータ変換のためのマッピング関数ハンドラーの場所を定義します。

フィールド	v0.0.1	v0.2.0	説明
name	String	𐄂	データソースの名前
kind	substrate/Runtime	substrate/Runtime, substrate/CustomDataSource	デフォルトの substrate ランタイムから、ブロック、イベント、外部関数(コール)などのデータタイプをサポートしています。 v0.2.0 からは、スマートコントラクトなどのカスタムランタイムからのデータをサポートします。
startBlock	Integer	Integer	インデックス開始ブロックを変更します。高く設定すれば初期ブロックをスキップするため、より少ないデータになります。
mapping	Mapping Spec	Mapping Spec
filter	network-filters	𐄂	ネットワークエンドポイントの仕様名で実行するデータソースをフィルタします。

Mapping の仕様

フィールド	v0.0.1	v0.2.0	説明
file	String	𐄂	マッピングエントリへのパス
handlers & filters	デフォルトのハンドラとフィルタ	デフォルトのハンドラとフィルタ、 カスタムハンドラとフィルタ	追加のマッピングフィルタを使用して、すべての マッピング関数 とそれに対応するハンドラータイプをリストします。 カスタムランタイムマッピングハンドラについては、 カスタムデータソース を参照してください。

データソースとマッピング

このセクションでは、デフォルトの Substrate ランタイムとそのマッピングについて説明します。 次に例を示します。

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

デフォルトのハンドラとフィルタ

以下の表では、異なるハンドラでサポートされているフィルタについて説明します。

SubQuery プロジェクトは、イベントと適切なマッピングフィルタを使用するだけで、より効率的になります。

ハンドラ	サポートされるフィルタ
BlockHandler	specVersion
EventHandler	module,method
CallHandler	module,method ,success

デフォルトのランタイムマッピングフィルタは、どのブロック、イベント、または外部のどちらがマッピングハンドラをトリガーするかを決定するために非常に便利な機能です。

フィルター条件を満たす受信データのみがマッピング関数により処理されます。 マッピングフィルタはオプションですが、SubQuery プロジェクトによって処理されるデータの量を大幅に削減し、インデックス作成のパフォーマンスを向上させるために強く推奨されます。

# Example filter from callHandler
filter:
  module: balances
  method: Deposit
  success: true

• モジュールとメソッドフィルタは、Substrate-based chain でサポートされています。
• success フィルタはブール値を取り、成功状況によって外部値をフィルタリングするために使用できます。
• specVersion フィルタは、Substrate ブロックの仕様バージョン範囲を指定します。 以下の例では、バージョン範囲を設定する方法を説明します。

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.

カスタムチェーン

Network の仕様

別の Polkadot parachain やカスタム substrate チェーンに接続する場合は、このマニフェストの Network の仕様 セクションを編集する必要があります。

genesisHash は常にカスタムネットワークの最初のブロックのハッシュでなければなりません。 PolkadotJS にアクセスして、block 0 のハッシュを探せば、これを簡単に探すことができます（下の画像参照）。

さらに、 エンドポイント を更新する必要があります。 インデックスを作成するブロックチェーンの wss または ws エンドポイントを定義します - これは フルアーカイブノード でなければなりません。 OnFinalityでは、すべてのパラチェーンのエンドポイントを無料で取得できます。

チェーンタイプ

マニフェストにチェーンタイプを含めることで、カスタムチェーンからのデータのインデックスを作成できます。

substrate ランタイムモジュールで使用される追加の型をサポートしています。 typesAlias、 typesBundle、typesChain、typesSpecもサポートされています。

以下の v0.2.0 の例では、network.chaintypesは、すべてのカスタムタイプが含まれているファイルを指しています。 これは、このブロックチェーンがサポートする特定のタイプを.jsonまたは.yaml形式で宣言する標準的なチェーンスペックファイルです。

::: code-tabs @tab v0.2.0 yml network: genesisHash: '0x91b171bb158e2d3848fa23a9f1c25182fb8e20313b2c1eb49219da7a70ce90c3' endpoint: 'ws://host.kittychain.io/public-ws' chaintypes: file: ./types.json # The relative filepath to where custom types are stored ... @tab v0.0.1 yml ... network: endpoint: "ws://host.kittychain.io/public-ws" types: { "KittyIndex": "u32", "Kitty": "[u8; 16]" } # typesChain: { chain: { Type5: 'example' } } # typesSpec: { spec: { Type6: 'example' } } dataSources: - name: runtime kind: substrate/Runtime startBlock: 1 filter: #Optional specName: kitty-chain mapping: handlers: - handler: handleKittyBred kind: substrate/CallHandler filter: module: kitties method: breed success: true :::

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

拡張子が .ts または .js のチェーンタイプファイルを使用する場合の注意 :

• マニフェストのバージョンは v0.2.0 以上である必要があります。
• ブロック取得時にpolkadot apiに含まれるのは、デフォルトのエクスポートのみとなります。

以下は、 .ts チェーンタイプファイルの例です:

::: code-tabs @tab types.ts ts import { typesBundleDeprecated } from "moonbeam-types-bundle" export default { typesBundle: typesBundleDeprecated }; :::

カスタムデータソース

カスタムデータソースは、データの取り扱いを容易にするネットワーク固有の機能を提供します。

その良い例が EVM のサポートです。 EVM 用のカスタムデータソースプロセッサを持つことは、EVM レベルでのフィルタリング（コントラクトメソッドやログのフィルタリングなど）ができることを意味し、データは ABI でパラメータを解析するだけでなく、Ethereum のエコシステムに馴染みのある構造に変換されます。

カスタムデータソースは、通常のデータソースと併用することができます。 .

サポートされているカスタムデータソースの一覧です。

種類	サポートされているハンドラ	フィルタ	説明
substrate/Moonbeam	substrate/MoonbeamEvent, substrate/MoonbeamCall	See filters under each handlers	Moonbeams ネットワーク上の EVM トランザクションおよびイベントとの容易なインタラクションを提供します

ネットワークフィルタ

**ネットワークフィルタは、マニフェスト仕様 v0.0.1 にのみ適用されます。 **.

通常、ユーザーは SubQuery を作成し、それをテストネットとメインネットの両方の環境で再利用することを想定しています。 （例：Polkadot や Kusama など） ネットワーク間では、さまざまなオプションが異なる可能性があります。(インデックス開始ブロックなど) そのため、データソースごとに異なる詳細を定義することができ、1 つの SubQuery プロジェクトが複数のネットワークで使用できるようになっています。

ユーザーは、dataSourcesにfilterを追加して、各ネットワークで実行するデータソースを決定することができます。

以下は Polkadot と Kusama ネットワークの異なるデータソースを示す例です。

::: code-tabs @tab v0.0.1 yaml --- network: endpoint: 'wss://polkadot.api.onfinality.io/public-ws' #Create a template to avoid redundancy definitions: mapping: &mymapping handlers: - handler: handleBlock kind: substrate/BlockHandler dataSources: - name: polkadotRuntime kind: substrate/Runtime filter: #Optional specName: polkadot startBlock: 1000 mapping: *mymapping #use template here - name: kusamaRuntime kind: substrate/Runtime filter: specName: kusama startBlock: 12000 mapping: *mymapping # can reuse or change

:::