Table of Contents

We use Graph to index data to read from blockchains in a decentralized way. This is an example to get started and create a first subgraph to can be used by any application.

Deploy a subgraph using Subgraph Studio

1. Login The Graph Studio

Go to The Graph Studio and login using your web3 wallet.

Create a new subgraph and give it a name.
For example: subgraph26

2. Install graph-cli and initialize the subgraph

Install npm package graph-cli

npm install -g @graphprotocol/graph-cli

3. Choose a contract to index

In this example we are going to look at Test Tether USD token (USDT). Looking in Etherscan we can see that the contract address is 0x7169d38820dfd117c3fa1f22a697dba58d90ba06.

4. Initialize the subgraph

graph init --studio subgraph26

Initialize the subgraph (this will create a subfolder with the same name as the subgraph)

$ graph init --studio subgraph26

✔ Protocol · ethereum
✔ Subgraph slug · subgraph26
✔ Directory to create the subgraph in · subgraph26
✔ Ethereum network · sepolia
✔ Contract address · 0x7169d38820dfd117c3fa1f22a697dba58d90ba06
✔ Fetching ABI from Etherscan
✖ Failed to fetch Start Block: Failed to fetch contract creation transaction hash
  
✔ Start Block · 2060228
✔ Contract Name · TetherToken
✔ Index contract events as entities (Y/n) · true
  Generate subgraph
  Write subgraph to directory
✔ Create subgraph scaffold
✔ Initialize networks config
✔ Initialize subgraph repository
✔ Install dependencies with yarn
✔ Generate ABI and schema types with yarn codegen
Add another contract? (y/n): 
Subgraph subgraph26 created in subgraph26

Next steps:

  1. Run `graph auth` to authenticate with your deploy key.

  2. Type `cd subgraph26` to enter the subgraph.

  3. Run `yarn deploy` to deploy the subgraph.

Make sure to visit the documentation on https://thegraph.com/docs/ for further information.

The Start Block you can find in Etherscan. For example, for Test USDT in Sepolia it’s 2060228. The Contract name is is best practica to add the same name of the contract. In this case it is TetherToken. Another useful tool to get all the info I need about smart contract is miniscan.xyz. Not all blockchains are supported, but for the ones that are you can get useful information like the Start block very easyly.

Alt text

5. Authenticate in CLI

I copy paste the line I see in thegraph studio for this. In my case:

$ graph auth --studio fd433d3bc7xxxxxxxxxxxxxxxxxxxxx
Deploy key set for https://api.studio.thegraph.com/deploy/

6. Build the subgraph

$ cd subgraph26 && graph codegen && graph build

Output should something like this:

  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
  Skip migration: Bump mapping apiVersion from 0.0.4 to 0.0.5
  Skip migration: Bump mapping apiVersion from 0.0.5 to 0.0.6
  Skip migration: Bump manifest specVersion from 0.0.1 to 0.0.2
  Skip migration: Bump manifest specVersion from 0.0.2 to 0.0.4
✔ Apply migrations
✔ Load subgraph from subgraph.yaml
  Load contract ABI from abis/TetherToken.json
✔ Load contract ABIs
  Generate types for contract ABI: TetherToken (abis/TetherToken.json)
  Write types to generated/TetherToken/TetherToken.ts
✔ Generate types for contract ABIs
✔ Generate types for data source templates
✔ 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

  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
  Skip migration: Bump mapping apiVersion from 0.0.4 to 0.0.5
  Skip migration: Bump mapping apiVersion from 0.0.5 to 0.0.6
  Skip migration: Bump manifest specVersion from 0.0.1 to 0.0.2
  Skip migration: Bump manifest specVersion from 0.0.2 to 0.0.4
✔ Apply migrations
✔ Load subgraph from subgraph.yaml
  Compile data source: TetherToken => build/TetherToken/TetherToken.wasm
✔ Compile subgraph
  Copy schema file build/schema.graphql
  Write subgraph file build/TetherToken/abis/TetherToken.json
  Write subgraph manifest build/subgraph.yaml
✔ Write compiled subgraph to build/

Build completed: build/subgraph.yaml

7. Deploy to Studio

$ graph deploy --studio subgraph26 
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
  Skip migration: Bump mapping apiVersion from 0.0.3 to 0.0.4
  Skip migration: Bump mapping apiVersion from 0.0.4 to 0.0.5
  Skip migration: Bump mapping apiVersion from 0.0.5 to 0.0.6
  Skip migration: Bump manifest specVersion from 0.0.1 to 0.0.2
  Skip migration: Bump manifest specVersion from 0.0.2 to 0.0.4
✔ Apply migrations
✔ Load subgraph from subgraph.yaml
  Compile data source: TetherToken => build/TetherToken/TetherToken.wasm
✔ Compile subgraph
  Copy schema file build/schema.graphql
  Write subgraph file build/TetherToken/abis/TetherToken.json
  Write subgraph manifest build/subgraph.yaml
✔ Write compiled subgraph to build/
  Add file to IPFS build/schema.graphql
                .. QmQjchRTvjddW2pyxBAN3sWop2GUw8iLNyu58toiKoJoM7
  Add file to IPFS build/TetherToken/abis/TetherToken.json
                .. QmSju3H214f3VXyD3yDXGc3nVcs1dgvkTDQfFDfZ2yksJw
  Add file to IPFS build/TetherToken/TetherToken.wasm
                .. QmYZAJ5i7tKG2yr7PZxfYdgRTqCyepUFXKdMT9cKALMXjU
✔ Upload subgraph to IPFS

Build completed: QmSYeKC1SDwhjH3U8FhcbpEdXz51PeySJvcXBvi1VE233b

Deployed to https://thegraph.com/studio/subgraph/subgraph26

Subgraph endpoints:
Queries (HTTP):     https://api.studio.thegraph.com/query/56687/subgraph26/v0.0.1

Now in Studio you should see the version deployed and syncing:

Alt text

8. Change schema.graphql

By now you will have a file called schema.graphql in your folder, with a content similar to this:

type Issue @entity(immutable: true) {
  id: Bytes!
  amount: BigInt! # uint256
  blockNumber: BigInt!
  blockTimestamp: BigInt!
  transactionHash: Bytes!
}

type Redeem @entity(immutable: true) {
  id: Bytes!
  amount: BigInt! # uint256
  blockNumber: BigInt!
  blockTimestamp: BigInt!
  transactionHash: Bytes!
}

type Deprecate @entity(immutable: true) {
  id: Bytes!
  newAddress: Bytes! # address
  blockNumber: BigInt!
  blockTimestamp: BigInt!
  transactionHash: Bytes!
}
...

We can now modify this graphql code to our needs and redeploy newer versions of my subgraph.

3 files are important here:

  • subgraph.yaml - this is the main file that contains the name of the subgraph, the contract address, the start block, the schema and the mapping.
  • mappings.ts - this is the file that contains the mapping of the contract events to the graphql schema.
  • schemas.graphql - this is the file that contains the graphql schema.

9. Example Query

Lets query the last 2 transfers of 10 USDT in Sepolia:

query firstquery {
  transfers(
    first: 2
    orderBy: blockNumber
    orderDirection: desc
    where: {value: "10000000"}
  ) {
    blockTimestamp
    id
    from
    to
    value
  }
}

Replies with:

{
  "data": {
    "transfers": [
      {
        "blockTimestamp": "1698246696",
        "id": "0x4d749cc7cb6c511b6ef90f0490ac6cb249b76ad5398c41a63e498cf1a34cb38e4f000000",
        "from": "0x00199b1aba7c18a068f2840d059246375e927dde",
        "to": "0xdccd1e7ef46a5620081e581398d5a77bf1e9762d",
        "value": "10000000"
      },
      {
        "blockTimestamp": "1698246072",
        "id": "0xc4b29d30dbe47dc00a6d5169ceeca665a145df1931b2c98820169fed853980c539000000",
        "from": "0xec6689752b235df0a70cf9e5d77bf416c74cf995",
        "to": "0x00199b1aba7c18a068f2840d059246375e927dde",
        "value": "10000000"
      }
    ]
  }
}

Notes

Graph Token is a ERC-20 Token on Ethereum (token address) and Arbitrum (token address).

Here is a good article explaining the differences between GraphQL APIs and REST API.

API KEY

Alt text

Alt text

If you enter an email you will get 1000 free queries to test your API key.

Comment a parragraph about the API key.