feat: add documentation for Graph Horizon upgrade

website/next.config.js

@@ -94,6 +94,13 @@ const withNextra = nextra({
       '---7': {
         type: 'separator',
       },
+      'graph-horizon': {
+        type: 'children',
+        title: t('global.navigation.graph-horizon'),
+      },
+      '---8': {
+        type: 'separator',
+      },
       resources: {
         type: 'children',
         title: t('global.navigation.resources'),

website/src/pages/en/global.json

@@ -10,6 +10,7 @@
     "ai-suite": "AI Suite",
     "tokenApi": "Token API",
     "indexing": "Indexing",
+    "graph-horizon": "Graph Horizon",
     "resources": "Resources",
     "archived": "Archived"
   },

website/src/pages/en/graph-horizon/_meta.js

@@ -0,0 +1,5 @@
+export default {
+  overview: '',
+  'what-changes': '',
+  'migration-guide': '',
+}

website/src/pages/en/graph-horizon/migration-guide.mdx

@@ -0,0 +1,45 @@
+---
+title: Graph Horizon Migration Guide
+sidebarTitle: Migration Guide
+---
+
+For updated progress and schedule for the upgrade please [Graph Horizon: Mainnet schedule](https://www.notion.so/edgeandnode/Graph-Horizon-Mainnet-schedule-2928686fc7c28058b906fb6c6dfbdb63?source=copy_link).
+
+## Who Needs to Take Action?
+
+The Graph Horizon upgrade has been designed to minimize disruption across the network. Here's what different participants need to know:
+
+### Indexers
+
+**Action Required**: Indexers must upgrade their infrastructure to support Graph Horizon.
+
+The upgrade involves updating indexer software components and infrastructure to be compatible with the new Horizon architecture.
+
+🚨 **Important**: Graph Horizon is a breaking change to the protocol. Indexers who do not upgrade will eventually lose access to indexing rewards and query fees. Existing allocations opened before Graph Horizon will continue to accrue rewards and fees, but non-upgraded indexers will be unable to open new allocations.
+
+For detailed upgrade instructions, see the [Indexer Upgrade Guide](https://www.notion.so/edgeandnode/Graph-Horizon-indexer-stack-upgrade-guide-2658686fc7c2808984fbcc55e535e3b2?source=copy_link).
+
+### Delegators
+
+**No Action Required**: Delegations will continue to work seamlessly.
+
+Your delegated stake will automatically transition to the new Horizon system, specifically it will be assigned to the `SubgraphService` data service for the original indexer that was delegated to. You don't need to undelegate, re-delegate, or make any changes to your existing delegations.
+
+### Curators
+
+**No Action Required**: Curation signals will be preserved.
+
+All existing curation signals on subgraphs will remain intact and continue to function as expected in the Horizon upgrade. No action is needed from curators.
+
+### End Users & Developers
+
+**No Action Required**: Subgraph queries will continue without interruption.
+
+Applications querying subgraphs will experience no disruption. The upgrade is designed to be transparent to end users and developers building on The Graph.
+
+## Support
+
+If you have questions about the upgrade process please reach out:
+
+- [The Graph Discord](https://discord.gg/graphprotocol)
+- [The Graph Forum](https://forum.thegraph.com/)

website/src/pages/en/graph-horizon/overview.mdx

@@ -0,0 +1,48 @@
+---
+title: Graph Horizon Overview
+sidebarTitle: Overview
+---
+
+This document provides a high level overview of Graph Horizon. For a deep dive the following GIPs are recommended:
+
+- [GIP-0066: Introducing Graph Horizon - A data services protocol](https://github.com/graphprotocol/graph-improvement-proposals/blob/3da23cbba56fbd211de61f08c60b8c3e93ba5bc5/gips/0066-graph-horizon.md)
+- [GIP-0068: Subgraph Service - A subgraph data service in Graph Horizon](https://github.com/graphprotocol/graph-improvement-proposals/blob/3da23cbba56fbd211de61f08c60b8c3e93ba5bc5/gips/0068-subgraph-service.md)
+- [GIP-0085: Graph Horizon: Arbitration Charter](https://github.com/graphprotocol/graph-improvement-proposals/blob/3da23cbba56fbd211de61f08c60b8c3e93ba5bc5/gips/0085-horizon-arbitration-charter.md)
+
+The Graph Protocol is evolving with Horizon, a major upgrade that transforms the protocol into a more flexible and modular data services platform. While The Graph's core mission of organizing the world's public data remains unchanged, Horizon introduces a new architecture that enables permissionless innovation and improved economic mechanisms.
+
+This upgrade represents the next evolution of The Graph, making it more composable, efficient, and capable of supporting various types of data services beyond just subgraphs.
+
+## Graph Horizon in a nutshell
+
+The Graph Protocol as originally designed and launched back in 2021 is comprised of three distinct parts:
+
+- Staking mechanisms to provide economic security to the network
+- Payments mechanisms to allow users to pay for access to data
+- Support for the subgraphs use case
+
+The protocol achieves this goals very well however it was designed specifically with the subgraph use case in mind. This resulted in those three components being very tightly coupled, making changes to the protocol hard to do and risky, and also not providing enough flexibility to support other use cases.
+
+Graph Horizon’s main goal is to transform The Graph into a protocol capable of serving a multitude of data services, not just subgraphs. It achieves this by extracting the core functionality into primitives that can be reused by arbitrary data service implementations:
+
+- Core staking protocol
+- Core payments protocol
+- Arbitrary data service implementations
+
+These primitives can be permissionlessly composed by developers by means of the Data Service Framework.
+
+## The Data Service Framework
+
+Horizon introduces a modular Data Service Framework that allows different types of data services to be built on top of The Graph's core staking and payments infrastructure.
+
+The **`SubgraphService`** is the first and currently only data service implementation, supporting the existing functionality of indexing subgraphs and serving queries. This modular approach means that in the future, other data services could be added to support different use cases like SQL queries, data streams, or other data delivery mechanisms. A key benefit of Horizon is that new data services can be developed and deployed permissionlessly with minimal cost and development time, as they can leverage the existing staking and payments infrastructure.
+
+## Enhanced Payment System
+
+### Integrated Payments Protocol
+
+While the current protocol uses TAP (Timeline Aggregation Protocol) for payments, Horizon brings the payments infrastructure directly into the core protocol. The payments protocol in Horizon was designed as a generalized version of TAP v1, allowing integration with TAPv2 (GraphTally) but also any other arbitrary payment collection system.
+
+### GraphPayments and PaymentsEscrow
+
+A new set of contracts `GraphPayments` and `PaymentsEscrow` contracts handle the escrow and distribution of fees to all relevant parties. This contracts enforce things like the protocol tax and ensures that payments are properly distributed between data services, delegators, and indexers, making the payment process transparent.

website/src/pages/en/graph-horizon/what-changes.mdx

@@ -0,0 +1,88 @@
+---
+title: What changes with Graph Horizon?
+sidebarTitle: What's new
+---
+
+## For Indexers
+
+### Provisions: A New Way to Manage Stake
+
+Previously, when indexers staked GRT, it was automatically available for use across all protocol operations. This made sense since the protocol only supported one use case, that one of subgraphs. With Horizon, indexers must explicitly assign stake to a desired data service before it being available for operations for that specific data service. This is known as creating a data service "provision" or “provisioning stake”. This gives indexers more control over how their stake is used and which services they want to support. Once stake is “provisioned” and assigned, it’s up to the data service to work out how that stake can be utilized. For example, in the specific case of the `SubgraphService` the sequence would be as follows:
+
+- Indexer stakes GRT to the protocol
+- Indexer assigns staked GRT to the `SubgraphService` data service
+- Indexer uses (part of) provisioned stake to create allocations
+
+### Data Service Registration
+
+Registration is now handled by each data service when needed. For the `SubgraphService`, indexers register directly with it rather than using a separate `ServiceRegistry` contract. Each data service can define its own registration requirements, or may not require registration at all.
+
+### Payment Collection Changes
+
+Collecting payments, for example query fees for serving subgraphs, now requires locking a portion of stake as collateral. The amount of stake locked is determined by a `stake-to-fees` ratio - for example, collecting 10 GRT in fees might require locking 50 GRT in stake temporarily. This ensures economic security for the query services provided.
+
+### Subgraph Service: Long-Lived Allocations
+
+One of the most significant changes is the allocation lifecycle. In the current protocol, indexers must close and recreate allocations every 28 days to collect rewards. With the new `SubgraphService`, allocations can remain open indefinitely. Indexers simply present Proofs of Indexing (POIs) periodically to collect rewards without closing allocations.
+
+While allocations no longer need to be closed, indexers must now present POIs regularly to keep allocations fresh. If an allocation becomes stale due to not presenting POIs in time, the indexer forfeits rewards for that period. Unlike the current protocol where rewards can still be collected retroactively, Horizon enforces stricter timing requirements to ensure active participation.
+
+⚠️ **Important:** At Horizon launch the indexer stack will continue to operate using the current “short lived” allocation lifecycle for an easier transition. This means that allocations will be recycled typically every 28 days same as they do in the current version of the protocol. A future version of the indexer-agent will take advantage of “long lived” allocations.
+
+### Subgraph Service: legacy allocations
+
+During a transition period after the upgrade, indexers can continue to close their existing “legacy” allocations on the old system while opening new ones on the `SubgraphService`. New allocations will only be allowed to be opened using the `SubgraphService` so any indexer wanting to continue to operate would have to migrate.
+
+### Clarification on indexing rewards
+
+Horizon does not change the way indexing rewards work, the rewards formula remains the same. The only thing that changes is that in Horizon the calculation considers both legacy and horizon allocations when determining the amount of stake allocated to a subgraph. This does not change how rewards are issued nor the amount that is issued. For example, this two scenarios will have the same amount of rewards distributed:
+
+- Legacy allocation 1 with 10k GRT + Legacy allocation 2 with 10k GRT
+- Legacy allocation 1 with 10k GRT + Horizon allocation 1 with 10k GRT
+
+### Serving queries and the gateway behavior
+
+The indexer stack will support both the current and Horizon gateway infrastructure, which means with the same indexer stack version indexers will be able to serve queries before and after the Horizon upgrade. It’s worth clarifying however the gateway behavior:
+
+- Before Horizon, the gateway will serve queries using TAPv1 receipts.
+- After Horizon, the gateway will _only_ serve queries using TAPv2 (GraphTally) receipts. This means that indexers that have not upgraded their stack to Horizon will stop receiving queries. The gateway infrastructure will continue to accept old TAPv1 receipts and vouchers to ensure those can be redeemed and no fees are lost.
+
+## For Delegators
+
+### Per Data-Service Delegation
+
+Delegation is now more specific - delegators must choose both an indexer AND a data service to delegate to. This gives delegators more control and ensures their stake is only used for services they've explicitly approved. Existing delegations will automatically migrate to the `SubgraphService`.
+
+For practical purposes, The Graph's user interfaces will only support delegation to the `SubgraphService`. While Horizon's architecture allows delegation to other data services, supporting them would require UI changes or new interfaces. In the future as new data services emerge new user interfaces will likely do so, or existing ones will be upgraded to support them.
+
+### Potential Future Slashability
+
+While delegation is currently not slashable, the new system includes the capability for delegation to become slashable in the future. This would add an additional layer of economic security to the network by increasing the amount of stake at risk.
+
+Note that delegation slashing will not be enabled by default. If it is ever enabled, the system includes protection mechanisms where indexer stake would always be slashed first before any delegator funds are touched, providing a buffer for delegators.
+
+### No More Delegation Tax
+
+The 0.5% delegation tax has been completely removed, making it more economical for delegators to participate in the network.
+
+### Multiple Undelegation Requests
+
+Delegators can now have multiple undelegation requests processing simultaneously (up to 100), providing more flexibility in managing their stake.
+
+## Changes to Slashing
+
+### Flexible slashing percentage
+
+Instead of fixed slashing percentages, arbitrators now have the flexibility to determine appropriate slash amounts based on the severity and context of infractions (up to a cap of 10% of the indexer’s stake). This allows for more nuanced and fair dispute resolution. Note however that the new Arbitration Charter will recommend using a fixed slashing percentage unless the Arbitration team deems it necessary to adjust. The recommended value is 2.5% of the indexer’s stake.
+
+### Fisherman protection
+
+Fishermen can now reclaim their bonds if disputes aren't resolved within the dispute period, preventing their funds from being locked indefinitely.
+
+## What Stays the Same
+
+While Horizon brings significant improvements, several core elements remain unchanged:
+
+- **Curation mechanism**: The way subgraphs are signaled and curated remains the same
+- **Indexing rewards formula**: The calculation and distribution of indexing rewards follows the same formula
+- **GRT token**: The Graph Token (GRT) remains unchanged