Cosmosでのサブグラフ構築

Reading time: 10 min

このガイドは、Cosmosベースのブロックチェーンをインデックスするサブグラフの構築について紹介するものです。

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

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

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

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

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

graph-cliは、サブグラフの構築とデプロイのためのCLIツールです。Cosmosサブグラフを扱うには、バージョン>=0.30.0が必要です。

graph-tsはサブグラフに特化した型のライブラリで、Cosmosのサブグラフを扱うにはバージョン>=0.27.0が必要です。

サブグラフの定義には、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が使用されています。

スキーマの定義は、結果として得られるサブグラフ・データベースの構造と、エンティティ間の関係を記述する。これは、元のデータソースに依存しません。スキーマ定義の詳細は、こちらにあります。

イベントを処理するためのハンドラはAssemblyScriptで書かれています。

Cosmosインデックスでは、Cosmos特有のデータ型を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統合の全種類一覧はこちらで確認できます。

Cosmosのメッセージはチェーンに固有であり、シリアル化されたProtocol Buffersペイロードの形でサブグラフに渡されることに注意することが重要です。その結果、メッセージデータは処理される前にマッピング関数でデコードされる必要があります。

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

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

$ graph codegen

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

$ graph build

サブグラフを作成したら、graph create CLIコマンドを実行した後、graph deploy CLIコマンドを使用してサブグラフをデプロイすることができます。

ホストされたサービス

グラフ作成アカウント/サブグラフ名 -製品ホスティングサービス

グラフ展開アカウント/サブグラフ名 -製品ホスティングサービス

ローカルのグラフノード(デフォルトの設定に基づく):

グラフ作成サブグラフ名 --ノード http://localhost:8020

グラフ展開サブグラフ名 --ノード http://localhost:8020/ --ipfs http://localhost:5001

CosmosサブグラフのGraphQLエンドポイントは、スキーマ定義によって決定され、既存のAPIインタフェースが使用されます。詳細はGraphQL API documentationを参照してください。

Cosmos Hubブロックチェーンは、Cosmosエコシステムの中で最初のブロックチェーンとなります。詳しくは公式ドキュメントをご覧ください。

Cosmos Hubのメインネットはcosmoshub-4です。コスモスハブの現在のテストネットはtheta-testnet-001です。
その他のCosmos Hubネットワーク、すなわちcosmoshub-3は停止しているため、データは提供されていません。

Osmosis は、Cosmos SDK の上に構築された分散型のクロスチェーン自動マーケット メーカー (AMM) プロトコルです。 IBC対応のトークンを取引します。詳細については、公式ドキュメントをご覧ください。

Osmosisメインネットはosmosis-1です。現在のテストネットは osmo-test-4 です。

参考までにサブグラフの例を紹介します:

ブロックフィルタリング例

バリデータ報酬の例

バリデータ・デリゲーションの例

Osmosisトークンスワップの例