Cosmos'ta Subgraph'ler Oluşturma

Reading time: 6 min

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

Graph, geliştiricilerin blockchain etkinliklerini işlemesine ve ortaya çıkan verileri subgraph olarak bilinen açık bir GraphQL API aracılığıyla kolayca kullanılabilir hale getirmesine olanak tanır. Graph Düğümü artık Cosmos etkinliklerini işleyebilir, bu da Cosmos geliştiricilerinin artık zincir üstü olayları kolayca dizine eklemek için subgraph'ler oluşturabileceği anlamına gelir.

Cosmos subgraph'lerinde desteklenen dört tür işleyici vardır:

• Blok işleyicileri, zincire her yeni blok eklendiğinde çalışır.
• Olay işleyicileri, belirli bir olay yayınlandığında çalışır.
• İşlem işleyicileri, bir işlem gerçekleştiğinde çalışır.
• Mesaj işleyicileri, belirli bir mesaj oluştuğunda çalışır.

resmi Cosmos belgelerine göre:

Tüm verilere bir blok işleyici ile erişilebilmesine rağmen, diğer işleyiciler, subgraph geliştiricilerin verileri çok daha ayrıntılı bir şekilde işlemesine olanak tanır.

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.

Bir subgraph'i tanımlama noktasında üç anahtar kısım vardır:

subgraph.yaml: hangi olayların izleneceğini ve bunların nasıl işleneceğini tanımlayan subgraph bildirimini içeren bir YAML dosyası.

schema.graphql: subgrpah'iniz için hangi verilerin depolandığını ve bunun GraphQL aracılığıyla nasıl sorgulanacağını tanımlayan bir GraphQL şeması.

AssemblyScript Eşlemeleri: AssemblyScript blok zinciri verilerinden şemanızda tanımlanan varlıklara çeviren kod.

Subgraph bildirimi (subgraph.yaml), subgraph için veri kaynaklarını, ilgilenilen tetikleyicileri ve bu tetikleyicilere yanıt olarak çalıştırılması gereken işlevleri (işleyiciler) tanımlar. Bir Cosmos subgrpah'i için örnek bir subgraph bildirimi için alt kısma göz atın:

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

• Cosmos subgraph'leri, yeni bir tür veri kaynağı sunar (cosmos).
• Ağ, Cosmos ekosistemindeki bir zincire karşılık gelmelidir. Örnekte, Cosmos Hub mainnet'i kullanılmıştır.

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.

Olayları işlemek için işleyiciler AssemblyScript içinde yazılmıştır.

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
}

Her işleyici türü, bir eşleme işlevine bağımsız değişken olarak iletilen kendi veri yapısıyla birlikte gelir.

• Blok işleyicileri Block tipini alır.
• Etkinlik işleyicileri, EventData türünü alır.
• İşlem işleyicileri, TransactionData türünü alır.
• Mesaj işleyicileri, MessageData tipini alır.

MessageData'ın bir parçası olarak, mesaj işleyici, bir mesajı kapsayan bir işlemle ilgili en önemli bilgileri içeren bir işlem bağlamı alır. İşlem bağlamı, EventData türünde de mevcuttur, ancak yalnızca karşılık gelen olay bir işlemle ilişkilendirildiğinde. Ek olarak, tüm işleyiciler bir bloğa başvuru alır (HeaderOnlyBlock).

Cosmos entegrasyonu türlerinin tam listesini burada bulabilirsiniz.

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.

Bir subgraph'taki mesaj verisinin nasıl çözüleceğine dair bir örnek burada bulunabilir.

Alt çizge eşlemelerini yazmaya başlamadan önceki ilk adım, alt çizge şema dosyasında (schema.graphql) tanımlanan varlıklara dayalı tip bağlarını oluşturmaktır. Bu, eşleme işlevlerinin bu türlerde yeni nesneler oluşturmasına ve bunları depoya kaydetmesine izin verecektir. Bu, codegen CLI komutu kullanılarak yapılır:

$ graph codegen

Eşlemeler hazır olduğunda, subgraph'in oluşturulması gerekir. Bu adım, bildirimde veya eşlemelerde olabilecek hataları vurgulayacaktır. Graph Node'una deploy edilmek için subgraph'in başarılı bir şekilde oluşturulması gerekir. build CLI komutu kullanılarak yapılabilir:

$ graph build

Subgraph'ınız oluşturulduktan sonra, graph deploy CLI komutunu kullanarak subgraph'ınızı dağıtabilirsiniz:

Subgraph Stüdyosu

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