Construction de subgraphs sur NEAR

Reading time: 9 min

Ce guide est une introduction à la construction de subgraphs indexant des contrats intelligents sur la blockchain NEAR.

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

Le Graph donne aux développeurs des outils pour traiter les événements de la blockchain et rendre les données résultantes facilement disponibles via une API GraphQL, connue individuellement comme un subgraph. Graph Node est désormais capable de traiter les événements NEAR, ce qui signifie que les développeurs NEAR peuvent désormais construire des subgraphs pour indexer leurs smart contracts.

Les subgraphs sont basés sur des événements, ce qui signifie qu'ils écoutent et traitent les événements de la chaîne. Il existe actuellement deux types de gestionnaires pour les subgraphs NEAR :

• Gestionnaires de blocs : ceux-ci sont exécutés à chaque nouveau bloc
• Gestionnaires de reçus : exécutés à chaque fois qu'un message est exécuté sur un compte spécifié

From the NEAR documentation:

@graphprotocol/graph-cli est un outil en ligne de commande pour construire et déployer des subgraphs.

@graphprotocol/graph-ts est une bibliothèque de types spécifiques aux subgraphs.

Le développement du subgraph NEAR nécessite graph-cli à partir de la version 0.23.0 et graph-ts à partir de la version 0.23.0.

La définition d'un subgraph comporte trois aspects :

subgraph.yaml : le manifeste du subgraph, définissant les sources de données d'intérêt et la manière dont elles doivent être traitées. NEAR est un nouveau type de source de données.

schema.graphql : un fichier de schéma qui définit quelles données sont stockées pour votre subgraph, et comment les interroger via GraphQL. Les exigences pour les subgraphs NEAR sont couvertes par la documentation existante.

Mappages AssemblyScript : Code AssemblyScript qui traduit les données d'événement en entités définies dans votre schéma. La prise en charge de NEAR introduit des types de données spécifiques à NEAR et une nouvelle fonctionnalité d'analyse JSON.

Lors du développement du subgraph, il y a deux commandes clés :

$ graph codegen # génère des types à partir du fichier de schéma identifié dans le manifeste
$ graph build # génère le Web Assembly à partir des fichiers AssemblyScript, et prépare tous les fichiers de subgraphs dans un dossier /build

Le manifeste de subgraph (subgraph.yaml) identifie les sources de données pour le subgraph, les déclencheurs d'intérêt et les fonctions qui doivent être exécutées en réponse à ces déclencheurs. Voici un exemple de manifeste de subgraph pour un subgraph NEAR:

specVersion: 0.0.2
schema:
  file: ./src/schema.graphql # lien vers le fichier de schéma
dataSources:
  - kind: near
    network: near-mainnet
    source:
      account: app.good-morning.near # Cette source de données surveillera ce compte
      startBlock: 10662188 # Requis pour NEAR
    mapping:
      apiVersion: 0.0.5
      language: wasm/assemblyscript
      blockHandlers:
        - handler: handleNewBlock # le nom de la fonction dans le fichier de mapping
      receiptHandlers:
        - handler: handleReceipt # le nom de la fonction dans le fichier de mappage
      file: ./src/mapping.ts # lien vers le fichier contenant les mappings Assemblyscript

• Les subgraphs NEAR introduisent un nouveau type de source de données (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.
• Les sources de données NEAR introduisent un champ source.accounts facultatif alternatif, qui contient des suffixes et des préfixes facultatifs. Au moins un préfixe ou un suffixe doit être spécifié, ils correspondront respectivement à n'importe quel compte commençant ou se terminant par la liste de valeurs. L'exemple ci-dessous correspondrait : [app|good].*[morning.near|morning.testnet]. Si seule une liste de préfixes ou de suffixes est nécessaire, l'autre champ peut être omis.

comptes:
  préfixes:
    - application
    - bien
  suffixes:
    - matin.près
    - matin.testnet

Les fichiers de données NEAR prennent en charge deux types de gestionnaires :

• blockHandlers : s'exécute sur chaque nouveau bloc NEAR. Aucun source.account n'est requis.
• 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 définition du schema décrit la structure de la base de données de subgraphs résultante et les relations entre les entités. Ceci est indépendant de la source de données originale. Vous trouverez plus de détails sur la définition du schema des subgraph ici.

Les gestionnaires de traitement des événements sont écrits dans l'AssemblyScript.

L'indexation NEAR introduit des types de données spécifiques à NEAR dans l'API AssemblyScript.

classe ExecutionOutcome {
       gaz brûlé : u64,
       blockHash : octets,
       identifiant : octets,
       logs : Array<string>,
       Id de réception : tableau <octets>,
       jetonsBurnt : BigInt,
       exécuteurId : chaîne,
   }

classe ActionReceipt {
       Id prédécesseur : chaîne,
       Id récepteur : chaîne,
       identifiant : CryptoHash,
       signataire : chaîne,
       prix du gaz : BigInt,
       OutputDataReceivers : Array<DataReceiver>,
       inputDataIds : tableau<CryptoHash>,
       actions : Tableau<ActionValue>,
   }

classe BlockHeader {
       taille: u64,
       prevHeight : u64,// Toujours zéro lorsque la version < V3
       epochId : octets,
       nextEpochId : octets,
       morceauxInclus: u64,
       hachage : octets,
       prevHash : octets,
       horodatageNanosec : u64,
       randomValue : octets,
       prix du gaz : BigInt,
       approvisionnement total : BigInt,
       dernière version du protocole : u32,
   }

classe ChunkHeader {
       gazUtilisé: u64,
       limite de gaz : u64,
       Id de fragment : u64,
       chunkHash : octets,
       prevBlockHash : octets,
       balanceBurnt : BigInt,
   }

bloc de classe {
       auteur : chaîne,
       en-tête : BlockHeader,
       morceaux : Array<ChunkHeader>,
   }

classe ReçuAvecRésultat {
       résultat : ExecutionOutcome,
       reçu : ActionReceipt,
       bloquer: bloquer,
   }

Ces types sont passés au bloc & gestionnaires de reçus :

• Les gestionnaires de blocs reçoivent un Block
• Les gestionnaires de reçus reçoivent un ReceiptWithOutcome

Sinon, le reste de l'API AssemblyScript est disponible pour les développeurs de subgraphs NEAR pendant l'exécution du mapping.

Cela inclut une nouvelle fonction d'analyse JSON - les journaux sur NEAR sont fréquemment émis sous forme de JSON stringifiés. Une nouvelle fonction json.fromString(...) est disponible dans le cadre de l'API JSON pour permettre aux développeurs pour traiter facilement ces journaux.

Une fois que vous avez construit un subgraph, il est temps de le déployer sur Graph Node pour l'indexation. Les subgraphs NEAR peuvent être déployés sur n'importe quel nœud The Graph >=v0.26.x (cette version n'a pas encore été marquée & et publiée).

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

Une fois votre subgraph créé, vous pouvez le déployer en utilisant la commande CLI graph deploy :

$ 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 configuration du nœud dépend de l'endroit où le subgraph est déployé.

graph auth --studio
graph deploy --studio <subgraph-name>

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

Une fois que votre subgraph a été déployé, il sera indexé par le nœud The Graph. Vous pouvez vérifier sa progression en interrogeant le subgraph lui-même :

{
  _meta {
    block {
      number
    }
  }
}

L'exécution d'un nœud de Graph qui indexe NEAR répond aux exigences opérationnelles suivantes :

• Cadre d'indexation NEAR avec instrumentation Firehose
• Composant(s) du NEAR Firehose
• Nœud Gaph avec point d'extrémité Firehose configuré

Nous fournirons bientôt plus d'informations sur l'utilisation des composants ci-dessus.

Le point de terminaison GraphQL pour les subgraphs NEAR est déterminé par la définition du schéma, avec l'interface API existante. Veuillez consulter la documentation de l'API GraphQL pour plus d'informations.

Here are some example subgraphs for reference:

NEAR Blocs

Des reçus de NEAR

Le support de NEAR est en version bêta, ce qui signifie qu'il peut y avoir des changements dans l'API alors que nous continuons à travailler sur l'amélioration de l'intégration. Veuillez envoyer un e-mail à [email protected] pour que nous puissions vous aider à construire des subgraphs NEAR et vous tenir au courant des derniers développements !

Non, un subgraph ne peut supporter que les sources de données d'une seule chaîne/réseau.

Actuellement, seuls les déclencheurs de blocage et de réception sont pris en charge. Nous étudions les déclencheurs pour les appels de fonction à un compte spécifique. Nous souhaitons également prendre en charge les déclencheurs d'événements, une fois que NEAR disposera d'un support natif pour les événements.

Si un compte est spécifié, il correspondra uniquement au nom exact du compte. Il est possible de faire correspondre des sous-comptes en spécifiant un champ comptes, avec des suffixes et des préfixes spécifiés pour faire correspondre les comptes et sous-comptes, par exemple ce qui suit correspondrait à tous les sous-comptes mintbase1.near :

comptes:
  suffixes:
    - mintbase1.near

Cette fonction n'est pas prise en charge. Nous sommes en train d'évaluer si cette fonctionnalité est nécessaire pour l'indexation.

Ceci n’est actuellement pas pris en charge. Nous évaluons si cette fonctionnalité est requise pour l'indexation.

La fonctionnalité "pending" n'est pas encore prise en charge pour les subgraphs NEAR. Dans l'intervalle, vous pouvez déployer une nouvelle version dans un autre subgraph "named", puis, lorsque celui-ci est synchronisé avec la tête de chaîne, vous pouvez redéployer dans votre subgraph principal "named", qui utilisera le même ID de déploiement sous-jacent, de sorte que le subgraph principal sera instantanément synchronisé.

S'il s'agit d'une question générale sur le développement de subgraphs, il y a beaucoup plus d'informations dans le reste de la Documentation du développeur. Sinon, veuillez rejoindre The Graph Protocol Discord et poser votre question sur le canal #near ou par e-mail à [email protected].

• Documentation du développeur NEAR