Byt ut ett kontrakt och behåll dess historia med ympning

Reading time: 5 min

I den här guiden kommer du att lära dig hur du bygger och distribuerar nya subgrafer genom att ympa befintliga subgrafer.

Ympning återanvänder data från en befintlig subgraf och börjar indexera den vid ett senare block. Detta är användbart under utveckling för att snabbt komma förbi enkla fel i mappningarna eller för att tillfälligt få en befintlig subgraf att fungera igen efter att den har misslyckats. Det kan också användas när du lägger till en funktion till en subgraf som tar lång tid att indexera från början.

Den ympade subgrafen kan använda ett GraphQL-schema som inte är identiskt med det i bas subgrafen, utan bara är kompatibelt med det. Det måste vara ett giltigt subgraf schema i sig, men kan avvika från bas undergrafens schema på följande sätt:

• Den lägger till eller tar bort entitetstyper
• Det tar bort attribut från entitetstyper
• Det tar bort attribut från entitetstyper
• Det förvandlar icke-nullbara attribut till nullbara attribut
• Det lägger till värden till enums
• Den lägger till eller tar bort gränssnitt
• Det ändrar för vilka entitetstyper ett gränssnitt implementeras

För mer information kan du kontrollera:

• Ympning

In this tutorial, we will be covering a basic use case. We will replace an existing contract with an identical contract (with a new address, but the same code). Then, graft the existing subgraph onto the "base" subgraph that tracks the new contract.

Grafting is a powerful feature that allows you to "graft" one subgraph onto another, effectively transferring historical data from the existing subgraph to a new version. It is not possible to graft a subgraph from The Graph Network back to Subgraph Studio.

Inledande Migration: När du först distribuerar din subgraph till det decentraliserade nätverket, gör det utan grafting. Se till att subgraphen är stabil och fungerar som förväntat.

Senare Uppdateringar: När din subgraph är aktiv och stabil på det decentraliserade nätverket kan du använda grafting för framtida versioner för att göra övergången smidigare och bevara historisk data.

Genom att följa dessa riktlinjer minimerar du riskerna och säkerställer en smidigare migreringsprocess.

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:

• Subgraf exempel repo

Subgrafmanifestet subgraph.yaml identifierar datakällorna för subgrafen, utlösare av intresse och funktionerna som ska köras som svar på dessa utlösare. Se nedan för ett exempel på subgraf manifest som du kommer att använda:

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

• Lock-datakällan är abi- och kontraktsadressen vi får när vi kompilerar och distribuerar kontraktet
• The network should correspond to an indexed network being queried. Since we're running on Sepolia testnet, the network is sepolia
• Avsnittet mappning definierar utlösare av intresse och de funktioner som ska köras som svar på dessa utlösare. I det här fallet lyssnar vi efter händelsen Withdrawal och anropar funktionen handleWithdrawal när den sänds.

Ympning kräver att två nya objekt läggs till i det ursprungliga subgraf manifestet:

---
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: är en karta över subgrafen base och blocket att ympa på. block är blocknumret att börja indexera från. Grafen kopierar data från bas subgrafen till och med det givna blocket och fortsätter sedan att indexera den nya subgrafen från och med det blocket.

Värdena base och block kan hittas genom att distribuera två subgrafer: en för basindexering och en med ympning

1. Go to Subgraph Studio and create a subgraph on Sepolia testnet called graft-example
2. Följ anvisningarna i AUTH & Sektionen DEPLOY på din subgraf sida i mappen graft-example från repo
3. När du är klar kontrollerar du att subgrafen indexerar korrekt. Om du kör följande kommando i The Graph Playground

{
  withdrawals(first: 5) {
    id
    amount
    when
  }
}

Den returnerar ungefär så här:

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

När du har verifierat att subgrafen indexerar korrekt kan du snabbt uppdatera subgrafen med ympning.

Transplantatersättningen subgraph.yaml kommer att ha en ny kontraktsadress. Detta kan hända när du uppdaterar din dapp, omdisponerar ett kontrakt, 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. Följ anvisningarna i AUTH & DEPLOY-avsnittet på din subgraf sida i mappen graft-replacement från repo
4. När du är klar kontrollerar du att subgrafen indexerar korrekt. Om du kör följande kommando i The Graph Lekplats

{
  withdrawals(first: 5) {
    id
    amount
    when
  }
}

Det bör returnera följande:

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

If you want more experience with grafting, here are a few examples for popular contracts:

• 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