マニフェストファイル
マニフェストファイル
マニフェストファイル 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 ```` :::
upgrade
v0.0.1 から v0.2.0 への移行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
:::