ไฟล์ Manifest

ไฟล์ Manifest project.yaml เป็นจุดเริ่มต้นโปรเจกต์ของคุณ และมันจะกำหนดรายละเอียดส่วนใหญ่ว่า SubQuery จะสร้างดัชนีและแปลงข้อมูลบนระบบอย่างไร

Manifest สามารถใช้เครื่องมือในรูปแบบของ 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

ถ้าหากคุณมีโปรเจกต์ที่ใช้เวอร์ชั่น v0.0.1 คุณสามารถใช้คำสั่ง subql migrate เพื่ออัพเกรดได้อย่างรวดเร็ว ดูที่นี่ สำหรับข้อมูลเพิ่มเติม

ภายใต้ network

• นี่คือฟิลด์ที่ถูกสร้างขึ้นใหม่ required genesisHash ซึ่งจะช่วยให้คุณรู้ว่า กำลังใช้งานอยู่บนระบบเครือข่ายใด
• สำหรับเวอร์ชั่น v0.2.0 หรือสูงกว่า คุณสามารถอ้างอิงถึงไฟล์จากภายนอก chaintype file ถ้าหากคุณกำลังอ้างอิงถึงระบบเครือข่ายที่คุณกำหนดเอง

ภายใต้ dataSources:

• สามารถเชื่อมโยง index.js สำหรับการ mapping handlers โดยพื้นฐาน index.js จะถูกสร้างขึ้นจาก index.ts ในกระบวนการสร้าง
• แหล่งข้อมูลสามารถเป็นได้ทั้งแหล่งข้อมูลทั่วไป หรือ custom data source

CLI Options

โดยค่าเริ่มต้น CLI จะสร้างโปรเจ็กต์ SubQuery สำหรับเวอร์ชัน v0.2.0 การกระทำนี้ สามารถแทนที่ได้โดยการเรียกใช้ subql init --specVersion 0.0.1 PROJECT_NAME แต่อย่างไรก็ตาม เราไม่แนะนำให้ทำ เนื่องจากโปรเจ็กต์จะไม่ได้รับการสนับสนุนโดย SubQuery hosted service ในอนาคต

สามารถเรียกใช้ subql migrate ในโปรเจกต์ที่มีอยู่ เพื่อย้ายไฟล์ Manifest ของโปรเจกต์เป็นเวอร์ชันล่าสุด

การใช้งาน $ subql init [PROJECTNAME]

หมายเหตุ PROJECTNAME ตั้งชื่อโปรเจกต์

| Options | Description | | ----------------------- | ----------------------------------------------------------------------- | -------------------------- | | -f, --force | | | -l, --location=location | ตำแหน่งแฟ้มข้อมูลของโปรเจกต์ | | --install-dependencies | การติดตั้ง | | --npm | บังคับให้ใช้ NPM แทน yarn ใช้งานได้เฉพาะกับ install-dependencies flag | | --specVersion=0.0.1 | 0.2.0 [default: 0.2.0] | เวอร์ชั่นที่ใช้กับโปรเจกต์ |

ภาพรวม

Top Level Spec

Field	v0.0.1	v0.2.0	Description
specVersion	String	String	0.0.1 หรือ 0.2.0 - เวอร์ชั่นของไฟล์ manifest
name	𐄂	String	ชื่อโปรเจกต์ของคุณ
version	𐄂	String	เวอร์ชั่นโปรเจกต์ของคุณ
description	String	String	คำอธิบายโปรเจกต์ของคุณ
repository	String	String	ตำแหน่ง Git repository ของโปรเจกต์คุณ
schema	String	Schema Spec	ตำแหน่งไฟล์ GraphQL schema ของคุณ
network	Network Spec	Network Spec	รายละเอียดของเครือข่ายที่จะถูกนำทำดัชนี
dataSources	DataSource Spec	DataSource Spec

Schema Spec

Field	v0.0.1	v0.2.0	Description
file	𐄂	String	ตำแหน่งไฟล์ GraphQL schema ของคุณ

Network Spec

Field	v0.0.1	v0.2.0	Description
genesisHash	𐄂	String	Genesis Hash ของเครือข่าย
endpoint	String	String	กำหนด wss หรือ ws ปลายทางของ blockchain ที่ต้องการเรียบเรียง - This must be a full archive node คุณสามารถดึงข้อมูลปลายทางได้ใน parachains ได้ฟรีจาก OnFinality
dictionary	String	String	ขอแนะนำให้ระบุ HTTP ปลายทางของระบบ full chain dictionary เพื่อเพิ่มความเร็วในการประมวลผล - อ่าน วิธีการทำงานของ SubQuery
chaintypes	𐄂	{file:String}	เส้นทางไปยังไฟล์เครือข่ายแต่ละประเภท ซึ่งรองรับรูปแบบ .json หรือ .yaml

Datasource Spec

กำหนดข้อมูลที่จะถูก คัดกรอง และ แยกออก จากตำแหน่งของตัวจัดการ mapping function handler สำหรับการแปลงข้อมูลที่จะนำไปใช้

Field	v0.0.1	v0.2.0	Description
name	String	𐄂	ชื่อสำหรับแหล่งข้อูล
kind	substrate/Runtime	substrate/Runtime, substrate/CustomDataSource	ระบบรองรับประเภทข้อมูลจากเริ่มต้นของซับสเตรต เช่น บล็อก เหตุการณ์ และ extrinsic(call)) ตั้งแต่ v0.2.0 ระบบรองรับข้อมูลที่กำหนดเอง เช่น smart contact
startBlock	Integer	Integer	สิ่งนี้จะเปลี่ยนตำแหน่งการเริ่มต้นการจัดทำดัชนีของคุณ ตั้งค่าให้สูงกว่านี้เพื่อข้ามบล็อกเริ่มต้นที่มีข้อมูลน้อยลง
mapping	Mapping Spec	Mapping Spec
filter	network-filters	𐄂	กรองข้อมูลเพื่อดำเนินการตามชื่อข้อมูลเฉพาะของเครือข่าย

Mapping Spec

Field	v0.0.1	v0.2.0	Description
file	String	𐄂	ตำแหน่งไฟล์ของ mapping entry
handlers & filters	Default handlers and filters	Default handlers and filters, Custom handlers and filters	ลิสท์รายการ mapping functions ทั้งหมด และ handler type ที่เกี่ยวข้อง รวมไปถึง mapping filters สำหรับการใช้ custom runtimes mapping handlers กรุณาดูต่อที่ Custom data sources

Data Sources and Mapping

ในส่วนนี้ เราจะพูดถึงการใช้งาน default substrate runtime และการ mapping ซึ่งมีตัวอย่างดังนี้:

dataSources:
  - kind: substrate/Runtime # ระบุค่าเริ่มต้น
    startBlock: 1 # สิ่งนี้จะเปลี่ยนบล็อคการเริ่มต้นการจัดทำดัชนีของคุณ ตั้งค่าให้สูงกว่านี้เพื่อข้ามบล็อกเริ่มต้นที่มีข้อมูลน้อยลง
    mapping:
      file: dist/index.js # เริ่มต้นการ mapping

Mapping Handlers and Filters

จากตารางต่อไปนี้ จะอธิบาย filters ที่รองรับกับ handlers ที่หลากหลาย

โปรเจ็คต์ SubQuery ของคุณจะมีประสิทธิภาพเพิ่มมากขึ้นเป็นอย่างมาก เมื่อคุณเพียงใช้ event และ call handlers ร่วมกับ mapping filters ที่เหมาะสม

Handlers (ตัวดำเนินการ)	Supported filter (ตัวกรองที่รองรับ)
BlockHandler	specVersion
EventHandler	module,method
CallHandler	module,method ,success

Runtime mapping filters เบื้องต้น เป็นฟีเจอร์ที่มีประโยชน์เป็นอย่างมาก ใช้ในการตัดสินใจว่า block, event หรือ extrinsic ใดจะใช้เรียก mapping handler

มีเพียงข้อมูลที่เข้ามาใหม่เท่านั้นที่จะเข้ากับเงื่อนไขในการกรอง และจะถูกประมวลผลโดย mapping functions Mapping filters เป็นตัวเลือกหนึ่ง แต่เราแนะนำเป็นอย่างยิ่งให้ใช้ เนื่องจากจะสามารถลดปริมาณข้อมูลที่จะต้องประมวลผลด้วยโปรเจกต์ SubQuery ของคุณได้มหาศาล และมันจะช่วยเพิ่มประสิทธิภาพในการทำดัชนีข้อมูล

# ตัวอย่าง filter from callHandler
filter:
  module: balances
  method: Deposit
  success: true

• Module และ method filters รองรับบน substrate-based chain ใดๆ
• success filter จะรับค่า boolean และใช้ในการกรอง extrinsic ที่ผ่านสถานะ success
• specVersion filter จะใช้กำหนด spec version ที่อยู่ในช่วงที่กำหนดสำหรับ substrate block ตัวอย่างดังต่อไปนี้จะอธิบายว่าจะกำหนด version ranges ได้อย่างไร

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.

Custom Chains

Network Spec

เมื่อเชื่อมต่อกับ Polkadot parachain หรือแม้แต่ custom substrate chain คุณจำเป็นจะต้องแก้ไขในส่วน Network Spec ของไฟล์ manifest นี้

genesisHash มักจะเป็น hash ของ block แรกในแต่ละเครือข่าย คุณสามารถยกเลิกค่าเหล่านี้ได้ง่ายๆ เพียงไปที่ PolkadotJS และมองหา hash บน block 0 (ดูรูปประกอบด้านล่าง)

นอกจากนี้ คุณจำเป็นจะต้องอัพเดท endpoint กำหนด wss เป็นจุดหมายปลายทางของ blockchain ที่ต้องการทำดัชนี - จำเป็นต้องเป็น full archive node คุณสามารถดึงข้อมูลปลายทางได้ใน parachains ได้ฟรีจาก OnFinality

Chain Types

คุณสามารถทำดัชนีข้อมูลจาก custom chains ได้ โดยการกำหนด chain types ใน manifest

พวกเรารองรับชนิดเพิ่มเติมที่ถูกใช้โดย substrate runtime modules โดยรองรับ typesAlias, typesBundle, typesChain, และ typesSpec

ใน v0.2.0 ตัวอย่างดังต่อไปนี้ network.chaintypes จะถูกชี้ไปที่ไฟล์ที่มี custom types ทั้งหมด นี่จะเป็นมาตรฐานของไฟล์ chainspec ที่ใช้ในการแสดงผลในรูปแบบ blockchain โดยรองรับทั้งรูปแบบ .json, .yaml หรือ .js.

::: 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 :::

หากต้องการใช้ typescript สำหรับเครือข่ายของคุณจะอยู่ใน src แฟ้มข้อมูล (e.g. ./src/types.ts), run yarn build จากนั้นชี้ไปที่ไฟล์ js ที่ถูกสร้างขึ้นซึ่งอยู่ในไฟล์ dist ของแฟ้มข้อมูล

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

สิ่งที่ควรทราบเกี่ยวกับการใช้งาน chain types file ด้วยนามสกุล .ts หรือ .js:

• ไฟล์ manifest version ต้องเป็นเวอร์ชั่น v0.2.0 หรือสูงกว่า
• มีเพียง default export เท่านั้นที่จะถูกรวมไปใน polkadot api เมื่อดึงข้อมูลจาก blocks

นี่คือตัวอย่างของ .ts ไฟล์ chain types:

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

Custom Data Sources

Custom Data Sources จะระบุฟังก์ชันของ network ที่กำหนด ที่จะทำให้จัดการกับข้อมูลได้ง่ายยิ่งขึ้น โดยการทำงานจะทำหน้าที่เสมือนตัวกลาง ที่จะช่วยในการคัดกรองเพิ่มเติมและการนำส่งของข้อมูล

ตัวอย่างที่ดีของอันนี้ คือการรองรับ EVM สามารถมีการประมวลผล data source สำหรับ EVM หมายความว่าคุณสามารถทำการกรองข้อมูลได้ตั้งแต่ระดับ EVM (e.g. กรอง contract methods หรือ logs) และข้อมูลเหล่านั้นจะถูกแปลงเป็นโครงสร้างที่ใกล้เคียงกับ Ethereum ecosystem เฉกเช่นเดียวกับการดึง parameters ด้วย ABIs.

Custom Data Sources สามารถใช้ร่วมกับ normal data sources.

นี่คือรายการ custom datasources ที่รองรับ:

Kind	Supported Handlers	Filters	Description
substrate/Moonbeam	substrate/MoonbeamEvent, substrate/MoonbeamCall	See filters under each handlers	ช่วยให้สื่อสารกับ EVM transaction ได้ง่าย และเหมือนกับที่เกิดขึ้นบน Moonbeams networks

Network Filters

Network filters จะใช้เฉพาะใน manifest spec v0.0.1.

โดยทั่วไปผู้ใช้จะสร้าง SubQuery และจะนำมาใช้ทั้ง testnet และ mainnet environments (e.g. Polkdaot และ Kusama) ระหว่างเครือข่าย ตัวแปรต่างๆ มักจะแตกต่างกัน (เช่น บล็อกเริ่มต้นดัชนี) นอกจากนี้ เราอนุญาติให้ผู้ใช้งานสามารถกำหนดรายละเอียดในแต่ละ data source ได้ นั่นหมายความว่าในหนึ่งโปรเจกต์ SubQuery จะสามารถนำไปใช้ได้หลายเครือข่าย

ผู้ใช้งานสามารถเพิ่ม filter บน dataSources เพื่อเลือกว่า data source ใดจะใช้ในแต่ละเครือข่าย

ด้านล่างนี้คือตัวอย่างที่แสดงแหล่งข้อมูลต่างๆ สำหรับทั้งเครือข่าย 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

:::