Skip to content

Update indexing documentation for Exponential Rebates #454

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Aug 10, 2023
Merged

Update indexing documentation for Exponential Rebates #454

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
46a564e
Update tokenomics.mdx
alex-pakalniskis Aug 1, 2023
192771f
Update glossary.mdx
alex-pakalniskis Aug 1, 2023
e03d5f9
Update indexing.mdx
alex-pakalniskis Aug 1, 2023
112952f
Update website/pages/en/tokenomics.mdx
alex-pakalniskis Aug 2, 2023
7d1c309
Update website/pages/en/network/indexing.mdx
alex-pakalniskis Aug 2, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 0 additions & 6 deletions website/pages/en/glossary.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,8 +38,6 @@ title: Glossary

- **Subgraph Manifest**: A JSON file that describes the subgraph's GraphQL schema, data sources, and other metadata. [Here](https://ipfs.io/ipfs/QmVQdzeGdPUiLiACeqXRpKAYpyj8Z1yfWLMUq7A7WundUf) is an example.

- **Rebate Pool**: An economic security measure that holds query fees paid by subgraph consumers until they may be claimed by Indexers as query fee rebates. Residual GRT is burned.

- **Epoch**: A unit of time that in network. One epoch is currently 6,646 blocks or approximately 1 day.

- **Allocation**: An Indexer can allocate their total GRT stake (including Delegators' stake) towards subgraphs that have been published on The Graph's decentralized network. Allocations exist in one of four phases.
Expand All @@ -48,10 +46,6 @@ title: Glossary

2. **Closed**: An Indexer may claim the accrued indexing rewards on a given subgraph by submitting a recent, and valid, Proof of Indexing (POI). This is known as closing an allocation. An allocation must have been open for a minimum of one epoch before it can be closed. The maximum allocation period is 28 epochs. If an indexer leaves an allocation open beyond 28 epochs, it is known as a stale allocation. When an allocation is in the **Closed** state, a fisherman can still open a dispute to challenge an Indexer for serving false data.

3. **Finalized**: The dispute period has ended, and query fee rebates are available to be claimed by Indexers.

4. **Claimed**: The final phase of an allocation, all eligible rewards have been distributed and its query fee rebates have been claimed.

- **Subgraph Studio**: A powerful dapp for building, deploying, and publishing subgraphs.

- **Fishermen**: Network participants may dispute Indexers' query responses and POIs. This is called being a Fisherman. A dispute resolved in the Fisherman’s favor results in a financial penalty for the Indexer, along with an award to the Fisherman, thus incentivizing the integrity of the indexing and query work performed by Indexers in the network. The penalty (slashing) is currently set at 2.5% of an Indexer's self stake, with 50% of the slashed GRT going to the Fisherman, and the other 50% being burned.
Expand Down
14 changes: 5 additions & 9 deletions website/pages/en/network/indexing.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: Indexing
---

Indexers are node operators in The Graph Network that stake Graph Tokens (GRT) in order to provide indexing and query processing services. Indexers earn query fees and indexing rewards for their services. They also earn from a Rebate Pool that is shared with all network contributors proportional to their work, following the Cobb-Douglas Rebate Function.
Indexers are node operators in The Graph Network that stake Graph Tokens (GRT) in order to provide indexing and query processing services. Indexers earn query fees and indexing rewards for their services. They also earn query fees that are rebated according to an exponential rebate function.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it might be worth providing a bit more of a legible explanation of what the rebate function is for (essentially ensuring that indexers have sufficient stake allocated when claiming a given amount of query fees)

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed. To be explicit, after "to an exponential rebate function.", you could add:

This aim of using this rebate function is to ensure indexers achieve the best outcome by faithfully serving queries. This works by incentivizing Indexers to allocate a large amount of stake (which can be slashed for erring when serving a query) relative to the amount of query fees they may collect.


GRT that is staked in the protocol is subject to a thawing period and can be slashed if Indexers are malicious and serve incorrect data to applications or if they index incorrectly. Indexers also earn rewards for delegated stake from Delegators, to contribute to the network.

Expand Down Expand Up @@ -81,17 +81,17 @@ Disputes can be viewed in the UI in an Indexer's profile page under the `Dispute

### What are query fee rebates and when are they distributed?

Query fees are collected by the gateway whenever an allocation is closed and accumulated in the subgraph's query fee rebate pool. The rebate pool is designed to encourage Indexers to allocate stake in rough proportion to the amount of query fees they earn for the network. The portion of query fees in the pool that are allocated to a particular Indexer is calculated using the Cobb-Douglas Production Function; the distributed amount per Indexer is a function of their contributions to the pool and their allocation of stake on the subgraph.
Query fees are collected by the gateway and distributed to indexers according to the exponential rebate function (see GIP [here](https://forum.thegraph.com/t/gip-0051-exponential-query-fee-rebates-for-indexers/4162)).

Once an allocation has been closed and the dispute period has passed the rebates are available to be claimed by the Indexer. Upon claiming, the query fee rebates are distributed to the Indexer and their Delegators based on the query fee cut and the delegation pool proportions.
Once an allocation has been closed the rebates are available to be claimed by the Indexer. Upon claiming, the query fee rebates are distributed to the Indexer and their Delegators based on the query fee cut and the exponential rebate function.

### What is query fee cut and indexing reward cut?

The `queryFeeCut` and `indexingRewardCut` values are delegation parameters that the Indexer may set along with cooldownBlocks to control the distribution of GRT between the Indexer and their Delegators. See the last steps in [Staking in the Protocol](/network/indexing#stake-in-the-protocol) for instructions on setting the delegation parameters.

- **queryFeeCut** - the % of query fee rebates accumulated on a subgraph that will be distributed to the Indexer. If this is set to 95%, the Indexer will receive 95% of the query fee rebate pool when an allocation is claimed with the other 5% going to the Delegators.
- **queryFeeCut** - the % of query fee rebates that will be distributed to the Indexer. If this is set to 95%, the Indexer will receive 95% of the query fees earned when an allocation is closed with the other 5% going to the Delegators.

- **indexingRewardCut** - the % of indexing rewards accumulated on a subgraph that will be distributed to the Indexer. If this is set to 95%, the Indexer will receive 95% of the indexing rewards pool when an allocation is closed and the Delegators will split the other 5%.
- **indexingRewardCut** - the % of indexing rewards that will be distributed to the Indexer. If this is set to 95%, the Indexer will receive 95% of the indexing rewards when an allocation is closed and the Delegators will split the other 5%.

### How do Indexers know which subgraphs to index?

Expand Down Expand Up @@ -798,8 +798,4 @@ After being created by an Indexer a healthy allocation goes through four states.

- **Closed** - An Indexer is free to close an allocation once 1 epoch has passed ([closeAllocation()](https://github.com/graphprotocol/contracts/blob/master/contracts/staking/Staking.sol#L873)) or their Indexer agent will automatically close the allocation after the **maxAllocationEpochs** (currently 28 days). When an allocation is closed with a valid proof of indexing (POI) their indexing rewards are distributed to the Indexer and its Delegators (see "how are rewards distributed?" below to learn more).

- **Finalized** - Once an allocation has been closed there is a dispute period after which the allocation is considered **finalized** and it's query fee rebates are available to be claimed (claim()). The Indexer agent monitors the network to detect **finalized** allocations and claims them if they are above a configurable (and optional) threshold, **—-allocation-claim-threshold**.

- **Claimed** - The final state of an allocation; it has run its course as an active allocation, all eligible rewards have been distributed and its query fee rebates have been claimed.

Indexers are recommended to utilize offchain syncing functionality to sync subgraph deployments to chainhead before creating the allocation on-chain. This feature is especially useful for subgraphs that may take longer than 28 epochs to sync or have some chances of failing undeterministically.
2 changes: 1 addition & 1 deletion website/pages/en/tokenomics.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ Indexers are the backbone of The Graph. They operate independent hardware and so

Indexers can earn GRT rewards in two ways:

1. Query fees: GRT paid by developers or users for subgraph data queries. Query fees are deposited into a rebate pool and distributed to Indexers.
1. Query fees: GRT paid by developers or users for subgraph data queries. Query fees are directly distributed to Indexers according to the exponential rebate function (see GIP [here](https://forum.thegraph.com/t/gip-0051-exponential-query-fee-rebates-for-indexers/4162)).

2. Indexing rewards: the 3% annual issuance is distributed to Indexers based on the number of subgraphs they are indexing. These rewards incentivize Indexers to index subgraphs, occasionally before the query fees begin, to accrue and submit Proofs of Indexing (POIs) verifying that they have indexed data accurately.

Expand Down