5 Simple Steps to Build a Subgraph

In the world of Web3, subgraphs are game-changers. They enable developers to access blockchain data, powering their dapps The Graph Network. Whether you're building your first subgraph or looking to streamline your indexing process, this guide will walk you through everything you need to know.

In just 5 simple steps, you’ll learn how to create, deploy, and publish a subgraph to start querying blockchain data like a pro. No matter your experience level, this tutorial will help you harness the power of The Graph to unlock new possibilities in decentralized development. Let’s get started!

Prerequisites

• A crypto wallet
• A smart contract address on a supported network
• Node.js installed
• A package manager of your choice (npm, yarn or pnpm)

How to Build a Subgraph

1. Create a subgraph in Subgraph Studio

Go to Subgraph Studio and connect your wallet.

Subgraph Studio lets you create, manage, deploy, and publish subgraphs, as well as create and manage API keys.

Click "Create a Subgraph". It is recommended to name the subgraph in Title Case: "Subgraph Name Chain Name".

2. Install the Graph CLI

On your local machine, run one of the following commands:

Using npm:

npm install -g @graphprotocol/graph-cli@latest

Using yarn:

yarn global add @graphprotocol/graph-cli

3. Initialize your subgraph

You can find commands for your specific subgraph on the subgraph page in Subgraph Studio.

The graph init command will automatically create a scaffold of a subgraph based on your contract's events.

The following command initializes your subgraph from an existing contract:

graph init

If your contract was verified on Etherscan, then the ABI will automatically be created in the CLI.

When you initialize your subgraph, the CLI will ask you for the following information:

• Protocol: Choose the protocol your subgraph will be indexing data from.
• Subgraph slug: Create a name for your subgraph. Your subgraph slug is an identifier for your subgraph.
• Directory: Choose a directory to create your subgraph in.
• Ethereum network (optional): You may need to specify which EVM-compatible network your subgraph will be indexing data from.
• Contract address: Locate the smart contract address you’d like to query data from.
• ABI: If the ABI is not auto-populated, you will need to input it manually as a JSON file.
• Start Block: You should input the start block to optimize subgraph indexing of blockchain data. Locate the start block by finding the block where your contract was deployed.
• Contract Name: Input the name of your contract.
• Index contract events as entities: It is suggested that you set this to true, as it will automatically add mappings to your subgraph for every emitted event.
• Add another contract (optional): You can add another contract.

See the following screenshot for an example for what to expect when initializing your subgraph:

4. Edit your subgraph

The init command in the previous step creates a scaffold subgraph that you can use as a starting point to build your subgraph.

When making changes to the subgraph, you will mainly work with three files:

• Manifest (subgraph.yaml) - defines what data sources your subgraph will index.
• Schema (schema.graphql) - defines what data you wish to retrieve from the subgraph.
• AssemblyScript Mappings (mapping.ts) - translates data from your data sources to the entities defined in the schema.

For a detailed breakdown on how to write your subgraph, check out Creating a Subgraph.

5. Deploy your subgraph

Remember, deploying is not the same as publishing.

When you deploy a subgraph, you push it to Subgraph Studio, where you can test, stage and review it.

When you publish a subgraph, you are publishing it onchain to the decentralized network.

Once your subgraph is written, run the following commands:

```sh
graph codegen && graph build
```

Authenticate and deploy your subgraph. The deploy key can be found on the subgraph's page in Subgraph Studio.

```sh

graph auth <DEPLOY_KEY>

graph deploy <SUBGRAPH_SLUG>
```

The CLI will ask for a version label. It's strongly recommended to use semantic versioning, e.g. 0.0.1.

6. Review your subgraph

If you’d like to test your subgraph before publishing it, you can use Subgraph Studio to do the following:

• Run a sample query.
• Analyze your subgraph in the dashboard to check information.
• Check the logs on the dashboard to see if there are any errors with your subgraph. The logs of an operational subgraph will look like this:

7. Publish your subgraph to The Graph Network

Publishing a subgraph to the decentralized network is an onchain action that makes your subgraph available for Curators to curate it and Indexers to index it.

Publishing with Subgraph Studio

To publish your subgraph, click the Publish button in the dashboard.

Select the network to which you would like to publish your subgraph.

Publishing from the CLI

As of version 0.73.0, you can also publish your subgraph with the Graph CLI.

Open the graph-cli.

Use the following commands:

```sh
graph codegen && graph build
```

Then,

```sh
graph publish
  ```

A window will open, allowing you to connect your wallet, add metadata, and deploy your finalized subgraph to a network of your choice.

To customize your deployment, see Publishing a Subgraph.

Adding signal to your subgraph

1. To attract Indexers to query your subgraph, you should add GRT curation signal to it.
   • This action improves quality of service, reduces latency, and enhances network redundancy and availability for your subgraph.
2. If eligible for indexing rewards, Indexers receive GRT rewards based on the signaled amount.
   • It’s recommended to curate at least 3,000 GRT to attract 3 Indexers. Check reward eligibility based on subgraph feature usage and supported networks.

To learn more about curation, read Curating.

To save on gas costs, you can curate your subgraph in the same transaction you publish it by selecting this option:

8. Query your subgraph

You now have access to 100,000 free queries per month with your subgraph on The Graph Network!

You can query your subgraph by sending GraphQL queries to its Query URL, which you can find by clicking the Query button.

For more information about querying data from your subgraph, read Querying The Graph.

Final Thoughts

Congratulations! You’ve just learned how to create, deploy, and publish a subgraph in five simple steps. With The Graph, you can now unlock blockchain data to power your dapp and take your Web3 development to the next level.

The future of Web3 starts with what you build today!

About The Graph

The Graph is the source of data and information for the decentralized internet. As the original decentralized data marketplace that introduced and standardized subgraphs, The Graph has become web3’s method of indexing and accessing blockchain data. Since its launch in 2018, tens of thousands of developers have built subgraphs for dapps across 80+ blockchains - including  Ethereum, Solana, Arbitrum, Optimism, Base, Polygon, Celo, Fantom, Gnosis, and Avalanche.

As demand for data in web3 continues to grow, The Graph enters a New Era with a more expansive vision including new data services and query languages, ensuring the decentralized protocol can serve any use case - now and into the future.

Discover more about how The Graph is shaping the future of decentralized physical infrastructure networks (DePIN) and stay connected with the community. Follow The Graph on X, LinkedIn, Instagram, Facebook, Reddit, Farcaster and Medium. Join the community on The Graph’s Telegram, join technical discussions on The Graph’s Discord.

The Graph Foundation oversees The Graph Network. The Graph Foundation is overseen by the Technical Council. Edge & Node, StreamingFast, Semiotic Labs, Messari, GraphOps, Pinax and Geo are eight of the many organizations within The Graph ecosystem.