Déploiement d'un subgraph dans le service hébergé

Reading time: 9 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.

Après avoir créé un compte, accédez à votre tableau de bord. Copiez le jeton d'accès affiché sur le tableau de bord et exécutez graph auth --product hosted-service <ACCESS_TOKEN>. Le jeton d'accès sera ainsi stocké sur votre ordinateur. Vous ne devez effectuer cette opération qu'une seule fois, ou si vous régénérez le jeton d'accès.

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 - Sélectionnez une image à utiliser comme image de prévisualisation et comme vignette pour le subgraph.

Nom du sous-graphe - Avec le nom du compte sous lequel le sous-graphe est créé, ce champ définit également le nom de style nom du compte/nom du sous-graphe utilisé pour les déploiements et les points de terminaison GraphQL. Ce champ ne peut pas être modifié ultérieurement.

Compte : le compte sous lequel le subgraph est créé. Il peut s'agir du compte d'un individu ou d'une organisation. Les subgraphs ne pourront pas être déplacés ultérieurement entre les comptes.

Sous-titre : texte qui apparaîtra dans les cartes subgraphs.

Description - Description du Subgraph, visible sur la page de détails du subgraph.

GitHub URL - Lien vers le dépôt du subgraph sur 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.

Vous déployez le subgraph en exécutant 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.

L'état du subgraph passe à Synced une fois que le nœud the Graph a extrait toutes les données des blocs historiques. Le nœud de the Graph continuera à inspecter les blocs de votre subgraph au fur et à mesure que ces blocs seront exploités.

Lorsque vous apportez des modifications à la définition de votre subgraph, par exemple pour corriger un problème dans les mappages d'entités, exécutez à nouveau la commande yarn deploy ci-dessus pour déployer la version mise à jour de votre subgraph.

Si votre subgraph précédemment déployé est toujours en statut Synchronisation, il sera immédiatement remplacé par la version nouvellement déployée. Si le subgraph précédemment déployé est déjà entièrement synchronisé, Graph Node marquera la nouvelle version déployée comme Version en attente, la synchronisera en arrière-plan et ne remplacera la version actuellement déployée par la nouvelle qu'une fois la synchronisation de la nouvelle version terminée. Cela permet de s'assurer que vous disposez d'un subgraph avec lequel travailler pendant la synchronisation de la nouvelle version.

Dans certains cas, vous souhaiterez déployer le même subgraph sur plusieurs réseaux sans dupliquer tout son code. Le principal défi qui en découle est que les adresses contractuelles sur ces réseaux sont différentes.

Le graph build (depuis v0.29.0) et le graph deploy (depuis v0.32.0) acceptent deux nouvelles options :

Options:

      ...
      --network <nom>          Configuration du réseau à utiliser à partir du fichier de configuration des réseaux
      --network-file <chemin>     Chemin du fichier de configuration des réseaux (par défaut : "./networks.json")"

Vous pouvez utiliser l'option --network pour spécifier une configuration de réseau à partir d'un fichier standard json (par défaut networks.json) afin de mettre à jour facilement votre subgraph pendant le développement.

Remarque : La commande init générera désormais automatiquement un networks.json basé sur les informations fournies. Vous pourrez alors mettre à jour des réseaux existants ou ajouter des réseaux supplémentaires.

Si vous n'avez pas de fichier networks.json, vous devrez en créer un manuellement avec la structure suivante :

{
    "network1": { // le nom du réseau
        "dataSource1": { // le nom de la source de données
            "address": "0xabc...", // l'adresse du contrat (facultatif)
            "startBlock": 123456 // le bloc de départ (facultatif)
        },
        "dataSource2": {
            "address": "0x123...",
            "startBlock": 123444
        }
    },
    "network2": {
        "dataSource1": {
            "address": "0x987...",
            "startBlock": 123
        },
        "dataSource2": {
            "address": "0xxyz..",
            "startBlock": 456
        }
    },
    ...
}

Note: Vous n'avez pas à spécifier les modèles (si vous en avez) dans le fichier de configuration, seulement les dataSources. S'il existe des modèles déclarés dans le fichier subgraph.yaml, leur réseau sera automatiquement mis à jour avec celui spécifié avec l'option --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

Voici à quoi devrait ressembler votre fichier de configuration réseau :

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

Nous pouvons maintenant exécuter l'une des commandes suivantes :

# 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

Vous êtes maintenant prêt à yarn deploy.

Remarque : Comme mentionné précédemment, depuis graph-cli 0.32.0 vous pouvez exécuter directement yarn deploy avec le --network option :

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

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

Une solution pour les anciennes versions de graph-cli qui permet de paramétrer des aspects tels que les adresses de contrat consiste à en générer des parties à l'aide d'un système de modèles comme Mustache ou 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..."
}

et

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

Parallèlement à cela, vous remplaceriez le nom et les adresses du réseau dans le manifeste par des espaces réservés variables {{network}} et {{address}} et renommez le manifeste par exemple. subgraph.template.yaml :

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

Afin de générer un manifeste sur l'un ou l'autre des réseaux, vous pouvez ajouter deux commandes supplémentaires à package.json ainsi qu'une dépendance sur mustache :

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

Un exemple concret de ce type d'action peut être trouvé ici.

Note: Cette approche peut également être appliquée à des situations plus complexes, lorsqu'il est nécessaire de substituer plus que des adresses contractuelles et des noms de réseau ou de générer des mappings ou des ABI à partir de modèles.

Si un subgraph se synchronise avec succès, c'est un bon signe qu'il continuera à bien fonctionner pour toujours. Cependant, de nouveaux déclencheurs sur le réseau peuvent amener votre subgraph à rencontrer une condition d'erreur non testée ou il peut commencer à prendre du retard en raison de problèmes de performances ou de problèmes avec les opérateurs de nœuds.

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
      }
    }
  }
}

Cela vous donnera le chainHeadBlock que vous pouvez comparer avec le latestBlock de votre subgraph pour vérifier s'il est en retard. synced indique si le subgraph a déjà rattrapé la chaîne. health peut actuellement prendre les valeurs healthy si aucune erreur ne s'est produite, ou failed si une erreur a interrompu la progression du subgraph. Dans ce cas, vous pouvez consulter le champ fatalError pour obtenir des détails sur cette erreur.

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.

Chaque subgraph concerné par cette politique dispose d'une option de restauration de la version en question.