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

Reading time: 6 min

Это руководство представляет собой введение в создание субграфов, индексирующих блокчейны на основе Cosmos.

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

Существует четыре типа обработчиков, поддерживаемых в субграфах Cosmos:

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

На основе официальной документации Cosmos:

Хотя доступ ко всем данным можно получить с помощью обработчика блоков, другие обработчики позволяют разработчикам субграфов обрабатывать данные гораздо более детально.

graph-cli — это инструмент CLI для создания и развертывания субграфов. Для работы с субграфами Cosmos требуется версия >=0.30.0.

graph-ts — это библиотека типов, специфичных для субграфов. Для работы с субграфами Cosmos требуется версия >=0.27.0.

Когда дело доходит до определения субграфа, имеется три ключевых момента:

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

schema.graphql: схема GraphQL, которая определяет, какие данные хранятся для Вашего субграфа и как их запрашивать через GraphQL.

AssemblyScript Mappings: код AssemblyScript, преобразующий данные блокчейна в определенные объекты в Вашей схеме.

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

specVersion: 0.0.5
description: Cosmos Subgraph Example
schema:
  file: ./schema.graphql # ссылка на файл схемы
dataSources:
  - kind: cosmos
    name: CosmosHub
    network: cosmoshub-4 # это будет меняться для каждого блокчейна, основанного на Cosmos. В данном случае в примере используется основная сеть Cosmos Hub.
    source:
      startBlock: 0 # требуется для Cosmos, установите для этого параметра значение 0, чтобы начать индексирование с начального блока генезиса чейна.
    mapping:
      apiVersion: 0.0.7
      language: wasm/assemblyscript
      blockHandlers:
        - handler: handleNewBlock # имя функции в мэппинг-файле
      eventHandlers:
        - event: rewards # тип события, которое будет обрабатываться
          handler: handleReward # имя функции в мэппинг-файле
      transactionHandlers:
        - handler: handleTransaction # имя функции в мэппинг-файле
      messageHandlers:
        - message: /cosmos.staking.v1beta1.MsgDelegate # тип сообщения
          handler: handleMsgDelegate # имя функции в мэппинг-файле
      file: ./src/mapping.ts # ссылка на мэппинг-файл скрипта сборки

• Субграфы на Cosmos представляют новый вид источника данных (cosmos).
• network должен соответствовать чейну в экосистеме Cosmos. В примере используется майннет Cosmos Hub.

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

Обработчики событий написаны на языке AssemblyScript.

Cosmos indexing introduces Cosmos-specific data types to the AssemblyScript API.

class Block {
  header: Header
  evidence: EvidenceList
  resultBeginBlock: ResponseBeginBlock
  resultEndBlock: ResponseEndBlock
  transactions: Array<TxResult>
  validatorUpdates: Array<Validator>
}

class EventData {
  event: Event
  block: HeaderOnlyBlock
  tx: TransactionContext
}

class TransactionData {
  tx: TxResult
  block: HeaderOnlyBlock
}

class MessageData {
  message: Any
  block: HeaderOnlyBlock
  tx: TransactionContext
}

class TransactionContext {
  hash: Bytes
  index: u32
  code: u32
  gasWanted: i64
  gasUsed: i64
}

class HeaderOnlyBlock {
  header: Header
}

class Header {
  version: Consensus
  chainId: string
  height: u64
  time: Timestamp
  lastBlockId: BlockID
  lastCommitHash: Bytes
  dataHash: Bytes
  validatorsHash: Bytes
  nextValidatorsHash: Bytes
  consensusHash: Bytes
  appHash: Bytes
  lastResultsHash: Bytes
  evidenceHash: Bytes
  proposerAddress: Bytes
  hash: Bytes
}

class TxResult {
  height: u64
  index: u32
  tx: Tx
  result: ResponseDeliverTx
  hash: Bytes
}

class Event {
  eventType: string
  attributes: Array<EventAttribute>
}

class Any {
  typeUrl: string
  value: Bytes
}

Каждый тип обработчика имеет свою собственную структуру данных, которая передается в качестве аргумента функции мэппинга.

• Обработчики блоков получают тип Block.
• Обработчики событий получают тип EventData.
• Обработчики транзакций получают тип TransactionData.
• Обработчики сообщений получают тип MessageData.

Как часть MessageData обработчик сообщения получает контекст транзакции, который содержит наиболее важную информацию о транзакции, включающей сообщение. Контекст транзакции также доступен в типе EventData, но только, когда соответствующее событие связано с транзакцией. Кроме того, все обработчики получают ссылку на блок (HeaderOnlyBlock).

Полный список типов для интеграции Cosmos можно найти здесь.

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

Пример того, как расшифровываются данные сообщения в субграфе, можно найти здесь.

Первым шагом перед началом написания мэппингов субграфов является создание привязок типов на основе объектов, определенных в файле схемы субграфа (schema.graphql). Это позволит функциям мэппинга создавать новые объекты этих типов и сохранять их в хранилище. Для этого используется команда CLI codegen:

$ graph codegen

После того, как мэппинги готовы, необходимо построить субграф. На этом шаге будут выделены все ошибки, которые могут быть в манифесте или мэппингах. Субграф должен быть успешно построен, чтобы его можно было развернуть на Graph Node. Это можно сделать с помощью команды build командной строки:

$ graph build

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

Subgraph Studio

Посетите Subgraph Studio, чтобы создать новый субграф.

graph deploy subgraph-name

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

graph create subgraph-name --node http://localhost:8020

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

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

Блокчейн Cosmos Hub — первый блокчейн в экосистеме Cosmos. Дополнительную информацию можно найти в официальной документации.

Основная сеть Cosmoshub — cosmoshub-4. Текущая тестовая сеть Cosmos Hub — theta-testnet-001.
Другие сети Cosmos Hub, например, cosmoshub-3, остановлены, поэтому данные для них не предоставляются.

Osmosis – это децентрализованный межсетевой протокол автоматизированного маркет-мейкера (AMM), построенный на основе Cosmos SDK. Он позволяет пользователям создавать собственные пулы ликвидности и торговать токенами с поддержкой IBC. Дополнительную информацию можно найти в официальной документации.

Майннет Osmosis — osmosis-1. Текущая тестовая сеть Osmosis — osmo-test-4.

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

Пример блочной фильтрации

Пример вознаграждения валидатора

Пример делегирования валидатору

Пример свопа токенов на Osmosis