サブグラフをホスティングサービスにデプロイする

Reading time: 12 min

This page explains how to deploy a subgraph to the hosted service. To deploy a subgraph you need to first install the Graph CLI. If you have not created a subgraph already, see creating a subgraph.

Before using the hosted service, create an account in our hosted service. You will need a Github account for that; if you don't have one, you need to create that first. Then, navigate to the hosted service, click on the 'Sign up with Github' button, and complete Github's authorization flow.

アカウントの作成後、dashboardに移動します。ダッシュボードに表示されているアクセストークンをコピーし、graph auth --product hosted-service <ACCESS_TOKEN>を実行します。これでアクセストークンがあなたのコンピュータに保存されます。この作業は 1 回だけ行う必要がありますが、アクセストークンを再生成する場合も同様です。

Before deploying the subgraph, you need to create it in Graph Explorer. Go to the dashboard and click on the Add Subgraph button and fill in the information below as appropriate:

Image - サブグラフのプレビュー画像やサムネイルとして使用する画像を選択します。

Subgraph Name - サブグラフが作成されるアカウント名と一緒に、デプロイメントや GraphQL エンドポイントで使用されるaccount-name/subgraph-nameのスタイル名も定義します。このフィールドは後で変更できませんこのフィールドは後で変更できません。

Account - サブグラフが作成されるアカウントです。これは個人または組織のアカウントになります。サブグラフは後でアカウント間で移動できません。

Subtitle - サブグラフカードに表示されるテキストです。

Description - サブグラフの説明、サブグラフの詳細ページで表示されます。

GitHub URL - GitHub 上のサブグラフのリポジトリへのリンクです。

Hide - Switching this on hides the subgraph in Graph Explorer.

After saving the new subgraph, you are shown a screen with help on how to install the Graph CLI, how to generate the scaffolding for a new subgraph, and how to deploy your subgraph. The first two steps were covered in the Creating a Subgraph section.

Deploying your subgraph will upload the subgraph files that you've built with yarn build to IPFS and tell Graph Explorer to start indexing your subgraph using these files.

サブグラフのデプロイは、yarn deployを実行して行います。

After deploying the subgraph, Graph Explorer will switch to showing the synchronization status of your subgraph. Depending on the amount of data and the number of events that need to be extracted from historical blocks, starting with the genesis block, syncing can take from a few minutes to several hours.

グラフ ノードが履歴ブロックからすべてのデータを抽出すると、サブグラフのステータスは Synced に切り替わります。これらのブロックがマイニングされると、グラフ ノードはサブグラフのブロックを検査し続けます。

エンティティ・マッピングの問題を修正するなど、サブグラフの定義に変更を加える場合は、上記のyarn deploy コマンドを再度実行して、サブグラフの更新版をデプロイします。サブグラフを更新する際には、グラフ・ノードがサブグラフ全体のインデックスを再作成する必要があります。

以前にデプロイされたサブグラフがまだSyncingの状態にある場合は、新しくデプロイされたバージョンにすぐに置き換えられます。以前にデプロイされたサブグラフがすでに完全に同期されている場合、グラフノードは新しくデプロイされたバージョンを「Pending Version」としてマークし、バックグラウンドで同期を行い、新しいバージョンの同期が終了してから、現在デプロイされているバージョンを新しいバージョンに置き換えます。これにより、新しいバージョンが同期している間も、サブグラフを使って作業することができます。

場合によっては、すべてのコードを複製せずに、同じサブグラフを複数のネットワークに展開する必要があります。これに伴う主な課題は、これらのネットワークのコントラクト アドレスが異なることです。

graph build (v0.29.0 から) と graph deploy (v0.32.0 から) は共に、二つの新しいオプションを受け入れるようになりました。

Options:

      ...
      --network <name>          Network configuration to use from the networks config file
      --network-file <path>     Networks config file path (default: "./networks.json")

--network オプションで、json 標準ファイル（デフォルトは networks.json ）からネットワーク設定を指定して、開発中にサブグラフを簡単に更新することが可能です。

Note: init コマンドは提供された情報に基づいて networks.json を自動生成するようになりました。これにより、既存のネットワークを更新したり、追加したりすることができます。

networks.jsonファイルがない場合は、以下の構造で手動で作成する必要があります:

{
    "network1": { // the network name
        "dataSource1": { // the dataSource name
            "address": "0xabc...", // the contract address (optional)
            "startBlock": 123456 // the startBlock (optional)
        },
        "dataSource2": {
            "address": "0x123...",
            "startBlock": 123444
        }
    },
    "network2": {
        "dataSource1": {
            "address": "0x987...",
            "startBlock": 123
        },
        "dataSource2": {
            "address": "0xxyz..",
            "startBlock": 456
        }
    },
    ...
}

Note: 設定ファイルではtemplates（もしあれば）を指定する必要はなく、dataSourcesだけを指定すればよいでしょう。もし、subgraph.yamlファイルで宣言されたtemplatesがあれば、それらのネットワークは自動的に--networkオプションで指定したものに更新されます。

Now, let's assume you want to be able to deploy your subgraph to the mainnet and sepolia networks, and this is your subgraph.yaml:

# ...
dataSources:
  - kind: ethereum/contract
    name: Gravity
    network: mainnet
    source:
      address: '0x123...'
      abi: Gravity
    mapping:
      kind: ethereum/events

ネットワーク設定ファイルはこのようになっているはずです:

{
  "mainnet": {
    "Gravity": {
      "address": "0x123..."
    }
  },
  "sepolia": {
    "Gravity": {
      "address": "0xabc..."
    }
  }
}

これで、次のいずれかのコマンドを実行できるようになりました:

# Using default networks.json file
yarn build --network sepolia

# Using custom named file
yarn build --network sepolia --network-file path/to/config

The build command will update your subgraph.yaml with the sepolia configuration and then re-compile the subgraph. Your subgraph.yaml file now should look like this:

# ...
dataSources:
  - kind: ethereum/contract
    name: Gravity
    network: sepolia
    source:
      address: '0xabc...'
      abi: Gravity
    mapping:
      kind: ethereum/events

これでyarn deployの準備が整いました。

Note: 前述のように、graph-cli 0.32.0 からは --network オプションで直接 yarn deploy を実行できるようになりました:

# Using default networks.json file
yarn deploy --network sepolia

# Using custom named file
yarn deploy --network sepolia --network-file path/to/config

古いバージョンのgraph-cliで、コントラクトアドレスのような側面をパラメータ化できるようにする一つの解決策は、Mustache や Handlebars などのテンプレートシステムを使ってその一部を生成することです。

To illustrate this approach, let's assume a subgraph should be deployed to mainnet and Sepolia using different contract addresses. You could then define two config files providing the addresses for each network:

{
  "network": "mainnet",
  "address": "0x123..."
}

and/と

{
  "network": "sepolia",
  "address": "0xabc..."
}

また、マニフェストのネットワーク名とアドレスを変数プレースホルダー{{network}}と{{address}}で置き換え、マニフェストの名前を例えばsubgraph.template.yamlに変更します。

# ...
dataSources:
  - kind: ethereum/contract
    name: Gravity
    network: mainnet
    network: {{network}}
    source:
      address: '0x2E645469f354BB4F5c8a05B3b30A929361cf77eC'
      address: '{{address}}'
      abi: Gravity
    mapping:
      kind: ethereum/events

どちらのネットワークにも対応したマニフェストを生成するには、package.jsonにmustacheへの依存関係とともに 2 つのコマンドを追加します:

{
  ...
  "scripts": {
    ...
    "prepare:mainnet": "mustache config/mainnet.json subgraph.template.yaml > subgraph.yaml",
    "prepare:sepolia": "mustache config/sepolia.json subgraph.template.yaml > subgraph.yaml"
  },
  "devDependencies": {
    ...
    "mustache": "^3.1.0"
  }
}

To deploy this subgraph for mainnet or Sepolia you would now simply run one of the two following commands:

# Mainnet:
yarn prepare:mainnet && yarn deploy

# Sepolia:
yarn prepare:sepolia && yarn deploy

この例は、こちらでご覧いただけます。

注: このアプローチは、より複雑な状況にも適用できます。たとえば、コントラクト アドレスやネットワーク名以外のものを置き換える必要がある場合や、テンプレートからマッピングや ABI を生成する場合にも適用できます。

サブグラフが正常に同期された場合、それはそれが永久に正常に動作し続けることを示す良い兆候です。ただし、ネットワーク上の新しいトリガーにより、サブグラフがテストされていないエラー状態に陥ったり、パフォーマンスの問題やノード オペレーターの問題により遅れが生じたりする可能性があります。

Graph Node exposes a graphql endpoint which you can query to check the status of your subgraph. On the hosted service, it is available at https://api.thegraph.com/index-node/graphql. On a local node, it is available on port 8030/graphql by default. The full schema for this endpoint can be found here. Here is an example query that checks the status of the current version of a subgraph:

{
  indexingStatusForCurrentVersion(subgraphName: "org/subgraph") {
    synced
    health
    fatalError {
      message
      block {
        number
        hash
      }
      handler
    }
    chains {
      chainHeadBlock {
        number
      }
      latestBlock {
        number
      }
    }
  }
}

これにより、chainHeadBlockが得られ、サブグラフのlatestBlockと比較して、遅れているかどうかを確認できます。 syncedは、サブグラフがチェーンに追いついたかどうかを通知します。healthは現在、エラーが発生していない場合はhealthy、サブグラフの進行を停止させるエラーが発生した場合はfailedという値を取ることができます。この場合、このエラーの詳細についてfatalErrorフィールドを確認できます。

The hosted service is a free Graph Node Indexer. Developers can deploy subgraphs indexing a range of networks, which will be indexed, and made available to query via graphQL.

To improve the performance of the service for active subgraphs, the hosted service will archive subgraphs that are inactive.

A subgraph is defined as "inactive" if it was deployed to the hosted service more than 45 days ago, and if it has received 0 queries in the last 45 days.

Developers will be notified by email if one of their subgraphs has been marked as inactive 7 days before it is removed. If they wish to "activate" their subgraph, they can do so by making a query in their subgraph's hosted service graphQL playground. Developers can always redeploy an archived subgraph if it is required again.

A subgraph version in Studio is archived if and only if it meets the following criteria:

• The version is not published to the network (or pending publish)
• The version was created 45 or more days ago
• The subgraph hasn't been queried in 30 days

In addition, when a new version is deployed, if the subgraph has not been published, then the N-2 version of the subgraph is archived.

このポリシーで影響を受けるすべてのサブグラフには、問題のバージョンを戻すオプションがあります。