Integrar GraphQL y subgraphs con The Graph

Integración de GraphQL y Subgraphs con The Graph

En el universo de las aplicaciones descentralizadas (dApps), la necesidad de consultar datos de manera eficiente y en tiempo real es esencial. The Graph ofrece una solución robusta mediante su arquitectura de indexing y querying con GraphQL. Este artículo detalla paso a paso cómo diseñar, desplegar e integrar subgraphs, analizando tanto la perspectiva del backend (subgraph) como la del frontend (cliente GraphQL).

1. ¿Qué es The Graph

The Graph es un protocolo descentralizado que permite construir APIs públicas llamadas subgraphs, las cuales extraen, indexan y exponen datos de blockchains utilizando GraphQL. En lugar de consultar nodos de Ethereum (u otras cadenas) directamente, los desarrolladores acceden a datos procesados y organizados.

Referencia oficial: The Graph Docs

2. Fundamentos de GraphQL en Blockchain

• Esquema declarativo: Define tipos y campos accesibles.
• Consultas a medida: El cliente especifica exactamente qué datos necesita.
• Una sola petición: Reduce la cantidad de llamadas frente a REST tradicional.

Para profundizar: Guía oficial de GraphQL

3. Arquitectura de The Graph

4. Creación de un Subgraph

4.1. Instalación de herramientas

Requisitos previos:

• Node.js v14
• npm install -g @graphprotocol/graph-cli
• Una red de blockchain (p.ej. Ethereum, Polygon)

4.2. Inicializar proyecto

graph init --from-contract 0x... --network mainnet MiSubgraph
  

4.3. Estructura clave de archivos

5. Descripción de Archivos Esenciales

5.1. subgraph.yaml

specVersion: 0.0.2
description: Un subgraph básico
repository: https://github.com/usuario/misubgraph
schema:
  file: ./schema.graphql
dataSources:
  - kind: ethereum/contract
    name: Example
    network: mainnet
    source:
      address: 0xYourContractAddress
      abi: ExampleABI
    mapping:
      kind: ethereum/events
      apiVersion: 0.0.5
      language: wasm/assemblyscript
      entities:
        - ExampleEntity
      abis:
        - name: ExampleABI
          file: ./abis/ExampleABI.json
      eventHandlers:
        - event: Transfer(indexed address,indexed address,uint256)
          handler: handleTransfer
      file: ./src/mapping.ts
  

5.2. schema.graphql

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

5.3. mapping.ts

import { BigInt } from @graphprotocol/graph-ts
import { Transfer } from ../generated/Example/ExampleABI
import { ExampleEntity } from ../generated/schema

export function handleTransfer(event: Transfer): void {
  let id = event.transaction.hash.toHex()
  let entity = new ExampleEntity(id)
  entity.from = event.params.from
  entity.to = event.params.to
  entity.value = event.params.value
  entity.save()
}
  

6. Despliegue y Publicación

1. Autenticarse: graph auth --studio
2. Construir: graph codegen graph build
3. Desplegar: graph deploy --studio usuario/misubgraph --product hosted-service

Ver estado en: Panel de The Graph Studio

7. Integración desde el Cliente

Una vez desplegado, The Graph expone una URL GraphQL. Veamos un ejemplo con Apollo Client.

7.1. Instalación de Apollo Client

npm install @apollo/client graphql
  

7.2. Configuración en React

import { ApolloClient, InMemoryCache, gql } from @apollo/client

const client = new ApolloClient({
  uri: https://api.thegraph.com/subgraphs/name/usuario/misubgraph,
  cache: new InMemoryCache()
})

client
  .query({
    query: gql
      query {
        exampleEntities(first: 5, orderBy: value, orderDirection: desc) {
          id
          from
          to
          value
        }
      }
    
  })
  .then(result => console.log(result))
  

8. Mejores Prácticas

• Limitar campos: Define solo lo que necesites en el esquema.
• Versionado de subgraphs: Usa ramas y etiquetas semánticas.
• Curación de datos: Valida en mapping.ts antes de guardar.
• Escalabilidad: Segmenta subgraphs por conjunto de eventos o módulos.

9. Recursos Adicionales

• Guía rápida de The Graph
• Repositorios oficiales en GitHub
• Documentación de Apollo GraphQL

Conclusión

La combinación de GraphQL y The Graph proporciona una poderosa capa de consulta para dApps, optimizando tiempo de desarrollo y rendimiento al indexar datos de blockchain. Siguiendo esta guía, podrá diseñar, desplegar e integrar subgraphs de manera eficiente, ofreciendo a sus usuarios una experiencia ágil y fiable.