🚀

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
npm: @0xgraph/cli
npm
Install the 0xgraph npm package

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.

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.
Deployed subgraphs

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 modified 3mo ago