Despliegue de un subgrafo en el Servicio Alojado

Reading time: 9 min

This page explains how to deploy a subgraph to the hosted service. To deploy a subgraph you need to first install the Graph CLI. If you have not created a subgraph already, see creating a subgraph.

Before using the hosted service, create an account in our hosted service. You will need a Github account for that; if you don't have one, you need to create that first. Then, navigate to the hosted service, click on the 'Sign up with Github' button, and complete Github's authorization flow.

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.

Before deploying the subgraph, you need to create it in Graph Explorer. Go to the dashboard and click on the Add Subgraph button and fill in the information below as appropriate:

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 - Switching this on hides the subgraph in Graph Explorer.

After saving the new subgraph, you are shown a screen with help on how to install the Graph CLI, how to generate the scaffolding for a new subgraph, and how to deploy your subgraph. The first two steps were covered in the Creating a Subgraph section.

Deploying your subgraph will upload the subgraph files that you've built with yarn build to IPFS and tell Graph Explorer to start indexing your subgraph using these files.

El subgrafo lo deployas ejecutando yarn deploy

After deploying the subgraph, Graph Explorer will switch to showing the synchronization status of your subgraph. Depending on the amount of data and the number of events that need to be extracted from historical blocks, starting with the genesis block, syncing can take from a few minutes to several hours.

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.

Now, let's assume you want to be able to deploy your subgraph to the mainnet and sepolia networks, and this is your 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..."
    }
  },
  "sepolia": {
    "Gravity": {
      "address": "0xabc..."
    }
  }
}

Ahora podemos ejecutar uno de los siguientes comandos:

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

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

The build command will update your subgraph.yaml with the sepolia configuration and then re-compile the subgraph. Your subgraph.yaml file now should look like this:

# ...
dataSources:
  - kind: ethereum/contract
    name: Gravity
    network: sepolia
    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 sepolia

# Using custom named file
yarn deploy --network sepolia --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.

To illustrate this approach, let's assume a subgraph should be deployed to mainnet and Sepolia using different contract addresses. You could then define two config files providing the addresses for each network:

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

y

{
  "network": "sepolia",
  "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:sepolia": "mustache config/sepolia.json subgraph.template.yaml > subgraph.yaml"
  },
  "devDependencies": {
    ...
    "mustache": "^3.1.0"
  }
}

To deploy this subgraph for mainnet or Sepolia you would now simply run one of the two following commands:

# Mainnet:
yarn prepare:mainnet && yarn deploy

# Sepolia:
yarn prepare:sepolia && 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 exposes a graphql endpoint which you can query to check the status of your subgraph. On the hosted service, it is available at https://api.thegraph.com/index-node/graphql. On a local node, it is available on port 8030/graphql by default. The full schema for this endpoint can be found here. Here is an example query that checks the status of the current version of a subgraph:

{
  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.

The hosted service is a free Graph Node Indexer. Developers can deploy subgraphs indexing a range of networks, which will be indexed, and made available to query via graphQL.

To improve the performance of the service for active subgraphs, the hosted service will archive subgraphs that are inactive.

A subgraph is defined as "inactive" if it was deployed to the hosted service more than 45 days ago, and if it has received 0 queries in the last 45 days.

Developers will be notified by email if one of their subgraphs has been marked as inactive 7 days before it is removed. If they wish to "activate" their subgraph, they can do so by making a query in their subgraph's hosted service graphQL playground. Developers can always redeploy an archived subgraph if it is required again.

A subgraph version in Studio is archived if and only if it meets the following criteria:

• The version is not published to the network (or pending publish)
• The version was created 45 or more days ago
• The subgraph hasn't been queried in 30 days

In addition, when a new version is deployed, if the subgraph has not been published, then the N-2 version of the subgraph is archived.

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