• 24 Jan 2022
  • 4 Minutes to read
  • Dark


  • Dark

For any dApp to provide good UX, you need a solution that quickly loads the data stored on chain and on IPFS. Querying data directly from blockchain is complex. This is where the middleware comes in, which is essentially a layer in between blockchain and your dApp, allowing you to index and query your blockchain data easily and efficiently.

The Graph & subgraphs

At the heart of our middleware solution is the The Graph, a protocol for indexing and querying blockchain data from networks. It can be used with all EVM-compatible chains like Ethereum, Polygon, Binance Smart Chain and Avalanche. You can run it on your own blockchain nodes (both public and permissioned) and IPFS nodes.

Using the Graph protocol, you can create subgraphs that define which blockchain data will be indexed. These subgraphs are defined in the smart contract set and deployed to the middleware. The middleware will then use these subgraphs to correctly index your smart contracts and expose a developer-friendly and efficient GraphQL API, allowing you to query the data you need.

The middleware is fully preconfigured and integrated with the smart contract sets. We have some prebuild subgraph indexing modules, but you can build your own modules if you have a custom smart contract set.

Before you start, make sure you are running:
  • An EVM-compatible network (Ethereum, Polygon, Binance Smart Chain or Avalanche)
  • A smart contract set
  • An IPFS node

Follow the steps below to start using the middleware.

Step 1: Add the middleware

Navigate to the application where you want to add the middleware. Click Middleware in the left navigation, and then click Add a middleware. This opens a form.

Follow these steps to add the middleware:

  1. Select to which of your smart contract sets the middleware needs to connect, and click Continue.
  2. Choose the Graph Middleware.
  3. Choose a Middleware name. Choose one that will be easily recognizable in your dashboards.
  4. Select the storage provider, in this case IPFS.
  5. Choose a deployment plan. Select the type, cloud provider, region and resource pack. More about deployment plans.
  6. You see the resource cost for this middleware displayed at the bottom of the form. Click Confirm to add the smart contract set.

When the middleware is deployed, the next step (see below) is to define the indexing specifications in the subgraph, and load it into the middleware. This happens in the IDE of your smart contract set.

Step 2: Define and deploy a subgraph

Navigate to the smart contract set that you connected to the middleware, go the details and open the IDE. Here you will define the subgraph to set the indexing specifications, and deploy it so it can be loaded into the middleware.

Subgraph raw configuration

Inside the root you will find a file called subgraph.config.template.json that contains the raw configuration of the subgraph. The important section is the datasources section.

  • Name - here we defined the smart contracts with their name (the name of the artifact created in the 'deployments' folder when running the deploy task)
  • Address & Startblock - You will notice the startblock and address to be 0. These will be filled in using the graph:config task based on the hardhat deployments.
  • Module - In the modules array all the indexing modules to activate for this smart contract.

About the indexing modules

We provide two libraries of indexing modules: one by the OpenZeppelin team for all the common smart contracts in their smart contract library, and one by the SettleMint team to extend the capabilities of the OpenZeppelin one, and to provide indexing of the specific SettleMint smart contract sets.

The OpenZeppelin set contains the following indexing modules:

  • accesscontrol
  • erc1155
  • erc1967upgrade
  • erc20
  • erc721
  • governor
  • ownable
  • pausable
  • timelock
  • voting

The SettleMint set contains the following indexing modules:

  • erc721ipfs: to extend the erc721 from OpenZeppelin to index IPFS metadata of your erc721 tokens

You can also write your own custom indexing module for smart contracts that are not part of the default sets. Follow these steps to create a custom indexing module:

  • Primitives to generate a GraphQL schema: subgraph/datasource/x.gql.json - In order to allow composability, the schema are not defined in the GraphQL format but rather in a dedicated JSON format which is can be assembled and compiled to GraphQL.
  • Template to generate a subgraph manifest: subgraph/datasource/x.yaml - This file lists all the events that the datasources should listen to, and links that to the corresponding indexing logic.
  • Indexing logic: subgraph/datasources/x.ts and (optionally) subgraph/fetch/x.ts - This is the core logic that processes the events and to index the onchain activity.

To learn more, check it out on Github.

Tweak the subgraph configuration

You can tweak the subgraph.config.template.json file to your liking, and run the graph:config task. This will generate subgraph.config.json for the next steps.

The following tasks need to be run in this sequence:

  • graph:compile - Uses subgraph.config.json to generate the GraphQL schema and subgraph configuration.
  • graph:codegen - Generates the AssemblyScript types for your contracts ABI based on the output of graph:compile.
  • graph:build - Compiles the WASM files based on the outputs generated by graph:codegen.
  • graph:deploy - Deploys the WASM files to IPFS and updates the middleware to start or update the indexing.

The middleware is now updated and ready to start indexing the data.

Step 3: Start using the middleware

Navigate back to the middleware.

The indexing of your smart contracts has now started. This can take a while, but once done you can query the middleware for your data in seconds using the GraphQL API. You can find the endpoint in the Connect-tab.

Was this article helpful?

What's Next