Construcción de subgrafos en NEAR

Reading time: 8 min

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

NEAR is a smart contract platform for building decentralized applications. Visit the official documentation for more information.

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

From the NEAR documentation:

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

AssemblyScript Mappings: AssemblyScript code that translates from the event data to the entities defined in your schema. NEAR support introduces NEAR-specific data types and new JSON parsing functionality.

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)
• The network should correspond to a network on the hosting Graph Node. On Subgraph Studio, NEAR's mainnet is near-mainnet, and NEAR's testnet is near-testnet
• NEAR data sources introduce an optional source.account field, which is a human-readable ID corresponding to a NEAR account. This can be an account or a sub-account.
• 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: run on every receipt where the data source's source.account is the recipient. Note that only exact matches are processed (subaccounts must be added as independent data sources).

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.

NEAR indexing introduces NEAR-specific data types to the AssemblyScript API.

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

Otherwise, the rest of the AssemblyScript API is available to NEAR subgraph developers during mapping execution.

This includes a new JSON parsing function - logs on NEAR are frequently emitted as stringified JSONs. A new json.fromString(...) function is available as part of the JSON API to allow developers to easily process these logs.

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

Subgraph Studio and the upgrade Indexer on The Graph Network currently supports indexing NEAR mainnet and testnet in beta, with the following network names:

• near-mainnet
• near-testnet

More information on creating and deploying subgraphs on Subgraph Studio can be found here.

As a quick primer - the first step is to "create" your subgraph - this only needs to be done once. On Subgraph Studio, this can be done from your Dashboard: "Create a subgraph".

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 Subgraph Studio, this is done via the UI)
$ graph deploy --node <graph-node-url> --ipfs https://api.thegraph.com/ipfs/ <subgraph-name> # uploads the build files to a specified IPFS endpoint, and then deploys the subgraph to a specified Graph Node based on the manifest IPFS hash

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

graph auth
graph deploy <subgraph-name>

graph deploy --node http://localhost:8020/ --ipfs http://localhost:5001 <subgraph-name>

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