Docs
⌘ K

7 минуты

Создание субграфов на NEAR

Это руководство является введением в создание субграфов для индексирования смарт-контрактов на блокчейне NEAR⁠.

Что такое NEAR?

NEAR⁠ — это платформа для смарт-контрактов, предназначенная для создания децентрализованных приложений. Для получения дополнительной информации ознакомьтесь с официальной документацией⁠.

Что такое субграфы NEAR?

The Graph предоставляет разработчикам инструменты для обработки событий блокчейна и предоставления полученных данных через API GraphQL, который называется субграфом. Graph Node⁠ теперь может обрабатывать события NEAR, что означает, что разработчики на платформе NEAR могут создавать субграфы для индексирования своих смарт-контрактов.

Субграфы основаны на событиях, что означает, что они слушают и затем обрабатывают события с блокчейна. В настоящее время для субграфов NEAR поддерживаются два типа обработчиков:

  • Обработчики блоков: они запускаются для каждого нового блока
  • Обработчики поступлений: запускаются каждый раз, когда сообщение выполняется в указанной учетной записи

Из документации NEAR⁠:

Поступление - это единственный объект, к которому можно применить действие в системе. Когда мы говорим об “обработке транзакции” на платформе NEAR, это в конечном итоге означает “применение поступлений” в какой-то момент.

Создание NEAR субграфа

@graphprotocol/graph-cli — это инструмент командной строки для создания и развертывания субграфов.

@graphprotocol/graph-ts — это библиотека типов, специфичных для субграфов.

Для разработки субграфа NEAR требуется версия graph-cli выше 0.23.0 и версия graph-ts выше 0.23.0.

Создание субграфа NEAR очень похоже на создание субграфа, индексирующего Ethereum.

Существует три аспекта определения субграфов:

subgraph.yaml: манифест субграфа, который определяет интересующие источники данных и то, как они должны обрабатываться. NEAR является новым kind (типом) источника данных.

schema.graphql: файл схемы, который определяет, какие данные хранятся для вашего субграфа, и как их можно запрашивать через GraphQL. Требования для субграфов NEAR описаны в существующей документации.

Мэппинги на AssemblyScript: код на AssemblyScript, который преобразует данные событий в элементы, определенные в Вашей схеме. Поддержка NEAR вводит специфичные для NEAR типы данных и новую функциональность для парсинга JSON.

Во время разработки субграфа есть две ключевые команды:

$ graph codegen # генерирует типы из файла схемы, указанного в манифесте$ graph build # генерирует Web Assembly из файлов AssemblyScript и подготавливает все файлы субграфа в папке /build

Определение манифеста субграфа

Манифест субграфа (subgraph.yaml) идентифицирует источники данных для субграфа, триггеры интересующих событий и функции, которые должны быть выполнены в ответ на эти триггеры. Ниже приведен пример манифеста субграфа для субграфа NEAR:

specVersion: 1.3.0schema:  file: ./src/schema.graphql # ссылка на файл схемыdataSources:  - kind: near    network: near-mainnet    source:      account: app.good-morning.near # Этот источник данных будет контролировать эту учетную запись      startBlock: 10662188 # Required for NEAR    mapping:      apiVersion: 0.0.9      language: wasm/assemblyscript      blockHandlers:        - handler: handleNewBlock # имя функции в файле мэппинга      receiptHandlers:        - handler: handleReceipt # имя функции в файле мэппингаe      file: ./src/mapping.ts # ссылка на файл с мэппингами Assemblyscript
  • Субграфы NEAR вводят новый тип источника данных (near).
  • network должен соответствовать сети на хостинговой Graph Node. В Subgraph Studio майннет NEAR называется near-mainnet, а теснет NEAR — near-testnet
  • Источники данных NEAR содержат необязательное поле source.account, которое представляет собой удобочитаемый идентификатор, соответствующий [учетной записи NEAR] (https://docs.near.org/concepts/protocol/account-model⁠). Это может быть как основной аккаунт, так и суб-аккаунт.
  • Источники данных NEAR вводят альтернативное необязательное поле source.accounts, которое содержит необязательные префиксы и суффиксы. Необходимо указать хотя бы один префикс или суффикс, они будут соответствовать любому аккаунту, начинающемуся или заканчивающемуся на значения из списка соответственно. Приведенный ниже пример будет совпадать с: [app|good].*[morning.near|morning.testnet]. Если необходим только список префиксов или суффиксов, другое поле можно опустить.
accounts:  prefixes:    - app    - good  suffixes:    - morning.near    - morning.testnet

Источники данных NEAR поддерживают два типа обработчиков:

  • blockHandlers: выполняется для каждого нового блока NEAR. source.account не требуется.
  • receiptHandlers: выполняется при каждом получении, где source.account источника данных является получателем. Обратите внимание, что обрабатываются только точные совпадения (субаккаунты⁠ должны быть добавлены как независимые источники данных).

Определение схемы

Определение схемы описывает структуру базы данных субграфа и отношения между объектами. Это не зависит от исходного источника данных. Подробнее об определении схемы субграфа можно прочитать здесь.

Мэппинги AssemblyScript

Обработчики для обработки событий написаны на AssemblyScript⁠.

Индексирование NEAR вводит специфичные для NEAR типы данных в API AssemblyScript.

class ExecutionOutcome {      gasBurnt: u64,      blockHash: Bytes,      id: Bytes,      logs: Array<string>,      receiptIds: Array<Bytes>,      tokensBurnt: BigInt,      executorId: string,  }class ActionReceipt {      predecessorId: string,      receiverId: string,      id: CryptoHash,      signerId: string,      gasPrice: BigInt,      outputDataReceivers: Array<DataReceiver>,      inputDataIds: Array<CryptoHash>,      actions: Array<ActionValue>,  }class BlockHeader {      height: u64,      prevHeight: u64,// Всегда 0 для версии < V3      epochId: Bytes,      nextEpochId: Bytes,      chunksIncluded: u64,      hash: Bytes,      prevHash: Bytes,      timestampNanosec: u64,      randomValue: Bytes,      gasPrice: BigInt,      totalSupply: BigInt,      latestProtocolVersion: u32,  }class ChunkHeader {      gasUsed: u64,      gasLimit: u64,      shardId: u64,      chunkHash: Bytes,      prevBlockHash: Bytes,      balanceBurnt: BigInt,  }class Block {      author: string,      header: BlockHeader,      chunks: Array<ChunkHeader>,  }class ReceiptWithOutcome {      outcome: ExecutionOutcome,      receipt: ActionReceipt,      block: Block,  }

Эти типы передаются в обработчики блоков и поступлений:

  • Обработчики блоков получат Block
  • Обработчики поступлений получат ReceiptWithOutcome

В противном случае, остальная часть API AssemblyScript доступна разработчикам субграфов NEAR во время выполнения мэппинга.

Это включает в себя новую функцию для парсинга JSON — логи в NEAR часто выводятся как строковые JSON. Новая функция json.fromString(...) доступна в рамках JSON API, что позволяет разработчикам легко обрабатывать эти логи.

Развертывание NEAR субграфа

После того как вы построите субграф, пришло время развернуть его на Graph Node для индексирования. Субграфы NEAR можно развернуть на любой Graph Node версии >=v0.26.x (эта версия еще не была отмечена и выпущена).

Subgraph Studio и Индексатор обновлений в The Graph Network в настоящее время поддерживают индексирование основной и тестовой сети NEAR в бета-версии со следующими именами сетей:

  • near-mainnet
  • near-testnet

Более подробную информацию о создании и развертывании субграфа в Subgraph Studio можно найти здесь.

Как быстрый вводный шаг — первым делом нужно “создать” ваш субграф — это нужно сделать только один раз. В Subgraph Studio это можно сделать через вашу панель управления: “Создать субграф”.

Как только ваш субграф будет создан, вы можете развернуть его, используя команду CLI graph deploy:

$ graph create --node <graph-node-url> <subgraph-name> # создает субграф на локальной Graph Node (в Subgraph Studio это делается через UI)$ graph deploy --node <graph-node-url> --ipfs https://ipfs.thegraph.com <subgraph-name> # загружает файлы сборки на указанную конечную точку IPFS и затем развертывает субграф на указанном Graph Node, основываясь на IPFS-хэше манифеста

Конфигурация ноды будет зависеть от того, где развертывается субграф.

Subgraph Studio

graph authgraph deploy <subgraph-name>

Локальная Graph Node (на основе конфигурации по умолчанию)

graph deploy --node http://localhost:8020/ --ipfs http://localhost:5001 <subgraph-name>

После того как ваш субграф был развернут, он будет индексироваться Graph Node. Вы можете проверить его прогресс, сделав запрос к самому субграфу:

{  _meta {    block {      number    }  }}

Индексирование NEAR с помощью локальной Graph Node

Запуск Graph Node, который индексирует NEAR, имеет следующие эксплуатационные требования:

  • Фреймворк NEAR Indexer с инструментарием Firehose
  • Компонент(ы) NEAR Firehose
  • Graph Node с настроенным эндпоинтом Firehose

В ближайшее время мы предоставим более подробную информацию о запуске вышеуказанных компонентов.

Запрос NEAR субграфа

Конечная точка GraphQL для субграфов NEAR определяется в соответствии с определением схемы и существующим интерфейсом API. Для получения дополнительной информации изучите документацию по GraphQL API.

Примеры субграфов

Вот несколько примеров субграфов для справки:

Блоки NEAR⁠

Подтверждения NEAR⁠

Часто задаваемые вопросы

Как работает бета-версия?

Поддержка NEAR находится на стадии бета-тестирования, что означает, что могут быть изменения в API по мере улучшения интеграции. Пожалуйста, отправьте письмо на адрес [email protected]⁠, чтобы мы могли помочь вам в создании субграфов NEAR и держать вас в курсе последних обновлений!

Может ли субграф индексировать чейны NEAR и EVM?

Нет, субграф может поддерживать источники данных только из одного чейна/сети.

Могут ли субграфы реагировать на более конкретные триггеры?

В настоящее время поддерживаются только триггеры Block и Receipt. Мы исследуем триггеры для вызовов функций к указанной учетной записи. Мы также заинтересованы в поддержке триггеров событий, когда NEAR обладает собственной поддержкой событий.

Будут ли срабатывать обработчики поступлений для учетных записей и их дочерних учетных записей?

Если указано account, это будет соответствовать только точному имени аккаунта. Для того чтобы соответствовать субаккаунтам, можно указать поле accounts, с suffixes и prefixes, которые будут соответствовать аккаунтам и субаккаунтам. Например, следующее выражение будет соответствовать всем субаккаунтам mintbase1.near:

accounts:  suffixes:    - mintbase1.near

Могут ли субграфы NEAR выполнять вызовы просмотра аккаунтов NEAR во время мэппингов?

Это не поддерживается. Мы оцениваем, требуется ли этот функционал для индексирования.

Могу ли я использовать шаблоны источников данных в своем субграфе NEAR?

В настоящее время это не поддерживается. Мы оцениваем, требуется ли этот функционал для индексирования.

Субграфы Ethereum поддерживают «ожидающие» и «текущие» версии. Как я могу развернуть «ожидающую» версию субграфа NEAR?

Функциональность ожидающих пока не поддерживается для субграфов NEAR. В промежуточный период вы можете развернуть новую версию на другом “именованном” субграфе, а затем, когда она будет синхронизирована с головой чейна, вы можете повторно развернуть ее на своем основном “именованном” субграфе, который будет использовать тот же самый идентификатор развертывания, так что основной субграф будет мгновенно синхронизирован.

На мой вопрос нет ответа, где я могу получить дополнительную помощь в создании субграфов NEAR?

Если это общий вопрос о разработке субграфов, дополнительную информацию можно найти в остальной части документации для разработчиков. В других случаях присоединяйтесь к Discord-каналу The Graph Protocol⁠ и задавайте вопросы в канале #near или отправьте email на адрес [email protected]⁠.

Ссылки