A process for specifying the subgraph API version and feature support matrix

As mentioned at The Graph Protocol Townhall last week, I’ve been working on a GIP for a process to more clearly specify what the official behavior of the subgraph API should be in the protocol, and how the respective features of the subgraph API relate to supported functionality in the protocol.

This is especially salient as, during the recent subgraph migration, some subgraphs have been deployed that include features only partially supported in the protocol.

The GIP can be found on the branch zerim/subgraph-api-versioning in the GIPs repo. For convenience, the Abstract and Motivation of the GIP are pasted below.

There are still a couple of sections that are WIP, but any feedback at this stage is welcome!


This proposal defines a process for defining the canonical behavior of the subgraph API in the protocol as well as establishing the matrix of subgraph API features and their corresponding supported protocol features.


A core value proposition of The Graph, as a decentralized protocol for indexing and querying public data is that a Consumer can trust the integrity of the work performed by the network, with minimal or zero trust in any individual Indexer. There are a number of techniques for achieving this with varying degrees of trust minimization. These include off-chain reputation systems as well as mechanisms that may be combined with slashing such as arbitration, refereed games and cryptographic fraud or validity proofs.

In general, the more trustless the mechanism, the greater the research and engineering effort required to implement it. This proposal therefore describes a support matrix comprising which subgraph API features can be used in conjunction with which features of the protocol, as determined by the strength of the techniques available for guaranteeing the integrity of said features. Having this granular support matrix allows new subgraph API features to be continuously and immediately added to the protocol with additional protocol features supported for those features in later stages–all while driving query volume for these features to the decentralized network, as opposed to any centralized services that might be used to expose these features.

Additionally, all the mentioned techniques with the notable exception of reputation systems, require that the work that Indexer perform be defined deterministically. Therefore, this proposal also describes how a canonical version of the subgraph API may be established via decentralized governance. This is a hard requirement for supporting protocol features such as disputing and slashing Indexers for invalid indexing or query work.