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

Reading time: 6 min

Dans ce guide, vous apprendrez à construire et à déployer de nouveaux subgraphs en utilisant le greffage sur des subgraphs existants.

C'est une méthode qui réutilise les données d'un subgraph existant et commence à les indexer à un bloc ultérieur. Elle est utile lors du développement pour contourner rapidement les erreurs simples dans les mappings ou pour remettre temporairement en service un subgraph existant qui a échoué. Elle peut également être utilisée pour ajouter une fonctionnalité à un subgraphe dont l'indexation depuis la genèse prend un temps considérable.

Le subgraph greffé peut utiliser un schema GraphQL qui n'est pas identique à celui du subgraph de base, mais simplement compatible avec lui. Il doit s'agir d'un schema de subgraph valide en tant que tel, mais il peut s'écarter du schema du subgraph de base de la manière suivante :

• 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 :

• Greffage

Dans ce tutoriel, nous allons aborder un cas d'utilisation de base. Nous allons remplacer 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.

La greffe est une fonctionnalité puissante qui permet de "greffer" un subgraph sur un autre, transférant ainsi les données historiques du subgraph existant vers une nouvelle version. Bien qu'il s'agisse d'un moyen efficace de préserver les données et de gagner du temps sur l'indexation, la greffe peut introduire des complexités et des problèmes potentiels lors de la migration d'un environnement hébergé vers le réseau décentralisé. Il n'est pas possible de greffer un subgraph du Graph Network vers le service hébergé ou le Subgraph Studio.

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

Mises à jour ultérieures : une fois que votre subgraph est actif et stable sur le réseau décentralisé, vous pouvez utiliser le greffage pour les versions futures afin de rendre la transition plus fluide 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.

Building subgraphs is an essential part of The Graph, described more in depth here. To be able to build and deploy the existing subgraph used in this tutorial, the following repo is provided:

• Exemple de subgraph repo

Le manifeste du subgraph subgraph.yaml identifie les sources de données pour le subgraph, les déclencheurs d'intérêt 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 pourrez utiliser :

specVersion: 0.0.4
schema:
  file: ./schema.graphql
dataSources:
  - kind: ethereum
    name: Lock
    network: sepolia
    source:
      address: '0xb3aabe721794b85fe4e72134795c2f93b4eb7e63'
      abi: Lock
      startBlock: 5955690
    mapping:
      kind: ethereum/events
      apiVersion: 0.0.6
      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 abi et le contrat que nous obtiendrons lorsque nous compilerons et déploierons le contrat
• The network should correspond to a indexed network being queried. Since we're running on Sepolia testnet, the network is sepolia
• La section mapping définit les déclencheurs d'intérêt 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'elle est émise.

Le greffage nécessite l'ajout de deux nouveaux éléments au manifeste du subgraph original :

---
features:
  - grafting # feature name
graft:
  base: Qm... # subgraph ID of base subgraph
  block: 5956000 # block number

• features: is a list of all used feature names.
• graft : est une carte du subgraph base et du bloc sur lequel greffer. Le block est le numéro de bloc à partir duquel commencer l'indexation. Le 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 de base et de bloc peuvent être trouvées en déployant deux subgraphs : un pour l'indexation de base et un avec la méthode du greffage

1. Go to Subgraph Studio and create a subgraph on Sepolia testnet called graft-example
2. Suivez les instructions de la section AUTH& DEPLOY sur la page de votre subgraph dans le dossier graft-example du dépôt
3. Une fois terminé, vérifiez que le subgraph s'indexe correctement. Si vous exécutez la commande suivante dans 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 s'indexe correctement, vous pouvez rapidement le mettre à jour grâce à la méthode du graffage.

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. Go to Subgraph Studio and create a subgraph on Sepolia testnet called graft-replacement
2. Create a new manifest. The subgraph.yaml for graph-replacement contains a different contract address and new information about how it should graft. These are the block of the last event emitted you care about by the old contract and the base of the old subgraph. The base subgraph ID is the Deployment ID of your original graph-example subgraph. You can find this in Subgraph Studio.
3. Suivez les instructions de la section AUTH& DEPLOY sur la page de votre subgraph dans le dossier graft-replacement du répertoire
4. Une fois cette opération terminée, vérifiez que le subgraph est correctement indexé. Si vous exécutez la commande suivante dans 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"
      }
    ]
  }
}

You can see that the graft-replacement subgraph is indexing from older graph-example data and newer data from the new contract address. The original contract emitted two Withdrawal events, Event 1 and Event 2. The new contract emitted one Withdrawal after, Event 3. The two previously indexed transactions (Event 1 and 2) and the new transaction (Event 3) were combined together in the graft-replacement subgraph.

Congrats! You have successfully grafted a subgraph onto another subgraph.

Si vous souhaitez acquérir plus d'expérience en matière de greffes, voici quelques exemples de contrats populaires :

• Curve
• ERC-721
• Uniswap,

To become even more of a Graph expert, consider learning about other ways to handle changes in underlying datasources. Alternatives like Data Source Templates can achieve similar results