Construção de Subgraphs no Cosmos

Reading time: 7 min

Este guia é uma introdução à construção de subgraphs através da indexação de blockchains baseadas no Cosmos.

The Graph permite que os programadores processem eventos em blockchain e façam dos dados resultantes facilmente disponíveis através de uma API aberta do GraphQL, conhecida como um subgraph. O Graph Node agora pode processar eventos no Cosmos, o que significa que programadores no Cosmos agora podem construir subgraphs para indexar com facilidade eventos on-chain.

Existem quatro categorias de handlers apoiados em subgraphs no Cosmos:

• Block handlers são executados quando um novo bloco é anexado à chain.
• Event handlers são executados quando um evento específico é emitido.
• Transaction handlers são executados quando uma transação ocorre.
• Message handlers são executados quando uma mensagem específica ocorre.

Baseado na documentação oficial do Cosmos:

Apesar de todos os dados poderem ser acessados com um block handler, outros handlers permitem a programadores de subgraphs processar dados de uma maneira muito mais granular.

O graph-cli é uma ferramenta de CLI para construir e lançar subgraphs. A versão >=0.30.0 é necessária para trabalhar com subgraphs no Cosmos.

O graph-ts é uma biblioteca de tipos específicos a subgraphs; a versão >=0.27.0 é necessária para trabalhar com subgraphs no Cosmos.

Quando definir um subgraph, estes três componentes serão muito importantes:

subgraph.yaml: um arquivo YAML que contém o manifest do subgraph, além de identificar quais eventos rastrear e como processá-los.

schema.graphql: um schema do GraphQL que define quais dados serão armazenados para o seu subgraph, e como consultá-los via GraphQL.

Mapeamentos de AssemblyScript: códigos em AssemblyScript que traduzem dos dados da blockchain às entidades definidas no seu schema.

O manifest do subgraph (subgraph.yaml) identifica as fontes de dados para o subgraph, os gatilhos de interesse, e as funções (handlers) que devem ser executadas em resposta àqueles gatilhos. Veja abaixo um exemplo de um manifest de subgraph para um subgraph no Cosmos:

specVersion: 0.0.5
description: Exemplo de Subgraph no Cosmos
schema:
  file: ./schema.graphql # link ao arquivo schema
dataSources:
  - kind: cosmos
    name: CosmosHub
    network: cosmoshub-4 # Isto mudará para cada blockchain baseada no Cosmos. Neste caso, o exemplo usa a mainnet Cosmos Hub.
    source:
      startBlock: 0 # Exigido para o Cosmos, coloque o valor de 0 para começar a indexar desde o gênese da chain
    mapping:
      apiVersion: 0.0.7
      language: wasm/assemblyscript
      blockHandlers:
        - handler: handleNewBlock # o nome da função no arquivo de mapeamento
      eventHandlers:
        - event: rewards # o tipo de evento que será lidado
          handler: handleReward # o nome da função no arquivo de mapeamento
      transactionHandlers:
        - handler: handleTransaction # o nome da função no arquivo de mapeamento
      messageHandlers:
        - message: /cosmos.staking.v1beta1.MsgDelegate # o tipo de uma mensagem
          handler: handleMsgDelegate # o nome da função no arquivo de mapeamento
      file: ./src/mapping.ts # link ao arquivo com os mapeamentos em AssemblyScript

• Subgraphs no Cosmos introduzem um novo tipo de fonte de dados (cosmos).
• A rede (network) deve corresponder a uma chain no ecossistema Cosmos. O exemplo acima usa a mainnet do Cosmos Hub.

A definição do schema descreve a estrutura do banco de dados do subgraph resultante e os relacionamentos entre entidades. Isto é agnóstico à fonte de dados original. Mais detalhes na definição do schema de subgraph aqui.

Os handlers para o processamento de eventos são escritos em AssemblyScript.

A indexação do Cosmos introduz categorias de dados específicas ao Cosmos ao API do AssemblyScript.

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
}

Cada tipo de handler vem com a sua própria estrutura de dados, a ser passada como argumento a uma função de mapeamento.

• Handlers de blocos recebem o tipo Block.
• Handlers de eventos recebem o tipo EventData.
• Handlers de transações recebem o tipo TransactionData.
• Handlers de mensagens recebem o tipo MessageData.

Como parte do MessageData, o handler de mensagens recebe um contexto de transação, que contém as informações mais importantes sobre uma transação a compor uma mensagem. O contexto da transação também está disponível no tipo EventData, mas só quando o evento correspondente é associado a uma transação. Além disso, todos os handlers recebem uma referência a um bloco (HeaderOnlyBlock).

A lista completa de tipos para integração ao Cosmos está aqui.

Repare que mensagens no Cosmos são específicas a chains, e são passadas a um subgraph na forma de um payload serializado de Buffers de Protocolo. Portanto, os dados das mensagens devem ser decodificados em uma função de mapeamento antes que possam ser processados.

Mais informações sobre como descodificar dados de mensagem em um subgraph aqui.

Antes de começar a escrever os mapeamentos do subgraph, o primeiro passo é gerar os vínculos baseados nas entidades definidas no arquivo de schema do subgraph (schema.graphql). Assim, as funções de mapeamento criarão novos objetos destes tipos e os salvarão ao armazenamento. Isto é feito usando o seguinte comando CLI codegen:

$ graph codegen

Quando os mapeamentos estiverem prontos, o subgraph precisará ser construído. Este passo destacará quaisquer erros possíveis no manifest ou nos mapeamentos. Um subgraph deve ser construído com êxito para ser lançado ao Graph Node. Isto é possível com o seguinte comando CLI build:

$ graph build

Quando o seu subgraph estiver pronto, lance o seu subgraph com o comando de CLI graph deploy:

Subgraph Studio

Crie um novo subgraph no Subgraph Studio.

graph deploy --studio subgraph-name

Graph Node local (baseado na configuração padrão):

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

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

O endpoint do GraphQL para subgraphs no Cosmos é determinado pela definição do schema, com a interface existente da API. Mais informações na documentação da API GraphQL.

A Cosmos Hub é a primeira blockchain no ecossistema Cosmos. Para saber mais, leia a documentação oficial.

A mainnet atual do Cosmos Hub é cosmoshub-4, e a testnet atual do Cosmos Hub é theta-testnet-001.
Outras redes do Cosmos Hub, por ex. cosmoshub-3, estão em hiato; portanto, elas não recebem dados.

Osmosis é um protocolo criador automático de mercado (AMM), descentralizado e cross-chain, construído em cima do SDK do Cosmos. Ele permite que os utilizadores criem pools customizados de liquidez e troquem tokens IBC. Para mais informações, visite a documentação oficial.

A mainnet do Osmosis é osmosis-1, e a testnet atual do Osmosis é osmo-test-4.

Aqui estão alguns exemplos de subgraphs para referência:

Exemplo de Filtragem de Blocos

Exemplo de Recompensas de Validador

Exemplo de Delegações de Validador

Exemplo de Trocas de Token no Osmosis