Skip to main content

Terra Бързо Стартиране

SubQuery TeamAbout 6 min

Terra Бързо Стартиране

В това ръководство за бърз старт ще започнем с прост стартов проект на Terra и след това ще завършим, като индексираме някои действителни реални данни. Това е перфекта основа, с която да започнете при разработка свой собствен проект SubQuery.

Ако търсите ръководства за Substrate/Polkadot, можете да прочетете Специфичното за субстрат/Polkadot ръководство за бързо начало.

В края на това ръководство ще получите работещ SubQuery проект, стартиран върху нодата SubQuery и с крайна точка GraphQL, от която можете да изисквате необходими данни.

Ако все още не сте го направили, ви предлагаме да разгледате терминологиятаизползвана в SubQuery.

Целта на това ръководство за бързо стартиране е да адаптира стандартния стартов проект, за да започне индексирането на всички трансфери от Terra, трябва да отнеме само 10-15 минути

Подготовка

Локална Среда за Разработка

Инсталирайте SubQuery CLI

Инсталирайте SubQuery CLI глобално на вашият терминал с помощта на NPM:

# NPM
npm install -g @subql/cli

Обърнете внимание, ние НЕ препоръчваме използването на yarn global за инсталиране на @subql/cli поради лошото управление на зависимостите, което може да доведе до грешки в бъдеще.

След това можете да стартирате помощ, за да видите наличните команди и начините на използване, предоставени от CLI

subql помощ

Инициализиране на Стартов Проект в SubQuery

Вътре в директорията, в която искате да създадете проект SubQuery, изпълнете следната команда, за да започнете.

subql init

Ще ви бъдат зададени някои въпроси, по време на инициализирането на проекта SubQuery:

  • Project Name: A name for your SubQuery project
  • Мрежово семейство: Блокчейн мрежовото семейство от слой 1, което този проект SubQuery ще бъде разработен за индексиране, използвайте клавишите със стрелки на клавиатурата си, за да изберете от опциите, за това ръководство ще използваме „Terra“
  • Мрежа: Конкретната мрежа, която този проект SubQuery ще бъде разработен за индексиране, използвайте клавишите със стрелки на клавиатурата си, за да изберете от опциите, за това ръководство ще използваме „Terra“
  • Template: Изберете шаблон за проекта SubQuery, който ще служи като начална точка за започване на разработка, предлагаме да изберете "Starter project"
  • Git repository (опционално): посочете Git URL хранилище, в което ще се съхранява този проект SubQuery (при разполагане в SubQuery Explorer)
  • RPC endpoint (Необходимо): Укажете HTTPS URL за работеща крайна точка RPC която ще бъде използвана по подразбиране за този проект. Този вид нода RPC трябва да представлява архивна нода (да има състояние на пълна веригата). За това ръководство ще използваме стойността по подразбиране "https://terra-columbus-5.beta.api.onfinality.io"
  • Authors (задължително): въведете собственика на този проект за SubQuery тук (например вашето име!)
  • Description (опционално): можете да предоставите кратко описание за вашия проект, който описва какви данни съдържа и какво могат да правят потребителите с него
  • Version (Задължително): въведете свой персонализиран номер на версията или използвайте стойността по подразбиране (1.0.0)
  • License (задължително): предоставете софтуерен лиценз за този проект или потвърдете такъв по подразбиране (Apache-2.0)

След като процесът на инициализация приключи, трябва да видите, че в директорията е създадена папка с името на вашия проект. Съдържанието на тази директория трябва да бъде идентично с посоченото в Структурата на директорията.

И накрая, в директорията на проекта изпълнете следната команда, за да инсталирате зависимостите на новия проект.

::: code-tabs @tab:active yarn shell cd PROJECT_NAME yarn install @tab npm shell cd PROJECT_NAME npm install :::

Промени във вашият проект

В стартовия пакет, който току-що инициализирахте, ние сме предоставили стандартна конфигурация за вашия нов проект. Основно ще работите върху следните файлове:

  1. Схема GraphQL schema.graphql
  2. Манифест на проекта в project.yaml
  3. Показване на Функции в директорията src/mappings/

Целта на това ръководство за бързо стартиране е да адаптира стандартния стартов проект, за да започне индексирането на всички трансфери от интелигентния договор bLuna.

Актуализиране на вашия файл със схема на GraphQL

Файлът schema.graphql дефинира различните схеми на GraphQL. В зависимост от начина, по който работи езикът за заявки GraphQL, файлът със схемата по същество диктува формата на вашите данни от SubQuery. Това е страхотно място за начало, защото ви позволява предварително да дефинирате крайната си цел.

Щв актуализираме файла schema.graphql за да го прочетете, както следва

type Transfer @entity {
  id: ID! # id полето винаги е задължително и трябва да изглежда така
  txHash: String!
  blockHeight: BigInt # Височината на блока на трансфера
  sender: String! # Акаунт, от който се извършват преводите
  recipient: String! # Акаунт, към който се извършват преводите
  amount: String! # Сума, която се превежда
}

Важно: Когато правите промени във файла schema, моля, уверете се, че отново сте създали директорията си с типове със следната команда yarn codegen. Направете го сега.

::: code-tabs @tab:active yarn shell yarn codegen @tab npm shell npm run-script codegen :::

Ще намерите генирираните модели в директорията /src/types/models. За повече информация относно файла schema.graphql, проверете нашата документация в раздела Build/GraphQL Schema

Обновяване на файла Project Manifest

Файлът Projet Manifest (project.yaml) може да се разглежда като начална точка за вашия проект, той определя повечето подробности за това как SubQuery ще индексира и трансформира данните от веригата.

Няма да правим много промени във файла на манифеста, тъй като той вече е настроен правилно, но трябва да променим нашите handlers. Не забравяйте, че планираме да индексираме всички събития за трансфер на Terra, в резултат на което трябва да актуализираме секцията datasources, за да прочетем следното.

dataSources:
  - kind: terra/Runtime
    startBlock: 4724001 # Colombus-5 Starts at this height
    mapping:
      file: ./dist/index.js
      handlers:
        - handler: handleEvent
          kind: terra/EventHandler
          # това ще се задейства при всички събития, които съответстват на следното условие за филтър за интелигентен договор
          filter:
            type: transfer
            messageFilter:
              type: /terra.wasm.v1beta1.MsgExecuteContract
              values:
                # Ние се абонираме за интелигентния договор bLuna (напр. само прехвърляне на събития от този договор)
                contract: terra1j66jatn3k50hjtg2xemnjm8s7y8dws9xqa5y8w

Това означава, че ще стартираме функция за съпоставяне handleEvent всеки път, когато има събитие transfer от интелигентния договор на bLuna.

За повече информация относна файла Project Manifest (project.yaml), проверете документацията ни в раздела Build/Manifest File

Добавяне на Mappring функция

Mapping функциите определят как данните от веригата се трансформират в оптимизирани обекти GraphQL, които по-рано сме дефинирали във файла schema.graphql.

Преминете към функцията за картографиране по подразбиране в директорията src/mappings. Ще забележите три експортирани функции, handleBlock, handleEvent, and handleCall. Може да изтриете двете функции handleBlock и handleCall, ще продължим работа само с функцията handleEvent.

Функцията handleEvent получава данни всеки път, когато събитието е съответствало на филтрите, които сме указали в project.yaml. Ще го актуализираме, за да обработим всички събития transfer и да ги запазим в GraphQL обектите, които създадохме по-рано.

Може да актуализирате функцията handleEvent по следният начин (обърнете внимание на допълнителния импорт):

import { TerraEvent } from "@subql/types-terra";
import { Transfer } from "../types";
import { MsgExecuteContract } from "@terra-money/terra.js";

export async function handleEvent(
  event: TerraEvent<MsgExecuteContract>
): Promise<void> {
  // Print debugging data from the event
  // logger.info(JSON.stringify(event));

  // Create the new transfer entity with a unique ID
  const transfer = new Transfer(
    `${event.tx.tx.txhash}-${event.msg.idx}-${event.idx}`
  );
  transfer.blockHeight = BigInt(event.block.block.block.header.height);
  transfer.txHash = event.tx.tx.txhash;
  for (const attr of event.event.attributes) {
    switch (attr.key) {
      case "sender":
        transfer.sender = attr.value;
        break;
      case "recipient":
        transfer.recipient = attr.value;
        break;
      case "amount":
        transfer.amount = attr.value;
        break;
      default:
    }
  }
  await transfer.save();
}

Това, което прави, е получаване на SubstrateEvent, който включва данни за прехвърляне на payload. Ние извличаме тези данни и след това създаваме нов обект Transfer, който сме определили по-рано във файла schema.graphql. Добавяме допълнителна информация и след това използваме функцията .save() за запазване на новият обект (SubQuery автоматично ще го съхрани в базата данни).

За повече информация относно mapping функциите вижте нашата документация подBuild/Mappings

Изграждане на проект

За да стартираме вашия нов проект SubQuery, първо трябва да изградим нашата работа. Изпълнете командата за изграждане от основната директория на проекта.

::: code-tabs @tab:active yarn shell yarn build @tab npm shell npm run-script build :::

** Важно: Всеки път, когато правите промени във вашите mapping функции, ще трябва да изградите отново своя проект**

Стартиране и запитване във вашия проект

Стартиране на вашия проект с Docker

Всеки път, когато създавате нов проект на SubQuery, винаги трябва да го стартирате локално на вашия компютър, за да го тествате първо. Най-лесният начин да се направи това е чрез Docker.

Всички конфигурации, които контролират изпълнението на нодата SubQuery, са дефинирани в този файл docker-compose.yml. За нов проект, който току-що беше инициализиран, няма да е необходимо да променяте нищо, но можете да прочетете повече за файла и настройките в нашата Секция за стартиране на Проекта

В директорията на проекта изпълнете следната команда:

::: code-tabs @tab:active yarn shell yarn start:docker @tab npm shell npm run-script start:docker :::

Изтеглянето на необходимите пакети може да отнеме известно време (@subql/nodeopen in new window, @subql/queryopen in new window, and Postgres) за първи път, но скоро ще видите работеща нода SubQuery. Бъдете търпеливи.

Направете заявка за вашият проект

Отворете браузъра си и отидете на http://localhost:3000open in new window.

Трябва да може да видите платформа GraphQL, показана в explorer, и готовите за заявка схеми. В горния десен ъгъл на playground ще намерите бутон Docs, който ще отвори чертеж с документация. Тази документация се генерира автоматично и ви помага да намерите за какви обекти и методи можете да направите заявка.

За нов стартов SubQuery проект можете да опитате следната заявка, за да получите представа как работи или научете повече относно езика за заявки GraphQL .

{
  query {
    transfers(first: 10, orderBy: ID_DESC) {
      nodes {
        id
        txHash
        amount
        blockHeight
        sender
        recipient
      }
    }
  }
}

Публикувайте своя SubQuery проект

SubQuery предоставя безплатна управлявана услуга, с помощта който можете да разгърнете новия си проект. Може да го разгърнете в SubQuery Managed Serviceopen in new window и да направите запитване с помощта на нашият Exploreropen in new window.

Прочетете ръководството, за да публикувате новия си проект в SubQuery Projects

Следващите стъпки

Поздравления, вече имате локално работещ SubQuery проект, който приема заявки за GraphQL API за прехвърляне на данни от bLuna.

Сега, когато имате представа как се изгражда базисен SubQuery проект, възниква въпросът: какво да правите по-нататък? Ако се чувствате уверени, можете да започнете да научите повече за трите ключови файла. Файлът на манифеста, схемата GraphQL и mapping файл за съпоставяне в секцията за изграждане на тези документи.

В противен случай продължете към раздел Академия, където ще намерите повече обучителни семинари, уроци и примерни проекти. Там ще разгледаме по-разширени модификации и ще се потопим по-дълбоко в изпълнението на проекти на SubQuery, като стартираме лесно достъпни проекти с отворен код.

И накрая, ако търсите повече начини да стартирате и публикувате вашия проект, нашият Run & Раздел за публикуване предоставя подробна информация за всички начини за стартиране на вашия проект SubQuery и други разширени функции за агрегиране и абонамент на GraphQL.