Docs
⌘ K

6 minutos

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

Neste guia, aprenda como construir e implantar novos subgraphs com o enxerto de subgraphs existentes.

O que é Enxerto?

O processo de enxerto reutiliza os dados de um subgraph existente e o indexa em um bloco seguinte. Isto é útil durante o desenvolvimento para superar erros simples rapidamente 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.

The grafted Subgraph can use a GraphQL schema that is not identical to the one of the base Subgraph, but merely compatible with it. It has to be a valid Subgraph schema in its own right, but may deviate from the base Subgraph’s schema in the following ways:

  • 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:

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.

Notas Importantes sobre Enxertos ao Migrar Para a Graph Network

Cuidado: Não recomendamos usar enxertos para subgraphs editados na The Graph Network

Qual a Importância Disto?

É um recurso poderoso que permite que os programadores “enxertem” um subgraph em outro, o que, efetivamente, transfere dados históricos do subgraph existente até uma versão nova. Não é possível enxertar um subgraph da Graph Network de volta ao Subgraph Studio.

Boas práticas

Migração Inicial: Ao implantar o seu subgraph pela primeira vez na rede descentralizada, faça-o sem enxertos. Verifique se o subgraph está estável e funciona como esperado.

Atualizações Subsequentes: quando o seu subgraph estiver ativo e estável na rede descentralizada, será possível usar enxertos para 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.

Como Construir um Subgraph Existente

Construir subgraphs é uma parte essencial do The Graph, descrita mais profundamente aqui. Para poder construir e implementar o subgraph existente usado neste tutorial, veja o seguinte repositório:

Observação: O contrato usado no subgraph foi tirado do seguinte Kit para Iniciantes de Hackathon⁠.

Definição de Manifest de Subgraph

O manifest 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 esses gatilhos. Veja abaixo um exemplo de manifest de subgraph para usar:

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
  • A fonte de dados Lock consiste na ABI (Interface binária de aplicação), e o endereço de contrato que receberemos ao compilar e implantar o contrato
  • A rede deve corresponder a uma rede indexada a ser consultada em query. Como estamos a operar na testnet da Sepolia, a rede é sepolia
  • A seção mapping define os gatilhos de interesse e as funções a executar em resposta a esses. Neste caso, estamos à espera do evento Withdrawal; quando emitido, chamaremos a função handleWithdrawal.

Definição de Manifest de Enxertos

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

---features:  - grafting # feature namegraft:  base: Qm... # ID do subgraph base  block: 5956000 # Número do bloco
  • features: é uma lista de todos os nomes de função usados.
  • graft: é um mapa do subgraph base e ​​do bloco para enxertar. block é o número do bloco para começar a indexação. The Graph copiará os dados do subgraph base até, e incluindo, o bloco fornecido, e então continuará a indexar o novo subgraph a partir desse bloco em diante.

Os valores base e ​​block podem ser encontrados com a implantação de dois subgraphs: um para indexação de base e outro com enxerto

Como Lançar o Subgraph Base

  1. Vá para o Subgraph Studio e crie um subgraph na testnet da Sepolia chamado graft-example
  2. Siga as direções na seção AUTH & DEPLOY na sua página de subgraph, na pasta graft-example do repositório
  3. Once finished, verify the Subgraph is indexing properly. If you run the following command in 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.

Como Lançar o Subgraph de 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 da Sepolia chamado graft-replacement
  2. Crie um novo manifest. O subgraph.yaml para 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 importante emitido⁠ pelo contrato antigo, e o base do subgraph antigo. A ID de subgraph base é a Deployment ID do seu subgraph graph-example original. Você pode encontrá-la no Subgraph Studio.
  3. Siga as instruções na seção AUTH & DEPLOY da sua página de subgraph, na pasta graft-replacement do repositório
  4. Once finished, verify the Subgraph is indexing properly. If you run the following command in 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"      }    ]  }}

Repare que o subgraph graft-replacement está a indexar a partir de dados graph-example mais antigos e dados mais novos do novo endereço de contrato. O contrato original emitiu dois eventos Withdrawal: Evento 1⁠ e Evento 2⁠. O novo contrato emitiu um Withdrawal após, Evento 3⁠. As duas transações indexadas anteriormente (Evento 1 e 2) e a nova transação (Evento 3) foram combinadas no subgraph graft-replacement.

Parabéns! Você acaba de enxertar um subgraph sobre outro subgraph.

Outros Recursos

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

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

Nota: Grande parte do material deste artigo foi tirado do artigo anteriormente editado sobre o Arweave