Local Graph Dev with Scaffold-ETH 2

5 min readJan 19, 2024

If you are new to Scaffold-ETH-2 (SE-2), check out my Intro into Scaffold-ETH-2 blog.
Want to learn a little bit more before you get started? Here’s a post about writing, reading, and listening to Smart Contracts using SE-2.

What is a subgraph?

This is — simply put — a way of organizing blockchain data — rules and instructions you give to the indexers around the world so that you can query the data. Here is a great video going over the topic.

Image from video: https://youtu.be/EJ2em_QkQWU?si=zJ_1amXXLHwJ6JCZ

Off-chain data: A good example of this would be IPFS
subgraph.yaml: Rules/Overview && Shape/Structure
mapping.ts: Apply logic for Data Transformation (you could look at this as the “business logic”)
schema.graphql: Data goes into “buckets” (AKA: “entities”); you will send GraphQL queries to these “buckets” to get data to your front-end

To see a subgraph get deployed: https://youtu.be/EJ2em_QkQWU?t=517

This image sums it up pretty well ☝️

Why use The Graph?

Much more “reading from the blockchain” occurs than “writing to the blockchain”. The web 3.0 solution is to have decentralized reading and decentralized indexing from the blockchain.

☝️If any of the nodes in the middle go down, the front-end can use other nodes.

The idea is to take the advantages of blockchain/decentralization and apply that to the read layer.

The blockchain is used to being written-to ( all the time! ) … but now we need reading to become decentralized. That’s why we are using The Graph/Subgraphs for this project.

Start Coding

Before you can begin, you will need the following prerequisites:

A good project to tinker with is this SE-2 Subgraph Package.

For more details (OR IF YOU RUN INTO MAC ERRORS), check out these two outstanding articles by Shutterblock.eth (cryptomastery.eth):

At this point, you should either have this SE-2 Subgraph Package or this branch of the Crowd Fund V3 project downloaded and installed (via yarn install). If you need some more help getting started with SE-2, here you go:

Once you have three terminals (one running your local blockchain, one running your frontend localhost, and another that you are using for contract deploys), then open up a fourth (in the project directory)…
Run the following command to spin-up a local Graph Node with all of the containers for The Graph (keep this window open to see Docker’s output logs):

yarn run-node

☝️May take a while, but you can move forward when you see messages about websockets.

From a new terminal, create the local subgraph (only need to run this command once):

yarn local-create

After a local subgraph is in-place, you can ship it:

yarn local-ship

**Note that you will be prompted to provide a version number (start with “0.0.1”).

yarn local-ship copies the contract’s ABI (/hardhat/deployments); then, generates the networks.json file, AssemblyScript types from the subgraph’s schema, and the contract ABIs; then, compiles/checks the mapping functions; then, deploys the local subgraph.

If you want to stop your node, you can run:

yarn stop-node && yarn clean-node

Linux users: you may have to add sudo to these☝️ (to force it to remove postgres).

Windows users: clean-node will throw the error “‘rm’ command not found” unless you run it in git bash.

NOTE: If you restart your computer, then you will still need to run this before you can successfully yarn local-create again.

If you simply want to clean out the old data, you can run:

yarn clean-node

Upon a successful local-ship, you will see an output supplying your local subgraph endpoint (where you can run queries).

Making changes to your contract or subgraph

To copy over a new ABI:

yarn abi-copy

Run the following command if you change your schema because this Type-Safety checks all of the connections that you’ve built up and keeps those fresh (*generates the /generated directory):

yarn codegen

Run the following command if you change your mappings file:

yarn local-ship

Adding a new event to your Smart Contract

First, add the event, and re-deploy your local contract:

yarn deploy --reset

Add the new “Entity” (your Event) to your schema.graphql file in \packages\subgraph\src\

type EntityName @entity {
  id: ID!
  newStringParam: String!
}

Now add your Entity/Event and its (future) Handler (function name) to your subgraph.yaml file in \packages\subgraph\

entities:
    - EntityName
abis:
    - name: YourContract
      file: ./abis/localhost_YourContract.json
      eventHandlers:
        - event: NewEventName(string)
          handler: handleNewEventName

Then copy over the new ABI and run codegen:

yarn abi-copy && yarn codegen

Next, update the mapping.ts file in \packages\subgraph\src\

Update the imports from the generated contract as well as the schema:

import { EventName } from "../generated/YourContract/YourContract";
import { EntityName } from "../generated/schema";

And then, add the function for the actual event:

export function handleNewEventName(event: EventName): void {  
  //unique ID
  let test = new EntityName(
    event.transaction.hash.toHex() + "-" + event.logIndex.toString()
  );
  //set from event's params
  test.newStringParam = event.params.newStringParam;
  //save entity
  test.save();
}

Now, you can perform a local-ship

yarn local-ship

Local Graph Dev with Scaffold-ETH 2

What is a subgraph?

Why use The Graph?

Start Coding

Making changes to your contract or subgraph

Adding a new event to your Smart Contract

Want to learn more?

Check out my other blog posts on the subject:

Written by WebSculpt