Cosmosでのサブグラフ構築

Reading time: 9 min

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

Graph は、ブロックチェーンのイベントを処理し、その結果得られたデータを GraphQL API を介して簡単に利用できるようにするためのツールを開発者に提供するもので、個別にはサブグラフとして知られています。Graph Nodeが Cosmosイベントを処理できるようになったということは、Cosmosの開発者がスマートコントラクトの指標となるサブグラフを構築できるようになったということです。

Cosmosのサブグラフでサポートされているハンドラーは4種類あります。

• ブロックハンドラーは、新しいブロックがチェーンに追加されるたびに実行されます。
• イベントハンドラーは、特定のイベントが発生したときに実行されます。
• トランザクションハンドラーは、トランザクションが発生したときに実行されます。
• メッセージハンドラーは、特定のメッセージが発生したときに実行されます。

Cosmosの公式ドキュメントに基づきます。

ブロックハンドラーでは全てのデータにアクセスできますが、その他のハンドラーでは、サブグラフの開発者がよりきめ細かくデータを処理することができます。

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.

サブグラフの定義には、3つの重要な部分があります。

subgraph.yaml: サブグラフのマニフェストを含むYAMLファイルで、追跡するイベントとその処理方法を特定します。

schema.graphql: サブグラフにどのようなデータが保存されているか、また GraphQL を使ってどのようにクエリを行うかを定義します。

AssemblyScript Mappingsです。AssemblyScript ブロックチェーンデータからスキーマで定義されたエンティティに変換するコードです。

サブグラフ マニフェスト (subgraph.yaml) は、サブグラフのデータ ソース、関心のあるトリガー、およびこれらのトリガーに応答して実行される関数 (handlers) を特定します。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

• Cosmos subgraphs introduce a new kind of data source (cosmos).
• ネットワークは、Cosmosエコシステム内のチェーンに対応する必要があります。この例では、Cosmos Hub mainnetが使用されています。

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.

イベントを処理するためのハンドラは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
}

各ハンドラタイプは独自のデータ構造を持ち、マッピング関数の引数として渡されます。

• ブロックハンドラーは、Blockを受け取ります.
• イベントハンドラーは、EventDataを受け取ります.
• トランザクションハンドラーは、TransactionDataを受け取ります.
• メッセージハンドラーは、MassageDataを受け取ります.

MessageData の一部として、メッセージハンドラは、メッセージを包含するトランザクションに関する最も重要な情報を含む、トランザクションコンテキストを受け取ります。トランザクションコンテキストはEventData型でも利用できますが、対 応するイベントがトランザクションと関連付けられている場合に限ります。さらに、すべてのハンドラはブロック(HeaderOnlyBlock) への参照を受け取ります。

Cosmos統合の全種類一覧はこちらで確認できます。

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.

サブグラフ内のメッセージ データをデコードする方法の例は、ここにあります。

サブグラフ マッピングの記述を開始する前の最初のステップは、サブグラフ スキーマ ファイル (schema.graphql) で定義されたエンティティに基づいて型バインディングを生成することです。これにより、マッピング関数がそれらのタイプの新しいオブジェクトを作成し、ストアに保存できるようになります。これは、codegen CLI コマンドを使用して行います。

$ graph codegen

マッピングの準備ができたら、サブグラフをビルドする必要があります。このステップでは、マニフェストまたはマッピングにある可能性のあるエラーがハイライトされます。グラフノードにデプロイするためには、サブグラフを正常にビルドする必要があります。これは build CLI コマンドを使用して行うことができます。

$ graph build

サブグラフが作成されたら、CLI コマンドのgraph deployを使ってサブグラフをデプロイすることができます。

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