9 minutes
Construction de subgraphs sur NEAR
Ce guide est une introduction à la construction de subgraphs indexant des contrats intelligents sur la blockchain NEAR.
Que signifie NEAR ?
NEAR is a smart contract platform for building decentralized applications. Visit the official documentation for more information.
Que sont les subgraphs NEAR ?
Le graphique fournit aux développeurs des outils pour traiter les événements de la blockchain et rendre les données résultantes facilement accessibles via une API GraphQL, connue individuellement sous le nom de subgraph. Le Graph Node est désormais capable de traiter les événements NEAR, ce qui signifie que les développeurs NEAR peuvent désormais créer des subgraphs pour indexer leurs contrats intelligents.
Les subgraphs sont basés sur les événements, ce qui signifie qu’ils écoutent et traitent les événements de la blockchain. 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é
Un reçu est le seul objet actionnable dans le système. Lorsque nous parlons de “traitement d’une transaction” sur la plateforme NEAR, cela signifie en fin de compte “appliquer des reçus” à un moment ou à un autre.
Construction d’un subgraph NEAR
@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 de subgraphs NEAR nécessite graph-cli au-dessus de la version 0.23.0, et graph-ts au-dessus de la version 0.23.0.
La construction d’un subgraph NEAR est très similaire à la construction d’un subgraph qui indexe Ethereum.
La définition d’un subgraph comporte trois aspects :
subgraph.yaml: le manifeste du subgraph, définissant les sources de données intéressantes 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 les données stockées dans votre subgraph et la manière de les interroger via GraphQL. Les exigences pour les subgraphs NEAR sont couvertes par la documentation existante.
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.
During Subgraph development there are two key commands:
1$ graph codegen # generates types from the schema file identified in the manifest2$ graph build # generates Web Assembly from the AssemblyScript files, and prepares all the Subgraph files in a /build folderDéfinition du manifeste du subgraph
Le manifeste du subgraph (subgraph.yaml) identifie les sources de données pour le subgraph, les déclencheurs intéressants et les fonctions qui doivent être exécutées en réponse à ces déclencheurs. Voir ci-dessous un exemple de manifeste de subgraph pour un subgraph NEAR :
1specVersion: 1.3.02schema:3 file: ./src/schema.graphql # lien vers le fichier de schéma4dataSources:5 - kind: near6 network: near-mainnet7 source:8 account: app.good-morning.near # Cette source de données surveillera ce compte9 startBlock: 10662188 # Required for NEAR10 mapping:11 apiVersion: 0.0.912 language: wasm/assemblyscript13 blockHandlers:14 - handler: handleNewBlock # the function name in the mapping file15 receiptHandlers:16 - handler: handleReceipt # the function name in the mapping file17 file: ./src/mapping.ts # link to the file with the Assemblyscript mappings- Les subgraphs NEAR introduisent un nouveau
typede source de données (near) - The
networkshould correspond to a network on the hosting Graph Node. On Subgraph Studio, NEAR’s mainnet isnear-mainnet, and NEAR’s testnet isnear-testnet - NEAR data sources introduce an optional
source.accountfield, which is a human-readable ID corresponding to a NEAR account. This can be an account or a sub-account. - NEAR data sources introduce an alternative optional
source.accountsfield, which contains optional suffixes and prefixes. At least prefix or suffix must be specified, they will match the any account starting or ending with the list of values respectively. The example below would match:[app|good].*[morning.near|morning.testnet]. If only a list of prefixes or suffixes is necessary the other field can be omitted.
1comptes:2 préfixes:3 - application4 - bien5 suffixes:6 - matin.près7 - matin.testnetLes fichiers de données NEAR prennent en charge deux types de gestionnaires :
blockHandlers: run on every new NEAR block. Nosource.accountis required.receiptHandlers: run on every receipt where the data source’ssource.accountis the recipient. Note that only exact matches are processed (subaccounts must be added as independent data sources).
Définition de schéma
La définition du schéma décrit la structure de la base de données Subgraph résultante et les relations entre les entités. Elle est agnostique de la source de données d’origine. Vous trouverez plus de détails sur la définition du schéma du subgraph ici.
Cartographies AssemblyScript
Les gestionnaires d’événements sont écrits en AssemblyScript.
NEAR indexing introduces NEAR-specific data types to the AssemblyScript API.
1class ExecutionOutcome {2 gasBurnt: u64,3 blockHash: Bytes,4 id: Bytes,5 logs: Array<string>,6 receiptIds: Array<Bytes>,7 tokensBurnt: BigInt,8 executorId: string,9 }1011class ActionReceipt {12 predecessorId: string,13 receiverId: string,14 id: CryptoHash,15 signerId: string,16 gasPrice: BigInt,17 outputDataReceivers: Array<DataReceiver>,18 inputDataIds: Array<CryptoHash>,19 actions: Array<ActionValue>,20 }2122class BlockHeader {23 height: u64,24 prevHeight: u64,// Always zero when version < V325 epochId: Bytes,26 nextEpochId: Bytes,27 chunksIncluded: u64,28 hash: Bytes,29 prevHash: Bytes,30 timestampNanosec: u64,31 randomValue: Bytes,32 gasPrice: BigInt,33 totalSupply: BigInt,34 latestProtocolVersion: u32,35 }3637class ChunkHeader {38 gasUsed: u64,39 gasLimit: u64,40 shardId: u64,41 chunkHash: Bytes,42 prevBlockHash: Bytes,43 balanceBurnt: BigInt,44 }4546class Block {47 author: string,48 header: BlockHeader,49 chunks: Array<ChunkHeader>,50 }5152class ReceiptWithOutcome {53 outcome: ExecutionOutcome,54 receipt: ActionReceipt,55 block: Block,56 }These types are passed to block & receipt handlers:
- Block handlers will receive a
Block - Receipt handlers will receive a
ReceiptWithOutcome
Sinon, le reste de l’AssemblyScript API est à la disposition des développeurs de subgraphs NEAR pendant l’exécution du mappage.
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.
Déploiement d’un subgraph NEAR
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 Graph Node >=v0.26.x (cette version n’a pas encore été étiquetée et publiée).
Subgraph Studio et l’Indexeur de mise à niveau sur The Graph Network prennent en charge actuellement l’indexation du mainnet et du testnet NEAR en bêta, avec les noms de réseau suivants :
near-mainnetnear-testnet
De plus amples informations sur la création et le déploiement de subgraphs sur Subgraph Studio sont disponibles ici.
Pour commencer, la première étape consiste à “créer” votre subgraph, ce qui ne doit être fait qu’une seule fois. Sur Subgraph Studio, vous pouvez le faire à partir de votre tableau de bord : “Créer un Subgraph”.
Une fois votre subgraph créé, vous pouvez le déployer en utilisant la commande CLI graph deploy :
1$ graph create --node <graph-node-url> <subgraph-name> # crée un subgrpah sur un Graph Node local (sur Subgraph Studio, cela se fait via l'interface utilisateur)2$ graph deploy --node <graph-node-url> --ipfs https://ipfs.thegraph.com <subgraph-name> # upload les fichiers de build vers un endpoint IPFS spécifié, puis déploie le subgraph vers un Graph Node spécifié sur la base du hash IPFS du manifesteLa configuration des nœuds dépend de l’endroit où le subgraph est déployé.
Subgraph Studio
1graph auth2graph deploy <subgraph-name>Nœud Graph local ( en fonction de la configuration par défaut)
1graph deploy --node http://localhost:8020/ --ipfs http://localhost:5001 <subgraph-name>Une fois votre subgraph déployé, il sera indexé par Graph Node. Vous pouvez vérifier sa progression en interrogeant le subgraph lui-même :
1{2 _meta {3 block {4 number5 }6 }7}Indexation de NEAR avec un nœud The graph local
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.
Interrogation d’un subgraph NEAR
L’endpoint GraphQL pour les subgraphs NEAR est déterminé par la définition du schéma, avec l’interface API existante. Veuillez consulter la documentation API GraphQL pour plus d’informations.
Exemples de subgraphs
Voici quelques exemples de Subgraphs pour référence :
FAQ
Comment fonctionne la bêta ?
La prise en charge 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 email à [email protected] afin que nous puissions vous aider à construire des subgraphs NEAR et vous tenir au courant des derniers développements !
Un subgraph peut-il indexer simultanément les blockchains NEAR et EVM ?
No, a Subgraph can only support data sources from one chain/network.
Les subgraphs peuvent-ils réagir à des déclencheurs plus spécifiques ?
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.
Les gestionnaires de reçus se déclencheront-ils pour les comptes et leurs sous-comptes ?
If an account is specified, that will only match the exact account name. It is possible to match sub-accounts by specifying an accounts field, with suffixes and prefixes specified to match accounts and sub-accounts, for example the following would match all mintbase1.near sub-accounts:
1comptes:2 suffixes:3 - mintbase1.nearLes subgraphs NEAR peuvent-ils faire des appels de vue aux comptes NEAR pendant les mappages ?
Cette fonction n’est pas prise en charge. Nous sommes en train d’évaluer si cette fonctionnalité est nécessaire pour l’indexation.
Puis-je utiliser des modèles de sources de données dans mon subgraph NEAR ?
Ceci n’est actuellement pas pris en charge. Nous évaluons si cette fonctionnalité est requise pour l’indexation.
Les subgraphs Ethereum prennent en charge les versions “en attente”(pending) et “actuelles”(current), comment puis-je déployer une version “en attente” d’un subgraph NEAR ?
La fonctionnalité d’attente n’est pas encore prise en charge pour les subgraphs NEAR. Dans l’intervalle, vous pouvez déployer une nouvelle version dans un subgraph “nommé” différemment, puis, lorsque celui-ci est synchronisé avec la tête de chaîne, vous pouvez le redéployer dans votre subgraph principal “nommé”, qui utilisera le même ID de déploiement sous-jacent, de sorte que le subgraph principal sera instantanément synchronisé.
Ma question n’a pas reçu de réponse, où puis-je obtenir plus d’aide pour construire des subgraphs NEAR ?
S’il s’agit d’une question générale sur le développement de Subgraph, il y a beaucoup plus d’informations dans le reste de la Documentation du développeur. Sinon, rejoignez Le Discord de The Graph Protocol et posez votre question dans le canal #near ou envoyez un email à [email protected].