在 NEAR 上构建子图

Reading time: 11 min

本指南介绍了如何在NEAR 区块链上构建索引智能合约的子图。

NEAR is a smart contract platform for building decentralized applications. Visit the official documentation for more information.

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

子图是基于事件的，这意味着子图可以侦听并处理链上事件。 NEAR 子图目前支持两种类型的处理程序：

• 区块处理器: 这些处理程序在每个新区块上运行。
• 收据处理器: 每次在指定账户上一个消息被执行时运行。

From the NEAR documentation:

@graphprotocol/graph-cli是一个用于构建和部署子图的命令行工具。

@graphprotocol/graph-ts 是子图特定类型的库。

NEAR 子图开发需要0.23.0以上版本的graph-cli，以及 0.23.0以上版本的graph-ts。

子图定义包括三个方面：

subgraph.yaml: 子图清单，定义感兴趣的数据源以及如何处理它们。 NEAR 是一种全新类型数据源。

schema.graphql: 一个模式文件，定义子图存储的数据以及如何通过 GraphQL 查询数据。NEAR 子图的要求已经在现有的文档中介绍了。

AssemblyScript Mappings: AssemblyScript code that translates from the event data to the entities defined in your schema. NEAR support introduces NEAR-specific data types and new JSON parsing functionality.

在子图开发过程中，有两个关键命令：

$ graph codegen # 从清单中标识的模式文件生成类型
$ graph build # 从 AssemblyScript 文件生成 Web Assembly，并在 /build 文件夹中准备所有子图文件

子图清单(subgraph.yaml)标识子图的数据源、感兴趣的触发器以及响应这些触发器而运行的函数。 以下是一个 NEAR 的子图清单的例子：

specVersion: 0.0.2
schema:
  file: ./src/schema.graphql # link to the schema file
dataSources:
  - kind: near
    network: near-mainnet
    source:
      account: app.good-morning.near # This data source will monitor this account
      startBlock: 10662188 # Required for NEAR
    mapping:
      apiVersion: 0.0.5
      language: wasm/assemblyscript
      blockHandlers:
        - handler: handleNewBlock # the function name in the mapping file
      receiptHandlers:
        - handler: handleReceipt # the function name in the mapping file
      file: ./src/mapping.ts # link to the file with the Assemblyscript mappings

• NEAR 子图引入了一种新的 kind 数据源（near）。
• The network should correspond to a network on the hosting Graph Node. On Subgraph Studio, NEAR's mainnet is near-mainnet, and NEAR's testnet is near-testnet
• NEAR data sources introduce an optional source.account field, which is a human-readable ID corresponding to a NEAR account. This can be an account or a sub-account.
• NEAR 数据源引入了一个替代的可选 source. account 字段，其中包含可选的后缀和前缀。至少必须指定前缀或后缀，它们将分别与以值列表开始或结束的任何账户匹配。下面的例子将匹配: [ app | good]。* [ morning.near | morning.testnet].如果只需要一个前缀或后缀列表，则可以省略其他字段。

accounts:
  prefixes:
    - app
    - good
  suffixes:
    - morning.near
    - morning.testnet

NEAR 数据源支持两种类型的处理程序：

• blockHandlers：在每个新的 NEAR 区块上运行。 不需要 source.account。
• receiptHandlers: run on every receipt where the data source's source.account is the recipient. Note that only exact matches are processed (subaccounts must be added as independent data sources).

模式定义描述了生成的子图数据库结构以及实体之间的关系。这与原始数据源是不可知的。这里有更多关于子图模式定义的细节。

处理事件的处理程序是用 AssemblyScript 编写的。

NEAR indexing introduces NEAR-specific data types to the AssemblyScript API.

class ExecutionOutcome {
      gasBurnt: u64,
      blockHash: Bytes,
      id: Bytes,
      logs: Array<string>,
      receiptIds: Array<Bytes>,
      tokensBurnt: BigInt,
      executorId: string,
  }

class ActionReceipt {
      predecessorId: string,
      receiverId: string,
      id: CryptoHash,
      signerId: string,
      gasPrice: BigInt,
      outputDataReceivers: Array<DataReceiver>,
      inputDataIds: Array<CryptoHash>,
      actions: Array<ActionValue>,
  }

class BlockHeader {
      height: u64,
      prevHeight: u64,// Always zero when version < V3
      epochId: Bytes,
      nextEpochId: Bytes,
      chunksIncluded: u64,
      hash: Bytes,
      prevHash: Bytes,
      timestampNanosec: u64,
      randomValue: Bytes,
      gasPrice: BigInt,
      totalSupply: BigInt,
      latestProtocolVersion: u32,
  }

class ChunkHeader {
      gasUsed: u64,
      gasLimit: u64,
      shardId: u64,
      chunkHash: Bytes,
      prevBlockHash: Bytes,
      balanceBurnt: BigInt,
  }

class Block {
      author: string,
      header: BlockHeader,
      chunks: Array<ChunkHeader>,
  }

class ReceiptWithOutcome {
      outcome: ExecutionOutcome,
      receipt: ActionReceipt,
      block: Block,
  }

这些类型被传递给区块 & 收据处理程序：

• 块处理程序将收到 Block
• 收据处理程序将收到 ReceiptWithOutcome

Otherwise, the rest of the AssemblyScript API is available to NEAR subgraph developers during mapping execution.

This includes a new JSON parsing function - logs on NEAR are frequently emitted as stringified JSONs. A new json.fromString(...) function is available as part of the JSON API to allow developers to easily process these logs.

构建子图后，就可以将其部署到 Graph节点以进行索引了。 NEAR 子图可以部署到任何图节点 >=v0.26.x（此版本尚未标记和发布）。

Subgraph Studio and the upgrade Indexer on The Graph Network currently supports indexing NEAR mainnet and testnet in beta, with the following network names:

• near-主网
• near-测试网

More information on creating and deploying subgraphs on Subgraph Studio can be found here.

As a quick primer - the first step is to "create" your subgraph - this only needs to be done once. On Subgraph Studio, this can be done from your Dashboard: "Create a subgraph".

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

$ graph create --node <graph-node-url> <subgraph-name> # creates a subgraph on a local Graph Node (on Subgraph Studio, this is done via the UI)
$ graph deploy --node <graph-node-url> --ipfs https://api.thegraph.com/ipfs/ <subgraph-name> # uploads the build files to a specified IPFS endpoint, and then deploys the subgraph to a specified Graph Node based on the manifest IPFS hash

节点配置将取决于子图的部署位置。

graph auth
graph deploy <subgraph-name>

graph deploy --node http://localhost:8020/ --ipfs http://localhost:5001 <subgraph-name>

部署子图后，它将由 Graph节点索引。 您可以通过查询子图本身来检查其进度：

{
  _meta {
    block {
      number
    }
  }
}

运行索引 NEAR 的 Graph节点有以下操作要求：

• 带有 Firehose 工具的 NEAR 索引人框架
• NEAR Firehose 组件
• 配置了 Firehose 端点的Graph节点

我们将很快提供有关运行上述组件的更多信息。

NEAR 子图的 GraphQL 端点由模式定义和现有的 API 接口决定。更多信息，请访问 GraphQLAPI文档。

Here are some example subgraphs for reference:

NEAR块

NEAR收据

NEAR 支持处于测试阶段，这意味着随着我们继续致力于改进集成，API 可能会发生变化。 请发送电子邮件至 [email protected]，以便我们支持您构建 NEAR 子图，并让您了解最新进展！

不，子图只能支持来自一个链/网络的数据源。

目前，仅支持 Block 和 Receipt 触发器。 我们正在调查对指定帐户的函数调用的触发器。 一旦 NEAR 拥有原生事件支持，我们也对支持事件触发器感兴趣。

如果指定了账户，那么它将只与确切的账户名匹配。可以通过指定accounts字段来匹配子账户，并指定后缀和前缀来匹配账户和子账户，例如，下面将匹配所有 mintbase1.near 子账户:

accounts:
  suffixes:
    - mintbase1.near

这是不支持的。 我们正在评估索引是否需要此功能。

目前不支持此功能。 我们正在评估索引是否需要此功能。

NEAR 子图尚不支持挂起的功能。 在此期间，您可以将新版本部署到不同的“命名”子图，然后当它与链头同步时，您可以重新部署到您的主“命名”子图，它将使用相同的底层部署 ID，所以 主子图将立即同步。

If it is a general question about subgraph development, there is a lot more information in the rest of the Developer documentation. Otherwise please join The Graph Protocol Discord and ask in the #near channel or email [email protected].

• NEAR 开发者文档