The Graph
Text

The Subgraph Manifest

Lesson 7

If you recall,  there are three aspects of subgraph definition:

  1. subgraph.yaml - the subgraph manifest.  It defines the data sources of interest and how they should be processed.  NEAR is a new kind of data source.
  2. schema.graphql - a schema file that defines what data is stored for your subgraph, and how to query it via GraphQL. 
  3. AssemblyScript mapping.ts - AS code that translates from the log data to the entities defined in our schema.  For NEAR, there are NEAR-specific data types and JSON parsing functionality.

This lesson is focused on the subgraph.yaml file which is your subgraph manifest.  Open it up in your editor.

subgraph.yaml

The subgraph manifest (subgraph.yaml) identifies:

  • the data sources for the subgraph;
  • the triggers of interest; and
  • the functions that should be run in response to those triggers.

Your subgraph.yaml should look like the following if you're using the template:

specVersion: 0.0.4
description: DID registry # the name of the subgraph
repository: https://github.com/VitalPointAI/near-subgraph-template.git # repo where subgraph project is stored
schema:
     file: ./schema.graphql
dataSources:
     - kind: near
       name: receipts # could also be blocks
       network: near-mainnet # either near-mainnet or near-testnet
       source:
            account: did.near # contract account you want to pull data from
            startBlock: 54167320 # starting block on near-mainnet for indexing
       mapping:
            apiVersion: 0.0.5
            language: wasm/assemblyscript
            file: ./src/mapping.ts 
            entities:
                 - Account # the example entity in the schema.graphql file
                 - Log # example log entity in the schema.graphql file
            receiptHandlers:
                 - handler: handleReceipt # name of the receipt handler

We've included comments and generally speaking you'll simply tweak this file to suit your situation.  Things you'll typically change:

  • description - change to reflect the name of your subgraph.
  • repository - change to reflect where you are storing your subgraph (it's repo).
  • kind - will stay as near if you are building a near subgraph.
  • network - enter either near-mainnet or near-testnet.
  • account - this you will change to the contract account you want to listen to/index.
  • startBlock - change to reflect block where you want indexing to start
  • entities - in this section, you'll list the entities you define for your subgraph (we'll cover them in the next lesson)
  • receiptHandlers - name of the receipt handler which is a function you'll define in your mapping.ts file

Quick Notes

startBlock

Is required for NEAR.  It tells the Hosted Service to start indexing from that block. Considering that NEAR produces a new block every second or so, not specifying a start block or starting it long before your contract even gets deployed means it will take a really, really, really long time to index.


receiptHandlers

NEAR datasources currently support two types of handlers:

  • blockHandlers: run on every new NEAR block. This handler will get you data about a block - good for informational things like block explorers.
  • receiptHandlers: run on every receipt where the data source's source account is the recipient. In the template, that is did.near. It has to be an exact match - so subaccounts have to be added as additional data sources.

receiptHandlers that give you the outcome logs seem to be the most effective way to get specific data off the NEAR chain.

Action Steps

Modify your subgraph.yaml file in following ways:

1. Change startBlock to 54395933

2. Remove the comments

Next Steps

That's all there really is to modifying the subgraph.yaml manifest file.  Pretty straight forward, but again, the manifest is like your central coordinator.  It defines what entities are being used, where to find certain files, the types of things to listen for (receipts) and how/what contract and network to connect to.

Next up, we'll learn about entities which are basically the objects you populate with data (models in a MVC sense).

Maybe you'd rather have us build your NEAR subgraph for you?

Not a problem and it can be pretty quick and inexpensive depending on the complexity of your contract.  Get in touch using one of the methods below.

Pen
>