Docs

6 minutes

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

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

Vad är ympning?

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:

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.

Viktig anmärkning om ympning vid uppgradering till nätverket

Caution: It is recommended to not use grafting for subgraphs published to The Graph Network

Varför är detta viktigt?

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.

Bästa praxis

Initial Migration: when you first deploy your subgraph to the decentralized network, do so without grafting. Ensure that the subgraph is stable and functioning as expected.

Subsequent Updates: once your subgraph is live and stable on the decentralized network, you may use grafting for future versions to make the transition smoother and to preserve historical data.

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

Bygga en befintlig subgraf

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:

Note: The contract used in the subgraph was taken from the following Hackathon Starterkit⁠.

Definition av subgraf manifestet

The subgraph manifest subgraph.yaml identifies the data sources for the subgraph, the triggers of interest, and the functions that should be run in response to those triggers. See below for an example subgraph manifest that you will use:

specVersion: 0.0.4schema:  file: ./schema.graphqldataSources:  - 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
  • The Lock data source is the abi and contract address we will get when we compile and deploy the contract
  • The network should correspond to an indexed network being queried. Since we’re running on Sepolia testnet, the network is sepolia
  • The mapping section defines the triggers of interest and the functions that should be run in response to those triggers. In this case, we are listening for the Withdrawal event and calling the handleWithdrawal function when it is emitted.

Ympnings manifest Definition

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

---features:  - grafting # feature namegraft:  base: Qm... # subgraph ID of base subgraph  block: 5956000 # block number
  • features: is a list of all used feature names.
  • graft: is a map of the base subgraph and the block to graft on to. The block is the block number to start indexing from. The Graph will copy the data of the base subgraph up to and including the given block and then continue indexing the new subgraph from that block on.

The base and block values can be found by deploying two subgraphs: one for the base indexing and one with grafting

Distribuera Bas Subgraf

  1. Go to Subgraph Studio and create a subgraph on Sepolia testnet called graft-example
  2. Follow the directions in the AUTH & DEPLOY section on your subgraph page in the graft-example folder from the 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.

Utplacering av ympning subgraf

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. Follow the directions in the AUTH & DEPLOY section on your subgraph page in the graft-replacement folder from the repo
  4. 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  }}

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.

Ytterligare resurser

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

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

Note: A lot of material from this article was taken from the previously published Arweave article

⁠Edit on GitHub⁠