Subgraphs

Modules for easily indexing OpenZeppelin Contracts activity.

Install from npm as @openzeppelin/subgraphs.

Browse on GitHub at OpenZeppelin/openzeppelin-subgraphs.

Usage

Subgraph are described using three components:

  • The graphql schema, usually named schema.graphql, which describes the database entities and links.

  • The subgraph manifest, usually named subgraph.yaml, which describes the activity that should be listened to (addresses of contracts, events handlers, function handlers).

  • The indexing logic, written in assembly script, which will process the blockchain activity and update the database accordingly.

OpenZeppelin Subgraphs provide schemas description, with the corresponding indexing logic and templates for building your subgraph manifest.

Similarly to how OpenZeppelin Contracts provide solidity code containing sets of features that one can assemble to ease building an application, OpenZeppelin subgraphs provides modules dedicated to indexing the activity corresponding to these features. These modules can be composed to index complex onchain activity without the need to actually write the indexing logic for most of the features.

Building your manifest

You can build a manifest for your application using the templates provided for each module. These templates are available in src/datasource/<module-name>.yaml. For each datasource, you will have to fill in the name, network, address, and startBlock of your contract. If a contract implements multiple modules, you will want to have multiple datasources listenning to the same address (one per module).

Note: For the indexing logic to work you will have, for each module used, to name one of your datasources with the name of the module.

The @amxx/graphprotocol-utils provides tooling to automate the generation of manifests.

Assembling your schema

Depending on the modules you are using, your schema will have to include the corresponding entities. Assembling a schema can be difficult since graphql schema do not natively support import and merging operations. We do provide precompiled schemas for each module in generated/<module-name>.schema.graphql. We also provide a schema that includes all the entities for all the modules in generated/all.schema.graphql.

Similar to the manifest, @amxx/graphprotocol-utils provides tooling to automate the generation of schemas.

Modules

Module name Availability

erc20

✔

erc20votes

Planned

erc721

✔

erc777

Planned

erc1155

✔

erc1967upgrade

✔

ownable

✔

accesscontrol

✔

pausable

✔

timelock

✔

governor

✔

Usage example

By combining multiple modules and datasources in your subgraph, you can build query such as the following one, which check the details of an ERC20 token with AccessControl on top of it, and returns the balance of the administrators.

{
  erc20Contract(id: "<erc20-with-accesscontrol-address-in-lowercase>") {
    name
    symbol
    decimals
    totalSupply { value }
    asAccount {
      asAccessControl {
        admins: roles(where: { role: "0x0000000000000000000000000000000000000000000000000000000000000000" }) {
          members {
            account {
              address: id
              balance: ERC20balances(where: { contract: "<erc20-with-accesscontrol-address-in-lowercase>" }) {
                value
              }
            }
          }
        }
      }
    }
  }
}
Automatic generation →