Fonctionnalités avancées des subgraphs

Aperçu

Ajouter et mettre en œuvre des fonctionnalités avancées de subgraph pour améliorer la construction de votre subgraph.

A partir de la specVersion 0.0.4, les fonctionnalités de Subgraph doivent être explicitement déclarées dans la section features au premier niveau du fichier manifest, en utilisant leur nom camelCase, comme listé dans le tableau ci-dessous :

Par exemple, si un subgraph utilise les fonctionnalités Recherche plein texte et Erreurs non fatales, le champ features dans le manifeste devrait être :

1specVersion: 1.3.02description: Gravatar for Ethereum3features:4  - fullTextSearch5  - nonFatalErrors6dataSources: ...

Séries chronologiques et agrégations

Prérequis :

• Le subgraph specVersion doit être ≥1.1.0.

Les séries chronologiques et les agrégations permettent à votre subgraph de suivre des statistiques telles que le prix moyen quotidien, le nombre total de transferts par heure, etc.

Cette fonctionnalité introduit deux nouveaux types d’entités de subgraph. Les entités de séries chronologiques enregistrent des points de données avec des horodatages. Les entités d’agrégation effectuent des calculs prédéfinis sur les points de données des séries chronologiques sur une base horaire ou quotidienne, puis stockent les résultats pour faciliter l’accès via GraphQL.

Exemple de schéma

1type Data @entity(timeseries: true) {2  id: Int8!3  timestamp: Timestamp!4  price: BigDecimal!5}67type Stats @aggregation(intervals: ["hour", "day"], source: "Data") {8  id: Int8!9  timestamp: Timestamp!10  sum: BigDecimal! @aggregate(fn: "sum", arg: "price")11}

Comment définir des séries chronologiques et des agrégations ?

Les entités de séries chronologiques sont définies avec @entity(timeseries : true) dans le schéma GraphQL. Chaque entité timeseries doit :

• ont un ID unique de type int8
• ont un horodatage de type Horodatage
• inclure les données qui seront utilisées pour le calcul par les entités d’agrégation.

Ces entités de séries chronologiques peuvent être enregistrées dans des gestionnaires de déclencheurs ordinaires et servent de “données brutes” pour les entités d’agrégation.

Les entités d’agrégation sont définies avec @aggregation dans le schéma GraphQL. Chaque entité d’agrégation définit la source à partir de laquelle elle recueillera les données (qui doit être une entité de série chronologique), définit les intervalles (par exemple, heure, jour) et spécifie la fonction d’agrégation qu’elle utilisera (par exemple, sum, count, min, max, first, last).

Les entités d’agrégation sont automatiquement calculées sur la base de la source spécifiée à la fin de l’intervalle requis.

Intervalles d’Agrégation disponibles

• hour: définit la période de séries chronologiques toutes les heures, à l’heure pile.
• day: définit la période de séries chronologiques chaque jour, commençant et se terminant à 00:00.

Fonctions d’Agrégation disponibles

• sum: Total de toutes les valeurs.
• count: Nombre de valeurs.
• min: Valeur minimum.
• max: Valeur maximum.
• first: Première valeur de la période.
• last : Dernière valeur de la période.

Exemple de requête d’Agrégations

1{2  stats(interval: "hour", where: { timestamp_gt: 1704085200 }) {3    id4    timestamp5    sum6  }7}

En savoir plus⁠ sur les séries chronologiques et Agrégations.

Erreurs non fatales

Les erreurs d’indexation sur des subgraphs déjà synchronisés entraîneront, par défaut, l’échec du subgraph et l’arrêt de la synchronisation. Les subgraphs peuvent également être configurés pour continuer la synchronisation en présence d’erreurs, en ignorant les modifications apportées par le gestionnaire qui a provoqué l’erreur. Les auteurs de subgraphs ont ainsi le temps de corriger leurs subgraphs tandis que les requêtes continuent d’être servies par rapport au dernier bloc, bien que les résultats puissent être incohérents en raison du bug qui a provoqué l’erreur. Notez que certaines erreurs sont toujours fatales. Pour être non fatale, l’erreur doit être connue comme étant déterministe.

Pour activer les erreurs non fatales, il faut définir l’indicateur de fonctionnalité suivant dans le manifeste du subgraph :

1specVersion: 1.3.02description: Gravatar for Ethereum3features:4    - nonFatalErrors5    ...

La requête doit également accepter d’interroger des données avec des incohérences potentielles grâce à l’argument subgraphError. Il est également recommandé d’interroger _meta pour vérifier si le subgraph a ignoré les erreurs, comme dans l’exemple :

1foos(first: 100, subgraphError: allow) {2  id3}45_meta {6  hasIndexingErrors7}

Si le subgraph rencontre une erreur, cette requête renverra à la fois les données et une erreur graphql avec le message "indexing_error", comme dans cet exemple de réponse :

1"data": {2    "foos": [3        {4          "id": "0xdead"5        }6    ],7    "_meta": {8        "hasIndexingErrors": true9    }10},11"errors": [12    {13        "message": "indexing_error"14    }15]

File Data Sources de fichiers IPFS/Arweave

Les fichiers sources de données sont une nouvelle fonctionnalité de Subgraph permettant d’accéder à des données hors chaîne pendant l’indexation d’une manière robuste et extensible. Les fichiers sources de données permettent de récupérer des fichiers à partir d’IPFS et d’Arweave.

Aperçu

Plutôt que de récupérer les fichiers “ligne par ligne” pendant l’exécution du gestionnaire, ceci introduit des modèles qui peuvent être générés comme nouvelles sources de données pour un identifiant de fichier donné. Ces nouvelles sources de données récupèrent les fichiers, réessayant en cas d’échec, et exécutant un gestionnaire dédié lorsque le fichier est trouvé.

Cela est similaire aux modèles de source de données existants, qui sont utilisés pour créer dynamiquement de nouvelles sources de données basées sur la blockchain.

Guide de mise à niveau

Mise à jour de graph-ts et graph-cli

Les fichiers sources de données requièrent graph-ts >=0.29.0 et graph-cli >=0.33.1

Ajouter un nouveau type d’entité qui sera mis à jour lorsque des fichiers seront trouvés

Les sources de données de fichier ne peuvent pas accéder ni mettre à jour les entités basées sur une chaîne, mais doivent mettre à jour les entités spécifiques au fichier.

Cela peut impliquer de diviser les champs des entités existantes en entités distinctes, liées entre elles.

Entité combinée d’origine :

1type Token @entity {2  id: ID!3  tokenID: BigInt!4  tokenURI: String!5  externalURL: String!6  ipfsURI: String!7  image: String!8  name: String!9  description: String!10  type: String!11  updatedAtTimestamp: BigInt12  owner: User!13}

Nouvelle entité scindée :

1type Token @entity {2  id: ID!3  tokenID: BigInt!4  tokenURI: String!5  ipfsURI: TokenMetadata6  updatedAtTimestamp: BigInt7  owner: String!8}910type TokenMetadata @entity {11  id: ID!12  image: String!13  externalURL: String!14  name: String!15  description: String!16}

Si la relation est 1:1 entre l’entité parent et l’entité de source de données de fichier résultante, le modèle le plus simple consiste à lier l’entité parent à une entité de fichier résultante en utilisant le CID IPFS comme recherche. Contactez Discord si vous rencontrez des difficultés pour modéliser vos nouvelles entités basées sur des fichiers !

Ajouter une nouvelle source de données modélisée avec kind : file/ipfs ou kind : file/arweave

Il s’agit de la source de données qui sera générée lorsqu’un fichier d’intérêt est identifié.

1templates:2  - name: TokenMetadata3    kind: file/ipfs4    mapping:5      apiVersion: 0.0.96      language: wasm/assemblyscript7      file: ./src/mapping.ts8      handler: handleMetadata9      entities:10        - TokenMetadata11      abis:12        - name: Token13          file: ./abis/Token.json

Le fichier source de données doit mentionner spécifiquement tous les types d’entités avec lesquels elle interagira sous entities. Voir limitations pour plus de détails.

Créer un nouveau gestionnaire pour traiter les fichiers

Ce gestionnaire devrait accepter un paramètre Bytes, qui sera le contenu du fichier, lorsqu’il sera trouvé, il pourra alors être traité. Il s’agira souvent d’un fichier JSON, qui peut être traité à l’aide des utilitaires de graph-ts (documentation).

Le CID du fichier sous forme de chaîne de caractères lisible est accessible via dataSource de la manière suivante :

1const cid = dataSource.stringParam()

Exemple de gestionnaire :

1import { json, Bytes, dataSource } from '@graphprotocol/graph-ts'2import { TokenMetadata } from '../generated/schema'34export function handleMetadata(content: Bytes): void {5  let tokenMetadata = new TokenMetadata(dataSource.stringParam())6  const value = json.fromBytes(content).toObject()7  if (value) {8    const image = value.get('image')9    const name = value.get('name')10    const description = value.get('description')11    const externalURL = value.get('external_url')1213    if (name && image && description && externalURL) {14      tokenMetadata.name = name.toString()15      tokenMetadata.image = image.toString()16      tokenMetadata.externalURL = externalURL.toString()17      tokenMetadata.description = description.toString()18    }1920    tokenMetadata.save()21  }22}

Générer des sources de données de fichiers si nécessaire

Vous pouvez désormais créer des sources de données de fichiers lors de l’exécution de gestionnaires basés sur une chaîne :

• Importer le modèle à partir du fichier templates généré automatiquement
• appeler TemplateName.create(cid : string) à partir d’un mappage, où le cid est un identifiant de contenu valide pour IPFS ou Arweave

Pour IPFS, Graph Node prend en charge les identifiants de contenu v0 et v1⁠, et les identifiants de contenu avec des répertoires (par exemple, bafyreighykzv2we26wfrbzkcdw37sbrby4upq7ae3aqobbq7i4er3tnxci/metadata.json).

Pour Arweave, à partir de la version 0.33.0, Graph Node peut récupérer des fichiers stockés sur Arweave sur la base de leur identifiant de transaction⁠ à partir d’une passerelle Arweave (exemple de fichier⁠). Arweave prend en charge les transactions téléchargées via Irys (anciennement Bundlr), et Graph Node peut également récupérer des fichiers sur la base les manifestes Irys⁠.

L’exemple:

1import { TokenMetadata as TokenMetadataTemplate } from '../generated/templates'23const ipfshash = 'QmaXzZhcYnsisuue5WRdQDH6FDvqkLQX1NckLqBYeYYEfm'4//Cet exemple de code concerne un subgraph Crypto coven. Le hash ipfs ci-dessus est un répertoire contenant les métadonnées des jetons pour tous les NFT de la communauté crypto56export function handleTransfer(event: TransferEvent): void {7  let token = Token.load(event.params.tokenId.toString())8  if (!token) {9    token = new Token(event.params.tokenId.toString())10    token.tokenID = event.params.tokenId1112    token.tokenURI = '/' + event.params.tokenId.toString() + '.json'13    const tokenIpfsHash = ipfshash + token.tokenURI14    //Cette opération crée un chemin d'accès aux métadonnées d'un seul Crypto coven NFT. Il concatène le répertoire avec  "/" + nom de fichier +  ".json"1516    token.ipfsURI = tokenIpfsHash1718    TokenMetadataTemplate.create(tokenIpfsHash)19  }2021  token.updatedAtTimestamp = event.block.timestamp22  token.owner = event.params.to.toHexString()23  token.save()24}

Cela créera une nouvelle source de données de fichier, qui interrogera le point d’extrémité IPFS ou Arweave configuré du nœud de graphique, en réessayant si elle n’est pas trouvée. Lorsque le fichier est trouvé, le gestionnaire de la source de données de fichier est exécuté.

Cet exemple utilise le CID comme référence entre l’entité parent Token et l’entité résultante TokenMetadata.

Félicitations, vous utilisez des sources de données de fichiers !

Déploiement de vos Subgraphs

Vous pouvez maintenant construire et déployer votre Subgraph sur n’importe quel Graph Node >=v0.30.0-rc.0.

Limitations

Les entités et les gestionnaires de fichiers sources de données sont isolés des autres entités du subgraph, ce qui garantit qu’ils sont déterministes lorsqu’ils sont exécutés et qu’il n’y a pas de contamination des sources de données basées sur des blockchain. Pour être plus précis :

• Les entités créées par les sources de données de fichiers sont immuables et ne peuvent pas être mises à jour
• Les gestionnaires de sources de données de fichiers ne peuvent pas accéder à des entités provenant d’autres sources de données de fichiers
• Les entités associées aux sources de données de fichiers ne sont pas accessibles aux gestionnaires basés sur des chaînes

En outre, il n’est pas possible de créer des sources de données à partir d’une source de données de fichier, qu’il s’agisse d’une source de données onchain ou d’une autre source de données de fichier. Cette restriction pourrait être levée à l’avenir.

Meilleures pratiques

Si vous liez des métadonnées NFT aux jetons correspondants, utilisez le hachage IPFS des métadonnées pour référencer une entité Metadata à partir de l’entité Token. Enregistrez l’entité Metadata en utilisant le hachage IPFS comme identifiant.

Vous pouvez utiliser Le contexte de DataSource lors de la création de fichiers sources de données(File Data Sources) pour transmettre des informations supplémentaires qui seront disponibles pour le gestionnaire de la File Data Source.

Si vous avez des entités qui sont actualisées plusieurs fois, créez des entités uniques basées sur des fichiers en utilisant le hash IPFS & l’ID de l’entité, puis référencez-les en utilisant un champ dérivé dans l’entité basée sur la chaîne.

Problèmes connus

Les fichiers sources de données nécessitent actuellement des ABI, même si les ABI ne sont pas utilisées (problème⁠). La solution consiste à ajouter n’importe quel ABI.

Les gestionnaires pour les fichiers sources de données ne peuvent pas être dans des fichiers qui importent des liaisons de contrat eth_call, échouant avec “unknown import : ethereum::ethereum.call n’a pas été défini” (problème⁠). La solution consiste à créer des gestionnaires de fichiers de sources de données dans un fichier dédié.

Exemples

migration de subgraph Crypto Coven ⁠

Les Références

fichier sources de données GIP⁠

Filtres d’Arguments indexés / Filtres de Topics

Les filtres thématiques, également connus sous le nom de filtres d’arguments indexés, sont une fonctionnalité puissante de Subgraphs qui permet aux utilisateurs de filtrer précisément les événements de la blockchain en fonction des valeurs de leurs arguments indexés.

• Ces filtres permettent d’isoler des événements spécifiques intéressants du vaste flux d’événements sur la blockchain, ce qui permet aux Subgraphs de fonctionner plus efficacement en se concentrant uniquement sur les données pertinentes.

• Ceci est utile pour créer des subgraphs personnels qui suivent des adresses spécifiques et leurs interactions avec divers contrats intelligents sur la blockchain.

Comment fonctionnent les filtres de Topics

Lorsqu’un contrat intelligent émet un événement, tous les arguments marqués comme indexés peuvent être utilisés comme filtres dans le manifeste d’un subgraph. Cela permet au subgraph d’écouter sélectivement les événements qui correspondent à ces arguments indexés.

• Le premier argument indexé de l’événement correspond à topic1, le second à topic2, et ainsi de suite, jusqu’à topic3, puisque la machine virtuelle Ethereum (EVM) autorise jusqu’à trois arguments indexés par événement.

1// SPDX-License-Identifier: MIT2pragma solidity ^0.8.0;34contract Token {5    // Déclaration de l'événement avec des paramètres indexés pour les adresses6    event Transfer(address indexed from, address indexed to, uint256 value);78    // Fonction pour simuler le transfert de tokens9    function transfer(address to, uint256 value) public {10        // Emission de l'événement Transfer avec from, to, et value11        emit Transfer(msg.sender, to, value);12    }13}

Dans cet exemple:

• L’événement Transfer est utilisé pour enregistrer les transactions de jetons entre adresses.
• Les paramètres from et to sont indexés, ce qui permet aux auditeurs d’événements de filtrer et de surveiller les transferts impliquant des adresses spécifiques.
• La fonction transfer est une représentation simple d’une action de transfert de jeton, émettant l’événement Transfer à chaque fois qu’elle est appelée.

Configuration dans les subgraphs

Les filtres thématiques sont définis directement dans la configuration du gestionnaire d’événements dans le manifeste Subgraph. Voici comment ils sont configurés :

1eventHandlers:2  - event: SomeEvent(indexed uint256, indexed address, indexed uint256)3    handler: handleSomeEvent4    topic1: ['0xValue1', '0xValue2']5    topic2: ['0xAddress1', '0xAddress2']6    topic3: ['0xValue3']

Dans cette configuration :

• topic1 correspond au premier argument indexé de l’événement, topic2 au deuxième et topic3 au troisième.
• Chaque topic peut avoir une ou plusieurs valeurs, et un événement n’est traité que s’il correspond à l’une des valeurs de chaque rubrique spécifiée.

Logique des Filtres

• Au sein d’une même Topic: La logique fonctionne comme une condition OR. L’événement sera traité s’il correspond à l’une des valeurs listées dans une rubrique donnée.
• Entre différents Topics: La logique fonctionne comme une condition AND. Un événement doit satisfaire toutes les conditions spécifiées à travers les différents topics pour déclencher le gestionnaire associé.

Exemple 1 : Suivi des transferts directs de l’adresse A à l’adresse B

1eventHandlers:2  - event: Transfer(indexed address,indexed address,uint256)3    handler: handleDirectedTransfer4    topic1: ['0xAddressA'] # Sender Address5    topic2: ['0xAddressB'] # Receiver Address

Dans cette configuration:

• topic1 est configuré pour filtrer les événements Transfer dont l’expéditeur est 0xAddressA.
• topic2 est configuré pour filtrer les événements Transfer dont 0xAddressB est le destinataire.
• Le subgraph n’indexera que les transactions qui se produisent directement de 0xAddressA à 0xAddressB.

Exemple 2 : Suivi des transactions dans les deux sens entre deux ou plusieurs adresses

1eventHandlers:2  - event: Transfer(indexed address,indexed address,uint256)3    handler: handleTransferToOrFrom4    topic1: ['0xAddressA', '0xAddressB', '0xAddressC'] # Sender Address5    topic2: ['0xAddressB', '0xAddressC'] # Receiver Address

Dans cette configuration:

• topic1 est configuré pour filtrer les événements Transfer dont l’expéditeur est 0xAddressA, 0xAddressB, 0xAddressC.
• topic2 est configuré pour filtrer les événements Transfer où 0xAddressB et 0xAddressC sont les destinataires.
• Le subgraph indexe les transactions qui se produisent dans les deux sens entre plusieurs adresses, ce qui permet un suivi complet des interactions impliquant toutes les adresses.

Déclaration eth_call

Les eth_calls déclaratifs sont une fonctionnalité précieuse de Subgraph qui permet aux eth_calls d’être exécutés à l’avance, permettant à graph-node de les exécuter en parallèle.

Cette fonctionnalité permet de :

• Améliore considérablement les performances de la récupération des données de la blockchain Ethereum en réduisant le temps total des appels multiples et en optimisant l’efficacité globale du subgraph.
• Permet une récupération plus rapide des données, entraînant des réponses de requête plus rapides et une meilleure expérience utilisateur.
• Réduire les temps d’attente pour les applications qui doivent réunir des données de plusieurs appels Ethereum, rendant le processus de récupération des données plus efficace.

Concepts clés

• Les eth_calls déclaratifs : Appels Ethereum qui sont définis pour être exécutés en parallèle plutôt que séquentiellement.
• Exécution en parallèle : Au lieu d’attendre la fin d’un appel avant de commencer le suivant, plusieurs appels peuvent être initiés simultanément.
• Efficacité temporelle : Le temps total nécessaire pour tous les appels passe de la somme des temps d’appel individuels (séquentiels) au temps pris par l’appel le plus long (parallèle).

Scénario sans eth_calls déclaratifs

Imaginez que vous ayez un subgraph qui doit faire trois appels Ethereum pour récupérer des données sur les transactions, le solde et les avoirs en jetons d’un utilisateur.

Traditionnellement, ces appels pourraient être effectués de manière séquentielle :

1. Appel 1 (Transactions) : Prend 3 secondes
2. Appel 2 (Solde) : Prend 2 secondes
3. Appel 3 (Avoirs en jetons) : Prend 4 secondes

Temps total pris = 3 + 2 + 4 = 9 secondes

Scénario avec eth_calls déclaratif

Avec cette fonctionnalité, vous pouvez déclarer que ces appels soient exécutés en parallèle :

1. Appel 1 (Transactions) : Prend 3 secondes
2. Appel 2 (Solde) : Prend 2 secondes
3. Appel 3 (Avoirs en jetons) : Prend 4 secondes

Puisque ces appels sont exécutés en parallèle, le temps total pris est égal au temps pris par l’appel le plus long.

Temps total pris = max (3, 2, 4) = 4 secondes

Comment ça marche

1. Définition déclarative : Dans le manifeste Subgraph, vous déclarez les appels Ethereum d’une manière qui indique qu’ils peuvent être exécutés en parallèle.
2. Moteur d’exécution parallèle : Le moteur d’exécution de Graph Node reconnaît ces déclarations et exécute les appels simultanément.
3. Agrégation des résultats : Une fois tous les appels terminés, les résultats sont agrégés et utilisés par le Subgraph pour la suite du traitement.

Exemple de configuration dans le manifeste du subgraph

Les eth_calls déclarés peuvent accéder à l’adresse event.address de l’événement sous-jacent ainsi qu’à tous les paramètres event.params.

subgraph.yaml en utilisant event.address:

1eventHandlers:2event: Swap(indexed address,indexed address,int256,int256,uint160,uint128,int24)3handler: handleSwap4calls:5  global0X128: Pool[event.address].feeGrowthGlobal0X128()6  global1X128: Pool[event.address].feeGrowthGlobal1X128()

Détails pour l’exemple ci-dessus :

• global0X128 est le nom déclaré de eth_call.
• Le texte (global0X128) est le label de ce eth_call qui est utilisé lors de la journalisation des erreurs.
• Le texte (Pool[event.address].feeGrowthGlobal0X128()) est le eth_call réel qui sera exécuté, et est sous la forme de Contract[address].function(arguments)
• L’adresse et les arguments peuvent être remplacés par des variables qui seront disponibles lorsque le gestionnaire sera exécuté.

subgraph.yaml en utilisant event.params

1calls:2  - ERC20DecimalsToken0: ERC20[event.params.token0].decimals()

Greffe sur des subgraphs existants

Lorsqu’un subgraph est déployé pour la première fois, il commence à indexer les événements au bloc de genèse de la chaîne correspondante (ou au startBlock défini avec chaque source de données). Dans certaines circonstances, il est avantageux de réutiliser les données d’un subgraph existant et de commencer l’indexation à un bloc beaucoup plus tardif. Ce mode d’indexation est appelé “greffage”. Le greffage est, par exemple, utile pendant le développement pour surmonter rapidement de simples erreurs dans les mappages ou pour rétablir temporairement le fonctionnement d’un subgraph existant après qu’il ait échoué.

Un subgraph est greffé sur un subgraph de base lorsque le manifeste du subgraph dans subgraph.yaml contient un bloc graft au niveau supérieur :

1description: ...2graft:3  base: Qm... #  ID du Subgraph de base Subgraph4  block: 7345624 # Numéro de bloc

Lorsqu’un subgraph dont le manifeste contient un bloc graft est déployé, Graph Node va copier les données du subgraph base jusqu’au block donné inclus, puis continuer à indexer le nouveau subgraph à partir de ce bloc. Le subgraph de base doit exister sur l’instance du Graph Node cible et doit avoir été indexé au moins jusqu’au bloc donné. En raison de cette restriction, le greffage ne devrait être utilisée qu’en cours de développement ou en cas d’urgence pour accélérer la production d’un subgraph équivalent non greffé.

Étant donné que la greffe copie les données de base plutôt que de les indexer, il est beaucoup plus rapide d’amener le subgraph au bloc souhaité que de l’indexer à partir de zéro, bien que la copie initiale des données puisse encore prendre plusieurs heures pour les très grands subgraphs. Pendant l’initialisation du subgraph greffé, Graph Node enregistre des informations sur les types d’entités qui ont déjà été copiés.

The grafted Subgraph can use a GraphQL schema that is not identical to the one of the base Subgraph, but merely compatible with it. It has to be a valid Subgraph schema in its own right, but may deviate from the base Subgraph’s schema in the following ways:

• Il ajoute ou supprime des types d’entité
• Il supprime les attributs des types d’entité
• Il ajoute des attributs nullables aux types d’entités
• Il transforme les attributs non nullables en attributs nuls
• Cela ajoute des valeurs aux énumérations
• Il ajoute ou supprime des interfaces
• Cela change pour quels types d’entités une interface est implémentée