Создание субграфов на 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 вводит специфичные для Cosmos типы данных в 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 --studio 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