Construcción de subgrafos en NEAR

Reading time: 9 min

Esta guía es una introducción a la construcción de subgrafos que indexan contratos inteligentes en la blockchain NEAR.

NEAR es una plataforma de contrato inteligente para crear aplicaciones descentralizadas. Visita la documentación oficial para obtener más información.

The Graph brinda a los desarrolladores herramientas para procesar eventos de blockchain y hacer que los datos resultantes estén fácilmente disponibles a través de una API GraphQL, conocido individualmente como subgrafo. Graph Node ahora puede procesar eventos NEAR, lo que significa que los desarrolladores de NEAR ahora pueden crear subgrafos para indexar sus contratos inteligentes.

Los subgrafos se basan en eventos, lo que significa que escuchan y procesan los eventos on-chain. Actualmente hay dos tipos de handlers compatibles con los subgrafos NEAR:

• Handlers de bloques: se ejecutan en cada nuevo bloque
• Handlers de recibos: se realizan cada vez que se ejecuta un mensaje en una cuenta específica

De la documentación de NEAR:

@graphprotocol/graph-cli es una herramienta de línea de comandos para crear e implementar subgrafos.

@graphprotocol/graph-ts es una biblioteca de tipos específicos de subgrafos.

El desarrollo de subgrafos NEAR requiere graph-cli versión superior a 0.23.0 y graph-ts versión superior a 0.23.0.

Hay tres aspectos de la definición de subgrafo:

subgraph.yaml: el manifiesto del subgrafo, que define las fuentes de datos de interés y cómo deben procesarse. NEAR es un nuevo tipo de fuente de datos.

schema.graphql: un archivo de esquema que define qué datos se almacenan para su subgrafo y cómo consultarlos a través de GraphQL. Los requisitos para los subgrafos NEAR están cubiertos por la documentación existente.

Asignaciones de AssemblyScript: Código de AssemblyScript que traduce los datos del evento a las entidades definidas en su esquema. La compatibilidad con NEAR introduce tipos de datos específicos de NEAR y una nueva funcionalidad de análisis de JSON.

Durante el desarrollo del subgrafo hay dos comandos clave:

$ graph codegen # genera tipos a partir del archivo de esquema identificado en el manifiesto
$ graph build # genera Web Assembly a partir de los archivos de AssemblyScript y prepara todos los archivos de subgrafo en una carpeta /build

El manifiesto del subgrafo (subgraph.yaml) identifica las fuentes de datos para el subgrafo, los activadores de interés y las funciones que deben ejecutarse en respuesta a esos activadores. Consulta a continuación un manifiesto de subgrafo de ejemplo para un subgrafo NEAR:

specVersion: 0.0.2
schema:
  file: ./src/schema.graphql # link to the schema file
dataSources:
  - kind: near
    network: near-mainnet
    source:
      account: app.good-morning.near # This data source will monitor this account
      startBlock: 10662188 # Required for NEAR
    mapping:
      apiVersion: 0.0.5
      language: wasm/assemblyscript
      blockHandlers:
        - handler: handleNewBlock # the function name in the mapping file
      receiptHandlers:
        - handler: handleReceipt # the function name in the mapping file
      file: ./src/mapping.ts # link to the file with the Assemblyscript mappings

• Los subgrafos NEAR introducen un nuevo tipo de fuente de datos (near)
• La red debe corresponder a una red en el Graph Node de alojamiento. En el servicio alojado, la red principal de NEAR es near-mainnet, y la red de prueba de NEAR es near-testnet
• Las fuentes de datos NEAR introducen un campo source.account opcional, que es una identificación legible por humanos correspondiente a una cuenta NEAR. Puede ser una cuenta o una subcuenta.
• Las fuentes de datos NEAR introducen un campo alternativo opcional source.accounts, que contiene sufijos y prefijos opcionales. Se debe especificar al menos el prefijo o el sufijo, coincidirán con cualquier cuenta que comience o termine con la lista de valores, respectivamente. El siguiente ejemplo coincidiría con: [app|good].*[morning.near|morning.testnet]. Si solo se necesita una lista de prefijos o sufijos, se puede omitir el otro campo.

accounts:
  prefixes:
    - app
    - good
  suffixes:
    - morning.near
    - morning.testnet

Las fuentes de datos NEAR admiten dos tipos de handlers:

• blockHandlers: se ejecuta en cada nuevo bloque NEAR. No se requiere source.account.
• receiptHandlers: se ejecuta en cada recibo donde la fuente de datos source.account es el destinatario. Tenga en cuenta que solo se procesan las coincidencias exactas (las subcuentas deben agregarse como fuentes de datos independientes).

La definición de esquema describe la estructura de la base de datos de subgrafos resultante y las relaciones entre las entidades. Esto es independiente de la fuente de datos original. Hay más detalles sobre la definición de esquema de subgrafo aquí.

Los handlers para procesar eventos están escritos en AssemblyScript.

La indexación NEAR introduce tipos de datos específicos de NEAR en la API de AssemblyScript.

class ExecutionOutcome {
      gasBurnt: u64,
      blockHash: Bytes,
      id: Bytes,
      logs: Array<string>,
      receiptIds: Array<Bytes>,
      tokensBurnt: BigInt,
      executorId: string,
  }

class ActionReceipt {
      predecessorId: string,
      receiverId: string,
      id: CryptoHash,
      signerId: string,
      gasPrice: BigInt,
      outputDataReceivers: Array<DataReceiver>,
      inputDataIds: Array<CryptoHash>,
      actions: Array<ActionValue>,
  }

class BlockHeader {
      height: u64,
      prevHeight: u64,// Always zero when version < V3
      epochId: Bytes,
      nextEpochId: Bytes,
      chunksIncluded: u64,
      hash: Bytes,
      prevHash: Bytes,
      timestampNanosec: u64,
      randomValue: Bytes,
      gasPrice: BigInt,
      totalSupply: BigInt,
      latestProtocolVersion: u32,
  }

class ChunkHeader {
      gasUsed: u64,
      gasLimit: u64,
      shardId: u64,
      chunkHash: Bytes,
      prevBlockHash: Bytes,
      balanceBurnt: BigInt,
  }

class Block {
      author: string,
      header: BlockHeader,
      chunks: Array<ChunkHeader>,
  }

class ReceiptWithOutcome {
      outcome: ExecutionOutcome,
      receipt: ActionReceipt,
      block: Block,
  }

Estos tipos se pasan a block & handlers de recibos:

• Los handlers de bloques recibirán un Block
• Los handlers de recibos recibirán un ReceiptWithOutcome

De lo contrario, el resto de la API de AssemblyScript está disponible para los desarrolladores de subgrafos NEAR durante la ejecución del mapeo.

Esto incluye una nueva función de análisis de JSON: los registros en NEAR se emiten con frecuencia como JSON en cadena. Una nueva función json.fromString(...) está disponible como parte de la API JSON para permitir a los desarrolladores para procesar fácilmente estos registros.

Una vez que hayas creado un subgrafo, es hora de implementarlo en Graph Node para indexarlo. Los subgrafos NEAR se pueden implementar en cualquier Graph Node >=v0.26.x (esta versión aún no se ha etiquetado & publicada).

El servicio alojado de The Graph actualmente admite la indexación de NEAR mainnet y testnet en versión beta, con los siguientes nombres de red:

• near-mainnet
• near-testnet

Puede encontrar más información sobre la creación y la implementación de subgrafos en el servicio alojado aquí.

Como introducción rápida, el primer paso es "crear" su subgrafo; esto solo debe hacerse una vez. En el Servicio alojado, esto se puede hacer desde su dashboard: "Agregar subgrafo".

Una vez que se haya creado su subgrafo, puede implementar su subgrafo usando el comando CLI graph deployment:

$ graph create --node <graph-node-url> subgraph/name # creates a subgraph on a local Graph Node (on the Hosted Service, this is done via the UI)
$ graph deploy --node <graph-node-url> --ipfs https://api.thegraph.com/ipfs/ # carga los archivos de compilación en un punto final de IPFS específico y luego implementa el subgrafo en un Graph Node específico en función del hash de IPFS del manifiesto

La configuración del nodo dependerá de dónde se implemente el subgrafo.

graph deploy --node https://api.thegraph.com/deploy/ --ipfs https://api.thegraph.com/ipfs/ --access-token <your-access-token>

graph deploy --node http://localhost:8020/ --ipfs http://localhost:5001

Una vez que se haya implementado su subgrafo, Graph Node lo indexará. Puede comprobar su progreso consultando el propio subgrafo:

{
  _meta {
    block {
      number
    }
  }
}

Ejecutar un Graph Node que indexa NEAR tiene los siguientes requisitos operativos:

• NEAR Indexer Framework con instrumentación Firehose
• Componente(s) NEAR Firehose
• Graph Node con endpoint de Firehose configurado

Pronto proporcionaremos más información sobre cómo ejecutar los componentes anteriores.

El endpoint de GraphQL para los subgrafos NEAR está determinado por la definición del esquema, con la interfaz API existente. Visite la documentación de la API de GraphQL para obtener más información.

A continuación se presentan algunos ejemplos de subgrafos como referencia:

Bloques NEAR

Recibos NEAR

El soporte NEAR está en versión beta, lo que significa que puede haber cambios en la API a medida que continuamos trabajando para mejorar la integración. Envíe un correo electrónico a [email protected] para que podamos ayudarlo a crear subgrafos NEAR y mantenerte actualizado sobre los últimos desarrollos!

No, un subgrafo sólo puede admitir fuentes de datos de una cadena/red.

Actualmente, solo se admiten los activadores de Bloque y Recibo. Estamos investigando activadores para llamadas a funciones a una cuenta específica. También estamos interesados en admitir activadores de eventos, una vez que NEAR tenga soporte nativo para eventos.

Si se especifica una cuenta, solo coincidirá con el nombre exacto de la cuenta. Es posible hacer coincidir subcuentas especificando un campo cuentas, con sufijos y prefijos especificados para hacer coincidir cuentas y subcuentas, por ejemplo lo siguiente coincidiría con todas las subcuentas mintbase1.near:

accounts:
  suffixes:
    - mintbase1.near

Esto no es compatible. Estamos evaluando si esta funcionalidad es necesaria para la indexación.

Esto no es compatible actualmente. Estamos evaluando si esta funcionalidad es necesaria para la indexación.

La funcionalidad pendiente aún no es compatible con los subgrafos NEAR. Mientras tanto, puedes implementar una nueva versión en un subgrafo "nombrado" diferente y luego, cuando se sincroniza con el encabezado de la cadena, puedes volver a implementarlo en su subgrafo principal "nombrado", que usará el mismo ID de implementación subyacente, por lo que el subgrafo principal se sincronizará instantáneamente.

If it is a general question about subgraph development, there is a lot more information in the rest of the Developer documentation. Otherwise please join The Graph Protocol Discord and ask in the #near channel or email [email protected].

• Documentación para desarrolladores de NEAR