Docs

8 minutes

Bygger subgrafer på NEAR

This guide is an introduction to building subgraphs indexing smart contracts on the NEAR blockchain⁠.

Vad är NEAR?

NEAR⁠ is a smart contract platform for building decentralized applications. Visit the official documentation⁠ for more information.

Vad är NEAR subgrafer?

The Graph gives developers tools to process blockchain events and make the resulting data easily available via a GraphQL API, known individually as a subgraph. Graph Node⁠ is now able to process NEAR events, which means that NEAR developers can now build subgraphs to index their smart contracts.

Subgraphs are event-based, which means that they listen for and then process onchain events. There are currently two types of handlers supported for NEAR subgraphs:

  • Blockhanterare: dessa körs på varje nytt block
  • Kvittohanterare: körs varje gång ett meddelande körs på ett angivet konto

From the NEAR documentation⁠:

Ett kvitto är det enda handlingsbara objektet i systemet. När vi pratar om att “bearbeta en transaktion” på NEAR plattformen betyder det så småningom att “tillämpa kvitton” någon gång.

Att bygga en NEAR Subgraf

@graphprotocol/graph-cli is a command-line tool for building and deploying subgraphs.

@graphprotocol/graph-ts is a library of subgraph-specific types.

NEAR subgraph development requires graph-cli above version 0.23.0, and graph-ts above version 0.23.0.

Att bygga en NEAR subgraf är mycket lik att bygga en subgraf som indexerar Ethereum.

Det finns tre aspekter av subgraf definition:

subgraph.yaml: the subgraph manifest, defining the data sources of interest, and how they should be processed. NEAR is a new kind of data source.

schema.graphql: a schema file that defines what data is stored for your subgraph, and how to query it via GraphQL. The requirements for NEAR subgraphs are covered by the existing documentation.

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.

Under subgrafutveckling finns det två nyckelkommandon:

$ graph codegen # generates types from the schema file identified in the manifest$ graph build # generates Web Assembly from the AssemblyScript files, and prepares all the subgraph files in a /build folder

Definition av subgraf manifestet

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. See below for an example subgraph manifest for a NEAR subgraph:

specVersion: 0.0.2schema:  file: ./src/schema.graphql # link to the schema filedataSources:  - kind: near    network: near-mainnet    source:      account: app.good-morning.near # This data source will monitor this account      startBlock: 10662188 # Required for NEAR    mapping:      apiVersion: 0.0.5      language: wasm/assemblyscript      blockHandlers:        - handler: handleNewBlock # the function name in the mapping file      receiptHandlers:        - handler: handleReceipt # the function name in the mapping file      file: ./src/mapping.ts # link to the file with the Assemblyscript mappings
  • NEAR subgraphs introduce a new kind of data source (near)
  • The network should correspond to a network on the hosting Graph Node. On Subgraph Studio, NEAR’s mainnet is near-mainnet, and NEAR’s testnet is near-testnet
  • NEAR data sources introduce an optional source.account field, 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.accounts field, 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.
accounts:  prefixes:    - app    - good  suffixes:    - morning.near    - morning.testnet

NEAR datakällor stöder två typer av hanterare:

  • blockHandlers: run on every new NEAR block. No source.account is required.
  • receiptHandlers: run on every receipt where the data source’s source.account is the recipient. Note that only exact matches are processed (subaccounts⁠ must be added as independent data sources).

Schema Definition

Schema definition describes the structure of the resulting subgraph database and the relationships between entities. This is agnostic of the original data source. There are more details on subgraph schema definition here.

AssemblyScript mappningar

The handlers for processing events are written in AssemblyScript⁠.

NEAR indexing introduces NEAR-specific data types to the AssemblyScript API.

class ExecutionOutcome {      gasBurnt: u64,      blockHash: Bytes,      id: Bytes,      logs: Array<string>,      receiptIds: Array<Bytes>,      tokensBurnt: BigInt,      executorId: string,  }class ActionReceipt {      predecessorId: string,      receiverId: string,      id: CryptoHash,      signerId: string,      gasPrice: BigInt,      outputDataReceivers: Array<DataReceiver>,      inputDataIds: Array<CryptoHash>,      actions: Array<ActionValue>,  }class BlockHeader {      height: u64,      prevHeight: u64,// Always zero when version < V3      epochId: Bytes,      nextEpochId: Bytes,      chunksIncluded: u64,      hash: Bytes,      prevHash: Bytes,      timestampNanosec: u64,      randomValue: Bytes,      gasPrice: BigInt,      totalSupply: BigInt,      latestProtocolVersion: u32,  }class ChunkHeader {      gasUsed: u64,      gasLimit: u64,      shardId: u64,      chunkHash: Bytes,      prevBlockHash: Bytes,      balanceBurnt: BigInt,  }class Block {      author: string,      header: BlockHeader,      chunks: Array<ChunkHeader>,  }class ReceiptWithOutcome {      outcome: ExecutionOutcome,      receipt: ActionReceipt,      block: Block,  }

These types are passed to block & receipt handlers:

  • Block handlers will receive a Block
  • Receipt handlers will receive a ReceiptWithOutcome

Otherwise, the rest of the AssemblyScript API is available to NEAR subgraph developers during mapping execution.

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.

Utplacera en NEAR Subgraf

Once you have a built subgraph, it is time to deploy it to Graph Node for indexing. NEAR subgraphs can be deployed to any Graph Node >=v0.26.x (this version has not yet been tagged & released).

Subgraph Studio and the upgrade Indexer on The Graph Network currently supports indexing NEAR mainnet and testnet in beta, with the following network names:

  • near-mainnet
  • near-testnet

More information on creating and deploying subgraphs on Subgraph Studio can be found here.

As a quick primer - the first step is to “create” your subgraph - this only needs to be done once. On Subgraph Studio, this can be done from your Dashboard: “Create a subgraph”.

Once your subgraph has been created, you can deploy your subgraph by using the graph deploy CLI command:

$ graph create --node <graph-node-url> <subgraph-name> # creates a subgraph on a local Graph Node (on Subgraph Studio, this is done via the UI)$ graph deploy --node <graph-node-url> --ipfs https://api.thegraph.com/ipfs/ <subgraph-name> # uploads the build files to a specified IPFS endpoint, and then deploys the subgraph to a specified Graph Node based on the manifest IPFS hash

Nodkonfigurationen beror på var subgrafen distribueras.

Subgraf Studion

graph authgraph deploy <subgraph-name>

Lokal graf nod (baserat på standardkonfiguration)

graph deploy --node http://localhost:8020/ --ipfs http://localhost:5001 <subgraph-name>

När din subgraf har distribuerats kommer den att indexeras av Graph Node. Du kan kontrollera dess framsteg genom att fråga själva subgrafen:

{  _meta {    block {      number    }  }}

Indexering av NEAR med en lokal grafnod

Att köra en Graph Node som indexerar NEAR har följande operativa krav:

  • NEAR Indexer Framework med Firehose-instrumentering
  • NEAR Brandslangskomponent(er)
  • Graf Nod med Firehose ändpunkt konfigurerad

Vi kommer snart att ge mer information om hur du kör ovanstående komponenter.

Fråga efter en NEAR subgraf

The GraphQL endpoint for NEAR subgraphs is determined by the schema definition, with the existing API interface. Please visit the GraphQL API documentation for more information.

Exempel på subgrafer

Here are some example subgraphs for reference:

NEAR Blocks⁠

NEAR Receipts⁠

FAQ

Hur fungerar betan?

NEAR stödet är i beta, vilket innebär att det kan bli ändringar i API:t när vi fortsätter att arbeta med att förbättra integrationen. Skicka ett e-postmeddelande till near@thegraph.com⁠ så att vi kan hjälpa dig att bygga NEAR subgrafer och hålla dig uppdaterad om den senaste utvecklingen!

Kan en subgraf indexera både NEAR och EVM kedjor?

Nej, en subgraf kan bara stödja datakällor från en kedja/nätverk.

Kan subgrafer reagera på mer specifika triggers?

För närvarande stöds endast blockerings- och kvittoutlösare. Vi undersöker utlösare för funktionsanrop till ett specificerat konto. Vi är också intresserade av att stödja eventutlösare, när NEAR har inbyggt eventsupport.

Kommer kvittohanterare att utlösa för konton och deras underkonton?

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:

accounts:  suffixes:    - mintbase1.near

Kan NEAR subgrafer göra visningsanrop till NEAR konton under mappningar?

Detta stöds inte. Vi utvärderar om denna funktionalitet krävs för indexering.

Kan jag använda data källmallar i min NEAR subgraf?

Detta stöds inte för närvarande. Vi utvärderar om denna funktionalitet krävs för indexering.

Ethereum subgrafer stöder “väntande” och “nuvarande” versioner, hur kan jag distribuera en “väntande” version av en NEAR subgraf?

Väntande funktionalitet stöds ännu inte för NEAR subgrafer. Under tiden kan du distribuera en ny version till en annan “namngiven” subgraf, och när den sedan synkroniseras med kedjehuvudet kan du distribuera om till din primära “namngivna” subgraf, som kommer att använda samma underliggande implementerings-ID, så huvudsubgrafen synkroniseras omedelbart.

Min fråga har inte besvarats, var kan jag få mer hjälp med att bygga NEAR subgrafer?

If it is a general question about subgraph development, there is a lot more information in the rest of the Developer documentation. Otherwise please join The Graph Protocol Discord⁠ and ask in the #near channel or email near@thegraph.com⁠.

Referenser

⁠Edit on GitHub⁠