Docs
⌘ K

5 минуты

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

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

Что такое Grafting?

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

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

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

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

В этом руководстве мы рассмотрим базовый случай. Мы заменим существующий контракт на идентичный контракт (с новым адресом, но с тем же кодом). Затем, с помощью графтинга, мы подключим существующий субграф к “базовому” субграфу, который отслеживает новый контракт.

Важное примечание о Grafting при обновлении до сети

Предупреждение: рекомендуется не использовать графтинг для субграфов, опубликованных в сети The Graph

Почему это важно?

Графтинг — это мощная функция, которая позволяет «приращивать» один субграф к другому, эффективно передавая исторические данные из существующего субграфа в новую версию. Невозможно выполнить графтинг субграфа из сети The Graph обратно в Subgraph Studio.

Лучшие практики

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

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

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

Создание существующего субграфа

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

Примечание: контракт, использованный в субграфе, был взят из следующего Hackathon Starterkit⁠.

Определение манифеста субграфа

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

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
  • Источник данных Lock — это ABI и адрес контракта, которые мы получим при компиляции и развертывании контракта
  • Сеть должна соответствовать индексируемой сети, к которой выполняется запрос. Поскольку мы работаем в тестнете Sepolia, сеть будет sepolia.
  • Раздел mapping определяет триггеры, которые представляют интерес, и функции, которые должны быть выполнены в ответ на эти триггеры. В данном случае мы слушаем событие Withdrawal и вызываем функцию handleWithdrawal, когда оно срабатывает.

Определение Манифеста Grafting

Для использования функции графтинга необходимо добавить два новых элемента в исходный манифест субграфа:

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

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

Развертывание базового субграфа

  1. Перейдите в Subgraph Studio и создайте субграф в тестовой сети Sepolia с названием 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"      }    ]  }}

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

Развертывание grafting субграфа

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

  1. Перейдите в Subgraph Studio и создайте субграф в тестовой сети Sepolia с названием graft-replacement
  2. Создайте новый манифест. subgraph.yaml для graph-replacement содержит другой адрес контракта и новую информацию о том, как следует выполнить графтинг. Это block последнего события, сгенерированного⁠ старым контрактом, и base старого субграфа. Идентификатор субграфа base — это Deployment ID вашего оригинального graph-example субграфа. Вы можете найти его в 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"      }    ]  }}

Вы можете увидеть, что субграф graft-replacement индексирует данные из старого субграфа graph-example и новые данные с нового адреса контракта. Оригинальный контракт сгенерировал два события Withdrawal, Событие 1⁠ и Событие 2⁠. Новый контракт сгенерировал одно событие Withdrawal, Событие 3⁠. Два ранее индексированных транзакции (События 1 и 2) и новая транзакция (Событие 3) были объединены в субграфе graft-replacement.

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

Дополнительные ресурсы

Если Вы хотите получить больше опыта в графтинге (переносе), вот несколько примеров популярных контрактов:

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

Примечание: Многие материалы из этой статьи были взяты из ранее опубликованной статьи об Arweave