Création de subgraphes sur Cosmos

Reading time: 7 min

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

The Graph permet aux développeurs de traiter les événements de la blockchain et de rendre les données résultantes facilement disponibles via une API GraphQL publique, connue sous le nom de subgraph. Par exemple : Graph Node est désormais capable de traiter les événements Cosmos, ce qui signifie que les développeurs peuvent désormais construire des subgraphs pour indexer facilement les événements sur cette chaîne.

Il existe quatre types de gestionnaires pris en charge dans les subgraphs de Cosmos :

• Les gestionnaires de blocs s'exécutent chaque fois qu'un nouveau bloc est ajouté à la chaîne.
• Les gestionnaires d'événements s'exécutent lorsqu'un événement spécifique est émis.
• Les gestionnaires d'événements s'exécutent lorsqu'un événement spécifique est émis.
• Les gestionnaires de messages s'exécutent lorsqu'un message spécifique apparaît.

Basé sur la documentation officielle de Cosmos :

Même si toutes les données sont accessibles avec un gestionnaire de blocs, des gestionnaires tiers permettent aux développeurs de subgraphs de traiter les données de manière beaucoup plus précise.

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.

La définition d'un subgraph comporte trois éléments clés :

subgraph.yaml : un fichier YAML contenant le manifeste du subgraph, qui identifie les événements à suivre et la façon de les traiter.

schema.graphql : un schéma GraphQL qui définit quelles données sont stockées pour votre subgraph, et comment les interroger via GraphQL.

Mappings AssemblyScript : Code AssemblyScript qui a traduit les données de la blockchain vers les entités définies dans votre schéma.

Le manifeste du subgraph (subgraph.yaml) identifie les sources de données du subgraph, les déclencheurs d'intérêt et les fonctions (handlers) qui doivent être exécutées en réponse à ces déclencheurs. Vous trouverez ci-dessous un exemple de manifeste de subgraph pour un subgraph Cosmos :

version spec: 0.0.5
description: Exemple de subgraph Cosmos
schéma:
  fichier: ./schema.graphql # lien vers le fichier de schéma
les sources de données:
  - genre: cosmos
    nom: CosmosHub
    réseau: cosmoshub-4 # Cela changera pour chaque blockchain basée sur le cosmos. Dans ce cas, l’exemple utilise le mainnet Cosmos Hub.
    source:
      startBlock: 0 # Requis pour Cosmos, définissez-le sur 0 pour démarrer l'indexation à partir de la genèse de la chaîne
    cartographie:
      Version api: 0.0.7
      langage: wasm/assemblyscript
      gestionnaires de blocs:
        - handler: handleNewBlock # le nom de la fonction dans le fichier de mappage
      Gestionnaires d'événements:
        - event: récompenses # le type d'événement qui sera géré
          handler: handleReward # le nom de la fonction dans le fichier de mappage
      Gestionnaires de transactions:
        - handler: handleTransaction # le nom de la fonction dans le fichier de mappage
      Gestionnaires de messages:
        - message: /cosmos.staking.v1beta1.MsgDelegate # le type d'un message
          handler: handleMsgDelegate # le nom de la fonction dans le fichier de mappage
      fichier: ./src/mapping.ts # lien vers le fichier avec les mappages Assemblyscript

• Les subgraphs cosmos introduisent un nouveau type de source de données (cosmos).
• Le réseau doit correspondre à une chaîne de l'écosystème Cosmos. Dans l’exemple, le mainnet Cosmos Hub est utilisé.

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.

Les gestionnaires pour le traitement des événements sont écrits en AssemblyScript.

L'indexation Cosmos introduit des types de données spécifiques à Cosmos dans l'API AssemblyScript.

class Block {
  header: Header
  preuve: Liste de preuves
  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
}

Chaque structure de type de gestionnaire transmise en tant qu'argument à une fonction de mappage.

• Les gestionnaires de blocs reçoivent le type Block.
• Les gestionnaires d'événements recevront le type EventData.
• Les gestionnaires de transactions recevront le type TransactionData.
• Les gestionnaires de messages recevront le type MessageData.

En tant que partie de MessageData, le gestionnaire de messages reçoit un contexte de transaction, qui contient les informations les plus importantes sur une transaction qui englobe un message. Le contexte de transaction est également disponible dans le type EventData, mais uniquement lorsque l'événement correspondant est associé à une transaction. En outre, tous les gestionnaires reçoivent une référence à un bloc (HeaderOnlyBlock).

Vous trouverez la liste complète des types pour l'intégration Cosmos ici.

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 exemple de décodage des données d'un message dans un subgraph peut être trouvé ici.

La première étape avant de commencer à écrire les mappings du subgraphs est de générer les liaisons de type basées sur les entités qui ont été définies dans le fichier schéma du subgraph (schema.graphql). Cela permettra aux fonctions de mappage de créer de nouveaux objets de ces types et de les enregistrer dans le magasin. Ceci est fait en utilisant la commande CLI codegen :

$ codegen graph

Une fois que le mapping est prêt, le subgraph peut être construit. Cette étape mettra en évidence toute erreur que le manifeste ou le mapping pourraient avoir. Un subgraph doit être construit avec succès afin d'être déployé sur Graph Node. Ceci est fait en utilisant la commande CLI build :

$ construction de graph

Une fois votre subgraph créé, vous pouvez le déployer en utilisant la commande CLI graph deploy :

Subgraph Studio

Visit the Subgraph Studio to create a new subgraph.

graph deploy --studio 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