在 Cosmos上构建子图

Reading time: 8 min

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

Graph 为开发人员提供了一种被称为子图的工具，利用这个工具，开发人员能够处理区块链事件，并通过 GraphQL API 提供结果数据。 Graph 节点现在能够处理 Cosmos 事件，这意味着 Cosmos 开发人员现在可以构建子图来索引链上事件。

Cosmos 子图目前支持四种类型的处理程序：

• 每当一个新的区块被追加到链中时，区块处理程序就会运行。
• 事件处理程序在发出特定事件时运行。
• 交易处理程序在发生交易时运行。
• 消息处理程序在发生特定消息时运行。

根据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.

定义子图有三个关键部分:

subgraph.yaml: 包含子图清单的 YAML 文件，标识需要跟踪以及如何处理哪些事件。

schema.graphql: 一个 GraphQL 模式文件，定义了为子图存储哪些数据，以及如何通过 GraphQL 查询这些数据。

AssemblyScript 映射: 将区块链数据转换为模式文件中定义的实体的AssemblyScript 代码。

子图清单(subgraph.yaml)标识子图的数据源、感兴趣的触发器以及应该响应这些触发器而运行的函数(处理程序)。下面是 Cosmos 子图的子图清单示例:

specVersion: 0.0.5
description: Cosmos Subgraph Example
schema:
  file: ./schema.graphql #指向模式文件的链接
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 # 映射文件中的函数名称
      eventHandlers:
        - event: rewards #将要处理的事件类型
          handler: handleReward # 映射文件中的函数名称
      transactionHandlers:
        - handler: handleTransaction # 映射文件中的函数名称
      messageHandlers:
        - message: /cosmos.staking.v1beta1.MsgDelegate # 消息的类型
          handler: handleMsgDelegate #映射文件中的函数名称
      file: ./src/mapping.ts #指向包含Assemblyscript映射的文件的链接

• Cosmos子图引入了一种新的数据源(Cosmos)。
• 该网络应该对应于 Cosmos 生态系统中的一个链。在示例中，使用了Cosmos Hub主网。

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 索引向 AssemblyScriptAPI引入了特定于 Cosmos 的数据类型。

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 类型。
• 消息处理程序接收 MessageData 类型。

作为 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

一旦映射就绪，就需要构建子图。此步骤将标记出清单或映射可能具有的任何错误。为了将子图部署到 Graph 节点，需要成功构建子图。可以使用build CLI 命令来完成:

$ graph build

创建子图后，您可以使用 graph deploy CLI 命令部署子图：

子图工作室

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 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