Docs
⌘ K

6 minutes

Remplacer un contrat et conserver son historique grâce au « greffage »

Dans ce guide, vous apprendrez à construire et à déployer de nouveaux subgraphs en greffant des subgraps existants.

Qu’est-ce qu’une greffe ?

Le greffage permet de réutiliser les données d’un subgraph existant et de commencer à les indexer dans un bloc ultérieur. Cette méthode est utile au cours du développement pour surmonter rapidement de simples erreurs dans les mappages ou pour rétablir temporairement le fonctionnement d’un subgraph existant après une défaillance. Elle peut également être utilisée lors de l’ajout d’une fonctionnalité à un subgraph dont l’indexation à partir de zéro prend beaucoup de temps.

The grafted Subgraph can use a GraphQL schema that is not identical to the one of the base Subgraph, but merely compatible with it. It has to be a valid Subgraph schema in its own right, but may deviate from the base Subgraph’s schema in the following ways:

  • Il ajoute ou supprime des types d’entité
  • Il supprime les attributs des types d’entité
  • Il ajoute des attributs nullables aux types d’entités
  • Il transforme les attributs non nullables en attributs nuls
  • Cela ajoute des valeurs aux énumérations
  • Il ajoute ou supprime des interfaces
  • Cela change pour quels types d’entités une interface est implémentée

Pour plus d’informations, vous pouvez vérifier :

Dans ce tutoriel, nous allons couvrir un cas d’utilisation de base. Nous remplacerons un contrat existant par un contrat identique (avec une nouvelle adresse, mais le même code). Ensuite, nous grefferons le subgraph existant sur le subgraph “de base” qui suit le nouveau contrat.

Remarque importante sur le greffage lors de la mise à niveau vers le réseau

Attention : Il est recommandé de ne pas utiliser le greffage pour les subgraphs publiés sur The Graph Network

Pourquoi est-ce important?

Le greffage est une fonction puissante qui vous permet de “greffer” un subgraph sur un autre, en transférant efficacement les données historiques du subgraph existant vers une nouvelle version. Il n’est pas possible de greffer un subgraph provenant de The Graph Network vers Subgraph Studio.

Les meilleures pratiques

Migration initiale : lorsque vous déployez pour la première fois votre subgraph sur le réseau décentralisé, faites-le sans greffage. Assurez-vous que le subgraph est stable et fonctionne comme prévu.

Mises à jour ultérieures : une fois que votre subgraph est en ligne et stable sur le réseau décentralisé, vous pouvez utiliser le greffage pour les versions ultérieures afin de faciliter la transition et de préserver les données historiques.

En respectant ces lignes directrices, vous minimisez les risques et vous vous assurez que le processus de migration se déroule sans heurts.

Création d’un subgraph existant

La construction de subgraphs est une partie essentielle de The Graph, décrite plus en profondeur ici. Pour pouvoir construire et déployer le subgraph existant utilisé dans ce tutoriel, la repo suivant est fourni :

Remarque : le contrat utilisé dans le subgraph est tiré du Hackathon Starterkit⁠ suivant.

Définition du manifeste du subgraph

Le manifeste du subgraph subgraph.yaml identifie les sources de données pour le subgraph, les déclencheurs interessants et les fonctions qui doivent être exécutées en réponse à ces déclencheurs. Vous trouverez ci-dessous un exemple de manifeste de subgraph que vous utiliserez :

specVersion: 1.3.0schema:  file: ./schema.graphqldataSources:  - kind: ethereum    name: Lock    network: sepolia    source:      address: '0xb3aabe721794b85fe4e72134795c2f93b4eb7e63'      abi: Lock      startBlock: 5955690    mapping:      kind: ethereum/events      apiVersion: 0.0.9      language: wasm/assemblyscript      entities:        - Withdrawal      abis:        - name: Lock          file: ./abis/Lock.json      eventHandlers:        - event: Withdrawal(uint256,uint256)          handler: handleWithdrawal      file: ./src/lock.ts
  • La source de données Lock est l’adresse de l’abi et du contrat que nous obtiendrons lorsque nous compilerons et déploierons le contrat
  • Le réseau doit correspondre à un réseau indexé qui est interrogé. Comme nous fonctionnons sur le réseau de test Sepolia, le réseau est sepolia
  • La section mapping définit les déclencheurs intéressants et les fonctions qui doivent être exécutées en réponse à ces déclencheurs. Dans ce cas, nous écoutons l’événement Withdrawal et appelons la fonction handleWithdrawal lorsqu’il est émis.

Définition de manifeste de greffage

Le greffage consiste à ajouter deux nouveaux éléments au manifeste original du subgraph :

---features:  - grafting # nom de la caractéristiquegraft:  base: Qm... # Subgraph ID of base Subgraph  block: 5956000 # block number
  • features: est une liste de tous les noms de fonctionnalités utilisées.
  • graft: est une carte du subgraph base et du bloc sur lequel se greffer. Le bloc est le numéro du bloc à partir duquel l’indexation doit commencer. The Graph copiera les données du subgraph de base jusqu’au bloc donné inclus, puis continuera à indexer le nouveau subgraph à partir de ce bloc.

Les valeurs base et block peuvent être trouvées en déployant deux subgraphs : l’un pour l’indexation de base et l’autre avec le greffage

Déploiement du subgraph de base

  1. Allez sur Subgraph Studio et créez un subgraph sur le réseau de test Sepolia appelé graft-example
  2. Suivez les instructions dans la section AUTH & DEPLOY sur votre page Subgraph dans le dossier graft-example de la repo
  3. Once finished, verify the Subgraph is indexing properly. If you run the following command in The Graph Playground
{  withdrawals(first: 5) {    id    amount    when  }}

Cela renvoie quelque chose comme ceci :

{  "data": {    "withdrawals": [      {        "id": "0xe8323d21c4f104607b10b0fff9fc24b9612b9488795dea8196b2d5f980d3dc1d0a000000",        "amount": "0",        "when": "1716394824"      },      {        "id": "0xea1cee35036f2cacb72f2a336be3e54ab911f5bebd58f23400ebb8ecc5cfc45203000000",        "amount": "0",        "when": "1716394848"      }    ]  }}

Une fois que vous avez vérifié que le subgraph est correctement indexé, vous pouvez rapidement le mettre à jour par greffage.

Déploiement du subgraph greffé

Le subgraph.yaml de remplacement du greffon aura une nouvelle adresse de contrat. Cela peut arriver lorsque vous mettez à jour votre dapp, redéployez un contrat, etc.

  1. Allez sur Subgraph Studio et créez un subgraph sur le réseau test de Sepolia appelé graft-replacement
  2. Créer un nouveau manifeste. Le subgraph.yaml de graph-replacement contient une adresse de contrat différente et de nouvelles informations sur la façon dont il devrait se greffer. Il s’agit du block du dernier événement émis⁠ qui vous intéresse dans l’ancien contrat et de la base de l’ancien subgraph. L’ID du subgraph base est l’ID de déploiement de votre subgraph original graph-example. Vous pouvez le trouver dans Subgraph Studio.
  3. Suivez les instructions de la section AUTH & DEPLOY sur votre page Subgraph dans le dossier graft-replacement de la repo
  4. Once finished, verify the Subgraph is indexing properly. If you run the following command in The Graph Playground
{  withdrawals(first: 5) {    id    amount    when  }}

Le résultat devrait être le suivant :

{  "data": {    "withdrawals": [      {        "id": "0xe8323d21c4f104607b10b0fff9fc24b9612b9488795dea8196b2d5f980d3dc1d0a000000",        "amount": "0",        "when": "1716394824"      },      {        "id": "0xea1cee35036f2cacb72f2a336be3e54ab911f5bebd58f23400ebb8ecc5cfc45203000000",        "amount": "0",        "when": "1716394848"      },      {        "id": "0x2410475f76a44754bae66d293d14eac34f98ec03a3689cbbb56a716d20b209af06000000",        "amount": "0",        "when": "1716429732"      }    ]  }}

Vous pouvez voir que le subgraph graft-replacement indexe les anciennes données du graph-example et les nouvelles données de la nouvelle adresse du contrat. Le contrat original a émis deux événements Withdrawal, Event 1⁠ et Event 2⁠. Le nouveau contrat a émis un seul événement de retrait, Event 3⁠. Les deux transactions précédemment indexées (événements 1 et 2) et la nouvelle transaction (événement 3) ont été combinées ensemble dans le subgraph de remplacement de greffe.

Félicitations ! Vous avez réussi à greffer un subgraph sur un autre subgraph.

Ressources supplémentaires

Si vous souhaitez acquérir plus d’expérience avec le greffage, voici quelques exemples pour des contrats populaires :

Pour devenir encore plus expert sur The Graph, vous pouvez vous familiariser avec d’autres méthodes de gestion des modifications apportées aux sources de données sous-jacentes. Des alternatives comme des Modèles de sources de données permettent d’obtenir des résultats similaires

Note : De nombreux éléments de cet article ont été repris de l’article Arweave publié précédemment