---
title: Building Subgraphs on NEAR
---

This guide is an introduction to building Subgraphs indexing smart contracts on the [NEAR blockchain](https://docs.near.org/).

## What is NEAR?

[NEAR](https://near.org/) is a smart contract platform for building decentralized applications. Visit the [official documentation](https://docs.near.org/concepts/basics/protocol) for more information.

## What are NEAR Subgraphs?

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](https://github.com/graphprotocol/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:

- Block handlers: these are run on every new block
- Receipt handlers: run every time a message is executed at a specified account

[From the NEAR documentation](https://docs.near.org/build/data-infrastructure/lake-data-structures/receipt):

> A Receipt is the only actionable object in the system. When we talk about "processing a transaction" on the NEAR platform, this eventually means "applying receipts" at some point.

## Building a NEAR Subgraph

`@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`.

> Building a NEAR Subgraph is very similar to building a Subgraph that indexes Ethereum.

There are three aspects of Subgraph 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](/developing/creating-a-subgraph/#the-graphql-schema).

**AssemblyScript Mappings:** [AssemblyScript code](/subgraphs/developing/creating/graph-ts/api/) 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.

During Subgraph development there are two key commands:

```bash
$ 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
```

### Subgraph Manifest Definition

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:

```yaml
specVersion: 1.3.0
schema:
  file: ./src/schema.graphql # link to the schema file
dataSources:
  - 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.9
      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](https://docs.near.org/concepts/protocol/account-model). 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.

```yaml
accounts:
  prefixes:
    - app
    - good
  suffixes:
    - morning.near
    - morning.testnet
```

NEAR data sources support two types of handlers:

- `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](https://docs.near.org/tutorials/crosswords/basics/add-functions-call#create-a-subaccount) 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](/developing/creating-a-subgraph/#the-graphql-schema).

### AssemblyScript Mappings

The handlers for processing events are written in [AssemblyScript](https://www.assemblyscript.org/).

NEAR indexing introduces NEAR-specific data types to the [AssemblyScript API](/subgraphs/developing/creating/graph-ts/api/).

```typescript

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](/subgraphs/developing/creating/graph-ts/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](/subgraphs/developing/creating/graph-ts/api/#json-api) to allow developers to easily process these logs.

## Deploying a NEAR Subgraph

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](/deploying/deploying-a-subgraph-to-studio/).

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](https://thegraph.com/studio/): "Create a Subgraph".

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

```sh
$ 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://ipfs.thegraph.com <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
```

The node configuration will depend on where the Subgraph is being deployed.

### Subgraph Studio

```sh
graph auth
graph deploy <subgraph-name>
```

### Local Graph Node (based on default configuration)

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

Once your Subgraph has been deployed, it will be indexed by Graph Node. You can check its progress by querying the Subgraph itself:

```graphql
{
  _meta {
    block {
      number
    }
  }
}
```

### Indexing NEAR with a Local Graph Node

Running a Graph Node that indexes NEAR has the following operational requirements:

- NEAR Indexer Framework with Firehose instrumentation
- NEAR Firehose Component(s)
- Graph Node with Firehose endpoint configured

We will provide more information on running the above components soon.

## Querying a NEAR Subgraph

The GraphQL endpoint for NEAR Subgraphs is determined by the schema definition, with the existing API interface. Please visit the [GraphQL API documentation](/subgraphs/querying/graphql-api/) for more information.

## Example Subgraphs

Here are some example Subgraphs for reference:

[NEAR Blocks](https://github.com/graphprotocol/graph-tooling/tree/main/examples/near-blocks)

[NEAR Receipts](https://github.com/graphprotocol/graph-tooling/tree/main/examples/near-receipts)

## FAQ

### How does the beta work?

NEAR support is in beta, which means that there may be changes to the API.

### Can a Subgraph index both NEAR and EVM chains?

No, a Subgraph can only support data sources from one chain/network.

### Can Subgraphs react to more specific triggers?

Currently, only Block and Receipt triggers are supported. We are investigating triggers for function calls to a specified account. We are also interested in supporting event triggers, once NEAR has native event support.

### Will receipt handlers trigger for accounts and their sub-accounts?

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:

```yaml
accounts:
  suffixes:
    - mintbase1.near
```

### Can NEAR Subgraphs make view calls to NEAR accounts during mappings?

This is not supported. We are evaluating whether this functionality is required for indexing.

### Can I use data source templates in my NEAR Subgraph?

This is not currently supported. We are evaluating whether this functionality is required for indexing.

### Ethereum Subgraphs support "pending" and "current" versions, how can I deploy a "pending" version of a NEAR Subgraph?

Pending functionality is not yet supported for NEAR Subgraphs. In the interim, you can deploy a new version to a different "named" Subgraph, and then when that is synced with the chain head, you can redeploy to your primary "named" Subgraph, which will use the same underlying deployment ID, so the main Subgraph will be instantly synced.

### My question hasn't been answered, where can I get more help building NEAR Subgraphs?

If it is a general question about Subgraph development, there is a lot more information in the rest of the [Developer documentation](/subgraphs/quick-start/). Otherwise please join [The Graph Protocol Discord](https://discord.gg/graphprotocol) and ask in the #near channel or email near@thegraph.com.

## References

- [NEAR developer documentation](https://docs.near.org/tutorials/crosswords/basics/set-up-skeleton)
