Desplegar subgraphs en The Graph: tutorial

Introducción

La plataforma The Graph ha revolucionado la forma de obtener datos de blockchains de manera eficiente y escalable. Un subgraph es la unidad básica de esta arquitectura: define cómo indexar, transformar y exponer datos on-chain a través de una API GraphQL.

En este tutorial detallado aprenderás paso a paso a crear, probar y desplegar tus propios subgraphs, primero en el servicio alojado de The Graph y posteriormente en la red descentralizada.

¿Qué es The Graph

• Indexación on-chain: Construye índices de eventos y transacciones.
• API GraphQL: Proporciona un endpoint optimizado para consultas flexibles.
• Descentralización: Protocolos de gobernanza y staking para garantizar robustez.

Requisitos previos

• Node.js gt= 14.x
• NPM o Yarn
• IPFS (opcional para red descentralizada)
• Una cuenta en The Graph Hosted Service
• Familiaridad básica con Solidity, JavaScript/TypeScript y GraphQL

1. Configurar el entorno

Instala Graph CLI globalmente:

npm install -g @graphprotocol/graph-cli

Luego, inicializa un nuevo proyecto:

graph init --from-contract ltCONTRACT_ADDRESSgt ltGITHUB_USER/SUBGRAPH_NAMEgt

2. Crear la definición de tu subgraph

La estructura típica de carpetas incluye:

• subgraph.yaml: Configuración principal.
• schema.graphql: Definición de entidades.
• /src/mappings.ts: Lógica para convertir eventos en entidades.

3. Definir el schema.graphql

Ejemplo de entidad Transfer para un ERC-20:

type Transfer @entity {
  id: ID!
  from: Bytes!
  to: Bytes!
  value: BigInt!
  transactionHash: Bytes!
}
    

Este esquema permite almacenar transferencias y consultarlas desde GraphQL.

4. Escribir mappings en TypeScript

En src/mappings.ts asigna eventos a entidades:

import { BigInt } from @graphprotocol/graph-ts
import { Transfer as TransferEvent } from ../generated/YourToken/YourToken
import { Transfer } from ../generated/schema

export function handleTransfer(event: TransferEvent): void {
  let entity = new Transfer(event.transaction.hash.toHex()   -   event.logIndex.toString())
  entity.from = event.params.from
  entity.to = event.params.to
  entity.value = event.params.value
  entity.transactionHash = event.transaction.hash
  entity.save()
}
    

Tip: Siempre genera IDs únicas combinando hash de transacción y logIndex.

5. Probar localmente

Ejecuta un nodo local de Graph CLI:

graph create --node http://127.0.0.1:8020/ ltGITHUB_USER/SUBGRAPH_NAMEgt --protocol ethereum
graph deploy --node http://127.0.0.1:8020/ ltGITHUB_USER/SUBGRAPH_NAMEgt

Luego sube bloques de prueba y consulta con:

curl -g http://127.0.0.1:9000/subgraphs/name/ltGITHUB_USER/SUBGRAPH_NAMEgtquery={transfers{from,to,value}}

6. Desplegar en el servicio alojado de The Graph

1. Autenticar CLI:

   graph auth --product hosted-service ltAPI_KEYgt

2. Crear subgraph en Hosted Service:

   graph create --product hosted-service ltGITHUB_USER/SUBGRAPH_NAMEgt

3. Desplegar:

   graph deploy --product hosted-service ltGITHUB_USER/SUBGRAPH_NAMEgt

En minutos tu endpoint GraphQL estará disponible en la interfaz de Hosted Service.

7. Publicar en la red descentralizada

Para garantizar que tu subgraph sea inmutable y resistente a la censura:

• Instala y configura IPFS y un nodo de Graph Protocol.
• Registra tu subgraph con la Verification Network.
• Firma y despliega usando tu wallet (MetaMask / WalletConnect).

Consulta la guía oficial de red descentralizada: thegraph.com/docs.

Monitorización y mantenimiento

• Alertas: Configura notificaciones en The Graph Dashboard.
• Versionado: Cada despliegue define una nueva versión disponible.
• Costes: Revisa métricas de indexación y uso de recursos.

Buenas prácticas

• Limita el tamaño de tus entidades.
• Evita cálculos costosos en mappings.
• Documenta tu esquema y estrategias de actualización.
• Reutiliza fragments de GraphQL para consultas complejas.

Recursos adicionales

© 2024 Your Name. Todos los derechos reservados.