Лучшая практика субграфов 6 — используйте графтинг для быстрого развертывания исправлений

Краткое содержание

Grafting is a powerful feature in Subgraph development that allows you to build and deploy new Subgraphs while reusing the indexed data from existing ones.

Обзор

This feature enables quick deployment of hotfixes for critical issues, eliminating the need to re-index the entire Subgraph from scratch. By preserving historical data, grafting minimizes downtime and ensures continuity in data services.

Преимущества графтинга для оперативных исправлений

1. Быстрое развертывание

   • Minimize Downtime: When a Subgraph encounters a critical error and stops indexing, grafting enables you to deploy a fix immediately without waiting for re-indexing.
   • Immediate Recovery: The new Subgraph continues from the last indexed block, ensuring that data services remain uninterrupted.

2. Сохранение данных

   • Reuse Historical Data: Grafting copies the existing data from the base Subgraph, so you don’t lose valuable historical records.
   • Консистентность: поддерживает непрерывность данных, что имеет решающее значение для приложений, полагающихся на согласованные исторические данные.

3. Эффективность

   • Экономия времени и ресурсов: избегает вычислительных затрат на повторное индексирование больших объемов данных.
   • Фокус на исправлениях: позволяет разработчикам сосредоточиться на решении проблем, а не на восстановлении данных.

Лучшие практики при использовании графтинга для оперативных исправлений

1. Первоначальное развертывание без графтинга

   • Start Clean: Always deploy your initial Subgraph without grafting to ensure that it’s stable and functions as expected.
   • Test Thoroughly: Validate the Subgraph’s performance to minimize the need for future hotfixes.

2. Реализация исправления с использованием графтинга

   • Определите проблему: при возникновении критической ошибки определите номер блока последнего успешно проиндексированного события.
   • Create a New Subgraph: Develop a new Subgraph that includes the hotfix.
   • Configure Grafting: Use grafting to copy data up to the identified block number from the failed Subgraph.
   • Deploy Quickly: Publish the grafted Subgraph to restore service as soon as possible.

3. Действия после оперативного исправления

   • Monitor Performance: Ensure the grafted Subgraph is indexing correctly and the hotfix resolves the issue.
   • Republish Without Grafting: Once stable, deploy a new version of the Subgraph without grafting for long-term maintenance.
     Примечание: Не рекомендуется использовать графтинг бесконечно, так как это может усложнить будущие обновления и обслуживание.

   • Update References: Redirect any services or applications to use the new, non-grafted Subgraph.

4. Важные замечания

   • Тщательный выбор блока: тщательно выбирайте номер блока графтинга, чтобы избежать потери данных.
   • Совет: используйте номер блока последнего корректно обработанного события.
   • Use Deployment ID: Ensure you reference the Deployment ID of the base Subgraph, not the Subgraph ID.
   • Note: The Deployment ID is the unique identifier for a specific Subgraph deployment.
   • Feature Declaration: Remember to declare grafting in the Subgraph manifest under features.

Пример: развертывание оперативного исправления с использованием графтинга

Suppose you have a Subgraph tracking a smart contract that has stopped indexing due to a critical error. Here’s how you can use grafting to deploy a hotfix.

1. Манифест неудачного субграфа (subgraph.yaml)

   1specVersion: 1.3.02schema:3  file: ./schema.graphql4dataSources:5  - kind: ethereum/contract6    name: OldSmartContract7    network: sepolia8    source:9      address: '0xOldContractAddress'10      abi: Lock11      startBlock: 500000012    mapping:13      kind: ethereum/events14      apiVersion: 0.0.915      language: wasm/assemblyscript16      entities:17        - Withdrawal18      abis:19        - name: Lock20          file: ./abis/OldLock.json21      eventHandlers:22        - event: Withdrawal(uint256,uint256)23          handler: handleOldWithdrawal24      file: ./src/old-lock.ts

2. Манифест нового субграфа с графтингом (subgraph.yaml)

   1specVersion: 1.3.02schema:3  file: ./schema.graphql4dataSources:5  - kind: ethereum/contract6    name: NewSmartContract7    network: sepolia8    source:9      address: '0xNewContractAddress'10      abi: Lock11      startBlock: 6000001 # Block after the last indexed block12    mapping:13      kind: ethereum/events14      apiVersion: 0.0.915      language: wasm/assemblyscript16      entities:17        - Withdrawal18      abis:19        - name: Lock20          file: ./abis/Lock.json21      eventHandlers:22        - event: Withdrawal(uint256,uint256)23          handler: handleWithdrawal24      file: ./src/lock.ts25features:26  - grafting27graft:28  base: QmBaseDeploymentID # Deployment ID of the failed Subgraph29  block: 6000000 # Last successfully indexed block

Пояснение:

• Data Source Update: The new Subgraph points to 0xNewContractAddress, which may be a fixed version of the smart contract.
• Начальный блок: устанавливается на один блок после последнего успешно индексированного блока, чтобы избежать повторной обработки ошибки.
• Конфигурация графтинга:
  • base: Deployment ID of the failed Subgraph.
  • block: номер блока, с которого должен начаться графтинг.

3. Шаги развертывания

   • Обновите код: внедрите исправление в свои скрипты мэппинга (например, handleWithdrawal).
   • Отредактируйте манифест: как показано выше, обновите файл subgraph.yaml с конфигурациями для графтинга.
   • Разверните субграф:
     • Аутентифицируйтесь с помощью Graph CLI.
     • Deploy the new Subgraph using graph deploy.

4. После развертывания

   • Verify Indexing: Check that the Subgraph is indexing correctly from the graft point.
   • Следите за данными: убедитесь, что новые данные индексируются и что исправление работает эффективно.
   • Запланируйте повторную публикацию: запланируйте развертывание версии без графтинга для обеспечения долгосрочной стабильности.

Предупреждения и предостережения

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

• Incompatible Schema Changes: If your hotfix requires altering the type of existing fields or removing fields from your schema, grafting is not suitable. Grafting expects the new Subgraph’s schema to be compatible with the base Subgraph’s schema. Incompatible changes can lead to data inconsistencies and errors because the existing data won’t align with the new schema.
• Значительные изменения логики мэппинга: когда исправление включает существенные изменения в вашей логике мэппинга, такие как изменение обработки событий или изменение функций обработчиков, графтинг может работать некорректно. Новая логика может быть несовместима с данными, обработанными по старой логике, что приведет к некорректным данным или сбоям в индексировании.
• Deployments to The Graph Network: Grafting is not recommended for Subgraphs intended for The Graph’s decentralized network (mainnet). It can complicate indexing and may not be fully supported by all Indexers, potentially causing unexpected behavior or increased costs. For mainnet deployments, it’s safer to re-index the Subgraph from scratch to ensure full compatibility and reliability.

Управление рисками

• Целостность данных: неверно указанные номера блоков могут привести к потере данных или их дублированию.
• Тестирование: всегда тестируйте графтинг в среде разработки перед развертыванием в рабочей среде.

Заключение

Grafting is an effective strategy for deploying hotfixes in Subgraph development, enabling you to:

• Быстро восстанавливаться после критических ошибок без повторного индексирования.
• Сохранять исторические данные, поддерживая непрерывности работы для приложений и пользователей.
• Обеспечить доступность сервиса, минимизируя время простоя при критических исправлениях.

However, it’s important to use grafting judiciously and follow best practices to mitigate risks. After stabilizing your Subgraph with the hotfix, plan to deploy a non-grafted version to ensure long-term maintainability.

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

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

By incorporating grafting into your Subgraph development workflow, you can enhance your ability to respond to issues swiftly, ensuring that your data services remain robust and reliable.

Лучшие практики для субграфов 1-6

1. Improve Query Speed with Subgraph Pruning

2. Improve Indexing and Query Responsiveness by Using @derivedFrom

3. Improve Indexing and Query Performance by Using Immutable Entities and Bytes as IDs

4. Improve Indexing Speed by Avoiding eth_calls

5. Simplify and Optimize with Timeseries and Aggregations

6. Use Grafting for Quick Hotfix Deployment