Melhores Práticas de Subgraph #6 - Use Enxertos para Implantar Hotfixes Mais Rápido

TLDR

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.

Visão geral

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.

Benefícios de Enxertos para Hotfixes

1. Lançamento Rápido

   • 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. Preservação de Dados

   • Reuse Historical Data: Grafting copies the existing data from the base Subgraph, so you don’t lose valuable historical records.
   • Consistência: Mantém a continuidade de dados, que é crucial para aplicativos que dependem de dados históricos consistentes.

3. Eficiência

   • Economia de Tempo e Recursos: Evita o fardo computacional de repetir a indexação de grandes conjuntos de dados.
   • Foco em Conserto: Os programadores podem se concentrar na solução de problemas, em vez de controlar a recuperação de dados.

Melhores Práticas ao Usar Enxertos para Hotfixes

1. *Implantação Inicial sem Enxerto**

   • 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. Implementação do Hotfix com Enxerto

   • Identificar o Problema: Quando ocorrer um erro crítico, determine o número de bloco do último evento indexado com êxito.
   • 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. Depois do Hotfix

   • 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.
     Nota: Não é recomendado depender de enxertos indefinidamente, pois isto pode complicar a manutenção e implantação de futuras atualizações.

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

4. Considerações Importantes

   • Selecione Blocos Corretamente: Escolha o número de bloco do enxerto com cuidado, para evitar perdas de dados.
   • Dica: Use o número de bloco do último evento corretamente processado.
   • 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.

Exemplo: Como Implantar um Subgraph com Enxertos

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. Manifest Falho de Subgraph (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. Novo Manifest Enxertado de Subgraph (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

Explicação:

• Data Source Update: The new Subgraph points to 0xNewContractAddress, which may be a fixed version of the smart contract.
• Bloco Inicial: Configure para um bloco após o último indexado com êxito, para evitar processar o erro novamente.
• Configuração de Enxerto:
  • base: Deployment ID of the failed Subgraph.
  • block: Número de blocos onde o enxerto deve começar.

3. Etapas de Implantação

   • Atualize o Código: Implemente o hotfix nos seus scripts de mapeamento (por exemplo, handleWithdrawal).
   • Ajuste o Manifest: Conforme detalhado acima, atualize o subgraph.yaml com configurações de enxerto.
   • Lance o Subgraph:
     • Autentique com a Graph CLI.
     • Deploy the new Subgraph using graph deploy.

4. Após a Implantação

   • Verify Indexing: Check that the Subgraph is indexing correctly from the graft point.
   • Monitore os Dados: Verifique se há novos dados sendo capturados, e se o hotfix funciona.
   • Planeie Para uma Reedição: Prepare a implantação de uma versão não enxertada, para mais estabilidade a longo prazo.

Tome Cuidado

O enxerto é uma ferramenta poderosa para implantar hotfixes rapidamente, mas deve ser evitado em algumas situações específicas — para manter a integridade dos dados e garantir o melhor desempenho.

• 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.
• Mudanças Significantes na Lógica de Mapeamento: Quando o hotfix envolve modificações substanciais na sua lógica de mapeamento — como alterar o processamento de eventos ​de funções do handler — o enxerto pode não funcionar corretamente. A nova lógica pode não ser compatível com os dados processados ​​sob a lógica antiga, levando a dados incorretos ou indexação com falha.
• 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.

Controle de Riscos

• Integridade de Dados: Números de bloco incorretos podem causar perda ou duplicação de dados.
• Testes: Sempre experimente enxertos num ambiente de testes antes de lançá-los para produção.

Conclusão

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

• Se recuperar rapidamente de erros críticos sem recomeçar a indexação.
• Preservar dados históricos, mantendo a continuidade tanto para aplicativos quanto para utilizadores.
• Garantir a disponibilidade do serviço ao minimizar o tempo de espera em períodos importantes de manutenção.

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.

Outros Recursos

• Documentação de Enxertos: Substitua um Contrato e Mantenha o Seu Histórico com Enxertos
• Como Entender IDs de Implantação: Aprenda a diferença entre ID de Implantação e ID de Subgraph.

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.

Melhores Práticas para um Subgraph 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