Building Subgraphs on NEAR Protocol

This guide explores how to construct subgraphs for indexing smart contracts on the NEAR blockchain, leveraging The Graph's decentralized indexing protocol.

What is a NEAR Subgraph?

The Graph provides developers with subgraphs—tools to process blockchain events and deliver queryable data via GraphQL APIs. With Graph Node now supporting NEAR events, developers can build subgraphs to index NEAR smart contracts.

NEAR subgraphs are event-driven, listening to and processing on-chain activities. Currently, two handler types are supported:

• Block Handlers: Execute with each new block.
• Receipt Handlers: Triggered when a message is executed on a specified account.

👉 Learn how NEAR receipts work

Developing a NEAR Subgraph

Prerequisites

• @graphprotocol/graph-cli (v0.23.0+)
• @graphprotocol/graph-ts (v0.23.0+)

NEAR subgraph development mirrors Ethereum subgraph creation but introduces NEAR-specific data types and JSON parsing enhancements.

Key Components

1. Subgraph Manifest (subgraph.yaml):
   Defines data sources and their handlers. Example:

   specVersion: 1.3.0
   dataSources:
     - kind: near
       network: near-mainnet
       source:
         account: app.good-morning.near
       mapping:
         blockHandlers:
           - handler: handleNewBlock
         receiptHandlers:
           - handler: handleReceipt

2. Schema (schema.graphql):
   Outlines the data structure for GraphQL queries. Follows existing schema guidelines.
3. AssemblyScript Mappings:
   Converts raw data into schema-defined entities using NEAR-specific types like BlockHeader and ReceiptWithOutcome.

Development Commands

graph codegen  # Generates types from schema
graph build    # Compiles mappings into WASM

Deploying NEAR Subgraphs

Deploy to Graph nodes (v0.26.x+) supporting NEAR networks:

• Mainnet: near-mainnet
• Testnet: near-testnet

Deployment Steps

1. Subgraph Studio:

   graph auth
   graph deploy --studio <subgraph-name>

2. Local Node:

   graph deploy --node http://localhost:8020/ --ipfs http://localhost:5001

Monitor indexing progress via:

query { _meta { block { number } } }

Querying NEAR Subgraphs

Use standard GraphQL queries as outlined in the GraphQL API docs.

Example Subgraphs

• NEAR Blocks
• NEAR Receipts

👉 Explore NEAR subgraph examples

Frequently Asked Questions

Can a subgraph index both NEAR and EVM chains?

No—subgraphs are chain-specific.

How do handlers trigger for sub-accounts?

Exact account matching is required. Use prefixes/suffixes in accounts to match sub-accounts:

accounts:
  suffixes:
    - mintbase1.near

Are view calls to NEAR accounts supported?

Not currently. This feature is under evaluation.

Where can I get help?

Join The Graph’s Discord (#near channel) or email [email protected].

References

• NEAR Developer Docs