クックブック > Cosmosでのサブグラフ構築

Cosmosでのサブグラフ構築

Reading time: 9 min

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

Cosmosのサブグラフとは何ですか?

このセクションへのリンク

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

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

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

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

Events are objects that contain information about the execution of the application. They are mainly used by service providers like block explorers and wallets to track the execution of various messages and index transactions.

Transactions are objects created by end-users to trigger state changes in the application.

Messages are module-specific objects that trigger state transitions within the scope of the module they belong to.

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

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 マッピング

このセクションへのリンク

イベントを処理するためのハンドラは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統合の全種類一覧はこちらで確認できます。

メッセージ・デコーディング

このセクションへのリンク

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.

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

Cosmosサブグラフの作成と構築

このセクションへのリンク

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

$ graph codegen

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

$ graph build

Cosmosサブグラフの展開

このセクションへのリンク

サブグラフが作成されたら、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

Cosmosサブグラフのクエリ

このセクションへのリンク

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.

Cosmosブロックチェーンに対応

このセクションへのリンク

コスモスハブとは?

このセクションへのリンク

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 support in Graph Node and on Subgraph Studio is in beta: please contact the graph team with any questions about building Osmosis subgraphs!

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

ページを編集

NEAR でサブグラフを作成する
Arweaveでのサブグラフ構築
ページを編集