Reemplazar un contrato y mantener su historia con el grafting

Reading time: 6 min

En esta guía, aprenderás a construir y deployar nuevos subgrafos mediante grafting (injerto) de subgrafos existentes.

El grafting reutiliza los datos de un subgrafo existente y comienza a indexarlo en un bloque posterior. Esto es útil durante el desarrollo para superar rápidamente errores simples en los mapeos o para hacer funcionar temporalmente un subgrafo existente después de que haya fallado. También se puede utilizar cuando se añade un feature a un subgrafo que tarda en indexarse desde cero.

El subgrafo grafteado puede utilizar un esquema GraphQL que no es idéntico al del subgrafo base, sino simplemente compatible con él. Tiene que ser un esquema de subgrafo válido por sí mismo, pero puede diferir del esquema del subgrafo base de las siguientes maneras:

• Agrega o elimina tipos de entidades
• Elimina los atributos de los tipos de entidad
• Agrega atributos anulables a los tipos de entidad
• Convierte los atributos no anulables en atributos anulables
• Añade valores a los enums
• Agrega o elimina interfaces
• Cambia para qué tipos de entidades se implementa una interfaz

Para más información, puedes consultar:

• Grafting

En este tutorial vamos a cubrir un caso de uso básico. Reemplazaremos un contrato existente con un contrato idéntico (con una nueva dirección, pero el mismo código). Luego, haremos grafting del subgrafo existente en el subgrafo "base" que rastrea el nuevo contrato.

Grafting is a powerful feature that allows you to "graft" one subgraph onto another, effectively transferring historical data from the existing subgraph to a new version. While this is an effective way to preserve data and save time on indexing, grafting may introduce complexities and potential issues when migrating from a hosted environment to the decentralized network. It is not possible to graft a subgraph from The Graph Network back to the hosted service or Subgraph Studio.

Initial Migration: when you first deploy your subgraph to the decentralized network, do so without grafting. Ensure that the subgraph is stable and functioning as expected.

Subsequent Updates: once your subgraph is live and stable on the decentralized network, you may use grafting for future versions to make the transition smoother and to preserve historical data.

By adhering to these guidelines, you minimize risks and ensure a smoother migration process.

La construcción de subgrafos es una parte esencial de The Graph, descrita más a fondo aquí. Para poder construir y deployar el subgrafo existente utilizado en este tutorial, se proporciona el siguiente repo:

• Repo de ejemplo de subgrafo

El manifiesto del subgrafo subgraph.yaml identifica las fuentes de datos para el subgrafo, los disparadores de interés y las funciones que deben ejecutarse en respuesta a esos disparadores. A continuación se muestra un ejemplo de manifiesto de subgrafos que se utilizará:

specVersion: 0.0.4
schema:
  file: ./schema.graphql
dataSources:
  - kind: ethereum
    name: Lock
    network: goerli
    source:
      address: '0x4Ed995e775D3629b0566D2279f058729Ae6EA493'
      abi: Lock
      startBlock: 7674603
    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

• La fuente de datos de Lock es el ABI y la dirección del contrato que obtendremos cuando compilemos y realicemos el deploy del contrato
• La red debe corresponder a una red indexada que se esté consultando. Como estamos ejecutando en Goerli testnet, la red es goerli
• La sección de mapeo define los disparadores de interés y las funciones que deben ejecutarse en respuesta a esos disparadores. En este caso, estamos escuchando el evento Withdrawal y llamando a la función handleWithdrawal cuando se emite.

El grafting requiere añadir dos nuevos items al manifiesto original del subgrafo:

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

• features: es una lista de todos los nombres de features utilizados.
• graft: es un mapa del subgrafo base y del bloque al que se va a realizar el grafting. El bloque es el número de bloque desde el que se empieza a indexar. The Graph copiará los datos del subgrafo base hasta el bloque dado, inclusive, y luego continuará indexando el nuevo subgrafo a partir de ese bloque.

Los valores de la base y del bloque se pueden encontrar deployando dos subgrafos: uno para la indexación de la base y otro con grafting

1. Ve a The Graph Studio UI y crea un subgrafo en Goerli testnet llamado graft-example
2. Sigue las instrucciones de la sección AUTH & DEPLOY en tu página de subgrafo en la carpeta graft-example del repo
3. Una vez que hayas terminado, verifica que el subgrafo se está indexando correctamente. Si ejecutas el siguiente comando en The Graph Playground

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

Devuelve algo como esto:

{
  "data": {
    "withdrawals": [
      {
        "id": "0x13098b538a61837e9f29b32fb40527bbbe63c9120c250242b02b69bb42c287e5-5",
        "amount": "0",
        "when": "1664367528"
      },
      {
        "id": "0x800c92fcc0edbd26f74e19ad058c62008a47c7789f2064023b987028343dd498-3",
        "amount": "0",
        "when": "1664367648"
      }
    ]
  }
}

Una vez que hayas verificado que el subgrafo se está indexando correctamente, puedes actualizar rápidamente el subgrafo con grafting.

El subgraph.yaml de sustitución del graft tendrá una nueva dirección de contrato. Esto podría ocurrir cuando actualices tu dApp, vuelvas a deployar un contrato, etc.

1. Ve a The Graph Studio UI y crea un subgrafo en Goerli testnet llamado graft-replacement
2. Crea un nuevo manifiesto. El subgraph.yaml para el graph-replacement contiene una dirección de contrato diferente y nueva información sobre cómo debe realizarse el grafting. Estos son el bloque del último evento emitido que te interesa por el antiguo contrato y la base del antiguo subgrafo. El ID del subgrafo base es el ID de deploy de tu graph-example subgrafo original. Puedes encontrarlo en la UI de The Graph Studio.
3. Sigue las instrucciones de la sección AUTH & DEPLOY en la página de tu subgrafo en la carpeta graft-replacement del repo
4. Una vez que hayas terminado, verifica que el subgrafo se está indexando correctamente. Si ejecutas el siguiente comando en The Graph Playground

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

Debería devolver lo siguiente:

{
  "data": {
    "withdrawals": [
      {
        "id": "0x13098b538a61837e9f29b32fb40527bbbe63c9120c250242b02b69bb42c287e5-5",
        "amount": "0",
        "when": "1664367528"
      },
      {
        "id": "0x800c92fcc0edbd26f74e19ad058c62008a47c7789f2064023b987028343dd498-3",
        "amount": "0",
        "when": "1664367648"
      },
      {
        "id": "0xb4010e4c76f86762beb997a13cf020231778eaf7c64fa3b7794971a5e6b343d3-22",
        "amount": "0",
        "when": "1664371512"
      }
    ]
  }
}

Se puede ver que el subgrafo graft-replacement está indexando a partir de los datos más antiguos del graph-example y los datos más actuales de la dirección del contrato. El contrato original emitió dos eventos de Withdrawal, Evento 1 y Evento 2. El nuevo contrato emitió un evento de Withdrawal después, el Evento 3. Las dos transacciones indexadas anteriormente (Evento 1 y 2) y la nueva transacción (Evento 3) se combinaron juntas en el subgrafo graft-replacement.

Felicidades. Has conseguido graftear un subgrafo en otro subgrafo exitosamente.

Si quieres tener más experiencia con el grafting, aquí tienes algunos ejemplos de contratos populares:

• Curve
• ERC-721
• Uniswap,

Para convertirte en un experto en Graph, considera la posibilidad de aprender otras formas de manejar los cambios en las fuentes de datos subyacentes. Alternativas como las plantillas de fuentes de datos pueden lograr resultados similares