Construyendo subgrafos en Cosmos

Reading time: 7 min

Esta guía es una introducción a la creación de subgrafos que indexan blockchains basadas en Cosmos.

The Graph permite a los developers procesar eventos de blockchain y hacer que los datos resultantes estén fácilmente disponibles a través de una API GraphQL abierta, conocida como subgrafo. Graph Node ahora puede procesar eventos de Cosmos, lo que significa que los developers de Cosmos ahora pueden crear subgrafos para indexar fácilmente eventos on-chain.

Hay cuatro tipos de handlers admitidos en los subgrafos de Cosmos:

• Block handlers se ejecutan cada vez que se agrega un nuevo bloque a la cadena.
• Event handlers se ejecutan cuando se emite un evento específico.
• Los handlers de transacciones se ejecutan cuando se produce una transacción.
• Message handlers se ejecutan cuando ocurre un mensaje específico.

Basado en la documentación oficial de Cosmos:

Aunque se puede acceder a todos los datos con un handler de bloques, otros handlers permiten a los developers de subgrafos procesar datos de una manera mucho más granular.

graph-cli es una herramienta CLI para crear e implementar subgrafos, versión >=0.30.0 es necesario para trabajar con subgrafos de Cosmos.

graph-ts es una biblioteca de tipos específicos de subgrafos, versión >=0.27.0 es necesario para trabajar con subgrafos de Cosmos.

Hay tres partes clave cuando se trata de definir un subgrafo:

subgraph.yaml: un archivo YAML que contiene el manifiesto del subgrafo, que identifica qué eventos rastrear y cómo procesarlos.

schema.graphql: un esquema de GraphQL que define qué datos se almacenan para su subgrafo y cómo consultarlos a través de GraphQL.

Asignaciones AssemblyScript: código AssemblyScript que traduce los datos de la blockchain a las entidades definidas en tu esquema.

El manifiesto del subgrafo (subgraph.yaml) identifica las fuentes de datos para el subgrafo, los disparadores de interés y las funciones (handlers) que deben ejecutarse en respuesta a esos disparadores. Consulte a continuación un manifiesto de subgrafo de ejemplo para un subgrafo de Cosmos:

specVersion: 0.0.5
description: Cosmos Subgraph Example
schema:
  file: ./schema.graphql # link to the schema file
dataSources:
  - kind: cosmos
    name: CosmosHub
    network: cosmoshub-4 # This will change for each cosmos-based blockchain. In this case, the example uses the Cosmos Hub mainnet.
    source:
      startBlock: 0 # Required for Cosmos, set this to 0 to start indexing from chain genesis
    mapping:
      apiVersion: 0.0.7
      language: wasm/assemblyscript
      blockHandlers:
        - handler: handleNewBlock # the function name in the mapping file
      eventHandlers:
        - event: rewards # the type of the event that will be handled
          handler: handleReward # the function name in the mapping file
      transactionHandlers:
        - handler: handleTransaction # the function name in the mapping file
      messageHandlers:
        - message: /cosmos.staking.v1beta1.MsgDelegate # the type of a message
          handler: handleMsgDelegate # the function name in the mapping file
      file: ./src/mapping.ts # link to the file with the Assemblyscript mappings

• Los subgrafos de Cosmos introducen un nuevo tipo de origen de datos (cosmos).
• El network debe corresponder a una cadena en el ecosistema Cosmos. En el ejemplo, se usa la mainnet de Cosmos Hub.

La definición de esquema describe la estructura de la base de datos de subgrafos resultante y las relaciones entre las entidades. Esto es independiente de la fuente de datos original. Hay más detalles sobre la definición de esquema del subgrafo aquí.

Los controladores para procesar eventos están escritos en AssemblyScript.

La indexación de Cosmos introduce tipos de datos específicos de Cosmos en la 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
}

Cada tipo de handler viene con su propia estructura de datos que se pasa como argumento a una función de mapping.

• Los handlers de bloques reciben el tipo Block.
• Los handlers de eventos reciben el tipo EventData.
• Los handlers de transacciones reciben el tipo TransactionData.
• Los handlers de mensajes reciben el tipo MessageData.

Como parte de MessageData, el message handler recibe un contexto de transacción, que contiene la información más importante sobre una transacción que abarca un mensaje. El contexto de transacción también está disponible en el tipo EventData, pero solo cuando el evento correspondiente está asociado con una transacción. Además, todos los controladores reciben una referencia a un bloque (HeaderOnlyBlock).

Puedes encontrar una lista completa de los tipos para la integración Cosmos aquí here.

Es importante tener en cuenta que los mensajes de Cosmos son específicos de la cadena y se pasan a un subgrafo en forma de una carga de Protocol Buffers serializada Protocol Buffers Como resultado, los datos del mensaje deben decodificarse en una función de mapeo antes de que puedan ser procesados. Un ejemplo de cómo decodificar los datos de un mensaje en un subgrafo se puede encontrar aquí.

Un ejemplo de cómo decodificar los datos de un mensaje en un subgrafo se puede encontrar aquí.

El primer paso antes de comenzar a escribir las asignaciones de subgrafos es generar los enlaces de tipos en función de las entidades que se han definido en el archivo de esquema de subgrafos (schema.graphql). Esto permitirá que las funciones de mapeo creen nuevos objetos de esos tipos y los guarden en la tienda. Esto se hace usando el comando CLI codegen:

$ graph codegen

Una vez que las esquematizaciones están listas, se debe construir el subgrafo. Este paso resaltará cualquier error que puedan tener el manifiesto o las esquematizaciones. Un subgrafo debe construirse correctamente para deployarse en The Graph Node. Se puede hacer usando el comando CLI build:

$ graph build

Una vez creado el subgrafo, puedes deployarlo utilizando el comando CLI graph deployment después de ejecutar el comando CLI graph create:

Hosted Service

graph create account/subgraph-name --product hosted-service

graph create account/subgraph-name --product hosted-service

Graph Node local (basado en la configuración predeterminada):

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

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

El punto final de GraphQL para los subgrafos de Cosmos está determinado por la definición del esquema, con la interfaz API existente. Visite la GraphQL API documentation para obtener más información.

La blockchain de Cosmos Hub es la primera blockchain en el ecosistema Cosmos. Puede visitar la documentación oficial para obtener más información.

La red principal de Cosmos Hub es cosmoshub-4. La red de prueba actual de Cosmos Hub es theta-testnet-001.
Otras redes de Cosmos Hub, es decir, cosmoshub-3, están detenidas, por lo que no se proporcionan datos para ellas.

Osmosis es un protocolo automated market maker (AMM) descentralizado y cross chain construido sobre Cosmos SDK. Permite a los usuarios crear fondos de liquidez personalizados e intercambiar tokens habilitados para IBC. Puedes visitar la documentación oficial para obtener más información.

La red principal de Osmosis es osmosis-1. La red de prueba actual de Osmosis es osmo-test-4.

A continuación se presentan algunos ejemplos de subgrafos como referencia:

Ejemplo de filtrado de bloques

Ejemplo de recompensas del validador

Ejemplo de delegaciones de validador

Ejemplo de intercambio de tokens de Osmosis