If you’re diving into the world of decentralized finance (DeFi), you know how important it is to get accurate and comprehensive data. But what if we could get this data not just from one DeFi protocol, but from dozens all at once?

That’s where Messari’s standardized subgraphs come in.

These standardized subgraphs let us query multiple exchanges with a single query, essentially asking the same question of many different DeFi communities all at the same time! Imagine being able to track the Total Value Locked (TVL) across dozens of different protocols or analyzing trade volumes and user metrics - all with a single query!

In this post, we’ll walk you through the advantages of using Messari standardized subgraphs, show you how to query multiple exchanges, and even give you some creative queries to try out. Let’s get started!

Why Messari Standardized Subgraphs Are Awesome

1. Consistent Data Structure: Messari's subgraphs stick to a consistent schema, making it super easy to write queries that work across different exchanges. No more tweaking queries for each platform!

2. Comprehensive Insights: By querying multiple exchanges at once, you can get a complete view of the DeFi landscape. This is perfect for comparing TVL, spotting market trends, and finding new opportunities.

3. Efficient and Fast: Standardized subgraphs let you fetch data from various sources in one go. This saves time and cuts down on the hassle of handling multiple data sources.

How to Query Multiple Exchanges: A Step-by-Step Guide

Step 1: Find Messari Subgraphs that Index Exchanges

Go to subgraphs.messari.io and find the Exchanges category. All subgraphs under each category have the same standardized schema for us to query (Exchanges, erc721, Governance, etc).

We will query Messari’s Curve Finance subgraph and their SushiSwap subgraph, however if we wanted to we could send this query to nearly 40(!) Messari-standard Exchange subgraphs. Every Messari Exchange subgraph uses this schema, which will make designing queries simple!

Step 2: Design a Query and Test in the Subgraph’s Playground

Let’s find the TVL of both Curve Finance and SushiSwap on August 20th, 2023.

After analyzing the subgraph’s schema, as well as finding the UNIX timestamp for that specific date, here is our GraphQL query:

{
  dailySnapshot8_20_23: financialsDailySnapshots(
    where: {timestamp_gte: 1629417600, timestamp_lt: 1629504000},
  ) {
    totalValueLockedUSD
  }
}

We can run this query in each subgraph’s playground and see both are returning data:

But now, how do we build this in programmatically into our dapp?

Step 3: Set Up Our Project

First things first, make sure you have Node.js installed. Then, set up a new project:

mkdir messari-subgraphs
cd messari-subgraphs
npm init -y

Step 4: Gather Subgraph Endpoints

Create a file named app.js and gather both subgraph’s endpoints by pressing the Query button on each of their dashboards.

Save the endpoints as an array inside of a getTVLs() function:

//app.js	

async function getTVLs() {
        const urls = [
        {
            url: "https://gateway.thegraph.com/api/<API_KEY>/subgraphs/id/GAGwGKc4ArNKKq9eFTcwgd1UGymvqhTier9Npqo1YvZB",
            name: "Curve Finance",
        },
        {
            url: "https://gateway.thegraph.com/api/<API_KEY>/subgraphs/id/7h1x51fyT5KigAhXd8sdE3kzzxQDJxxz1y66LTFiC3mS",
            name: "SushiSwap",
        },
    ];
};

Step 5: Gather API Key

Go to Subgraph Studio and set up an API Key, then drop the API key into the endpoints:

//app.js

async function getTVLs() {
  const urls = [
      	{
            url:     "https://gateway.thegraph.com/api/0ab7a83b03a36ac8a536cd8fa19a8ad4/subgraphs/id/GAGwGKc4ArNKKq9eFTcwgd1UGymvqhTier9Npqo1YvZB",
            name: "Curve Finance",
        },
        {
            url: "https://gateway.thegraph.com/api/0ab7a83b03a36ac8a536cd8fa19a8ad4/subgraphs/id/7h1x51fyT5KigAhXd8sdE3kzzxQDJxxz1y66LTFiC3mS",
            name: "SushiSwap",
        },
    ];
};

Step 6: Programmatically Send Query to Endpoints

Next, we will create an array of POST requests to fetch the Total Value Locked (TVL) data for August 20th, 2023, from multiple subgraphs:

//app.js

const requests = urls.map((entry) =>
        fetch(entry.url, {
            method: "POST",
            headers: {
                "Content-Type": "application/json",
            },
            body: JSON.stringify({
                query: `
                    {
                        dailySnapshot8_20_23: financialsDailySnapshots(
                            where: { timestamp_gte: 1629417600, timestamp_lt: 1629504000 }
                        ) {
                            totalValueLockedUSD
                        }
                    }
                `,
            }),
        })
    );

    const results = await Promise.all(requests);
    const tvls = await Promise.all(results.map((result) => result.json()));

By using the map function on the urls array, we ensure that each subgraph endpoint is queried with the same GraphQL query.

Step 7: Display The Returned Data

Now that we've fetched the data from multiple subgraphs, the next step is to display it on our webpage. We will take the data returned from the subgraphs and dynamically create HTML elements to show this information.

1. Get the Data Container:

   • First, we need to select the HTML element where we will display our data. This element should have the ID data-container.

2. Iterate Over the Results:

   • We loop through the array of TVL results, and for each result, we create a new HTML div element to display the data.

3. Create HTML Elements:

   • Inside this loop, we create elements for the exchange name and the TVL, and then append these elements to the data-container.

Here is the final app.js file:

async function getTVLs() {
    const urls = [
        {
            url: "https://gateway.thegraph.com/api/0ab7a83b03a36ac8a536cd8fa19a8ad4/subgraphs/id/GAGwGKc4ArNKKq9eFTcwgd1UGymvqhTier9Npqo1YvZB",
            name: "Curve Finance",
        },
        {
            url: "https://gateway.thegraph.com/api/0ab7a83b03a36ac8a536cd8fa19a8ad4/subgraphs/id/7h1x51fyT5KigAhXd8sdE3kzzxQDJxxz1y66LTFiC3mS",
            name: "SushiSwap",
        },
    ];

    const requests = urls.map((entry) =>
        fetch(entry.url, {
            method: "POST",
            headers: {
                "Content-Type": "application/json",
            },
            body: JSON.stringify({
                query: `
                    {
                        dailySnapshot8_20_23: financialsDailySnapshots(
                            where: { timestamp_gte: 1629417600, timestamp_lt: 1629504000 }
                        ) {
                            totalValueLockedUSD
                        }
                    }
                `,
            }),
        })
    );

    const results = await Promise.all(requests);
    const tvls = await Promise.all(results.map((result) => result.json()));

    const dataContainer = document.getElementById("data-container");
    tvls.forEach((feed, index) => {
        const platformName = urls[index].name;
        const feedData = feed.data.dailySnapshot8_20_23;
        feedData.forEach((snapshot) => {
            const snapshotElement = document.createElement("div");
            snapshotElement.innerHTML = `
                <h3>${platformName}</h3>
                <p>Total Value Locked USD: ${snapshot.totalValueLockedUSD}</p>
                <hr>
            `;
            dataContainer.appendChild(snapshotElement);
        });
    });
}

getTVLs();

Step 8: Create the HTML File

Create an HTML file to display the results:

// index.html

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>TVL on Aug 20th, 2023</title>
        <link rel="stylesheet" href="styles.css" />
        <link
            href="https://fonts.googleapis.com/css2?family=Raleway:ital,wght@0,300;1,300&display=swap"
            rel="stylesheet"
        />
    </head>
    <body class="container">
        <h1>TVL on Aug 20th, 2023</h1>
        <div id="data-container"></div>
        <script type="text/javascript" src="app.js"></script>
    </body>
</html>

Step 9: Add Some Style

Create a CSS file (styles.css) to make everything look nice:

// styles.css

body {
    font-family: "Raleway", sans-serif;
    background-color: #f4f4f9;
    color: #333;
    margin: 0;
    padding: 20px;
}

.container {
    max-width: 800px;
    margin: auto;
    padding: 20px;
    background-color: #ffffff;
    box-shadow: 0 0 10px rgba(0, 0, 0, 0.1);
}

h1 {
    color: #0a4870;
    text-align: center;
}

div#data-container {
    margin-top: 20px;
}

div#data-container > div {
    padding: 10px;
    border-bottom: 1px solid #eee;
}

h3 {
    color: #0a4870;
    margin: 0 0 5px 0;
}

p {
    margin: 5px 0;
}

hr {
    margin-top: 10px;
    border: none;
    height: 1px;
    background-color: #eee;
}

More Creative Queries for Exchange Subgraphs

Once you’ve got the basic setup down, you can start writing more interesting queries to get even more insights about many DeFi protocols. Here are a few ideas:

Number of Daily Active Users Between Jan 1st, 2021 and Feb 1st, 2021

query DailyActiveUsers {
  usageMetricsDailySnapshots(
    where: {timestamp_gt: "1609480861", timestamp_lt: "1612159261"}
  ) {
    dailyActiveUsers
    timestamp
  }
}

Daily Trading Volume, Daily Revenue, and TVL Over the Past 10 Days

{
  financialsDailySnapshots(
    first: 10
    orderBy: timestamp
    orderDirection: desc
  ) {
    timestamp
    dailyVolumeUSD
    dailyTotalRevenueUSD
    totalValueLockedUSD
  }
}

By querying these standardized subgraphs, you can gather valuable insights across multiple exchanges efficiently, helping you stay ahead in the fast-paced DeFi landscape. Happy querying!

Marcus Rein

Developer Relations and Success

Edge & Node - Working on The Graph

Final repo of this tutorial:

https://github.com/marcusrein/TutorialSubgraphTemplate

Documentation on Data Source Templating with Subgraphs:

https://thegraph.com/docs/en/developing/creating-a-subgraph/#data-source-templates

Intro

Do you have a child?

Imagine having ten more. Then fifty more after that. Then imagine you have ten thousand.

Whelp, in this shoehorned metaphor, it turns out that YOU are responsible for the information, safety, and whereabouts of each and every single child!

Good luck!

So what does this have to do with decentralized data you might ask?

It all comes down to smart contracts.

Smart contracts aren’t just incredibly powerful executable warrior-files securely deployed to countless nodes throughout earth, hell-bent on disrupting the entrenched extractive ethos of web2…

Smart contracts, when lovingly set up and are in the mood, can also have children.

Lots and lots and LOTS of children. Infinite children!

Wouldn’t it be nice to be able to keep track of your children, no matter how infinite they may be?

I think so!

Welcome to a walkthrough tutorial on how to deploy and index factory pattern contracts using Remix IDE and The Graph’s subgraphs

Who This Tutorial Is For

• Web2 devs curious about getting started in web3

• Web3 devs looking to take their dapp to the next level by allowing their smart contracts to replicate and keep track of those replications’ actions.

Requirements

• A low to moderate level of understanding of Solidity, Typescript, and APIs

  • Here are a few of my favorite resources:

    • Solidity quickstart

    • Typescript quickstart

• A low to moderate level of understanding of how blockchain functions

• A decentralized wallet like Metamask

Objectives

• Deploy a gas-efficient Factory Pattern using clones

• Deploy a subgraph that features templating to index and search the contract and any children it produces

What We are Building:

We are going to be building a gas-efficient Factory Pattern smart contract and deploy it on the Goerli testnet. We will first build it locally before deploying on-chain.

We’ll then index and query the parent and any child created from the parent efficiently with a Graph Protocol Subgraph Template.

This is an high-level preview of what we will be building. Keep this diagram handy ! If you ever feel lost, refer to this!

Section 1: Building a Factory Pattern Efficiently

A Factory Pattern in solidity is ideally going to be a different pattern than a traditional Factory Pattern in other programming languages due to gas.

The typical Factory Pattern involves cloning the logic every time a cloned smart contract is made, which adds more data to every transaction, which wastes gas.

But no worries, there is a solution!

The EIP-1167 specification allows us to create a cloned proxy (aka ‘child’. The technical term is proxy, but ‘child’ is going to be used in this tutorial for the sake of shoehorning the metaphor) to forward all of the logic to an initial “implementation contract” through delegateCall, and then any calls other child smart contracts make will communicate with this implementation contract, call the function there, then relay the return value back to the caller!

I personally learned a TON about this pattern with these two resources:

https://betterprogramming.pub/learn-solidity-the-factory-pattern-75d11c3e7d29

https://www.youtube.com/watch?v=7H7GVI1gsTc (The beginning 5min of this is amazing and critical for you to understand!)

Please read the article and watch the video if you are unsure about these concepts.

Building an Implementation Contract for your Factory to Clone

In this tutorial, I’m going to be using Remix IDE which was specifically designed for interacting with Solidity and the blockchain.

Create a new file in Remix named Factory.sol

Let’s first write out a very basic contract of what we will want to create as our very first implementation contract that future child contracts will be based off of.

Factory.sol

//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
import "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";

contract Child {
   string public message = 'Default message';
   function initialize(string memory _message) public initializer {
       message = _message;
   }
}

You may be wondering why we are using initialize instead of a constructor .

initialize is used instead of constructor because this contract will be an implementation contract and should only be run once on this implementation contract.

The import Initializable has some great helper code that only allows initialize to run once on the implementation contract, then never again on the children.

To read more about initialize, check out the official OpenZeppelin documentation on “The Constructor Caveat.”

Now that this contract can be created, let's give it a basic set of functionality.

Factory.sol

//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
import "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";

contract Child is Initializable {
   string public message = 'Default message';
   uint256 updatedMessageTally = 0;

   event MessageUpdated(string message, uint256 
updatedMessageTally);

   function initialize(string memory _message) public initializer {
       message = _message;
   }
   function updateMessage(string memory _message) public {
       message = _message;
       updatedMessageTally++;
       emit MessageUpdated(_message, updatedMessageTally);
   }
 }

First, each child will have a tally of how many times the message has been updated.

Second, we define the MessageUpdated event that will eventually be emitted when the message is updated.

Next, the function updateMessage updates this message stored on the child, triggers an increase in the child’s tally, as well as emits a MessageUpdated event to be indexed by our (not yet written) subgraph that we will work on in Section 4.

Amazing! You’ve created a simple smart contract that can only be initialized once and is ready to be copied into infinite ‘child’ or proxy contracts by way of a Factory.

Building the Factory!

Create a new file named “CloneFactory.sol”.

Read up on the EIP-1167 standard, copy the standard into your CloneFactory.sol file, then import it into your main Factory.sol file.

CloneFactory.sol

//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

import './CloneFactory.sol';
import "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";

contract Factory is CloneFactory {
    Child[] public children;

    address implementation;

   constructor(address _implementation) {
       implementation = _implementation;
    }

    event ChildCreated(uint date, string message, address childAddress);

    function createChild(string memory message) public {
       Child child = Child(createClone(parent));
       child.initialize(message);
       children.push(child);
       emit ChildCreated(block.timestamp, message, address(child));
    }

    function getChildren() external view returns(Child[] memory){
        return children;
    }
}

contract Child is Initializable {
   string public message = 'Default message';
   uint256 updatedMessageTally = 0;

   event MessageUpdated(string message, uint256 updatedMessageTally);

   function initialize(string memory _message) public initializer {
       message = _message;
   }

   function updateMessage(string memory _message) public {
       message = _message;
       updatedMessageTally++;
       emit MessageUpdated(_message, updatedMessageTally);
   }
 }

Our factory is ready to start making proxies!

Let’s highlight a few key things to go over here for your understanding:

1. The constructor is being used as opposed to initialize as this will not be an implementation contract when deployed. This is the Factory contract that will not carry any data, just logic for the implementation to reference upon its deployment.

2. An event ChildCreated is made and is emitted in the function call createChild. This will be very helpful when we are trying to index these events with our subgraph in the next section!

3. createClone(parent) is called as its clones the parent address of the implementation contract that's imported upon its creation. This is an important part of the EIP-1167 standard as we are not creating a new child, but a CLONED child.

Now that we have our two smart contracts (Factory and Child) ready, lets deploy!

Section 2. Deploying Our Two Smart Contracts In the Correct Order

First thing’s first, go back to your Remix IDE and choose your virtual environment to test out your code.

Make sure your environment is set to Remix VM to keep the deployment local before we go deploy on Goerli.

Deploy your contracts and perform the following steps in this order:

1. Child is your Implementation Contract as its the first one! Every Child after that will not be the implementation as its not the first!

   You’ll need to initialize it with whatever word or phrase you'd prefer. I’ll put in “Blockchain!”. Remember, this can only be done once on the implementation contract. Feel free to try it on any future Child contracts (you won't be able to!).

Now that the implementation is active, you’re ready to create your Factory based on the address of this implementation!

2. Copy the address of the deployed Implementation contract and put it into the address_parent input field of Factory - contracts/Factory.sol, then click Deploy.

Your Factory is now deployed its first Child based off the initial Child Implementation contract!

Now let's make another child!

3. At your deployed Factory, create a child by inputting a string into createChild, then press the button! Perform this as many times as you’d like. Feel free to give them names or many words to identify each differently!

After you’ve created your children, go ahead and click “getChildren.”

Every time you create a child with your factory, a new address will pop up here! See how the addresses grow every time I add a new Child.

If you ever want to see how your children are doing and interact with their contracts directly as opposed to just listing them out, take the address and input it into the Deploy “At Address” field and make sure the contract you’ll be deploying is a Child.

Click “AtAddress” and boom! You can start interacting with your child!

If you try to Initialize your Child, you should see an error message as it has already initialized with the message you fed into it, and initialize can only be run once!

However, you CAN update the message of the contract using “updateMessage”, then check on the message using “message”.

Congratulations!

Now that you’ve been able to deploy your Factory Pattern onto your test environment, go ahead and change your environments from Remix VM to “Injected Provider”, then deploy it again on the test network Goerli!

Let's take a moment to appreciate how amazing this journey has been so far. you have created two smart contracts, you have understood and built an interesting little piece of software architecture, and have now deployed your smart contracts on the blockchain!

Now that your smart contract children are on the blockchain, let's create a dynamic subgraph that can index your Children, no matter how many of them are created from the factory!

To do this your subgraph will need to have templating enabled. Let’s go do that right now.

Section 3: Indexing Our Infinite Children With Subgraph Templating

Web2 has Google to index and search web2.

Web3 has The Graph to index and search the blockchain.

The Graph (www.thegraph.com) has done the hard work of creating a self-sustaining ecosystem that allows developers easy and affordable access to this data.

You access this blockchain data through an API they developed called a Subgraph.

Subgraphs can access different parts of the Ethereum blockchain depending on how the Subgraph is designed.

Read more about The Graph, Subgraphs, and more at https://thegraph.com/docs/en/

Let’s create a subgraph to index our Factory and dynamically created Children!

Go to www.thegraph.com and click on Subgraph Studio.

Click on Create a Subgraph, give it a title, and ensure you are on the Goerli Network.

You’ll see a list of instructions on the right of the screen.

If you haven’t installed graph-cli, do so in your terminal, then run graph init by copy/pasting the code and then follow these instructions:

1. Choose the ethereum network

2. Confirm the prenamed subgraph slug as well as the prenamed directory

3. Choose Goerli network, then init your subgraph with the code in the website by copy/pasting it into your terminal.

4. When it asks for your contract’s address, go back to remix and choose the contract address of your Factory from the Remix IDE

5. Get the ABI of your Factory from the Remix IDE as well, and save it as a json file anywhere on your computer (I saved mine in the working folder itself). Write the path into this portion of the CLI when it asks for it.

6. Also get the ABI for your Child contract and save it as well. You’ll need this later!

7. Name the contract “Factory”

8. Say Yes to indexing the contract events, after which it will install all dependencies.

9. When it asks you if you want to add another contract, add your Child contract address you previously deployed!

10. Remember saving the ABI for the child contract? Link that path now.

11. Name the second contract “Child”

12. Do not add any more contracts

13. After the installation, go back to your subgraph’s page at www.thegraph.com and copy/paste the “authenticate in CLI” code into your terminal.

14. cd into your folder as instructed.

15. Do NOT continue with graph codegen && graph build commands. We’ll do those in Section 4.

Another congratulations! You have set up 90% of a subgraph to be ready to index your smart contracts that are active on the blockchain! Now we need to implement subgraph templates by altering a little bit of code prior to deploying.

Section 4: Subgraph Templating

Read the official documentation on subgraph templating here.

By default, a subgraph indexes a single hard-coded smart contract’s events. It is also able to index many hard-coded smart contracts.

But what happens when a smart contract can dynamically create many smart contracts and hard-coding is impossible as each child has a new address?

Enter subgraph templating!

Subgraph templating allows for any dynamic creation of new smart contracts to be indexed automatically by the subgraph without changing any code!

And lucky for us, implementing a subgraph template is super easy.

First, lets open up subgraph.yaml that was generated from your amazing use of the CLI.

This file gives us a high-level perspective of what our subgraph is going to be indexing.

subgraph.yaml

specVersion: 0.0.5
schema:
   file: ./schema.graphql
dataSources:
   - kind: ethereum
     name: Factory
     network: goerli
     source:
         address: "0xCd5282c80fC3829db19743628D02d0e4281D74A4"
         abi: Factory
     mapping:
         kind: ethereum/events
         apiVersion: 0.0.7
         language: wasm/assemblyscript
         entities:
             - ChildCreated
         abis:
             - name: Factory
               file: ./abis/Factory.json
         eventHandlers:
             - event: ChildCreated(uint256,string,address)
               handler: handleChildCreated
         file: ./src/factory.ts

The two edits we need to do are as such:

1. Edit the startblock

2. Implement templating

Editing the Startblock

Editing the start block will significantly accelerate the performance of your subgraph, as your subgraph will not have to search very old blocks, only the recent relevant blocks where your smart contracts have since been deployed!

Go to your Remix IDE and copy the Factory’s address:

Go to www.etherscan.io and enter that address in the search bar.

After entering the address, click on the “B” to find your smart contract on Goerli.

See how the initial startblock was “8328718”?

That is when we should start indexing our subgraph!

Copy/paste that number as such into subgraph.yaml:

subgraph.yaml

{...^ Previous Code ^ ...}
- kind: ethereum
   name: Factory
   network: goerli
   source:
     address: "0xCd5282c80fC3829db19743628D02d0e4281D74A4"
     abi: Factory
     startBlock: 8328718

Implementing Subgraph Templating

We are ready to index and query our Factory smart contract, but what about the children!?

Don’t fear! Let’s give the subgraph.yaml a “template” portion so any children that are created will dynamically be indexed!

Templating is simple.

1. Add ‘templates’ to your Child portion of your subgraph.yaml file

2. Remove the “address” from the Child portion (see the “source” of the Child and compare that source to the one above. The child has their source address removed).

subgraph.yaml

specVersion: 0.0.5
schema:
   file: ./schema.graphql
dataSources:
   - kind: ethereum
     name: Factory
     network: goerli
     source:
         address: "0xCd5282c80fC3829db19743628D02d0e4281D74A4"
         abi: Factory
         startBlock: 8328718
     mapping:
         kind: ethereum/events
         apiVersion: 0.0.7
         language: wasm/assemblyscript
         entities:
             - ChildCreated
         abis:
             - name: Factory
               file: ./abis/Factory.json
         eventHandlers:
             - event: ChildCreated(uint256,string,address)
               handler: handleChildCreated
         file: ./src/factory.ts
templates:
   - kind: ethereum
     name: Child
     network: goerli
     source:
         abi: Child
     mapping:
         kind: ethereum/events
         apiVersion: 0.0.7
         language: wasm/assemblyscript
         entities:
             - Initialized
             - MessageUpdated
         abis:
             - name: Child
               file: ./abis/Child.json
         eventHandlers:
             - event: Initialized(uint8)
               handler: handleInitialized
             - event: MessageUpdated(string,uint256)
               handler: handleMessageUpdated
         file: ./src/child.ts

The next step is to now generate your template!

Go to your terminal and enter

graph codegen

This will generate typesafety to use in our subgraph as well as a Child.ts template file based off of your subgraph.yaml updates that will be stored in your generated/templates/Child/ folder!

Lets bring that Child.ts template logic into your factory.ts mappings.

Go to your src/factory.ts file. This file is where your subgraph will handle the data emitting from the event that has occurred on the blockchain.

Here is the base factory.ts in our subgraph:

src/factory.ts

import { ChildCreated as ChildCreatedEvent } from "../generated/Factory/Factory"
import { ChildCreated } from "../generated/schema"


export function handleChildCreated(event: ChildCreatedEvent): void {
 let entity = new ChildCreated(
   event.transaction.hash.concatI32(event.logIndex.toI32())
 )
 entity.date = event.params.date
 entity.message = event.params.message
 entity.childAddress = event.params.childAddress


 entity.blockNumber = event.block.number
 entity.blockTimestamp = event.block.timestamp
 entity.transactionHash = event.transaction.hash


 entity.save()

Update the file with these two lines of code:

import { ChildCreated as ChildCreatedEvent } from "../generated/Factory/Factory";
import { ChildCreated } from "../generated/schema";
import { Child } from "../generated/templates";  { THIS LINE }


export function handleChildCreated(event: ChildCreatedEvent): void {
 let entity = new ChildCreated(
   event.transaction.hash.concatI32(event.logIndex.toI32())
 );
 entity.date = event.params.date;
 entity.message = event.params.message;
 entity.childAddress = event.params.childAddress;


 entity.blockNumber = event.block.number;
 entity.blockTimestamp = event.block.timestamp;
 entity.transactionHash = event.transaction.hash;


 entity.save();


 Child.create(event.params.childAddress) { THIS LINE } 
}

These edits import the Child template, then pass in the childAddress to that Child template.

The template in subgraph.yaml now has that childAddress which means it can begin indexing that brand new address any time ChildCreated is run!

Now run this in terminal:

graph codegen && graph build

Now you’re ready to deploy the subgraph!

Go back to your www.thegraph.com subgraph page and copy/paste your “deploy subgraph” code into your terminal.

You’ve done it!

To start playing around with your subgraph, head over to the subgraph Playground. Use the Explorer button on the right to identify the events you’d like to query.

Design your query and you’ve got your data coming from the blockchain!

You can see what your Factory is doing by looking up “childsCreated”.

You can see what your children have been doing by looking up “messageUpdateds”.

These exact same steps you used in this tutorial can be used to deploy this on Ethereum mainnet if you’d like your contract and subgraph to be officially recognized on the Ethereum blockchain and not on a testnet.

Thank you for taking the time to go through this tutorial and learning about factory patterns and dynamic templating within subgraphs.

I hope you enjoyed learning as much as I enjoyed writing this up.

Feel free to watch the video version of this tutorial here and reach out to me on twitter if you have any further thoughts or questions:

http://www.twitter.com/marcus_rein_

Take care!

Marcus Rein

TLDR? Watch the video version of this tutorial!

And here is the completed repository of this project

Imagine being able to see every single transaction that has gone through Bank of America.

All of the pseudonymized users, all of the transaction amounts, the date, the time… all of it!

Here are some analysis and datapoints that I’d be curious to see:

• What are the biggest transactions in the history of Bank of America?

• What transactions typically occur the week before and after a person books a hotel room?

• How does spending change after payday for people making between $50k and $75k?

• When interest rates go up or down, how does that affect real-estate purchases?

Now imagine you could use that data to create your own app.

Powerful stuff!

Now while we cannot access Bank of America transactional data as it is a centralized bank, we CAN do that with the decentralized Ethereum blockchain, as all of the data is public!

So let’s get to work and build a simple app based on decentralized blockchain data, also known as a “dapp.”.

Learning Objectives

By the end of the article, you should know how to:

1. Set up a Python web server with Flask

2. Access blockchain data through an API known as a Subgraph - powered by The Graph Protocol

3. Present this blockchain data clearly in a table.

4. Take what you’ve learned and build your own custom dapp!

What We Are Building

Our dapp is going to find the biggest swaps ever performed on the token exchange, Uniswap.

Let’s name it Top Swaps!

Here is what our dapp will look like when completed:

What is Uniswap?

Uniswap is an exchange built on the Ethereum blockchain, which means that it allows users to easily interact with blockchain transactions of tokens. This is similar to how the New York Stock Exchange allows individuals to quickly and easily exchange stocks, Uniswap allows individuals to quickly and easily exchange tokens.

Personally, I'm a HUGE fan of Uniswap as it doesn’t ask its users to trust the custody of their tokens to a centralized exchange, such as with FTX (and we all saw what happens when a centralized exchange takes these private keys to do illicit things!).

All users retain full security within their accounts, and the code is fully open-sourced for auditing.

To read more about Uniswap, check out this article:

https://www.coindesk.com/business/2021/02/04/what-is-uniswap-a-complete-beginners-guide/

Lets Build!

Set Up Your Virtual Environment

In your code editor, open up your terminal and create a virtual environment.

In python (and many other languages), it’s best practice to use virtual environments as they keep your installed packages separate from your other projects. To read more on why virtual environments are amazing, check out this article: https://www.geeksforgeeks.org/python-virtual-environment/

Let's create a new virtual environment.

python3 -m venv .venv

Nice! .venv is your new virtual environment!

Now we have to activate the virtual environment.

If you are working in Linux or Mac, you’ll use this:

source .venv/bin/activate

If you’re on windows, you can activate your virtual environment using this:

.venv/bin/activate.bat

Install Dependencies

Our dapp requires the following items to be installed in our virtual environment.

• Flask - the python webserver we will be using

  • Documentation: https://flask.palletsprojects.com/en/2.2.x/

  • Short video introduction: https://www.youtube.com/watch?v=2BbuB8QP1D4

• Dotenv - allows our dapp to pass secure information around our files safely

  • Documentation: https://pypi.org/project/python-dotenv/

  • Short video introduction: https://www.youtube.com/watch?v=ryVzkQAtpKQ

• GraphQL Client - allows for our python app to make GraphQL queries

  • Documentation: https://github.com/graphql-python/gql

• JsonToHTML - takes a Json file and converts it to a HTML table

  • Documentation: https://pypi.org/project/json2html/

To install all of these at once, use this command:

pip install Flask python-dotenv json2html

As well as:

pip install ‘gql[all]’

Start our Flask Server

In your home directory of subgraph-to-dapp, create a file called app.py

Copy/paste this code into the file.

This code imports what is required to run our dapp as well as starts the Flask server when Flask is run.

from flask import Flask, render_template, request
from dotenv import load_dotenv
from json2html import *
from gql import Client, gql
from gql.transport.aiohttp import AIOHTTPTransport
import os

app = Flask(__name__)
if __name__ == '__main__':
   app.run()

Now let’s tell Flask that this file is the main file that should run when Flask is activated by entering this code in the terminal:

export FLASK_APP=app.py

Let's also tell Flask that it should be in Debug Mode, which means it will quickly restart the server any time we change the code so we don’t have to manually restart it.

export FLASK_DEBUG=1

We now have a server ready to run! But before we run it, let’s set up a simple landing page so we can actually see if our server is running properly.

Connecting our Server to Our Front End

Add this code below the code you have previously written:

@app.route("/", methods=["GET", "POST"])
def index():
   return render_template('index.html')

Now create a folder in your subgraph-to-dapp directory named templates and create a file called index.html

Your project structure should look something like this:

Copy paste this code into index.html:

<!DOCTYPE html>
<html lang="en">
   <head>
       <meta charset="UTF-8" />
       <meta http-equiv="X-UA-Compatible" content="IE=edge" />
       <meta name="viewport" content="width=device-width, initial-scale=1.0" />
       <title>Top Swaps</title>
   </head>
   <body>
       <h1>Testing our server!</h1>
   </body>
</html>

We now have a basic landing page ready to connect to our Flask server.

Now let's run our Flask server!

flask run

You should see this code! Your server is running!

Check the website it suggests http://127.0.0.1:5000/ to see if your index.html is also working properly.

It works!

Create a Form For User Input

The users of Top Swaps will input how many Top Swaps they would like to see and Top Swaps will dynamically update to provide that data.

To do this, we need to update our index.html to have a form that will get the input that we need from the user:

<!DOCTYPE html>
<html lang="en">
   <head>
       <meta charset="UTF-8" />
       <meta http-equiv="X-UA-Compatible" content="IE=edge" />
       <meta name="viewport" content="width=device-width, initial-scale=1.0" />
       <title>Top Swaps</title>
   </head>
   <body>
       <form method="post">
           <h1>
               Want to see the Top Swaps in the history of Uniswap? Enter the number of Top Swaps you want to see!
           </h1>
           <p><input type="number" name="top_swap_count" /></p>
           <p><input type="submit" value="submit" /></p>
       </form>
   </body>
</html>

We added some context as well as created an input and submit component that is tagged with

name="top_swap_count"

Which will allow our app.py to both recognize and import the inputted value so it can be processed.

If you check your webpage, it should update to look like this:

Congratulations! You have set up your Flask server as well as your input fields for your users!

Connecting our Server to the Uniswap Subgraph

The blockchain is a HUGE public database that is not easily accessed. In the past, searching blockchain data was terribly costly and time-consuming.

Luckily, The Graph (www.thegraph.com) has done the hard work of creating a system that allows developers easy and affordable access to this data.

You access this blockchain data through an API they developed called a Subgraph.

Subgraphs can access different parts of the Ethereum blockchain depending on how the Subgraph is designed.

The Graph has two types of Subgraphs:

Hosted, and Decentralized.

1. Hosted: a centralized Subgraph that is hosted by The Graph

2. Decentralized: a Subgraph that is published on the The Graph Network, the decentralized network of indexers around the world!

Read more about The Graph, Subgraphs, and The Graph Network at https://thegraph.com/docs/en/

Lets go to The Graph Explorer page and find the Uniswap V3 Decentralized Subgraph which allows access to Uniswap blockchain data, then design our GraphQL query for our dapp.

Designing our GraphQL Query Using Subgraph Playground

Go to the Playground button.

This will show you a wonderful GraphQL interface that will allow you to easily query the Subgraph in small test queries that you might want to use in your dapp!

Read more about GraphQL here: https://graphql.org/

Press the big “Play” button in the middle of the page to run a test query that’s prepopulated with a “tokens” and “rewardTokens” query.

This Subgraph is reading from the Ethereum blockchain and the data is ready to be used by you! This would be impossible with current banking institutions such as Bank of America!

Let’s click on this button on the right of the Playground where we can design our query to find the Top Swaps of this Subgraph:

Let’s design our Top Swaps query! We want to know:

• The value of the token transaction

• Who its from and who it's going to

• When it occurred

• The names of the tokens swapped

Click around the Explorer tab and create a GraphQL query that contains this information. Once completed, your GraphQL query should look like this:

You can test your GraphQL query once you’re done by clicking the big “Play” button in the middle of the Playground.

Perfect. This is the data that we need!

Let’s copy the GraphQL query we designed and bring it into our app as a variable so we can use it!

Our app.py file should now look this:

app = Flask(__name__)
if __name__ == '__main__':
  app.run()
  
subgraph_gql_query = """
   {
   swaps(orderBy: amountInUSD, orderDirection: desc, first: 10) {
       amountInUSD
       from
       to
       timestamp
       tokenIn {
       name
       }
       tokenOut {
       name
       }
   }
   }
"""


@app.route("/", methods=["GET", "POST"])
def index():
   return render_template('index.html')

Great! Now we have the query variable we want for our dapp.

Accessing A Subgraph’s Endpoint

Now let’s find the Uniswap Subgraph endpoint address where we can send our beautifully designed query:

1. Go to the Uniswap V3 Ethereum Subgraph found on Subgraph Explorer (at the time of writing this article, this is the most current link though it might be updated to a newer subgraph by now. Go search Subgraph Explorer to confirm!)

2. Click the “Query” button in the top right corner and bring that link into your app.py workspace.

3. Copy the Query URL and bring it into your app.py file.

Your app.py should look like this:

from flask import Flask, render_template, request
from dotenv import load_dotenv
from json2html import *
import requests
import json
import os


app = Flask(__name__)
if __name__ == '__main__':
  app.run()


subgraph_endpoint = 'https://gateway.thegraph.com/api/[api-key]/subgraphs/id/ELUcwgpm14LKPLrBRuVvPvNKHQ9HvwmtKgKSH6123cr7'


query = """
   {
   swaps(orderBy: amountInUSD, orderDirection: desc, first: 10) {
       amountInUSD
       from
       to
       timestamp
       tokenIn {
       name
       }
       tokenOut {
       name
       }
   }
   }
"""


@app.route("/", methods=["GET", "POST"])
def index():
   return render_template('index.html')

We now have the endpoint address of the Uniswap Subgraph to which we will be sending our Playground-designed query!

Retrieving and Implementing our API Key Securely

The Uniswap Subgraph has a “lock” on it to keep it secure.

To open this lock and use the Subgraph, we need an API Key. Let's go get that key!

• Click “Manage API Keys”

Create and connect your Metamask wallet if you haven’t already. Think of this as your own personal wallet - keep it SECURE!

• https://metamask.io/

• What is Metamask? https://www.youtube.com/watch?v=YVgfHZMFFFQ

Create your first API key

The Graph gives you 1000 free queries with your first API key! Let’s use those queries to test out our new dapp.

Create a .env file in your home directory, then put your API Key in there. Your file structure should look something like this:

We’ll be implementing environment variable security with this .env file. If you don’t know about this concept, you need to watch the video links below!

To implement this security, include these final steps to your project:

• Use dotenv() to secure this API Key in your .env file by following these video or written instructions:

  • Video tutorial:Using Python Dotenv to Manage Environment Variables

  • Written tutorial: https://paulapivat.com/technical_notes/example_tech/python_dotenv/

• After you’ve set up your dotenv(), lets import that key into our query url by using f-strings

  • F-strings: https://www.geeksforgeeks.org/formatted-string-literals-f-strings-python/

• Your app.py Environment Variable code should look something like this when finished with this section.

I’ve added a print() function to confirm that your API key is being imported correctly.

# Environment Variable Management
load_dotenv()
api_key = os.getenv('SUBGRAPH_API')
subgraph_endpoint = f'https://gateway.thegraph.com/api/{api_key}/subgraphs/id/ELUcwgpm14LKPLrBRuVvPvNKHQ9HvwmtKgKSH6123cr7'


print('This is my API key: ' + api_key)

AMAZING!

We’ve got our API key into the dapp!

Let’s make our query accept the number that we have in our front end

Running our Query Through the Uniswap Subgraph

Let’s go back to app.py and start building out the logic that creates Top Swaps!

To begin passing our GraphQL query, we should use the GraphQL Client we imported earlier!

As per the GraphQL Client documentation, the client needs a “transport” and “client” variable written right below our Environment Variable Management.:

# Environment Variable Management
load_dotenv()
api_key = os.getenv('SUBGRAPH_API')
subgraph_endpoint = f'https://gateway.thegraph.com/api/{api_key}/subgraphs/id/ELUcwgpm14LKPLrBRuVvPvNKHQ9HvwmtKgKSH6123cr7'

transport = AIOHTTPTransport(
   url=subgraph_endpoint
)

client = Client(
   transport=transport,
   fetch_schema_from_transport=True,
)

Lets update our GraphQL query that we found previously to be dynamically updated by wrapping it in a function as such, written below your previous code:

load_dotenv()
api_key = os.getenv('SUBGRAPH_API')
subgraph_endpoint = f'https://gateway.thegraph.com/api/{api_key}/subgraphs/id/ELUcwgpm14LKPLrBRuVvPvNKHQ9HvwmtKgKSH6123cr7'

transport = AIOHTTPTransport(
   url=subgraph_endpoint
)

client = Client(
   transport=transport,
   fetch_schema_from_transport=True,
)

def update_subgraph_query(input_number):
   subgraph_gql_query = gql(
               """
               {
               swaps(orderBy: amountInUSD, orderDirection: desc, first: replaceMe) {
                   amountInUSD
                   from
                   to
                   timestamp
                   tokenIn {
                   name
                   }
                   tokenOut {
                   name
                   }
               }
               }
           """.replace('replaceMe', input_number))
   return subgraph_gql_query

You’ll see now that this function takes an input_number and dynamically puts that number into the GraphQL query before returning the updated query. Amazing!

Let’s take our newly updated query and query the subgraph, then save it as a new variable, ‘response’, then print its contents:

@app.route("/", methods=["GET", "POST"])
def index():
   if request.method == "POST":
       swapInputNumberData = request.form["top_swap_count"]
       subgraph_gql_query_result = update_subgraph_query(swap_input_number_data)
       response = client.execute(subgraph_gql_query_result)
       print(response)


       return render_template('index.html')

Enter and submit a number in your webpage:

Boom! You should see your data in your terminal!

Let's take our data and bring it into Top Swaps front-end!

Update your index.html with this code:

<!DOCTYPE html>
<html lang="en">
   <head>
       <meta charset="UTF-8" />
       <meta http-equiv="X-UA-Compatible" content="IE=edge" />
       <meta name="viewport" content="width=device-width, initial-scale=1.0" />
       <title>Top Swaps</title>
   </head>
   <body>
       <form method="post">
           <h1>
               Want to see the Top Swaps in the history of Uniswap? Enter the
               number of Top Swaps you want to see!
           </h1>
           <p><input type="number" name="top_swap_count" /></p>
           <p><input type="submit" value="submit" /></p>
       </form>
       <div>{{ response }}</div>
   </body>
</html>

Enter and submit a number in your dapp. Boom! All of your data should be present on your dapp’s front-end.

Now let's take that data and make it pretty!

1. Add this single line of code below our response variable that will first properly format, then convert our data into a nice table.

2. Also update the return to json_table to reflect we’ve converted the data into a table!

@app.route("/", methods=["GET", "POST"])
def index():
   if request.method == "POST":
       swap_input_number_data = request.form["top_swap_count"]
       subgraph_gql_query_result = update_subgraph_query(swap_input_number_data)
       response = client.execute(subgraph_gql_query_result)
       json_table = json2html.convert(json = response)
     
       return render_template('index.html', json_table = json_table)
   else:
       return render_template('index.html')

3. In index.html, replace {{ response }} with  {{ json_table | safe }} to allow the HTML to run properly in our dapp.

<!DOCTYPE html>
<html lang="en">
   <head>
       <meta charset="UTF-8" />
       <meta http-equiv="X-UA-Compatible" content="IE=edge" />
       <meta name="viewport" content="width=device-width, initial-scale=1.0" />
       <title>Top Swaps</title>
   </head>
   <body>
       <form method="post">
           <h1>
               Want to see the Top Swaps in the history of Uniswap? Enter the number of Top Swaps you want to see!
           </h1>
           <p><input type="number" name="top_swap_count" /></p>
           <p><input type="submit" value="submit" /></p>
       </form>
       <div>{{ json_table | safe }}</div>
   </body>
</html>

This data is now formatted in a super nice table!

We’re done!

You created your first dapp!

Hopefully this was helpful in getting you started in dapp development.

Here is the completed repository for you to look over: https://github.com/marcusrein/subgraph-to-dapp

Feel free to reach out and happy developing!

–

Marcus Rein

http://www.twitter.com/marcus_rein_