Tệp Manifest

... 2022-10-5 Khoảng 11 phút

# Tệp Manifest

Tệp Manifest project.yaml có thể được xem như một điểm đầu vào cho dự án của bạn, và nó định nghĩa hầu hết các chi tiết về cách SubQuery sẽ lập chỉ mục và chuyển đổi dữ liệu chuỗi.

Tệp kê khai có thể ở định dạng YAML hoặc JSON. Trong tài liệu này, chúng tôi sẽ sử dụng YAML trong tất cả các ví dụ. Dưới đây là ví dụ tiêu chuẩn về project.yaml cơ bản.

# Di chuyển từ v0.0.1 sang v0.2.0upgrade

**Nếu bạn có một dự án với specVersion v0.0.1, bạn có thể sử dụng subql migrate để nâng cấp nhanh chóng. Xem tại đây để biết thêm thông tin **

Trong network:

  • Có một trường mới ** bắt buộc ** genesisHash giúp xác định chuỗi đang được sử dụng.
  • Đối với v0.2.0 trở lên, bạn có thể tham chiếu đến chaintype file bên ngoài nếu bạn đang tham chiếu đến một chuỗi tùy chỉnh.

Trong dataSources:

  • Có thể liên kết trực tiếp điểm vào index.js cho các trình xử lý ánh xạ. Theo mặc định, index.js này sẽ được tạo từ index.ts trong quá trình xây dựng.
  • Nguồn dữ liệu có thể là nguồn dữ liệu runtime thông thường hoặc nguồn dữ liệu tùy chỉnh.

# Tùy chọn CLI

Theo mặc định, CLI sẽ tạo các dự án SubQuery theo phiên bản v0.2.0. Thao tác này có thể bị ghi đè bằng cách chạy subql init --specVersion 0.0.1 PROJECT_NAME, mặc dù điều này không được khuyến khích vì dự án sẽ không được hỗ trợ bởi dịch vụ lưu trữ SubQuery trong tương lai

subql migrate có thể giúp chuyển tệp manifest (của một dự án đã có sẵn) lên phiên bản mới nhất.

USAGE $ subql init [PROJECTNAME]

ARGUMENTS PROJECTNAME Give the starter project name

Các Tùy chọn Mô tả
-f, --force
-l, --location=location thư mục cục bộ để chứa dự án tạo ra
-install-dependencies Cài đặt các phần phụ thuộc
--npm Buộc sử dụng NPM thay vì yarn, chỉ hoạt động với install-dependencies flag
--specVersion=0.0.1 0.2.0 [mặc định: 0.2.0]

# Tổng quan

# Thông số kỹ thuật cấp cao nhất

Trường v0.0.1 v0.2.0 Mô tả
specVersion String String 0.0.1 or 0.2.0 - thông số kỹ thuật phiên bản của tệp manifest
name String String Tên của dự án
version String String Phiên bản dự án của bạn
description String String Mô tả dự án của bạn
repository String String Địa chỉ kho lưu trữ Git của dự án của bạn
schema String Schema Spec Vị trí tệp GraphQL schema của bạn
network Network Spec Network Spec Chi tiết của mạng được lập chỉ mục
dataSources DataSource Spec DataSource Spec

# Schema Spec

Trường v0.0.1 v0.2.0 Mô tả
file String String Vị trí tệp GraphQL schema của bạn

# Network Spec

Trường v0.0.1 v0.2.0 Mô tả
genesisHash String String Hàm băm gốc của mạng
endpoint String String Xác định điểm cuối ws hoặc wss của chuỗi khối được lập chỉ mục - Đây phải là một full archive node. Bạn có thể truy xuất miễn phí các điểm cuối cho tất cả các parachain từ OnFinality (opens new window)
dictionary String String Cung cấp điểm cuối HTTP của full chain dictionary để tăng tốc độ xử lý - đọc cách để SubQuery dictionary hoạt động.
chaintypes String {file:String} Đường dẫn đến tệp types, chấp nhận định dạng .json hoặc .yaml

# Thông số kỹ thuật Data Source

Định nghĩa phần dữ liệu sẽ được lọc và trích xuất và vị trí của trình xử lý hàm ánh xạ để áp dụng chuyển đổi dữ liệu.

Trường v0.0.1 v0.2.0 Mô tả
name String String Tên của nguồn dữ liệu
kind substrate/Runtime substrate/Runtime, substrate/CustomDataSource Chúng tôi hỗ trợ các kiểu dữ liệu mặc định của Substrate runtime, chẳng hạn như khối, sự kiện và phần bổ sung (gọi).
Từ v0.2.0, chúng tôi hỗ trợ dữ liệu runtime tùy chỉnh, chẳng hạn như smart contract.
startBlock Integer Integer Thao tác này sẽ thay đổi khối bắt đầu lập chỉ mục, đặt khối này cao hơn để bỏ qua khối ban đầu với ít dữ liệu hơn
mapping Thông số kỹ thuật ánh xạ Thông số kỹ thuật ánh xạ
filter network-filters String Lọc nguồn dữ liệu để thực thi theo tên thông số điểm cuối mạng

# Thông số kỹ thuật ánh xạ

Trường v0.0.1 v0.2.0 Mô tả
file String String Đường dẫn đến mục nhập ánh xạ
handlers & filters Default handlers and filters Default handlers and filters,
Custom handlers and filters
Liệt kê tất cả hàm ánh xạ và các hàm xử lý tương ứng của chúng, với các bộ lọc ánh xạ bổ sung.

Đối với hàm xử lý ánh xạ runtime tùy chỉnh, vui lòng xem Nguồn dữ liệu tùy chỉnh

# Nguồn dữ liệu và ánh xạ

Trong phần này, chúng ta sẽ nói về Substrate runtime thông thường và ánh xạ của nó. Đây là một ví dụ:

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

# Trình xử lý ánh xạ và bộ lọc

Bảng sau giải thích các bộ lọc được hỗ trợ bởi các trình xử lý khác nhau.

Dự án SubQuery của bạn sẽ hiệu quả hơn nhiều khi bạn sử dụng trình xử lý sự kiện và cuộc gọi với các bộ lọc ánh xạ thích hợp

Hàm xử lý Bộ lọc được hỗ trợ
BlockHandler specVersion
EventHandler module,method
CallHandler module,method ,success

Bộ lọc ánh xạ runtime mặc định là một tính năng cực kỳ hữu ích để quyết định khối, sự kiện hoặc thông tin ngoại lai nào sẽ kích hoạt trình xử lý ánh xạ.

Chỉ dữ liệu đến thỏa mãn các điều kiện lọc mới được xử lý bởi các hàm ánh xạ. Bộ lọc ánh xạ tuy không bắt buộc nhưng được khuyên dùng vì chúng làm giảm đáng kể lượng dữ liệu được xử lý bởi dự án sử dụng SubQuery của bạn và giúp cải thiện hiệu suất lập chỉ mục.

# Ví dụ từ callHandler
filter:
  module: balances
  method: Deposit
  success: true
1
2
3
4
5
  • Module và phương pháp lọc được hỗ trợ trên bất kỳ Substrate chain nào.
  • Bộ lọc success nhận một giá trị boolean và có thể được sử dụng để lọc phần bên ngoài theo trạng thái thành công của nó.
  • Bộ lọc specVersion chỉ định phạm vi phiên bản cụ thể cho Substrate block. Các ví dụ sau đây mô tả cách đặt phạm vi phiên bản.
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

# Chuỗi tùy chỉnh

# Thông số kỹ thuật mạng

Khi kết nối với một parachain Polkadot khác hoặc một Substrate chain tùy chỉnh, bạn sẽ cần chỉnh sửa phần Thông số mạng của tệp manifest này.

Hàm genesisHash phải luôn là hàm băm cho block đầu tiên của mạng tùy chỉnh. Bạn có thể gỡ bỏ điều này một cách dễ dàng bằng cách truy cập PolkadotJS (opens new window) và tìm mã băm trên khối 0 (xem hình ảnh bên dưới).

Genesis Hash

Ngoài ra, bạn sẽ cần cập nhật điểm cuối. Xác định điểm cuối wss hoặc ws của chuỗi khối được lập chỉ mục - Đây phải là một nút lưu trữ đầy đủ. Bạn có thể truy xuất miễn phí các điểm cuối cho tất cả các parachain từ OnFinality (opens new window)

# Các loại chuỗi

Bạn có thể lập chỉ mục dữ liệu từ các chuỗi tùy chỉnh bằng cách bao gồm các loại chuỗi trong manifest.

Chúng tôi hỗ trợ các kiểu bổ sung được sử dụng bởi các module Substrate runtime, typeAlias​, typeBundle, typeChaintypeSpec cũng được hỗ trợ.

Trong ví dụ v0.2.0 bên dưới, network.chaintypes đang trỏ đến một tệp có tất cả các loại tùy chỉnh được nhúng vào, Đây là tệp chainpec tiêu chuẩn khai báo các kiểu cụ thể được hỗ trợ bởi chuỗi khối này trong cả định dạng .json, .yaml hoặc .js.

Để sử dụng typescript cho các loại chuỗi của bạn, hãy bao gồm tệp đó trong thư mục src (ví dụ: ./src/types.ts), chạy yarn build và sau đó trỏ đến tệp js đã tạo nằm trong thư mục dist.

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

Những điều cần lưu ý khi sử dụng tệp loại chuỗi có phần mở rộng .ts hoặc .js:

  • Phiên bản manifest của bạn phải từ v0.2.0 trở lên.
  • Chỉ xuất mặc định sẽ được đưa vào polkadot api (opens new window) khi tìm nạp các khối.

Đây là ví dụ về tệp loại chuỗi .ts:

# Nguồn dữ liệu tùy chỉnh

Nguồn dữ liệu tùy chỉnh cung cấp chức năng cụ thể của mạng giúp việc xử lý dữ liệu dễ dàng hơn. Chúng hoạt động như một phần mềm trung gian có thể cung cấp thêm khả năng lọc và chuyển đổi dữ liệu.

Một ví dụ điển hình về điều này là hỗ trợ EVM, có bộ xử lý nguồn dữ liệu tùy chỉnh cho EVM có nghĩa là bạn có thể lọc ở cấp EVM (ví dụ: lọc các phương pháp hợp đồng hoặc nhật ký) và dữ liệu được chuyển đổi thành các cấu trúc trang trại riêng cho hệ sinh thái Ethereum cũng như các tham số phân tích cú pháp với ABIs.

Nguồn dữ liệu tùy chỉnh có thể được sử dụng với các nguồn dữ liệu thông thường.

Dưới đây là danh sách các nguồn dữ liệu tùy chỉnh được hỗ trợ:

Kind Trình xử lý được hỗ trợ Bộ lọc Mô tả
substrate/Moonbeam substrate/MoonbeamEvent, substrate/MoonbeamCall Xem các bộ lọc dưới mỗi trình xử lý Cung cấp khả năng tương tác dễ dàng với các giao dịch và sự kiện EVM trên mạng Moonbeams

# Bộ lọc mạng

Bộ lọc mạng chỉ áp dụng cho thông số tệp manifest v0.0.1.

Thông thường người dùng sẽ tạo SubQuery và mong muốn sử dụng lại nó cho cả môi trường testnet và mainnet của họ (ví dụ: Polkadot và Kusama). Giữa các mạng, nhiều tùy chọn có thể có sự khác biệt (ví dụ: khối bắt đầu lập chỉ mục). Do đó, chúng tôi cho phép người dùng xác định các chi tiết khác nhau cho từng nguồn dữ liệu, có nghĩa là một dự án SubQuery vẫn có thể được sử dụng trên nhiều mạng.

Người dùng có thể thêm filter trên dataSources để quyết định nguồn dữ liệu nào sẽ chạy trên mỗi mạng.

Dưới đây là một ví dụ hiển thị các nguồn dữ liệu khác nhau cho cả mạng Polkadot và Kusama.

Cập nhật gần nhất lúc: October 5, 2022 01:44