From 021ee94bbef38f34d52bd4bc830b89a311542b3e Mon Sep 17 00:00:00 2001 From: Pedro Diogo Date: Tue, 28 Oct 2025 00:20:11 +0000 Subject: [PATCH 1/3] Add subgraphs arbitration policy documentation - 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 --- README.md | 1 + docs/subgraphs-arbitration-policy.md | 76 ++++++++++++++++++++++++++++ 2 files changed, 77 insertions(+) create mode 100644 docs/subgraphs-arbitration-policy.md diff --git a/README.md b/README.md index 2bf3c67..11779bd 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,7 @@ This repository manages a registry of networks in The Graph ecosystem. See [Releases](https://github.com/graphprotocol/networks-registry/releases) page for the latest version of the registry. See [Networks Table](./docs/networks-table.md) for an up-to-date auto-generated networks list. +See [Subgraphs Arbitration Policy](./docs/subgraphs-arbitration-policy.md) for information about network arbitration support. [Libraries](https://github.com/pinax-network/graph-networks-libs) for Typescript, Go and Rust. diff --git a/docs/subgraphs-arbitration-policy.md b/docs/subgraphs-arbitration-policy.md new file mode 100644 index 0000000..d297e63 --- /dev/null +++ b/docs/subgraphs-arbitration-policy.md @@ -0,0 +1,76 @@ +# Network Arbitration Policy for Subgraphs + +> **Note**: This policy applies to **subgraphs** specifically. The Networks Registry tracks multiple Graph services (subgraphs, firehose, substreams, token API), but arbitration is currently only applicable to subgraph indexing and querying. + +## What is Arbitration? + +Arbitration is The Graph Network's dispute resolution system for subgraphs. It allows fishermen to challenge indexers who provide incorrect query responses or Proofs of Indexing (POIs). If proven incorrect, the indexer is penalized (slashed) and the fisherman receives a reward. + +This system ensures data integrity and indexer accountability on The Graph Network. + +For complete details, see: +- [GIP-0008: Timeline for Sunsetting Hosted Service](https://snapshot.org/#/council.graphprotocol.eth/proposal/0xbdd884654a393620a7e8665b4289201b7542c3ee62becfad133e951b0c408444) - Introduced the Feature Support Matrix +- [Arbitration Charter](https://github.com/graphprotocol/graph-improvement-proposals/blob/main/gips/0009-arbitration-charter.md) - Detailed arbitration rules and procedures + +## Default Rule + +Networks with indexing rewards (`issuanceRewards: true`) support both query and indexing arbitration on The Graph Network unless explicitly documented as exceptions in the [Feature Support Matrix](https://github.com/graphprotocol/indexer/blob/main/docs/feature-support-matrix.md). + +This is a bidirectional relationship: +- **Indexing rewards enabled** → Arbitration support enabled +- **Arbitration support enabled** → Indexing rewards enabled + +## Checking Arbitration Support + +To verify if a network supports arbitration: + +1. Check the [Networks Table](./networks-table.md) +2. Look for ✅ in the **"Indexing Rewards"** column +3. If ✅ present → Network has full arbitration support (query + indexing) +4. If no ✅ → Network does not have arbitration support +5. For rare exceptions, check the [Feature Support Matrix](https://github.com/graphprotocol/indexer/blob/main/docs/feature-support-matrix.md) + +## Examples + +### Networks with Arbitration Support + +- **Ethereum** (`issuanceRewards: true`) → ✅ Full arbitration support +- **Arbitrum One** (`issuanceRewards: true`) → ✅ Full arbitration support +- **Polygon** (`issuanceRewards: true`) → ✅ Full arbitration support +- **Gnosis** (`issuanceRewards: true`) → ✅ Full arbitration support + +### Networks without Arbitration Support + +- **Near** (`issuanceRewards: false`) → ❌ No arbitration support +- **Solana** (`issuanceRewards: false`) → ❌ No arbitration support +- **Bitcoin** (`issuanceRewards: false`) → ❌ No arbitration support + +## Governance + +Per [GGP-0062](https://snapshot.org/#/s:council.graphprotocol.eth/proposal/0x4eff14202f6204c0927860a9adff865fce33c32b6cbe7054227457631ee261b9): + +**Network-level (managed in this registry)**: +- **The Graph Foundation** (with Technical Advisory Board review) has authority to add or remove indexing rewards for networks via the `issuanceRewards` field +- Since indexing rewards determine arbitration support, this authority also controls network arbitration eligibility + +**Feature-level (managed in Feature Support Matrix)**: +- **The Graph Council** can determine which new graph-node features or data source types are eligible for indexing rewards and arbitration +- These decisions are documented in the [Feature Support Matrix](https://github.com/graphprotocol/indexer/blob/main/docs/feature-support-matrix.md) + +## Relationship with Feature Support Matrix + +Historically, both network support and indexing rewards were documented in the [Feature Support Matrix](https://github.com/graphprotocol/indexer/blob/main/docs/feature-support-matrix.md) in the indexer repository. This created duplication with the Networks Registry. + +**New approach (established by this documentation)**: +- **Networks Registry** (`issuanceRewards` field) = Source of truth for which networks have indexing rewards +- **Feature Support Matrix** = Documents graph-node features and arbitration rules, references registry for network-level data + +This separation eliminates duplication and clarifies ownership: network metadata lives in the registry, graph-node behavior lives in the feature matrix. + +## Related Documentation + +- [Feature Support Matrix](https://github.com/graphprotocol/indexer/blob/main/docs/feature-support-matrix.md) - Graph-node features and arbitration policy +- [Networks Table](./networks-table.md) - Complete list of supported networks +- [GIP-0008](https://snapshot.org/#/council.graphprotocol.eth/proposal/0xbdd884654a393620a7e8665b4289201b7542c3ee62becfad133e951b0c408444) - Introduced the Feature Support Matrix +- [Arbitration Charter](https://github.com/graphprotocol/graph-improvement-proposals/blob/main/gips/0009-arbitration-charter.md) - Detailed arbitration rules and procedures +- [GGP-0062](https://snapshot.org/#/s:council.graphprotocol.eth/proposal/0x4eff14202f6204c0927860a9adff865fce33c32b6cbe7054227457631ee261b9) - Governance structure for feature matrix From 05519cefb69ef5ccbbd4369f435aeb6fb369d029 Mon Sep 17 00:00:00 2001 From: YaroShkvorets Date: Mon, 3 Nov 2025 11:48:07 -0500 Subject: [PATCH 2/3] removed extra examples --- docs/subgraphs-arbitration-policy.md | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/docs/subgraphs-arbitration-policy.md b/docs/subgraphs-arbitration-policy.md index d297e63..c1201ae 100644 --- a/docs/subgraphs-arbitration-policy.md +++ b/docs/subgraphs-arbitration-policy.md @@ -32,18 +32,8 @@ To verify if a network supports arbitration: ## Examples -### Networks with Arbitration Support - - **Ethereum** (`issuanceRewards: true`) → ✅ Full arbitration support -- **Arbitrum One** (`issuanceRewards: true`) → ✅ Full arbitration support -- **Polygon** (`issuanceRewards: true`) → ✅ Full arbitration support -- **Gnosis** (`issuanceRewards: true`) → ✅ Full arbitration support - -### Networks without Arbitration Support - - **Near** (`issuanceRewards: false`) → ❌ No arbitration support -- **Solana** (`issuanceRewards: false`) → ❌ No arbitration support -- **Bitcoin** (`issuanceRewards: false`) → ❌ No arbitration support ## Governance From 66d8a33f445288829bf7fab9d829dea0ad605ac1 Mon Sep 17 00:00:00 2001 From: YaroShkvorets Date: Mon, 3 Nov 2025 12:23:56 -0500 Subject: [PATCH 3/3] add updating rewards procedure --- docs/subgraphs-arbitration-policy.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/subgraphs-arbitration-policy.md b/docs/subgraphs-arbitration-policy.md index c1201ae..47b6e50 100644 --- a/docs/subgraphs-arbitration-policy.md +++ b/docs/subgraphs-arbitration-policy.md @@ -47,6 +47,13 @@ Per [GGP-0062](https://snapshot.org/#/s:council.graphprotocol.eth/proposal/0x4ef - **The Graph Council** can determine which new graph-node features or data source types are eligible for indexing rewards and arbitration - These decisions are documented in the [Feature Support Matrix](https://github.com/graphprotocol/indexer/blob/main/docs/feature-support-matrix.md) +### Updating Indexing Rewards in the Registry +When adding/removing indexing rewards to networks, the following steps must be taken: +1. PR with the updated `issuanceRewards` field is opened by the maintainers or the Foundation +2. PR is reviewed by the maintainers +3. Transaction enabling/disabling rewards is executed on chain +4. PR is merged by the maintainers or the Foundation, and the registry is published + ## Relationship with Feature Support Matrix Historically, both network support and indexing rewards were documented in the [Feature Support Matrix](https://github.com/graphprotocol/indexer/blob/main/docs/feature-support-matrix.md) in the indexer repository. This created duplication with the Networks Registry.