How to Build a Subgraph on Linea
The emergence of the internet transformed how we share information, connecting people globally in unprecedented ways. However, this explosion of data introduced significant organizational challenges. Search engines like Google addressed this by indexing web pages, making information easily accessible.
Today, a new digital frontier is unfolding: web3. With rapid growth and widespread adoption, web3 is forging a a decentralized internet that give users ownership of assets and digital identity. But like earlier iterations of the internet, web3 faces a challenge — how to effectively access and read blockchain data. Enter The Graph.
The Graph on Linea: Unlocking Blockchain Data
The Graph is a decentralized protocol for indexing and querying blockchain data. It enables anyone to access blockchain data by querying open APIs called subgraphs. Independent network participants coordinate and contribute to the network.
Network participants work together to provide data to end users in exchange for GRT rewards. GRT, the utility token of The Graph, coordinates efforts between data providers and consumers, incentivizing efficient data organization.
Key network participants include:
Subgraph Developers: Create and publish subgraphs accessible to everyone.
Indexers: Operate nodes to index subgraphs and serve data to consumers.
Curators: Identify and curate valuable subgraphs for Indexers.
Delegators: Secure the network by delegating GRT to Indexers.
The Graph’s decentralized structure ensures open access to data, fostering innovation, collaboration, and transparency within web3. By democratizing information, The Graph empowers individuals and communities to participate in the web3 revolution without relying on centralized entities.
Benefits for the Linea Ecosystem
Linea’s ecosystem leverages The Graph to access blockchain data without the control of a single entity, reducing censorship risks and enhancing transparency and accountability.
The Graph is powered by hundreds of independent Indexers across the world, guaranteeing robust and reliable access to data any time you need it. Data performance on The Graph is significantly better when compared to operating your own hardware. And performance on the decentralized network will only continue to increase thanks to the ongoing contributions from The Graph community.
Subgraphs have become the industry standard for accessing blockchain data, and can power all the data needs for your dapp’s front end. Hundreds of dapps are using subgraphs to serve data to users already, with billions of queries being made to the network.
How to Create a Subgraph on Linea
This guide will quickly take you through how to initialize, create, deploy, and publish your Linea network subgraph on The Graph’s decentralized network.
This guide is written assuming that you have:
A link to a smart contract deployed to Linea network.
GRT to curate your subgraph.
A crypto wallet.
Step 0: Go to Subgraph Studio and Create a New Subgraph
Go to Subgraph Studio and connect your wallet.
Once connected, you can begin by clicking “create a subgraph.” Select Linea as the network and click continue.
Step 1: Install the Graph CLI
The Graph CLI is written in JavaScript and you will need to have npm or yarn installed to use it.
On your local machine, run one of the following commands:
# NPM
$ npm install -g @graphprotocol/graph-cli
# Yarn
$ yarn global add @graphprotocol/graph-cli
Step 2: Initialize Your Subgraph
Initialize your subgraph from an existing contract by running the following command:
graph init --studio <SUBGRAPH_SLUG>
The Graph CLI will ask you to enter information.
Protocol: select Ethereum because Linea is EVM-compatible. Subgraph Slug: Create a name for your subgraph. Your subgraph slug is an identifier for your subgraph. Directory to Create the Subgraph: Choose your local directory. Ethereum Network: Linea or Linea Sepolia. Contract Address: Locate the address of the smart contract you’d like to query data from Linea Explorer or if using a Sepolia via Linea Sepolia Explorer. If the ABI is not auto populated, you will need to input it manually as a JSON file. Start Block: It is suggested that you input the start block to save time while your subgraph indexes blockchain data. You can 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: You can optionally add another contract. Once you have completed this step, the graph CLI will prompt you with next steps.
Here is an example:
Step 3: Write Your Subgraph
The previous commands create a scaffold subgraph that you can use as a starting point for building your subgraph. This scaffold is already very useful. That being said, you might want to make changes to the subgraph, you will mainly work with three files:
Manifest (subgraph.yaml): The manifest defines what data sources your subgraphs will index.
Schema (schema.graphql): The GraphQL schema defines what data you wish to retrieve from the subgraph.
AssemblyScript Mappings (mapping.ts): This is the code that translates data from your data sources to the entities defined in the schema.
For more information on how to write your subgraph, see this page.
Step 4: Deploy to the Subgraph Studio
Once your subgraph is written, run the following commands:
$ graph codegen
$ graph build
The ‘graph codegen’ command will generate AssemblyScript types for smart contract ABIs and the subgraph schema.
The ‘graph build’ command will compile your subgraph to WebAssembly.
Next, authenticate and deploy your subgraph to a Graph Node. The deploy key can be found on the Subgraph page in Subgraph Studio.
$ graph auth --studio <DEPLOY_KEY>
$ graph deploy --studio <SUBGRAPH_SLUG>
You will be asked for a version label. It's strongly recommended to use semver for versioning like 0.0.1. That said, you are free to choose any string as version such as:v1, version1, asdf
Step 5: Test Your Subgraph
You can test your subgraph by making a sample query in the playground section.
The logs will tell you if there are any errors with your subgraph. The logs of an operational subgraph will look like this:
If your subgraph is failing, you can query the subgraph health by using the GraphiQL Playground. Note that you can leverage the query below and input your deployment ID for your subgraph. In this case, Qm... is the deployment ID (which can be located on the Subgraph page under Details). The query below will tell you when a subgraph fails, so you can debug accordingly:
{
indexingStatuses(subgraphs: ["Qm..."]) {
node
synced
health
fatalError {
message
block {
number
hash
}
handler
}
nonFatalErrors {
message
block {
number
hash
}
handler
}
chains {
network
chainHeadBlock {
number
}
earliestBlock {
number
}
latestBlock {
number
}
lastHealthyBlock {
number
}
}
entityCount
}
}
Step 6: Publish Your Subgraph to The Graph’s Decentralized Network
Once your subgraph has been deployed to the Subgraph Studio, you have tested it out, and are ready to put it into production, you can then publish it to the decentralized network.
In the Subgraph Studio, click on your subgraph. On the subgraph’s page, you will be able to click the publish button on the top right.
Select the network you would like to publish your subgraph to. It is recommended to publish subgraphs to Arbitrum One to take advantage of the lower gas costs.
Before you can query your subgraph, Indexers need to begin serving queries on it. In order to streamline this process, you can curate your own subgraph using GRT.
At the time of writing, it is recommended that you curate your own subgraph with 10,000 GRT to ensure that it is indexed and available for querying as soon as possible.
To save on gas costs, you can curate your subgraph in the same transaction that you published it by selecting this button when you publish your subgraph to The Graph’s decentralized network:
Step 7: Query Your Subgraph
Now, you can query your subgraph by sending GraphQL queries to your subgraph’s Query URL, which you can find by clicking on the query button.
You can query from your dapp if you don't have your API key via the free, rate-limited temporary query URL that can be used for development and staging.
For more information about querying data from your subgraph, read here.