# The Graph Protocol

## Full-Stack Decentralization
The Graph protocol is shifting from a paradigm of businesses paying for the ongoing storage, compute, and other services required to keep an application running, toward users directly paying networks of decentralized service providers for granular usage of these resources.

*Today, most “decentralized” applications only adopt such a model in the bottom layer of the stack—the blockchain—where users pay for transactions that modify application state. The rest of the stack continues to be operated by centralized businesses and is subject to arbitrary failures and rent seeking.* - Interesting comment from The Graph :smile:

## What is The Graph Network
Developers can run a [**Graph Node**](https://github.com/graphprotocol/graph-node) on their own infrastructure, or they can build on our [hosted service](https://thegraph.com/docs/quick-start#hosted-service). In The Graph Network, any **Indexer** will be able to stake Graph Tokens (GRT) to participate in the network and earn rewards for indexing subgraphs and fees for serving queries on those subgraphs.

Consumers will be able to query this diverse set of Indexers by paying for their metered usage, proving a model where the laws of supply and demand sustain the services provided by the protocol.

## Protocol roles
1. **Consumers**. Consumers pay Indexers for queries. These will typically be end users but could also be web services or middleware that integrate with The Graph.
2. **Indexers**. Indexers are the node operators of The Graph. They are motivated by earning financial rewards.
3. **Curators**. Curators use GRT to signal what subgraphs are valuable to index. These will typically be developers and share their motivations but could also be end users supporting a valuable service they rely upon or a persona that is purely financially motivated.
4. **Delegators**. Delegators put GRT at stake on behalf of an Indexer in order to earn a portion of indexer rewards and fees, without having to personally run a Graph Node. They are financially motivated.

### Developers
Rather than deploying to a local or hosted Graph Node, they will **deploy their subgraph to a registry hosted on Ethereum and deposit a stake of GRT to curate that subgrap**h. This serves as a signal to Indexers that this subgraph should be indexed.

### End Users
End users query a decentralized network of Indexers via the query engine running on their machine-either in the browser, as an extension, or embedded in the dApp.

The query engine allows the user to safely query the vast amounts of data stored on The Graph without having to personally do the work to compute and store that data. The query engine also acts as a trading engine, making decisions such as which Indexers to do business with or how much to pay, based on the dApp being used or the user’s preferences.

**For the query engine to provide a good user experience, it will need the capability to automatically sign micropayment transactions on behalf of users rather than prompting them for every transaction that needs signing. We’re working with several state channel teams building on Ethereum to make sure that the wallets and functionality they ship meets the needs of metered usage protocols like The Graph. In the meantime, we will host a gateway that subsidizes queries on behalf of users.**

### Indexers
Indexers will be able to join The Graph by staking GRT and running a version of [Graph Node.](https://github.com/graphprotocol/graph-node)

### Curators and Delegators

Curators and delegators will curate and delegate via [Graph Explorer](https://thegraph.com/explorer/). Users will be able to curate and delegate through the Graph Explorer, that will be a fully decentralized application that requires a dApp-enabled browser with an Ethereum wallet.

## Architecture
[Article](https://thegraph.com/blog/the-graph-network-in-depth-part-1/)

The Graph Network includes smart contracts that run on Ethereum combined with a variety of additional services and clients that operate off-chain.


## Query Market
The query market serves a similar purpose to an API in a traditional cloud-based application - **efficiently serving data required by a front end running on a user’s device.**
The key difference is that whereas a traditional API is centralized, the query market in The Graph protocol comprises a decentralized network of Indexers, all competing to privde the best service at the best price.

#### What if Indexer goes offline?
If a single Indexer goes offline, as long as there exists demand for querying a dataset, other Indexers will be incentivized to absorb the additional work.

#### How is the query priced in the market?
Transactions in the query market are priced based on the bandwidth and compute required to process the query.

#### Typical flow for a consumer interacting with the query market

graph TD
    C(Consumer) -->|1. Find me an Indexers for Subgraph XYZ| SDL(Service Disovery Layer)
    SDL -->|2. Lists of Indexers| C

##### How is Indexer selected?
The consumer selects an Indexer to transact with based on which they deem most likely to provide the highest quality service at the best price. This involves weighing the utility of performance, freshness of data, economic security, as well as subjective measures of Indexer reputation.

##### How is the price set between Indexer and Consumer?
Indexers express their prices using a cost model which a Consumer can use to produce a GRT-denominated cost based on the features of a query and variables provided by the Indexer such as database statistics, the USD/GRT price, or a flag to indicate whether the Indexer is throttling queries. Thus, pricing is set between an Indexer and a Consumer, rather than at the network level as is the case in a smart contract platform like Ethereum.


## Indexer Staking
Indexers stake Graph Tokens in order to sell their services in the query market. This serves two primary functions:
1. It provides economic security, as the staked GRT can be slashed if Indexers perform their work maliciously. Once GRT is staked, it may only be withdrawn subject to a thawing period, which provides ample opportunity for verification and dispute resolution.
2. It provides a Sybil resistance mechanism. Having fake or low quality Indexers on a given subgraph makes it slower to find quality service providers. For this reason we only want Indexers who have skin in the game to be discoverable.

In order for the above mechanisms to function correctly, it’s important that Indexers are incentivized to hold GRT roughly in proportion to the amount of useful work they’re doing in the network.

A naive approach would be to try to make it so that each GRT staked entitles an Indexer to perform a specified amount of work on the network. There are two problems with this: first, it sets an arbitrary upper bound on the amount of work the network can perform; and second, it is nearly impossible to enforce in a way that is scalable, since it would require that all work be centrally coordinated on-chain.

A better approach has been pioneered by the team at 0x, and it involves collecting a protocol fee on all transactions in the protocol, and then rebating those fees to participants as a function of their proportional stake and proportional fees collected for the network, using the [Cobb-Douglas production function.](https://en.wikipedia.org/wiki/Cobb%E2%80%93Douglas_production_function#Cobb%E2%80%93Douglas_utilities)

[0x Research](https://forum.0x.org/t/research-on-protocol-fees-and-liquidity-incentives/340)

## Delegation
For token holders who do not wish to sell their Graph Tokens, but want to put their tokens to productive use securing the network, the protocol introduces delegation.

A Delegator can “loan” their GRT to an Indexer, in return for a share of their query fees and indexer rewards, as specified by the Indexer.

In addition to increasing token participation, delegation presents an opportunity for smaller, capital-constrained Indexers, to be more competitive in the decentralized network by providing a high quality of service and attracting Delegators.

An important choice staking protocols must make with respect to delegation is whether delegateed stake can be slashed due to Indexer misbehaviors. In The Graph, delegated stake will not be slashable, because this encourages a trust relationship between Delegators and Indexers that could lead to winner-take-all mechanics and hurt decentralization.

Similar to [other protocols](https://medium.com/cryptium/over-delegation-and-self-bond-requirements-for-bakers-and-delegators-in-tezos-17ac49230d3a) that have made this choice, The Graph will enforce a limit on how much delegated stake an Indexer can accept for every unit of their own stake. This “delegation capacity” ensures that an Indexer is always putting a minimum amount of their own funds at stake to participate in the network.

## Curator Signaling
For a consumer to query a subgraph, the subgraph must first be indexed—a process which can take hours or even days. If Indexers had to blindly guess which subgraphs they should index on the off-chance that they would earn query fees, the market would not be very efficient.

Curator signaling is the process of depositing GRT into a bonding curve for a subgraph to indicate to Indexers that the subgraph should be indexed.

Indexers can trust the signal because when curators deposit GRT into the bonding curve, they mint a curation share for the respective subgraph, entitling them to a portion of future query fees collected on that subgraph. A rationally self-interested curator should signal GRT toward subgraphs that they predict will generate fees for the network.

Using bonding curves—a type of algorithmic market maker where price is determined by a function—means that the more curation shares are minted, the higher the exchange rate between GRT and curation shares becomes. Thus, successful curators could take profits immediately if they feel that the value of future curation fees has been correctly priced in. Similarly, they should withdraw their GRT if they feel that the market has priced the value of curation shares too high.

This dynamic means that the amount of GRT signaled toward a subgraph should provide an ongoing and valuable market signal as to the market’s prediction for future query volume on a subgraph.

## Verifiable Indexing

Given the protocol’s subsidization of subgraph indexing through the indexer reward, it’s important that the mechanism is used to subsidize useful work. For this, we introduce Proofs of Indexing and a Subgraph Availability Oracle.

The intent of both these mechanisms is to mitigate possible economic attacks where an Indexer attempts to collect the Indexer reward without providing useful work to the network. This could take the following forms:

Not actually Indexing a subgraph that you are collecting rewards on.
Indexing a subgraph that is broken or whose subgraph manifest is unavailable.
To mitigate #1, and some instances of #2, the protocol introduces Proofs of Indexing. In their current form, these are simply a signature over a message digest that is generated during the indexing of a subgraph from genesis. Each time a subgraph’s state is updated, so does the message digest.

When an Indexer goes to claim their indexer reward on a given subgraph, they must supply a recent Proof of Indexing to claim the reward. Because the Proof of Indexing (PoI) is computed from the Indexer’s signature, each Indexer must submit a PoI that is specific to them. Since Indexers compete for indexer rewards on a given subgraph, it is not in the best interest of Indexers to collude to help each other generate correct PoIs without actually doing the work.

These PoIs are accepted optimistically, in that they immediately unlock rewards, but they can be used later to slash an Indexer if they are found to be incorrectly formed. Slashing conditions could include deterministically attributable faults such as:

A PoI that represents an incorrect state of a subgraph
Providing a PoI on an invalid subgraph
In the first version of the network, an Arbitrator set through governance will decide disputes and has the power to end them in “draw” if a fault is not clearly attributable, or if it was the result of a software bug rather than malicious behavior by the Indexer. The decisions of an Arbitrator will be based on the protocol specification as well as an “arbitration charter” which outlines how disputes should be settled.

Another type of fault, which is completely subjective due to speaker/listener fault equivalence, is whether or not a subgraph manifest is available. If a subgraph manifest is unavailable, then it becomes impossible for an Arbitrator to settle any of the other disputes for that subgraph, and also becomes impossible for other Indexers to compete for indexer rewards on that subgraph.

For this use case, we introduce a Subgraph Availability Oracle, also set through governance. The oracle will look at several prominent IPFS endpoints, such as the Cloudflare IPFS Gateway, to determine whether a subgraph manifest is available. If a subgraph manifest is unavailable, then that corresponding subgraph will not be eligible for any indexer rewards.

## Graph Explorer and Graph Name Service
The core value propositions of The Graph is to help developers find useful data to build on and make it effortless to incorporate data from a variety of underlying protocols and decentralized data sources into a single application.

Currently, developers accomplish this by navigating to Graph Explorer.

## Conditional Micropayments
Payments layer is designed to minimize trust between the consumer and the Indexer. Payment channels is a technology that has been developed for scalable, off-chain, trust-minimized payments. It involves two parties locking funds on-chain in an escrow where the funds may only be used to exchange funds off-chain between them until a transaction is submitted on-chain to withdraw funds from the escrow.

Traditionally, payment channel designs have emphasized securely sending a micropayment off-chain without regard for whether or not the service or good being paid for was actually received.

There has been some work, however, toward atomic swaps of micropayments for some digital good or outsourced computation, which we build on here. We call our construction WAVE Locks. WAVE stands for work, attestation, verification, expiration, and the general design is as follows:
1. Work. A consumer sends a locked micropayment with a description of the work to be performed. This specification of the work acts as the lock on the micropayment.
2. Attestation. A service provider responds with the digital good or service being requested along with a signed attestation that the work was performed correctly. This unlocks the micropayment optimistically, on the assumption that the attestation is correct.
3. Verification. The attestation is verified using some method of verification. There may be penalties, such as slashing, for attesting to work which was incorrectly performed. Verification of the attestation happens out-of-channel.
4. Expiration. The service provider must either receive a confirmation of receipt from the consumer or submit their attestation on-chain to receive their micropayment before the locked micropayment expires.

Using locks with payment channels is not new. Both Lightning and Raiden papers discuss using a hash preimage to unlock a micropayment. This is particularly useful for multi-hop micropayments where each “hop” is locked with the same hash and can be unlocked by a value, the preimage, that produces that hash when input to a specified hashing function.

### State channels
We can think of state channels being to payment channels, what smart contract blockchains like Ethereum are to Bitcoin. They can handle the simple payments use case, but they can also codify more complex state transitions while keeping the same scalability and security properties as a payment channel.

What payment and state channels have in common, however, is that in their most basic form they are a means of exchanging value or state updates between two participants, which are known ahead of time. As alluded to above with the multi-hop micropayments, sending between any two participants requires being able to form a chain of payment channels across multiple other participants, which connects the two original participants.


One advantage of having a state channel network available, aside from the scalability benefits, is that Consumers could use 3rd party off-chain market makers to buy GRT in exchange for ETH or the stable coin of their choice, just in time to pay for queries. This reduces balance sheet risk for Consumers that prefer to hold an asset whose value doesn’t fluctuate.

## Query Verification
Is a effective verification mechanism that is capable of reproducing the work performed by an Indexer.
This is handled through an on-chain dispute resolution process, which is decided through arbitration.

Two types of disputes:
1. Single Attestation Disputes
2. Conflicting Attestation Disputes

### Single attestation disputes
In single attestation disputes, Fishermen submit disputes along with a bond, as well as an attestation signed by an Indexer. If the Indexer is found to have attested to an incorrect query response, the fisherman receives a portion of the slashed amount as a reward. Conversely, the fisherman’s bond is forfeit if the dispute is unsuccessful.

Importantly, the fisherman’s reward must be less than the slashed amount. Otherwise, malicious Indexers could simply slash themselves to get around thawing periods or avoid slashing by someone else.

For single attestation disputes, the Fisherman is assumed to be an actor who got their hands through some extra-protocol means, for example a third party logging service.

### Conflicting attestation disputes
In this case, a Fisherman can submit two attestations for the same query, signed by two different Indexers. If the attestations don’t agree with one another, then it’s guaranteed that one or both Indexers committed a fault.

Consumers, when querying The Graph, may choose to intermittently query multiple Indexers for the same query results–for extra security and the chance of winning a portion of their slashed stake as a reward. This strategy works better as the number of unique Indexers on a subgraph increases.

In the first version of the network, there will be an Arbitrator set via protocol governance, which will decide the outcome of disputes. Similar to indexing disputes, the Arbitrator may exercise judgment when incorrect queries may arise as a result of bugs in the software, Indexers missing events from the blockchain, or other accidental factors that could lead to a slashable offense. Arbitration should settle disputes according to the protocol specification as well as the aforementioned arbitration charter.

# The Graph Studio

# API Keys
API keys are required to query subgraphs. You can receive 1,000 free queries on your first API key.

Required:
- Name of the API key
- Email
- Organization name

https://gateway.testnet.thegraph.com/api/c120bf3cfab17f750047049115f9a775/subgraphs/id/CptFsHp6zar7kdfGYbVAqMeF1wNA1pJs6GaaJvPgeCfu