Subgraph Manifest

Reading time: 15 min

The subgraph manifest, subgraph.yaml, defines the smart contracts & network your subgraph will index, the events from these contracts to pay attention to, and how to map event data to entities that Graph Node stores and allows to query.

The subgraph definition consists of the following files:

• subgraph.yaml: Contains the subgraph manifest

• schema.graphql: A GraphQL schema defining the data stored for your subgraph and how to query it via GraphQL

• mapping.ts: AssemblyScript Mappings code that translates event data into entities defined in your schema (e.g. mapping.ts in this guide)

Un seul subgraph peut :

• Indexer les données de plusieurs contrats intelligents (mais pas de plusieurs réseaux).

• Indexer des données de fichiers IPFS en utilisant des File Data Sources.

• Add an entry for each contract that requires indexing to the dataSources array.

The full specification for subgraph manifests can be found here.

For the example subgraph listed above, subgraph.yaml is:

version spec : 0.0.4
description : Gravatar pour Ethereum
référentiel : https://github.com/graphprotocol/graph-tooling
schéma:
   fichier : ./schema.graphql
indexeurConseils :
   tailler : automatique
les sources de données:
   - genre : ethereum/contrat
     nom: Gravité
     réseau : réseau principal
     source:
       adresse : '0x2E645469f354BB4F5c8a05B3b30A929361cf77eC'
       abi : Gravité
       bloc de démarrage : 6175244
       bloc de fin : 7175245
     contexte:
       foo :
         tapez : Booléen
         données : vrai
       bar:
         tapez : chaîne
         données : 'barre'
     cartographie :
       genre : ethereum/événements
       Version api : 0.0.6
       langage : wasm/assemblyscript
       entités :
         -Gravatar
       abis :
         - nom : Gravité
           fichier : ./abis/Gravity.json
       Gestionnaires d'événements :
         - événement : NewGravatar(uint256,adresse,chaîne,chaîne)
           gestionnaire : handleNewGravatar
         - événement : UpdatedGravatar (uint256, adresse, chaîne, chaîne)
           gestionnaire : handleUpdatedGravatar
       Gestionnaires d'appels :
         - fonction : createGravatar(string,string)
           gestionnaire : handleCreateGravatar
       gestionnaires de blocs :
         - gestionnaire : handleBlock
         - gestionnaire : handleBlockWithCall
           filtre:
             genre : appeler
       fichier : ./src/mapping.ts

Les entrées importantes à mettre à jour pour le manifeste sont :

• specVersion: a semver version that identifies the supported manifest structure and functionality for the subgraph. The latest version is 1.2.0. See specVersion releases section to see more details on features & releases.

• description: a human-readable description of what the subgraph is. This description is displayed in Graph Explorer when the subgraph is deployed to Subgraph Studio.

• repository: the URL of the repository where the subgraph manifest can be found. This is also displayed in Graph Explorer.

• features: a list of all used feature names.

• indexerHints.prune: Defines the retention of historical block data for a subgraph. See prune in indexerHints section.

• dataSources.source: the address of the smart contract the subgraph sources, and the ABI of the smart contract to use. The address is optional; omitting it allows to index matching events from all contracts.

• dataSources.source.startBlock: the optional number of the block that the data source starts indexing from. In most cases, we suggest using the block in which the contract was created.

• dataSources.source.endBlock: The optional number of the block that the data source stops indexing at, including that block. Minimum spec version required: 0.0.9.

• dataSources.context: key-value pairs that can be used within subgraph mappings. Supports various data types like Bool, String, Int, Int8, BigDecimal, Bytes, List, and BigInt. Each variable needs to specify its type and data. These context variables are then accessible in the mapping files, offering more configurable options for subgraph development.

• dataSources.mapping.entities: the entities that the data source writes to the store. The schema for each entity is defined in the schema.graphql file.

• dataSources.mapping.abis: one or more named ABI files for the source contract as well as any other smart contracts that you interact with from within the mappings.

• dataSources.mapping.eventHandlers: lists the smart contract events this subgraph reacts to and the handlers in the mapping—./src/mapping.ts in the example—that transform these events into entities in the store.

• dataSources.mapping.callHandlers: lists the smart contract functions this subgraph reacts to and handlers in the mapping that transform the inputs and outputs to function calls into entities in the store.

• dataSources.mapping.blockHandlers: lists the blocks this subgraph reacts to and handlers in the mapping to run when a block is appended to the chain. Without a filter, the block handler will be run every block. An optional call-filter can be provided by adding a filter field with kind: call to the handler. This will only run the handler if the block contains at least one call to the data source contract.

A single subgraph can index data from multiple smart contracts. Add an entry for each contract from which data needs to be indexed to the dataSources array.

Les gestionnaires d'événements dans un subgraph réagissent à des événements spécifiques émis par des contrats intelligents sur la blockchain et déclenchent des gestionnaires définis dans le manifeste du subgraph. Ceci permet aux subgraphs de traiter et de stocker les données des événements selon une logique définie.

Un gestionnaire d'événements est déclaré dans une source de données dans la configuration YAML du subgraph. Il spécifie quels événements écouter et la fonction correspondante à exécuter lorsque ces événements sont détectés.

dataSources:
  - kind: ethereum/contract
    name: Gravity
    network: dev
    source:
      address: '0x731a10897d267e19b34503ad902d0a29173ba4b1'
      abi: Gravity
    mapping:
      kind: ethereum/events
      apiVersion: 0.0.6
      language: wasm/assemblyscript
      entities:
        - Gravatar
        - Transaction
      abis:
        - name: Gravity
          file: ./abis/Gravity.json
      eventHandlers:
        - event: Approval(address,address,uint256)
          handler: handleApproval
        - event: Transfer(address,address,uint256)
          handler: handleTransfer
          topic1: ['0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045', '0xc8dA6BF26964aF9D7eEd9e03E53415D37aA96325'] # Filtre de rubrique optionnel qui filtre uniquement les événements avec la rubrique spécifiée.

While events provide an effective way to collect relevant changes to the state of a contract, many contracts avoid generating logs to optimize gas costs. In these cases, a subgraph can subscribe to calls made to the data source contract. This is achieved by defining call handlers referencing the function signature and the mapping handler that will process calls to this function. To process these calls, the mapping handler will receive an ethereum.Call as an argument with the typed inputs to and outputs from the call. Calls made at any depth in a transaction's call chain will trigger the mapping, allowing activity with the data source contract through proxy contracts to be captured.

Les gestionnaires d'appels ne se déclencheront que dans l'un des deux cas suivants : lorsque la fonction spécifiée est appelée par un compte autre que le contrat lui-même ou lorsqu'elle est marquée comme externe dans Solidity et appelée dans le cadre d'une autre fonction du même contrat.

To define a call handler in your manifest, simply add a callHandlers array under the data source you would like to subscribe to.

dataSources:
  - kind: ethereum/contract
    name: Gravity
    network: mainnet
    source:
      address: '0x731a10897d267e19b34503ad902d0a29173ba4b1'
      abi: Gravity
    mapping:
      kind: ethereum/events
      apiVersion: 0.0.6
      language: wasm/assemblyscript
      entities:
        - Gravatar
        - Transaction
      abis:
        - name: Gravity
          file: ./abis/Gravity.json
      callHandlers:
        - function: createGravatar(string,string)
          handler: handleCreateGravatar

The function is the normalized function signature to filter calls by. The handler property is the name of the function in your mapping you would like to execute when the target function is called in the data source contract.

Each call handler takes a single parameter that has a type corresponding to the name of the called function. In the example subgraph above, the mapping contains a handler for when the createGravatar function is called and receives a CreateGravatarCall parameter as an argument:

import { CreateGravatarCall } from '../generated/Gravity/Gravity'
import { Transaction } from '../generated/schema'

export function handleCreateGravatar(call: CreateGravatarCall): void {
  let id = call.transaction.hash
  let transaction = new Transaction(id)
  transaction.displayName = call.inputs._displayName
  transaction.imageUrl = call.inputs._imageUrl
  transaction.save()
}

The handleCreateGravatar function takes a new CreateGravatarCall which is a subclass of ethereum.Call, provided by @graphprotocol/graph-ts, that includes the typed inputs and outputs of the call. The CreateGravatarCall type is generated for you when you run graph codegen.

En plus de s'abonner à des événements de contrat ou à des appels de fonction, un subgraph peut souhaiter mettre à jour ses données à mesure que de nouveaux blocs sont ajoutés à la chaîne. Pour y parvenir, un subgraph peut exécuter une fonction après chaque bloc ou après des blocs correspondant à un filtre prédéfini.

filter:
  kind: call

The defined handler will be called once for every block which contains a call to the contract (data source) the handler is defined under.

L'absence de filtre pour un gestionnaire de bloc garantira que le gestionnaire est appelé à chaque bloc. Une source de données ne peut contenir qu'un seul gestionnaire de bloc pour chaque type de filtre.

dataSources:
  - kind: ethereum/contract
    name: Gravity
    network: dev
    source:
      address: '0x731a10897d267e19b34503ad902d0a29173ba4b1'
      abi: Gravity
    mapping:
      kind: ethereum/events
      apiVersion: 0.0.6
      language: wasm/assemblyscript
      entities:
        - Gravatar
        - Transaction
      abis:
        - name: Gravity
          file: ./abis/Gravity.json
      blockHandlers:
        - handler: handleBlock
        - handler: handleBlockWithCallToContract
          filter:
            kind: call

blockHandlers:
  - handler: handleBlock
    filter:
      kind: polling
      every: 10

The defined handler will be called once for every n blocks, where n is the value provided in the every field. This configuration allows the subgraph to perform specific operations at regular block intervals.

blockHandlers:
  - handler: handleOnce
    filter:
      kind: once

Le gestionnaire défini avec le filtre once ne sera appelé qu'une seule fois avant l'exécution de tous les autres gestionnaires. Cette configuration permet au subgraph d'utiliser le gestionnaire comme gestionnaire d'initialisation, effectuant des tâches spécifiques au début de l'indexation.

export function handleOnce(block: ethereum.Block): void {
  let data = new InitialData(Bytes.fromUTF8('initial'))
  data.data = 'Setup data here'
  data.save()
}

The mapping function will receive an ethereum.Block as its only argument. Like mapping functions for events, this function can access existing subgraph entities in the store, call smart contracts and create or update entities.

import { ethereum } from '@graphprotocol/graph-ts'

export function handleBlock(block: ethereum.Block): void {
  let id = block.hash
  let entity = new Block(id)
  entity.save()
}

Si vous devez traiter des événements anonymes dans Solidity, cela peut être réalisé en fournissant le sujet 0 de l'événement, comme dans l'exemple :

eventHandlers:
  - event: LogNote(bytes4,address,bytes32,bytes32,uint256,bytes)
    topic0: '0x644843f351d3fba4abcd60109eaff9f54bac8fb8ccf0bab941009c21df21cf31'
    handler: handleGive

An event will only be triggered when both the signature and topic 0 match. By default, topic0 is equal to the hash of the event signature.

Starting from specVersion 0.0.5 and apiVersion 0.0.7, event handlers can have access to the receipt for the transaction which emitted them.

To do so, event handlers must be declared in the subgraph manifest with the new receipt: true key, which is optional and defaults to false.

eventHandlers:
  - event: NewGravatar(uint256,address,string,string)
    handler: handleNewGravatar
    receipt: true

Inside the handler function, the receipt can be accessed in the Event.receipt field. When the receipt key is set to false or omitted in the manifest, a null value will be returned instead.

Les déclencheurs d'une source de données au sein d'un bloc sont classés à l'aide du processus suivant :

1. Les déclencheurs d'événements et d'appels sont d'abord classés par index de transaction au sein du bloc.
2. Les déclencheurs d'événements et d'appels au sein d'une même transaction sont classés selon une convention : les déclencheurs d'événements d'abord, puis les déclencheurs d'appel, chaque type respectant l'ordre dans lequel ils sont définis dans le manifeste.
3. Les déclencheurs de bloc sont exécutés après les déclencheurs d'événement et d'appel, dans l'ordre dans lequel ils sont définis dans le manifeste.

Ces règles de commande sont susceptibles de changer.

Un modèle courant dans les contrats intelligents compatibles EVM est l'utilisation de contrats de registre ou d'usine, dans lesquels un contrat crée, gère ou référence un nombre arbitraire d'autres contrats qui ont chacun leur propre état et leurs propres événements.

The addresses of these sub-contracts may or may not be known upfront and many of these contracts may be created and/or added over time. This is why, in such cases, defining a single data source or a fixed number of data sources is impossible and a more dynamic approach is needed: data source templates.

First, you define a regular data source for the main contract. The snippet below shows a simplified example data source for the Uniswap exchange factory contract. Note the NewExchange(address,address) event handler. This is emitted when a new exchange contract is created on-chain by the factory contract.

dataSources:
  - kind: ethereum/contract
    name: Factory
    network: mainnet
    source:
      address: '0xc0a47dFe034B400B47bDaD5FecDa2621de6c4d95'
      abi: Factory
    mapping:
      kind: ethereum/events
      apiVersion: 0.0.6
      language: wasm/assemblyscript
      file: ./src/mappings/factory.ts
      entities:
        - Directory
      abis:
        - name: Factory
          file: ./abis/factory.json
      eventHandlers:
        - event: NewExchange(address,address)
          handler: handleNewExchange

Then, you add data source templates to the manifest. These are identical to regular data sources, except that they lack a pre-defined contract address under source. Typically, you would define one template for each type of sub-contract managed or referenced by the parent contract.

dataSources:
  - kind: ethereum/contract
    name: Factory
    # ... other source fields for the main contract ...
templates:
  - name: Exchange
    kind: ethereum/contract
    network: mainnet
    source:
      abi: Exchange
    mapping:
      kind: ethereum/events
      apiVersion: 0.0.6
      language: wasm/assemblyscript
      file: ./src/mappings/exchange.ts
      entities:
        - Exchange
      abis:
        - name: Exchange
          file: ./abis/exchange.json
      eventHandlers:
        - event: TokenPurchase(address,uint256,uint256)
          handler: handleTokenPurchase
        - event: EthPurchase(address,uint256,uint256)
          handler: handleEthPurchase
        - event: AddLiquidity(address,uint256,uint256)
          handler: handleAddLiquidity
        - event: RemoveLiquidity(address,uint256,uint256)
          handler: handleRemoveLiquidity

In the final step, you update your main contract mapping to create a dynamic data source instance from one of the templates. In this example, you would change the main contract mapping to import the Exchange template and call the Exchange.create(address) method on it to start indexing the new exchange contract.

import { Exchange } from '../generated/templates'

export function handleNewExchange(event: NewExchange): void {
  // Commence à indexer l'échange ; `event.params.exchange` est le
  // adresse du nouveau contrat d'échange
  Exchange.create(event.params.exchange)
}

Data source contexts allow passing extra configuration when instantiating a template. In our example, let's say exchanges are associated with a particular trading pair, which is included in the NewExchange event. That information can be passed into the instantiated data source, like so:

import { Exchange } from '../generated/templates'

export function handleNewExchange(event: NewExchange): void {
  let context = new DataSourceContext()
  context.setString('tradingPair', event.params.tradingPair)
  Exchange.createWithContext(event.params.exchange, context)
}

Inside a mapping of the Exchange template, the context can then be accessed:

import { dataSource } from '@graphprotocol/graph-ts'

let context = dataSource.context()
let tradingPair = context.getString('tradingPair')

There are setters and getters like setString and getString for all value types.

The startBlock is an optional setting that allows you to define from which block in the chain the data source will start indexing. Setting the start block allows the data source to skip potentially millions of blocks that are irrelevant. Typically, a subgraph developer will set startBlock to the block in which the smart contract of the data source was created.

dataSources:
  - kind: ethereum/contract
    name: ExampleSource
    network: mainnet
    source:
      address: '0xc0a47dFe034B400B47bDaD5FecDa2621de6c4d95'
      abi: ExampleContract
      startBlock: 6627917
    mapping:
      kind: ethereum/events
      apiVersion: 0.0.6
      language: wasm/assemblyscript
      file: ./src/mappings/factory.ts
      entities:
        - User
      abis:
        - name: ExampleContract
          file: ./abis/ExampleContract.json
      eventHandlers:
        - event: NewEvent(address,address)
          handler: handleNewEvent

The indexerHints setting in a subgraph's manifest provides directives for indexers on processing and managing a subgraph. It influences operational decisions across data handling, indexing strategies, and optimizations. Presently, it features the prune option for managing historical data retention or pruning.

indexerHints.prune: Defines the retention of historical block data for a subgraph. Options include:

1. "never": No pruning of historical data; retains the entire history.
2. "auto": Retains the minimum necessary history as set by the indexer, optimizing query performance.
3. Un nombre spécifique : Fixe une limite personnalisée au nombre de blocs historiques à conserver.

indexerHints:
  prune: auto

L'historique à partir d'un bloc donné est requis pour :

• Time travel queries, which enable querying the past states of these entities at specific blocks throughout the subgraph's history
• Using the subgraph as a graft base in another subgraph, at that block
• Rembobiner le subgraph jusqu'à ce bloc

Si les données historiques à partir du bloc ont été purgées, les capacités ci-dessus ne seront pas disponibles.

For subgraphs leveraging time travel queries, it's advisable to either set a specific number of blocks for historical data retention or use prune: never to keep all historical entity states. Below are examples of how to configure both options in your subgraph's settings:

Pour conserver une quantité spécifique de données historiques :

indexerHints:
  prune: 1000 # Replace 1000 with the desired number of blocks to retain

Préserver l'histoire complète des États de l'entité :

indexerHints:
  prune: never