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

Reading time: 14 min

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

NEARは、非中央集権的なアプリケーションを構築するためのスマートコントラクトプラットフォームです。詳細は公式ドキュメントをご覧ください。

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

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

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

NEAR のドキュメントより:

@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は、イベントデータから、スキーマで定義されたエンティティに変換するコードです。NEAR サポートでは、NEAR 固有のデータタイプと、新しい JSON パース機能が導入されています。

サブグラフの開発には 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) を導入する
• ホスト側のグラフノード上のネットワークに対応している必要があります。ホスティングサービスでは、NEAR のメインネットはnear-mainnet,、NEAR のテストネットはnear-testnetです。
• NEAR のデータソースには、オプションでsource.accountフィールドが用意されており、これはNEAR accountに対応する人間が読める ID であり、アカウントまたはサブアカウントである可能性があります。
• 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:データソースのsource.accountが受信者であるすべてのレシートで実行されます。完全一致のみ処理されることに注意してください（subaccountsは独立したデータソースとして追加する必要があります）。

スキーマの定義は、結果として得られるサブグラフ・データベースの構造と、エンティティ間の関係を記述する。これは、元のデータソースに依存しません。スキーマ定義の詳細は、こちらにあります。

イベントを処理するためのハンドラはAssemblyScriptで書かれています。

NEAR インデックスは、AssemblyScript APIに NEAR 固有のデータタイプを導入します。

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を受け取ります

その他、マッピング実行中の NEAR サブグラフ開発者は、 AssemblyScript APIの残りの部分を利用できます。

これには、新しい JSON parsing function が含まれています。NEAR のログは、頻繁に文字列化された JSON として出力されます。新しいjson.fromString(...)関数は、開発者がこれらのログを簡単に処理できるように、JSON APIの一部として利用できます。

サブグラフを作成したら、それをインデックス作成のためにグラフ ノードにデプロイします。 NEAR サブグラフは、>=v0.26.x 以降のグラフ ノードにデプロイできます (このバージョンはまだタグ付けされていないか、リリースされていません)。

グラフのホステッドサービスは現在、NEAR mainnet と testnet のベータ版のインデックス作成をサポートしており、ネットワーク名は以下の通りです:

• near-mainnet
• near-testnet

ホステッドサービスでのサブグラフの作成と展開に関する詳細はこちらをご覧ください。

簡単に説明すると、最初のステップはサブグラフを「作成」することです。ホスティングサービスでは、ダッシュボードから行います。"Add Subgraph "をクリックします。

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

$ graph create --node <graph-node-url> subgraph/name # ローカルのグラフノードにサブグラフを作成します (Hosted Serviceでは、UI経由で実行)
$ graph deploy --node <graph-node-url> --ipfs https://api.thegraph.com/ipfs/ # 指定したIPFSエンドポイントにビルドファイルをアップロードし、マニフェストのIPFSハッシュに基づいて指定したグラフノードにサブグラフをデプロイします。

ノードの構成は、サブグラフがどこにディプロイされるかによって異なります。

graph deploy --node https://api.thegraph.com/deploy/ --ipfs https://api.thegraph.com/ipfs/ --access-token <your-access-token>

graph deploy --node http://localhost:8020/ --ipfs http://localhost:5001

デプロイされたサブグラフは、Graph Node によってインデックス化され、その進捗状況は、サブグラフ自体にクエリして確認できます:

{
  _meta {
    block {
      number
    }
  }
}

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

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

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

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

参考までにサブグラフの例を紹介します:

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 開発者ドキュメント