Cosmosでのサブグラフ構築
Reading time: 9 min
This guide is an introduction on building subgraphs indexing based blockchains.
Graph は、ブロックチェーンのイベントを処理し、その結果得られたデータを GraphQL API を介して簡単に利用できるようにするためのツールを開発者に提供するもので、個別にはサブグラフとして知られています。が Cosmosイベントを処理できるようになったということは、Cosmosの開発者がスマートコントラクトの指標となるサブグラフを構築できるようになったということです。
Cosmosのサブグラフでサポートされているハンドラーは4種類あります。
- ブロックハンドラーは、新しいブロックがチェーンに追加されるたびに実行されます。
- イベントハンドラーは、特定のイベントが発生したときに実行されます。
- トランザクションハンドラーは、トランザクションが発生したときに実行されます。
- メッセージハンドラーは、特定のメッセージが発生したときに実行されます。
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.
are module-specific objects that trigger state transitions within the scope of the module they belong to.
ブロックハンドラーでは全てのデータにアクセスできますが、その他のハンドラーでは、サブグラフの開発者がよりきめ細かくデータを処理することができます。
is a CLI tool to build and deploy subgraphs, version >=0.30.0
is required in order to work with Cosmos subgraphs.
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です。 ブロックチェーンデータからスキーマで定義されたエンティティに変換するコードです。
サブグラフ マニフェスト (subgraph.yaml
) は、サブグラフのデータ ソース、関心のあるトリガー、およびこれらのトリガーに応答して実行される関数 (handlers
) を特定します。Cosmos サブグラフのサブグラフ マニフェストの例については、以下を参照してください。
specVersion: 0.0.5description: Cosmos Subgraph Exampleschema:file: ./schema.graphql # link to the schema filedataSources:- kind: cosmosname: CosmosHubnetwork: 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 genesismapping:apiVersion: 0.0.7language: wasm/assemblyscriptblockHandlers:- handler: handleNewBlock # the function name in the mapping fileeventHandlers:- event: rewards # the type of the event that will be handledhandler: handleReward # the function name in the mapping filetransactionHandlers:- handler: handleTransaction # the function name in the mapping filemessageHandlers:- message: /cosmos.staking.v1beta1.MsgDelegate # the type of a messagehandler: handleMsgDelegate # the function name in the mapping filefile: ./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 .
Cosmosインデックスでは、Cosmos特有のデータ型をに導入しています。
class Block {header: Headerevidence: EvidenceListresultBeginBlock: ResponseBeginBlockresultEndBlock: ResponseEndBlocktransactions: Array<TxResult>validatorUpdates: Array<Validator>}class EventData {event: Eventblock: HeaderOnlyBlocktx: TransactionContext}class TransactionData {tx: TxResultblock: HeaderOnlyBlock}class MessageData {message: Anyblock: HeaderOnlyBlocktx: TransactionContext}class TransactionContext {hash: Bytesindex: u32code: u32gasWanted: i64gasUsed: i64}class HeaderOnlyBlock {header: Header}class Header {version: ConsensuschainId: stringheight: u64time: TimestamplastBlockId: BlockIDlastCommitHash: BytesdataHash: BytesvalidatorsHash: BytesnextValidatorsHash: BytesconsensusHash: BytesappHash: ByteslastResultsHash: BytesevidenceHash: BytesproposerAddress: Byteshash: Bytes}class TxResult {height: u64index: u32tx: Txresult: ResponseDeliverTxhash: Bytes}class Event {eventType: stringattributes: Array<EventAttribute>}class Any {typeUrl: stringvalue: Bytes}
各ハンドラタイプは独自のデータ構造を持ち、マッピング関数の引数として渡されます。
- ブロックハンドラーは、
Block
を受け取ります. - イベントハンドラーは、
EventData
を受け取ります. - トランザクションハンドラーは、
TransactionData
を受け取ります. - メッセージハンドラーは、
MassageData
を受け取ります.
MessageData
の一部として、メッセージハンドラは、メッセージを包含するトランザクションに関する最も重要な情報を含む、トランザクションコンテキストを受け取ります。トランザクションコンテキストはEventData
型でも利用できますが、対 応するイベントがトランザクションと関連付けられている場合に限ります。さらに、すべてのハンドラはブロック(HeaderOnlyBlock
) への参照を受け取ります。
It's important to note that Cosmos messages are chain-specific and they are passed to a subgraph in the form of a serialized 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 --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 for more information.
The is the first blockchain in the ecosystem. You can visit the 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!
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 for more information.
Osmosis mainnet is osmosis-1
. Osmosis current testnet is osmo-test-4
.
Here are some example subgraphs for reference: