Skip to content

Conversation

@p-diogo
Copy link
Contributor

@p-diogo p-diogo commented Oct 28, 2025

Problem

The issuanceRewards field exists in network JSON files but lacks documentation about:

  • Its importance in The Graph ecosystem
  • Who has authority to modify it
  • Why other repositories reference it

Meanwhile, this data is duplicated in the indexer repo's Feature Support Matrix, creating maintenance burden when networks are added or updated.


Proposed solution

Add documentation establishing this registry as the canonical source for the issuanceRewards field. This allows other repositories (like the indexer repo) to reference this registry instead of maintaining duplicate copies of network data.


Changes

New documentation (docs/subgraphs-arbitration-policy.md):

  • Documents what issuanceRewards means in The Graph ecosystem
  • Explains who manages this field (Foundation + TAB per GGP-0062)
  • Clarifies how this field is used by other parts of the ecosystem (subgraph indexing and dispute resolution)
  • Provides historical context on the duplication problem and the solution

Updated README:

  • Add link to the new documentation

Why Arbitration Documentation?

TL;DR: This adds new docs on arbitration because we're restructuring how the Feature Support Matrix works (and cleaning it up), and this registry should now become the central reference point.

The Feature Support Matrix in the indexer repo currently documents both:

  1. Graph-node features (its primary purpose)
  2. Network indexing rewards (duplicates this registry)

We're splitting these concerns:

  • This registry = Source of truth for network data (issuanceRewards)
  • Feature Support Matrix = Source of truth for graph-node features

The arbitration policy doc explains how issuanceRewards is used in the broader ecosystem (specifically for subgraph dispute resolution), which helps users understand why this field matters and why the Feature Support Matrix references it.


Review Notes

This is purely additive documentation:

  • ✅ No schema changes
  • ✅ No breaking changes
  • ✅ No changes to existing issuanceRewards values
  • ✅ Just documents what the field means and who manages it

Corresponding PR on the feature support matrix: graphprotocol/indexer#1143

- Clarify this applies to subgraphs specifically (registry tracks multiple services)
- Explain what arbitration is and its purpose
- Document historical duplication with Feature Support Matrix
- Establish registry as source of truth for issuanceRewards
- Clarify governance structure per GGP-0062
- Add references to GIP-0008 and Arbitration Charter
- Update README with link to new documentation
- Part 1 of feature matrix simplification effort
@YaroShkvorets
Copy link
Collaborator

@p-diogo How do we plan to update this field? The way it works right now, basically on every PR and on every daily maintenance check we validate that the list of chains with rewards in the registry matches with EBO subgraph, and flag if not, prompting to update the registry.

I suppose going forward the process could look like this:

  1. chain is approved for rewards
  2. PR into registry is created (by somebody from Foundation or InfraDAO?)
  3. Transaction enabling rewards is executed
  4. PR is merged and registry is published

Makes sense?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants