🚀Deploy a subgraph using the 0xgraph CLI

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

Summary: The 0xgraph CLI is an essential tool enabling developers to seamlessly create, deploy, and manage subgraphs - providing streamlined blockchain data querying and indexing. It gives you the superuser access to our enterprise-grade subgraph infrastructure.

Deployment Network definitions

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

Get started by install the 0xgraph cli

npm i @xgraph/cli

Authentication with API key

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

0xgraph auth

Enter your deploy key when promoted

What is the deploy key?: *************************
Deploy key set for http://api.0xgraph.xyz/deploy/

You can sign up for a deployment API key by visiting https://app.0xgraph.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.

0xgraph 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 0xgraph codegen command, for detail please use --help argument: 

$ 0xgraph codegen --help


Generates AssemblyScript types for a subgraph.

USAGE
  $ 0xgraph 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:

0xgraph 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 0xgraph build command, for detail please use --help argument:

$ 0xgraph build --help

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

USAGE
  $ 0xgraph 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 0xgraph's hosted 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

0xgraph create <my-subgraph-name>

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 0xgraph hosted service:

0xgraph deploy

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 http://api.0xgraph.xyz/subgraphs/name/<my-subgraph-name>/graphql

Subgraph endpoints:
Queries (HTTP):     http://api.0xgraph.xyz:8000/subgraphs/name/<my-subgraph-name>

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

$ 0xgraph create --help

Deploys a subgraph to a Graph node.

USAGE
  $ 0xgraph 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.

Delete your deployed subgraphs

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

0xgraph remove <my-subgraph-name>

Success output:

Removed subgraph: <my-subgraph-name>

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

Unregisters a subgraph name

USAGE
  $ 0xgraph 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