Como Substituir um Contrato e Manter a sua História com Enxertos

Reading time: 6 min

Neste guia, aprenda como construir e lançar novos subgraphs com o enxerto de subgraphs existentes.

O processo de enxerto reutiliza os dados de um subgraph existente e o indexa em um bloco seguinte. Isto é útil durante o desenvolvimento para rapidamente superar erros simples nos mapeamentos, ou fazer um subgraph existente funcionar temporariamente após ele ter falhado. Ele também pode ser usado ao adicionar uma característica a um subgraph que demora para ser indexado do zero.

O subgraph enxertado pode usar um schema GraphQL que não é idêntico ao schema do subgraph base, mas é apenas compatível com ele. Ele deve ser um schema válido no seu próprio mérito, mas pode desviar do schema do subgraph base nas seguintes maneiras:

• Ele adiciona ou remove tipos de entidade
• Ele retira atributos de tipos de entidade
• Ele adiciona atributos anuláveis a tipos de entidade
• Ele transforma atributos não anuláveis em atributos anuláveis
• Ele adiciona valores a enums
• Ele adiciona ou remove interfaces
• Ele muda os tipos de entidades para qual implementar uma interface

Para mais informações, confira:

• Enxertos

Neste tutorial, cobriremos um caso de uso básico. Substituiremos um contrato existente com um contrato idêntico (com um novo endereço, mas o mesmo código). Depois, enxertaremos o subgraph existente ao subgraph "base" que rastreará o novo contrato.

O enxerto é uma ferramenta poderosa que lhe permite "enxertar" um subgraph em outro — a fim de, efetivamente, transferir dados históricos do subgraph existente a uma nova versão. Enquanto isto é uma forma eficaz de preservar dados e poupar tempo de indexação, enxertos podem causar complexidades e possíveis problemas ao migrar de um ambiente hospedado até a rede descentralizada. Não é possível enxertar um subgraph da Graph Network de volta ao serviço hospedado ou ao Subgraph Studio.

Migração Inicial: na primeira publicação do seu subgraph à rede descentralizada, faça-o sem enxertos. Garanta que o subgraph está estável e que ele funciona como esperado.

Atualizações Subsequentes: quando o seu subgraph estiver ao vivo e estável na rede descentralizada, use o enxerto em versões futuras para suavizar a transição e preservar dados históricos.

Ao aderir a estas diretrizes, dá para minimizar riscos e garantir um processo de migração mais suave.

Construir subgraphs é essencial para o Graph; o processo é descrito em mais detalhes aqui. Para poder construir e lançar o subgraph existente usado neste tutorial, há o seguinte repo:

• Exemplo de repo de subgraph

O manifest de subgraph subgraph.yaml identifica as fontes de dados para o subgraph, os gatilhos de interesse, e as funções que devem ser executadas em resposta a tais gatilhos. Veja abaixo um exemplo de um manifest de subgraph para uso prático:

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

• A fonte de dados Lock é o abi e o endereço do contrato que receberemos ao compilar e lançar o contrato
• A rede deve corresponder a uma rede indexada a ser consultada em query. Como executamos na testnet Sepolia, a rede é sepolia
• A seção mapping define os gatilhos de interesse e as funções que devem ser executadas em resposta àqueles gatilhos. Neste caso, esperamos o evento Withdrawal e chamaremos a função handleWithdrawal quando o evento for emitido.

Enxertos exigem a adição de dois novos itens ao manifest do subgraph original:

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

• features: uma lista de todos os nomes de feature usados.
• graft: um mapa do subgraph base e o bloco que o enxertará. O block é o número do bloco de onde a indexação começará. O Graph então copiará os dados do subgraph base, até e incluindo o bloco dado, e então continuará a indexar o novo subgraph a partir daquele bloco.

Os valores base e block podem ser encontrados ao lançar dois subgraphs: um para a indexação base e um com o enxerto

1. Vá para o Subgraph Studio e crie um subgraph na testnet Goerli chamado graft-example
2. Siga as direções na seção AUTH & DEPLOY na página do seu subgraph, na pasta graft-example do repo
3. Ao terminar, verifique que o subgraph está a indexar corretamente. Se executar o seguinte comando no The Graph Playground

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

Ele deve retornar algo assim:

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

Após verificar que o subgraph está a indexar corretamente, será possível atualizar rapidamente o subgraph com o enxerto.

O subgraph.yaml do substituto terá um novo endereço de contrato. Isto pode acontecer quando atualizar o seu dapp, relançar um contrato, etc.

1. Vá para o Subgraph Studio e crie um subgraph na testnet Sepolia chamado graft-replacement
2. Crie um novo manifest. O subgraph.yaml para o graph-replacement contém um endereço de contrato diferente e novas informações sobre como ele deve enxertar. Estes são o block do último evento emitido de seu interesse pelo contrato antigo, e o base do subgraph antigo. O ID do subgraph base é o Deployment ID do seu subgraph graph-example. Isto está disponível no UI do Graph Studio.
3. Siga as direções na seção AUTH & DEPLOY na página do seu subgraph, na pasta graft-replacement do repo
4. Ao terminar, verifique que o subgraph está a indexar corretamente. Se executar o seguinte comando no The Graph Playground

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

Ele deve retornar algo como:

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

É possível ver que o subgraph graft-replacement indexa a partir de dados mais antigos do graph-example e de dados mais novos do novo endereço de contrato. O contrato original emitiu dois eventos Withdrawal, Event 1 e Event 2. O novo contrato emitiu um Withdrawal depois, Event 3. As duas transações indexadas anteriormente (Event 1 e 2) e a nova transação (Event 3) foram combinadas no subgraph graft-replacement.

Parabéns! Enxertaste um subgraph em outro subgraph.

Caso queira mais experiência com enxertos, veja alguns exemplos de contratos populares:

• Curve
• ERC-721
• Uniswap,

Para se tornar especialista no The Graph, aprenda sobre outras maneiras de cuidar de mudanças em fontes de dados subjacentes. Alternativas como Modelos de Fontes de Dados podem dar resultados parecidos