はじめに

OasysチェーンをThe Graphで取得するドキュメントの翻訳です。
2023.9.5現在です。
https://docs.oasys.games/docs/verse-developer/how-to-build-verse/1-11-the-graph

イントロ

The Graphは、ブロックチェーンのインデックス作成とクエリのためのプロトコルである。
「Subgraph」を導入することで、ブロックチェーンのデータはインデクサによって自動的にインデックス化され、GraphQLを介して簡単にアクセスすることができる。

グラフはトークンエコノミクスに基づく分散型Web3システムを採用しているが、インデックス作成ソフトウェアはオープンソースであり、Graph nodeとして誰でも利用できる。

このドキュメントでは、Verse-Layer上でGraphノードを実行し、Subgraphをデプロイする方法を説明する。

Graphノードの設定

docker-composeプロジェクトを作成する

プロジェクト・ディレクトリを作成する。

$ mkdir /path/to/project
$ cd /path/to/project

.envを作成する。

.env

NETWORK=<set the your verse's name (alphanumeric, hyphens, and underscores only)>
RPC_URL=<set the your verse's rpc (only http(s))>

docker-compose.ymlを作成します。

⚠制作上の注意事項

データベースのパスワードが堅牢であることを確認する。

Graph ノードの Admin API (TCP/8020) および IPFS API (TCP/5001) を公開しないでください。

docker-compose.yml

version: '3'

services:
  graph:
    image: graphprotocol/graph-node:v0.31.0
    environment:
      ethereum: $NETWORK:$RPC_URL
      postgres_db: graph_db
      postgres_user: graph_user
      postgres_pass: graph_pass
      postgres_host: postgres
      ipfs: http://ipfs:5001/
    ports:
      - 8000:8000/tcp # GraphQL(http)
      - 8001:8001/tcp # GraphQL(websocket)
      - 8020:8020/tcp # Admin API
    depends_on:
      - postgres
      - ipfs

  postgres:
    image: postgres:15.3
    environment:
      PGDATA: /data
      POSTGRES_DB: graph_db
      POSTGRES_USER: graph_user
      POSTGRES_PASSWORD: graph_pass
      POSTGRES_INITDB_ARGS: '--encoding=UTF8 --locale=C --lc-collate=C'
    volumes:
      - ./data/postgres:/data

  ipfs:
    image: ipfs/go-ipfs:v0.21.0
    environment:
      IPFS_PATH: /data
    volumes:
      - ./assets:/assets:ro
      - ./data/ipfs:/data
    ports:
      - 5001:5001/tcp

Postgresの実行

$ docker-compose up postgres

postgres-1  | 2023-08-01 05:57:59.611 UTC [1] LOG:  database system is ready to accept connections

IPFSノードの実行

IPFSデータディレクトリを初期化する（初回のみ）。

$ docker-compose run --rm --entrypoint ipfs ipfs init

generating ED25519 keypair...done
peer identity: 12D3KooWDqPCG7V9WgwyyFoF8sRy2RT19F7Ze84KxegAEew17zoS
initializing IPFS node at /data

設定ファイル(./data/ipfs/config)を修正する。

1. 他のノードとの接続を防ぐ。

# before
"Bootstrap": [
  // list of bootstrap nodes
]

# after
"Bootstrap": null

2.外部からのAPIアクセスを許可する。

# before
"Addresses": {
  "API": "/ip4/127.0.0.1/tcp/5001"
}

# after
"Addresses": {
  "API": "/ip4/0.0.0.0/tcp/5001"
}

IPFSを実行する。

$ docker-compose up ipfs

ipfs-1  | WebUI: http://0.0.0.0:5001/webui
ipfs-1  | Gateway server listening on /ip4/127.0.0.1/tcp/8080
ipfs-1  | Daemon is ready

APIアクセスを確認する。

$ curl -XPOST 'http://127.0.0.1:5001/api/v0/config?arg=Identity.PeerID'

{"Key":"Identity.PeerID","Value":"12D3KooWA25ixrGxRWsMVReWZc9Dn1qZkDYvuv7LTTgCEsz5M8ef"}

Graphノードの実行

$ docker-compose up graph

graph-1  | Aug 01 06:44:11.789 INFO Graph Node version: 0.26.0 (2022-04-22)

~

graph-1  | Aug 01 06:44:45.183 INFO Syncing 1 blocks from Ethereum, code: BlockIngestionStatus, blocks_needed: 1, blocks_behind: 1, latest_block_head: 167721, current_block_head: 167720, provider: verse-rpc-0, component: BlockIngestor

APIアクセスを確認する。

$ curl -H 'Content-Type: application/json' -d '{}' http://127.0.0.1:8020/

{"jsonrpc":"2.0","error":{"code":-32600,"message":"Invalid request"},"id":null}

サブグラフの展開

ERC20のTransferイベントのインデックスを作成するためにSubgraphを導入してみよう。

graph-cliをインストールする

$ npm install -g @graphprotocol/graph-cli

サブグラフの作成

パラメータを設定する。

$ CONTRACT_NAME=MyToken
$ CONTRACT_ADDRESS=0x...
$ CONTRACT_ABI=/path/to/contract/abi.json
$ SUBGRAPH_NAME=TestGraph
$ SUBGRAPH_DIR=/path/to/project/dir

サブグラフを作成する。

$ graph init $USER/$SUBGRAPH_NAME $SUBGRAPH_DIR \
  --node http://127.0.0.1:8020 \
  --protocol ethereum \
  --network mainnet \
  --contract-name $CONTRACT_NAME \
  --from-contract $CONTRACT_ADDRESS \
  --abi $CONTRACT_ABI \
  --index-events

Generate subgraph
  Write subgraph to directory
✔ Create subgraph scaffold
✔ Initialize networks config
✔ Initialize subgraph repository
✔ Install dependencies with yarn
✔ Generate ABI and schema types with yarn codegen

作業ディレクトリを変更する。

$ cd $SUBGRAPH_DIR

パッケージのダウングレード

The Graphパッケージの最新バージョンにおけるIPFSとの互換性の問題により、バージョンをダウングレードする必要があります。package.jsonを修正してください。

package.json

"dependencies": {
  "@graphprotocol/graph-cli": "0.45.1",
  "@graphprotocol/graph-ts": "0.30.0"
},
"resolutions": {
  "ipfs-http-client": "34.0.0",
  "concat-stream": "1.6.2"
}

ダウングレードの実行

$ yarn

マニフェストの修正

The Graphが公式にサポートしていないチェーンのインデックスを作成するには、マニフェストファイル(subgraph.yaml)のdataSources[].networkを.envファイルの$NETWORK変数と同じ文字列に変更する必要があります。

subgraph.yaml

# before
network: mainnet

# after
network: '<Set the $NETWORK value in the .env>'

デプロイ

サブグラフをインデクサに登録する。(初回のみ）

$ npm run create-local
> create-local
> graph create --node http://localhost:8020/ username/TestGraph

Created subgraph: username/TestGraph

デプロイしてください。
バージョン名を聞かれますので、適宜指定してください。

$ npm run deploy-local

> deploy-local
> graph deploy --node http://localhost:8020/ --ipfs http://localhost:5001 username/TestGraph

Which version label to use? (e.g. "v0.0.1"): v0.0.1

~

Build completed: QmbZC8ENbFWV7WNHqGuFPGzH4mSDtKRc9rXkst99eShT7i

Deployed to http://localhost:8000/subgraphs/name/username/TestGraph/graphql

Subgraph endpoints:
Queries (HTTP):     http://localhost:8000/subgraphs/name/username/TestGraph

クエリ

クエリを実行してみましょう。
まず、$CONTRACT_ADDRESS で指定された ERC20 コントラクトで mint または transfer メソッドを取引し、Transfer イベントを生成します。

次に、開発用クエリエディタ（GraphiQL）を開き、クエリを実行します。
エディターのURLはデプロイ時にQueries (HTTP)として表示されます。
(例: http://localhost:8000/subgraphs/name/{username}/{subgraph_name})

{
  transfers {
    id
    from
    to
    value
  }
}

セットアップが成功すれば、インデックス化された Transfer イベントを取得できるはずです。

関連文書

最後に

お役に立てれば幸いです。