Construyendo subgrafos en Cosmos

Reading time: 7 min

This guide is an introduction on building subgraphs indexing Cosmos based blockchains.

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 is a CLI tool to build and deploy subgraphs, version >=0.30.0 is required in order to work with Cosmos subgraphs.

graph-ts is a library of subgraph-specific types, version >=0.27.0 is required in order to work with Cosmos subgraphs.

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.

Schema definition describes the structure of the resulting subgraph database and the relationships between entities. This is agnostic of the original data source. There are more details on subgraph schema definition here.

Los controladores para procesar eventos están escritos en 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
}

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.

It's important to note that Cosmos messages are chain-specific and they are passed to a subgraph in the form of a serialized Protocol Buffers payload. As a result, the message data needs to be decoded in a mapping function before it can be processed.

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 que se haya creado su subgrafo, puede implementar su subgrafo usando el comando CLI graph deployment:

Subgraph Studio

Visit the Subgraph Studio to create a new subgraph.

graph deploy subgraph-name

Local Graph Node (based on default configuration):

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

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

The GraphQL endpoint for Cosmos subgraphs is determined by the schema definition, with the existing API interface. Please visit the GraphQL API documentation for more information.

The Cosmos Hub blockchain is the first blockchain in the Cosmos ecosystem. You can visit the official documentation for more information.

Cosmos Hub mainnet is cosmoshub-4. Cosmos Hub current testnet is theta-testnet-001.
Other Cosmos Hub networks, i.e. cosmoshub-3, are halted, therefore no data is provided for them.

Osmosis is a decentralized, cross-chain automated market maker (AMM) protocol built on top of the Cosmos SDK. It allows users to create custom liquidity pools and trade IBC-enabled tokens. You can visit the official documentation for more information.

Osmosis mainnet is osmosis-1. Osmosis current testnet is osmo-test-4.

Here are some example subgraphs for reference:

Block Filtering Example

Validator Rewards Example

Validator Delegations Example

Osmosis Token Swaps Example