🚀Deploy a subgraph using the Graph CLI

This document provides a quick start guide for deploying a subgraph using the Command Line Interface (CLI).

This quick start guide outlines streamlined instructions for deploying subgraphs using the Command Line Interface (CLI). Developers looking to swiftly incorporate subgraph capabilities into their projects will find straightforward guidance and pro tips for getting set up fast.

Summary: The Graph CLI is an essential tool enabling developers to seamlessly create, deploy, and manage subgraphs - providing streamlined blockchain data querying and indexing.

Deployment Network definitions

For developers who are already familiar with Graph Protocol tooling, below are the network definitions to deploy subgraphs on Mantle. These settings can be configured in the subgraph.yaml file: For Mantle Mainnet:

network: 'mantle'

For Mantle Goerli Testnet:

network: 'mantle-testnet'

For Mantle Sepolia Testnet:

network: 'mantle-sepolia'

Get started by install the Graph cli

npm i @graphprotocol/graph-cli

Authentication with API key

Log in with the API key created earlier, and enter the API key when prompted:

graph auth https://subgraph-api.mantle.xyz/deploy

Enter your deploy key when promoted

What is the deploy key?: *************************
Deploy key set for http://subgraph-api.mantle.xyz/deploy/

You can sign up for a deployment API key by visiting https://subgraph.mantle.xyz/dashboard/api

Create your own subgraph

Details regarding creating your own subgraph is beyond the scope of this documentation, the Graph's official documentation provides detailed guides and examples for each step of the subgraph creation process. It also covers advanced topics such as indexing strategies, filtering, and pagination. We recommend referring to their documentation for a comprehensive reference on subgraph development with The Graph. A typical subgraph project have the following components:

  • The manifest file. The subgraph.yaml at the root defines all the major parameters of a subgraph project. It contains a list of all the smart contracts being indexed, as well as a list of entities and their corresponding handler functions. We will be adding more properties like startBlock and description to the YAML file in the tutorial. You can read about all the specifications in detail in the Graph docs.

  • The schema file. At its core, a subgraph is a GraphQL API that indexes data from the blockchain.

    The schema.graphql file at the root of our project contains all our entities. These entities define what data our subgraph indexes.

    Here is what an entity could look like:

  • The mappings file. A mappings file contains functions that take the data from a blockchain, and convert it into manageable data along the lines of our GraphQL entities. It is written in AssemblyScript, which is a TypeScript-like language with a stricter syntax.

    This file contains the logic that dictates how data should be retrieved and stored when someone interacts with the smart contracts we intend to index.

Messari maintains a well-curated GitHub repository that offers a comprehensive collection of example subgraphs, which serves as a valuable resource for those seeking to start their subgraph development journey.

https://github.com/messari/subgraphs

Subgraph compilation

1. Generate types and mappings for your subgraph

The codegen step generate the necessary code files that will handle indexing and querying data according to your schema and mappings.

Running the following command in your subgraph project root will create types and mappings for your subgraph.

graph codegen

Success output:

  Skip migration: Bump mapping apiVersion from 0.0.1 to 0.0.2
  Skip migration: Bump mapping apiVersion from 0.0.2 to 0.0.3
  Skip migration: Bump mapping apiVersion from 0.0.3 to 0.0.4
  ...
✔ Load data source template ABIs
✔ Generate types for data source template ABIs
✔ Load GraphQL schema from schema.graphql
  Write types to generated/schema.ts
✔ Generate types for GraphQL schema

Types generated successfully

You may also pass in parameter for graph codegen command, for detail please use --help argument: 

$ graph codegen --help


Generates AssemblyScript types for a subgraph.

USAGE
  $ graph codegen [SUBGRAPH-MANIFEST] [-h] [-o <value>] [--skip-migrations] [-w] [--uncrashable-config
    <value> -u]

FLAGS
  -h, --help                    Show CLI help.
  -o, --output-dir=<value>      [default: generated/] Output directory for generated types.
  -u, --uncrashable             Generate Float Subgraph Uncrashable helper file.
  -w, --watch                   Regenerate types when subgraph files change.
  --skip-migrations             Skip subgraph migrations.
  --uncrashable-config=<value>  Directory for uncrashable config.

DESCRIPTION
  Generates AssemblyScript types for a subgraph.

2. Build your subgraph

After generating your subgraph types and mappings, you may proceed by executing the subsequent command to build your subgraph:

graph build

Success output:

  Skip migration: Bump mapping apiVersion from 0.0.1 to 0.0.2
  ...
✔ Apply migrations
✔ Load subgraph from subgraph.yaml
  Compile data source: ERC20Approve => build/ERC20Approve/ERC20Approve.wasm
  Compile data source: ERC721Approve => build/ERC721Approve/ERC721Approve.wasm
✔ Compile subgraph
  Copy schema file build/schema.graphql
  Write subgraph file build/ERC20Approve/abis/ERC20.json
  Write subgraph file build/ERC721Approve/abis/ERC721.json
  Write subgraph manifest build/subgraph.yaml
✔ Write compiled subgraph to build/

Build completed: build/subgraph.yaml

You may also pass in parameter for graph build command, for detail please use --help argument:

$ graph build --help

Builds a subgraph and (optionally) uploads it to IPFS.

USAGE
  $ graph build [SUBGRAPH-MANIFEST] [-h] [-i <value>] [-o <value>] [-t wasm|wast] [--skip-migrations] [-w]
    [--network <value>] [--network-file <value>]

FLAGS
  -h, --help                    Show CLI help.
  -i, --ipfs=<value>            Upload build results to an IPFS node.
  -o, --output-dir=<value>      [default: build/] Output directory for build results.
  -t, --output-format=<option>  [default: wasm] Output format for mappings.
                                <options: wasm|wast>
  -w, --watch                   Regenerate types when subgraph files change.
  --network=<value>             Network configuration to use from the networks config file.
  --network-file=<value>        [default: networks.json] Networks config file path.
  --skip-migrations             Skip subgraph migrations.

DESCRIPTION
  Builds a subgraph and (optionally) uploads it to IPFS.

Subgraph deployment

1. Create/register your subgraph name

Before you deploy the subgraph to Mantle Subgraph Service, you need to pick a unique name for the subgraph in order to create/register the subgraph in the system by running the command below, and prompts

graph create <my-subgraph-name> --node https://subgraph-api.mantle.xyz/deploy

Success output:

Created subgraph: <my-subgraph-name>

2. Deploy your subgraph 🚀

After creating/registering your subgraph name in the hosted service, you can run the following command to deploy the subgraph to the Mantle Subgraph Service:

graph deploy <my-subgraph-name> --node https://subgraph-api.mantle.xyz/deploy  --ipfs https://subgraph-api.mantle.xyz/ipfs

The command line will give you a list of prompts regarding subgraph name and version. Note: for the subgraph name, it must match the subgraph name you registered in the above step, i.e. <my-subgraph-name>

What is the subgraph name?: <my-subgraph-name>
Which version label to use? (e.g. "v0.0.1"): v0.0.1

Success output:

What is the subgraph name?: <my-subgraph-name>
Which version label to use? (e.g. "v0.0.1"): v0.0.1
  Skip migration: Bump mapping apiVersion from 0.0.1 to 0.0.2
  Skip migration: Bump mapping apiVersion from 0.0.2 to 0.0.3
...
  Add file to IPFS build/ERC721Approve/ERC721Approve.wasm
                .. Qmb9tMfmSqPAqfNe168ynSzk4FAjKtoSXhSov7B5kF1cX5
✔ Upload subgraph to IPFS

Build completed: QmXwohSk6cXszjzo2JFbMPf24JeXyxcGTvPfRAqGsECZte

Deployed to https://subgraph-api.mantle.xyz/subgraphs/name/<my-subgraph-name>/graphql

Subgraph endpoints:
Queries (HTTP):     https://subgraph-api.mantle.xyz/subgraphs/name/<my-subgraph-name>

You may also pass in parameter for graph create command, for detail please use --help argument:

$ graph deploy--help

Deploys a subgraph to a Graph node.

USAGE
  $ graph deploy [SUBGRAPH-NAME] [SUBGRAPH-MANIFEST] [-h] [-g <value>] [-l <value>] [-i <value>] [--ipfs-hash <value>] [--headers <value>] [--debug-fork <value>] [-o
    <value>] [--skip-migrations] [-w] [--network <value>] [--network-file <value>]

FLAGS
  -g, --node=<value>           Graph node for which to initialize.
  -h, --help                   Show CLI help.
  -i, --ipfs=<value>           [default: http://api.0xgraph.xyz/ipfs] Upload build results to an IPFS node.
  -l, --version-label=<value>  Version label used for the deployment.
  -o, --output-dir=<value>     [default: build/] Output directory for build results.
  -w, --watch                  Regenerate types when subgraph files change.
  --debug-fork=<value>         ID of a remote subgraph whose store will be GraphQL queried.
  --deploy-key=<value>         User deploy key.
  --headers=<value>            [default: [object Object]] Add custom headers that will be used by the IPFS HTTP client.
  --ipfs-hash=<value>          IPFS hash of the subgraph manifest to deploy.
  --network=<value>            Network configuration to use from the networks config file.
  --network-file=<value>       [default: networks.json] Networks config file path.
  --skip-migrations            Skip subgraph migrations.

DESCRIPTION
  Deploys a subgraph to a Graph node.

View your deployed subgraphs

Web UI

Your deployed subgraphs can be accessed and viewed through the web-based UI.

CLI

Your deployed subgraphs can also be accessed via the following command.

Delete your deployed subgraphs

To remove/delete your deployed subgraph, you may use the following command with your subgraph name.

graph remove <my-subgraph-name> --node https://subgraph-api.mantle.xyz/deploy

Success output:

Removed subgraph: <my-subgraph-name>

You may also pass in parameter for graph remove command, for detail please use --help argument:

Unregisters a subgraph name

USAGE
  $ graph remove SUBGRAPH-NAME [-h] [-g <value>]

FLAGS
  -g, --node=<value>      Graph node to delete the subgraph from.
  -h, --help              Show CLI help.

DESCRIPTION
  Unregisters a subgraph name

Last updated