Замените контракт и сохраните его историю с помощью Grafting

Reading time: 5 min

Из этого руководства Вы узнаете, как создавать и развертывать новые субграфы путем графтинга (переноса) существующих субграфов.

При графтинге (переносе) повторно используются данные из существующего субрафа и начинается их индексация в более позднем блоке. Это может быть полезно в период разработки, чтобы быстро устранить простые ошибки в мэппинге или временно восстановить работу существующего субграфа после его сбоя. Кроме того, его можно использовать при добавлении в субграф функции, индексация которой с нуля занимает много времени.

Перенесённый субграф может использовать схему GraphQL, которая не идентична схеме базового субграфа, а просто совместима с ней. Это должна быть автономно действующая схема субграфа, но она может отличаться от схемы базового субграфа следующим образом:

• Она добавляет или удаляет типы объектов
• Она удаляет атрибуты из типов объектов
• Она добавляет обнуляемые атрибуты к типам объектов
• Она превращает необнуляемые атрибуты в обнуляемые
• Она добавляет значения в перечисления
• Она добавляет или удаляет интерфейсы
• Она изменяется в зависимости от того, под какой тип объектов реализован интерфейс

Для получения дополнительной информации Вы можете перейти:

• Grafting

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.

Первоначальная миграция: когда вы впервые развертываете свой субграф в децентрализованной сети, делайте это без Grafting. Убедитесь, что субграф стабилен и функционирует должным образом.

Последующие обновления: как только Ваш субграф станет активным и стабильным в децентрализованной сети, Вы сможете использовать Grafting для будущих версий, чтобы сделать переход более плавным и сохранить исторические данные.

Соблюдая эти рекомендации, Вы минимизируете риски и обеспечите более плавный процесс миграции.

Создание субграфов — важная часть The Graph, более подробно описанная здесь. Чтобы иметь возможность создать и развернуть существующий субграф, используемый в этом руководстве, предоставляется следующий репозиторий:

• Репозиторий субграфа в качестве примера

Манифест субграфа subgraph.yaml определяет источники данных для субграфа, релевантные триггеры и функции, которые должны выполняться в ответ на эти триггеры. Ниже приведен пример манифеста субграфа, который Вы будете использовать:

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 — это abi и адрес контракта, которые мы получим при компиляции и развертывании контракта
• The network should correspond to an indexed network being queried. Since we're running on Sepolia testnet, the network is sepolia
• Раздел mapping определяет интересующие нас триггеры и функции, которые должны запускаться в ответ на эти триггеры. В этом случае мы уделяем внимание событию Withdrawal и вызываем функцию handleWithdrawal при его возникновении.

Grafting требует добавления двух новых элементов в исходный манифест субграфа:

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

• features — это список всех используемых названий функций.
• graft: — это карта субграфа base и блока, к которому применяется графтинг (перенос). block — это номер блока, с которого начинается индексация. The Graph скопирует данные базового субграфа до указанного блока включительно, а затем продолжит индексацию нового субграфа, начиная с этого блока.

Значения base и block можно найти, развернув два субграфа: один для базовой индексации, а другой с графтингом (переносом)

1. Go to Subgraph Studio and create a subgraph on Sepolia testnet called graft-example
2. Следуйте инструкциям в AUTH & DEPLOY на странице субграфа в graft-example из репо
3. После завершения убедитесь, что субграф правильно индексируется. Если Вы запустите следующую команду в The Graph Playground

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

Отклик будет подобным этому:

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

Убедившись, что субграф индексируется правильно, Вы можете быстро обновить его с помощью графтинга.

Замененный subgraph.yaml будет иметь новый адрес контракта. Это может произойти, когда Вы обновите свое децентрализованное приложение, повторно развернете контракт и т. д.

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. Следуйте инструкциям в AUTH & DEPLOY на странице субграфа в graft-replacement из репозитория
4. После завершения убедитесь, что субграф правильно индексируется. Если Вы запустите следующую команду в The Graph Playground

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

Это должно привести к следующему результату:

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

Поздравляем! Вы успешно перенесли один субграф в другой.

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

• Curve
• ERC-721
• Uniswap,

Чтобы стать еще большим экспертом по Graph, рассмотрите возможность узнать о других способах обработки изменений в базовых источниках данных. Такие альтернативы, как Data Source Templates, могут дать аналогичные результаты