Écrire des mappages en AssemblyScript

Aperçu

Les mappages prennent des données d’une source particulière et les transforment en entités définies dans votre schéma. Les mappages sont écrits dans un sous-ensemble de TypeScript⁠ appelé AssemblyScript⁠ qui peut être compilé en WASM (WebAssembly⁠). AssemblyScript est plus strict que le TypeScript normal, tout en offrant une syntaxe familière.

Écriture de mappages

Pour chaque gestionnaire d’événements défini dans subgraph.yaml sous mapping.eventHandlers, créez une fonction exportée du même nom. Chaque gestionnaire doit accepter un seul paramètre appelé event avec un type correspondant au nom de l’événement traité.

Dans l’exemple Subgraph, src/mapping.ts contient des gestionnaires pour les événements NewGravatar et UpdatedGravatar :

1import { NewGravatar, UpdatedGravatar } from '../generated/Gravity/Gravity'2import { Gravatar } from '../generated/schema'34export function handleNewGravatar(event: NewGravatar): void {5  let gravatar = new Gravatar(event.params.id)6  gravatar.owner = event.params.owner7  gravatar.displayName = event.params.displayName8  gravatar.imageUrl = event.params.imageUrl9  gravatar.save()10}1112export function handleUpdatedGravatar(event: UpdatedGravatar): void {13  let id = event.params.id14  let gravatar = Gravatar.load(id)15  if (gravatar == null) {16    gravatar = new Gravatar(id)17  }18  gravatar.owner = event.params.owner19  gravatar.displayName = event.params.displayName20  gravatar.imageUrl = event.params.imageUrl21  gravatar.save()22}

Le premier gestionnaire prend un événement NewGravatar et crée une nouvelle entité Gravatar avec new Gravatar(event.params.id.toHex()), en remplissant les champs de l’entité à l’aide des paramètres de l’événement correspondant. Cette instance d’entité est représentée par la variable gravatar, avec une valeur d’id de event.params.id.toHex().

Le deuxième gestionnaire tente de charger le Gravatar existant à partir du store Graph Node. S’il n’existe pas encore, il est créé à la demande. L’entité est ensuite mise à jour pour correspondre aux nouveaux paramètres de l’événement avant d’être sauvegardée dans le store à l’aide de gravatar.save().

ID recommandés pour la création de nouvelles entités

Il est fortement recommandé d’utiliser Bytes comme type pour les champs id, et de n’utiliser String que pour les attributs qui contiennent vraiment du texte lisible par l’homme, comme le nom d’un jeton. Voici quelques valeurs d’id recommandées à prendre en compte lors de la création de nouvelles entités.

• transfer.id = event.transaction.hash

• let id = event.transaction.hash.concatI32(event.logIndex.toI32())

• Pour les entités qui stockent des données agrégées, par exemple les volumes d’échanges quotidiens, l’id contient généralement le numéro du jour. Dans ce cas, l’utilisation d’un Bytes comme id est bénéfique. La détermination de l’id se fait de la manière suivante

1let dayID = event.block.timestamp.toI32() / 864002let id = Bytes.fromI32(dayID)

• Convertir les adresses constantes en Bytes.

const id = Bytes.fromHexString('0xdead...beef')

Il existe une Library Graph Typescript ⁠ qui contient des utilitaires pour interagir avec le store Graph Node et des commodités pour gérer les données et les entités des contrats intelligents. Elle peut être importée dans mapping.ts depuis @graphprotocol/graph-ts.

Traitement des entités ayant des identifiants identiques

Lors de la création et de l’enregistrement d’une nouvelle entité, si une entité avec le même ID existe déjà, les propriétés de la nouvelle entité sont toujours préférées lors du processus de fusion. Cela signifie que l’entité existante sera mise à jour avec les valeurs de la nouvelle entité.

Si une valeur nulle est intentionnellement définie pour un champ de la nouvelle entité avec le même ID, l’entité existante sera mise à jour avec la valeur nulle.

Si aucune valeur n’est définie pour un champ de la nouvelle entité avec le même ID, le champ aura également la valeur null.

Génération de code

Afin de faciliter le travail avec les contrats intelligents, les événements et les entités, Graph CLI peut générer des types AssemblyScript à partir du schéma GraphQL du Subgraph et des ABI des contrats inclus dans les sources de données.

Cela se fait avec

1graph codegen [--output-dir <Repertoire_D_Sortie>] [<MANIFESTE>]

mais dans la plupart des cas, les Subgraph sont déjà préconfigurés via package.json pour vous permettre d’exécuter simplement l’un des éléments suivants pour obtenir le même résultat :

1# Yarn2yarn codegen34# NPM5npm run codegen

Cela va générer une classe AssemblyScript pour chaque contrat intelligent dans les fichiers ABI mentionnés dans subgraph.yaml, vous permettant de lier ces contrats à des adresses spécifiques dans les mappages et d’appeler des méthodes de contrat en lecture seule sur le bloc en cours de traitement. Il génère également une classe pour chaque événement de contrat afin de fournir un accès facile aux paramètres de l’événement, ainsi qu’au bloc et à la transaction d’où provient l’événement. Tous ces types sont écrits dans <OUTPUT_DIR>/<DATA_SOURCE_NAME>/<ABI_NAME>.ts. Dans l’exemple Subgraph, ce serait generated/Gravity/Gravity.ts, permettant aux mappages d’importer ces types avec.

1import {2  // La classe de contrat :3  Gravity,4  // Les classes d'événements :5  NewGravatar,6  UpdatedGravatar,7} from '../generated/Gravity/Gravity'

En outre, une classe est générée pour chaque type d’entité dans le schéma GraphQL du Subgraph. Ces classes fournissent un chargement d’entité sécurisé, un accès en lecture et en écriture aux champs de l’entité ainsi qu’une méthode save() pour écrire les entités dans le store. Toutes les classes d’entités sont écrites dans le fichier <OUTPUT_DIR>/schema.ts, ce qui permet aux mappages de les importer avec la commande

1import { Gravatar } from '../generated/schema'

La génération de code ne vérifie pas votre code de mappage dans src/mapping.ts. Si vous voulez le vérifier avant d’essayer de déployer votre Subgraph dans Graph Explorer, vous pouvez lancer yarn build et corriger les erreurs de syntaxe que le compilateur TypeScript pourrait trouver.