NEAR でサブグラフを作成する

Reading time: 12 min

このガイドは、NEAR blockchain上のスマートコントラクトを索引するサブグラフを構築するための入門書です。

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

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

サブグラフはイベントベースなので、チェーン上のイベントをリッスンしてから処理します。現在、NEAR サブグラフでサポートされているハンドラーは 2 種類あります:

• ブロックハンドラ：新しいブロックごとに実行されます
• レシートハンドラ：指定されたアカウントでメッセージが実行されるたびに実行されます

From the NEAR documentation:

@graphprotocol/graph-cliは、サブグラフを構築・展開するためのコマンドラインツールです。

@graphprotocol/graph-tsは、サブグラフ固有の型のライブラリです。

NEAR サブグラフの開発には、バージョン0.23.0以上のgraph-cliと、バージョン0.23.0以上のgraph-tsが必要です。

サブグラフの定義には 3 つの側面があります:

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.

サブグラフの開発には 2 つの重要なコマンドがあります:

$ graph codegen # マニフェストで識別されたようにファイルから型を生成します
$ グラフ ビルド # AssemblyScript ファイルから Web アセンブリを生成し、/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 サブグラフは、新しい種類のデータソース(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.accounts フィールドを導入し、オプションのサフィックスとプレフィックスを含んでいます。少なくともプレフィックスまたはサフィックスを指定する必要があり、それぞれ値のリストで始まるまたは終わる任意のアカウントにマッチします。以下の例では、以下のようにマッチします。[app|good].*[morning.near|morning.testnet]. リストだけが必要な場合は、他のフィールドを省略することができます。

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

NEAR データソースは 2 種類のハンドラーをサポートしています:

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

サブグラフを作成したら、それをインデックス作成のためにグラフ ノードにデプロイします。 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-mainnet
• near-testnet

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

サブグラフが作成されたら、CLI コマンドのgraph deployを使ってサブグラフをデプロイすることができます。

$ 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 Node によってインデックス化され、その進捗状況は、サブグラフ自体にクエリして確認できます:

{
  _meta {
    block {
      number
    }
  }
}

NEAR のインデックスを作成するグラフノードの運用には、以下のような運用要件があります:

• NEAR Indexer Framework と Firehose instrumentation
• NEAR Firehose コンポーネント
• Firehose エンドポイントが設定されたグラフノード

上記のコンポーネントの運用については、近日中に詳しくご紹介します。

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

Here are some example subgraphs for reference:

NEARブロック

NEAR 領収書

NEAR サポートはベータ版です。統合の改善を続ける中で、API に変更が加えられる可能性があります。NEAR サブグラフの構築をサポートし、最新の開発状況をお知らせしますので、[email protected]までメールをお送りください。

いいえ、サブグラフは 1 つのチェーン/ネットワークのデータソースのみをサポートします。

現在、ブロックとレシートのトリガーのみがサポートされています。指定されたアカウントへのファンクションコールのトリガーを検討しています。また、NEAR がネイティブイベントをサポートするようになれば、イベントトリガーのサポートも検討しています。

もしaccountが指定された場合、それは正確なアカウント名にのみマッチします。accounts フィールドを指定して、suffixes と prefixes でアカウントとサブアカウントにマッチさせることが可能で、例えば、次のようにするとすべての mintbase1.near サブアカウントにマッチすることになります。

accounts:
  suffixes:
    - mintbase1.near

これはサポートされていません。この機能がインデックス作成に必要かどうかを評価しています。

これは現在サポートされていません。この機能がインデックス作成に必要かどうかを評価しています。

「pending」は、NEAR サブグラフではまだサポートされていません。暫定的に、新しいバージョンを別の「named」サブグラフにデプロイし、それがチェーンヘッドと同期したときに、メインの「named」サブグラフに再デプロイすることができます。

もし、サブグラフ開発に関する一般的な質問であれば、開発者ドキュメントに多くの情報があります。それ以外の場合は、The Graph Protocol Discordに参加し、#nearチャンネルで質問するか、[email protected]までお寄せください。

• NEAR 開発者ドキュメント