Despliegue de un subgrafo en el Servicio Alojado

Reading time: 9 min

Esta página explica cómo deployar un subgrafo en el Servicio Alojado. Para deployar un subgrafo, primero debes instalar la Graph CLI. Si aún no has creado un subgrafo, consulta creating a subgraph.

Antes de utilizar el Servicio Alojado, crea una cuenta en nuestro Servicio Alojado. Necesitarás una cuenta de Github para eso; si no tienes una, primero debes crearla. Luego, navega hasta el Servicio Alojado, haz clic en _'Registrarse con Github' _ y completa el flujo de autorización de Github.

Luego de crear la cuenta, navega a tu dashboard. Copia el token de acceso que aparece en el dashboard y ejecuta graph auth --product hosted-service <ACCESS_TOKEN>. Esto almacenará el token de acceso en tu computadora. Sólo tienes que hacerlo una vez, o si alguna vez regeneras el token de acceso.

Antes de deployar el subgrafo, es necesario crearlo en The Graph Explorer. Ve a dashboard y haz clic en el botón 'Add Subgraph' y completa la información siguiente según corresponda:

Image - Selecciona una imagen que se utilizará como imagen de vista previa y miniatura para el subgrafo.

Subgraph Name -Junto con el nombre de la cuenta con la que se crea el subgrafo, esto también definirá el nombre de estilo account-name/subgraph-name utilizado para los deploys y los endpoints de GraphQL. Este campo no puede ser cambiado posteriormente.

Account - La cuenta con la que se crea el subgrafo. Puede ser la cuenta de un individuo o de una organización. Los Subgrafos no pueden ser movidos entre cuentas posteriormente.

Subtitle - Texto que aparecerá en las tarjetas del subgrafo.

Description - Descripción del subgrafo, visible en la página de detalles del subgrafo.

GitHub URL Enlace al repositorio de subgrafos en GitHub.

Hide - Al activar esta opción se oculta el subgrafo en the Graph Explorer.

Después de guardar el nuevo subgrafo, se muestra una pantalla con ayuda sobre cómo instalar The Graph CLI, cómo generar el andamiaje para un nuevo subgrafo, y cómo deployar tu subgrafo. Los dos primeros pasos fueron cubiertos en la sección Definiendo un Subgrafo.

El deploy de tu subgrafo subirá los archivos del subgrafo que has construido con yarn build a IPFS y le dirá a Graph Explorer que empiece a indexar tu subgrafo usando estos archivos.

El subgrafo lo deployas ejecutando yarn deploy

Después de desplegar el subgrafo, el Graph Explorer pasará a mostrar el estado de sincronización de tu subgrafo. Dependiendo de la cantidad de datos y del número de eventos que haya que extraer de los bloques históricos, empezando por el bloque génesis, la sincronización puede tardar desde unos minutos hasta varias horas.

El estado del subgrafo cambia a Synced una vez que el Graph Node ha extraído todos los datos de los bloques históricos. El Graph Node continuará inspeccionando los bloques para tu subgrafo a medida que estos bloques sean minados.

Cuando hagas cambios en la definición de tu subgrafo, por ejemplo, para arreglar un problema en los mapeos de entidades, ejecuta el comando yarn deploy de arriba de nuevo para deployar la versión actualizada de tu subgrafo. Cualquier actualización de un subgrafo requiere que Graph Node reindexe todo tu subgrafo, de nuevo empezando por el bloque génesis.

Si tu subgrafo previamente deployado está todavía en estado Syncing, será inmediatamente reemplazado por la nueva versión deployada. Si el subgrafo previamente deployado ya está completamente sincronizado, Graph Node marcará la nueva versión deployada como Pending Version, la sincronizará en segundo plano, y sólo reemplazará la versión actualmente deployada por la nueva una vez que la sincronización de la nueva versión haya terminado. Esto asegura que tienes un subgrafo con el que trabajar mientras la nueva versión se sincroniza.

En algunos casos, querrás desplegar el mismo subgrafo en múltiples redes sin duplicar todo su código. El principal reto que conlleva esto es que las direcciones de los contratos en estas redes son diferentes.

Tanto graph build (desde v0.29.0) como graph deploy (desde v0.32.0) aceptan dos nuevas opciones:

Options:

      ...
      --network <name>          Network configuration to use from the networks config file
      --network-file <path>     Networks config file path (default: "./networks.json")

Puedes usar la opción --network para especificar una configuración de red desde un archivo estándar json (el valor predeterminado es networks.json) para actualizar fácilmente tu subgrafo durante el desarrollo.

Nota: El comando init ahora generará automáticamente un networks.json basado en la información proporcionada. Luego podrás actualizar redes existentes o agregar redes adicionales.

Si no tienes un archivo networks.json, deberás crear uno manualmente con la siguiente estructura:

{
    "network1": { // the network name
        "dataSource1": { // the dataSource name
            "address": "0xabc...", // the contract address (optional)
            "startBlock": 123456 // the startBlock (optional)
        },
        "dataSource2": {
            "address": "0x123...",
            "startBlock": 123444
        }
    },
    "network2": {
        "dataSource1": {
            "address": "0x987...",
            "startBlock": 123
        },
        "dataSource2": {
            "address": "0xxyz..",
            "startBlock": 456
        }
    },
    ...
}

Nota: No tienes que especificar ninguna de las templates (si tienes alguna) en el archivo de configuración, solo el dataSources. Si hay alguna templates declarada en el archivo subgraph.yaml, su red se actualizará automáticamente a la especificada con la opción --network.

Ahora, supongamos que deseas implementar tu subgrafo en las redes mainnet y goerli, y este es tu subgraph.yaml:

# ...
dataSources:
  - kind: ethereum/contract
    name: Gravity
    network: mainnet
    source:
      address: '0x123...'
      abi: Gravity
    mapping:
      kind: ethereum/events

Este es el aspecto que debe tener el archivo de configuración de tu red:

{
  "mainnet": {
    "Gravity": {
      "address": "0x123..."
    }
  },
  "goerli": {
    "Gravity": {
      "address": "0xabc..."
    }
  }
}

Ahora podemos ejecutar uno de los siguientes comandos:

# Using default networks.json file
yarn build --network goerli

# Using custom named file
yarn build --network goerli --network-file path/to/config

El comando build actualizará tu subgraph.yaml con la configuración de goerli y luego volverá a compilar el subgrafo. Tu archivo subgraph.yaml ahora debería verse así:

# ...
dataSources:
  - kind: ethereum/contract
    name: Gravity
    network: goerli
    source:
      address: '0xabc...'
      abi: Gravity
    mapping:
      kind: ethereum/events

Ahora está listo para yarn deploy.

Nota: como se mencionó anteriormente, desde graph-cli 0.32.0 puedes ejecutar directamente yarn deploy con la opción--network:

# Using default networks.json file
yarn deploy --network goerli

# Using custom named file
yarn deploy --network goerli --network-file path/to/config

Una solución para las versiones antiguas de graph-cli que permite parametrizar aspectos como las direcciones de los contratos es generar partes del mismo mediante un sistema de plantillas como Mustache o Handlebars.

Para ilustrar este enfoque, supongamos que un subgrafo debe deployarse en mainnet y Goerli utilizando diferentes direcciones de contrato. Podrías entonces definir dos archivos de configuración proporcionando las direcciones para cada red:

{
  "network": "mainnet",
  "address": "0x123..."
}

y

{
  "network": "goerli",
  "address": "0xabc..."
}

Junto con eso, sustituirías el nombre de la red y las direcciones en el manifiesto con marcadores de posición variables {{network}} y {{address}} y cambiarías el nombre del manifiesto a, por ejemplo subgraph.template.yaml:

# ...
dataSources:
  - kind: ethereum/contract
    name: Gravity
    network: mainnet
    network: {{network}}
    source:
      address: '0x2E645469f354BB4F5c8a05B3b30A929361cf77eC'
      address: '{{address}}'
      abi: Gravity
    mapping:
      kind: ethereum/events

Para generar un manifiesto para cualquiera de las redes, puedes agregar dos comandos adicionales a package.json junto con una dependencia de mustache:

{
  ...
  "scripts": {
    ...
    "prepare:mainnet": "mustache config/mainnet.json subgraph.template.yaml > subgraph.yaml",
    "prepare:goerli": "mustache config/goerli.json subgraph.template.yaml > subgraph.yaml"
  },
  "devDependencies": {
    ...
    "mustache": "^3.1.0"
  }
}

Para deployar este subgrafo para mainnet o Goerli ahora solo tendrías que ejecutar uno de los dos siguientes comandos:

# Mainnet:
yarn prepare:mainnet && yarn deploy

# Goerli:
yarn prepare:goerli && yarn deploy

Un ejemplo práctico de esto se puede encontrar aqui.

Nota: Este enfoque también se puede aplicar a situaciones más complejas, donde es necesario sustituir más que direcciones de contrato y nombres de red o donde también se generan asignaciones o ABIs a partir de plantillas.

Si un subgrafo se sincroniza con éxito, es una buena señal de que seguirá funcionando bien para siempre. Sin embargo, los nuevos activadores en la red pueden hacer que tu subgrafo alcance una condición de error no probada o puede comenzar a retrasarse debido a problemas de rendimiento o problemas con los operadores de nodos.

Graph Node expone un punto final de graphql que puedes consultar para verificar el estado de tu subgrafo. En el Servicio Alojado, está disponible en https://api.thegraph.com/index-node/graphql. En un nodo local, está disponible en el puerto 8030/graphql de forma predeterminada. El esquema completo para este punto final se puede encontrar aquí. Aquí hay una consulta de ejemplo que verifica el estado de la versión actual de un subgrafo:

{
  indexingStatusForCurrentVersion(subgraphName: "org/subgraph") {
    synced
    health
    fatalError {
      message
      block {
        number
        hash
      }
      handler
    }
    chains {
      chainHeadBlock {
        number
      }
      latestBlock {
        number
      }
    }
  }
}

Esto te dará el chainHeadBlock que puedes comparar con el latestBlock en tu subgrafo para verificar si se está quedando atrás. synced informa si el subgrafo alguna vez se ha puesto al día con la cadena. health actualmente puede tomar los valores de healthy si no se produjeron errores, o failed si hubo un error que detuvo el progreso del subgrafo. En este caso, puedes consultar el campo fatalError para obtener detalles sobre este error.

El Servicio Alojado es un indexador de Graph Node gratuito. Los desarrolladores pueden deployar subgrafos que indexen una variedad de redes, que se indexarán y estarán disponibles para consultar a través de graphQL.

Para mejorar el rendimiento del servicio para los subgrafos activos, el Servicio Alojado archivará los subgrafos que estén inactivos.

Un subgrafo se define como "inactivo" si fue deployado en el Servicio alojado hace más de 45 días y si no recibió consultas en los últimos 45 días.

Los desarrolladores serán notificados por correo electrónico si uno de sus subgrafos ha sido marcado como inactivo 7 días antes de ser eliminado. Si desean "activar" su subgrafo, pueden hacerlo haciendo una consulta en el campo de juego graphQL de su subgrafo. Los developers siempre pueden volver a deployar un subgrafo archivado si lo necesitan de nuevo.

Cuando se deploya una nueva versión de un subgrafo, la versión anterior se archiva (se elimina de la base de datos de graph-node). Esto solo sucede si la versión anterior no se publica en la red descentralizada de The Graph.

Cuando no se consulta una versión de subgrafo durante más de 45 días, esa versión se archiva.

Cada subgrafo afectado por esta política tiene una opción para recuperar la versión en cuestión.