Skip to content
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

Updating "Migrating an Existing Subgraph to The Graph Network" page #37

Merged
merged 5 commits into from
Feb 3, 2022
Merged

Updating "Migrating an Existing Subgraph to The Graph Network" page #37

Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
7759b37
Updating "Migrating an Existing Subgraph to The Graph Network" page
ahmadmardeni1 Jan 20, 2022
c555987
Minor
ahmadmardeni1 Jan 20, 2022
e0a27a7
Edits
ahmadmardeni1 Jan 22, 2022
6a19af3
Minor
ahmadmardeni1 Jan 22, 2022
6d9d973
Edits
ahmadmardeni1 Jan 24, 2022
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
35 changes: 23 additions & 12 deletions pages/en/hosted-service/migrating-subgraph.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,18 @@ title: Migrating an Existing Subgraph to The Graph Network

## Introduction

This is a guide for the migration of subgraphs from the Hosted Service (also known as the Hosted Service) to The Graph Network. The migration to The Graph Network has been successful for projects like Opyn, UMA, mStable, Audius, PoolTogether, Livepeer, RAI, Enzyme, DODO, Opyn, Pickle, and BadgerDAO all of which are relying on data served by Indexers on the network. There are now over 200 subgraphs live on The Graph Network, generating query fees and actively indexing web3 data.
This is a guide on how to migrate your subgraph from the Hosted Service to The Graph Network. The migration to The Graph Network has been successful for projects like Opyn, UMA, mStable, Audius, PoolTogether, Livepeer, RAI, Enzyme, DODO, Opyn, Pickle, and BadgerDAO all of which are relying on data served by Indexers on the network. There are now over 200 subgraphs live on The Graph Network, generating query fees and actively indexing web3 data.

This will tell you everything you need to know about how to migrate to the decentralized network and manage your subgraphs moving forward. The process is quick and your subgraphs will forever benefit from the reliability and performance that you can only get on The Graph Network.
The process of migration is quick and your subgraphs will forever benefit from the reliability and performance that you can only get on The Graph Network.

### Migrating An Existing Subgraph to The Graph Network
### When not to Migrate?

If your subgraph:

- Is not generating too many queries, and at the same time you are not willing to self-signal.
Copy link
Contributor

Choose a reason for hiding this comment

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

Good idea with this section. We should be careful about the wording here. Too little queries is not a reason to not migrate. Also self-signalling is not necessary a problem. But these are good reasons to not migrate:

  • Usage of IPFS
  • Usage of full-text search
  • Deployed on other chains than Ethereum mainnet

- Is only for test purposes.

### Migrating an Existing Subgraph to The Graph Network

1. Get the latest version of the graph-cli installed:

Expand Down Expand Up @@ -64,6 +71,8 @@ graph codegen && graph build

And that's it! After you are done publishing, you'll be able to view your subgraphs live on the network via [The Graph Explorer](https://thegraph.com/explorer).

Feel free to leverage the Curation Station (Unofficial) [Discord](https://discord.gg/GVfH3PgANH) and [Telegram](https://t.me/+RqzR_Y_a5eY2Zjdh) to let Curators know that your subgraph is ready to be signaled. It would also be helpful if you share your expected query volume with them.
Copy link
Contributor

Choose a reason for hiding this comment

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

These are unofficial sources and we should not reference them on the public docs. But a paragraph that explains the general process of advertising a subgraph is definitely good. Main place for such thing is the official The Graph Discord: thegraph.com/discord


### Upgrading a Subgraph on the Network

If you would like to upgrade an existing subgraph on the network, you can do this by deploying a new version of your subgraph to the Subgraph Studio using the Graph CLI.
Expand All @@ -82,34 +91,36 @@ graph deploy --studio <SUBGRAPH_SLUG>

An upgrade requires GRT to be migrated from the old version of the subgraph to the new version. This means that for every upgrade, a new bonding curve will be created (more on bonding curves [here](/curating#bonding-curve-101)).

The new bonding curve charges the 2.5% curation tax on all GRT being migrated to the new version. The owner must pay 50% of this, or 1.25%. The other 1.25% is absorbed by all the curators as a fee. This incentive design is in place to prevent an owner of a subgraph from being able to drain all their curator's funds with recursive upgrade calls. The example below is only the case if your subgraph is being actively curated on. If there is no curation activity, you will have to pay a minimum of 100 GRT in order to signal yourself on your own subgraph.
The new bonding curve charges the 2.5% curation tax on all GRT being migrated to the new version. The owner must pay 50% of this, or 1.25%. The other 1.25% is absorbed by all the curators as a fee. This incentive design is in place to prevent an owner of a subgraph from being able to drain all their curator's funds with recursive upgrade calls. If there is no curation activity, you will have to pay a minimum of 100 GRT in order to signal your own subgraph.

Let's make an example, this is only the case if your subgraph is being actively curated on:

- 100,000 GRT is signaled using auto-migrate on v1 of a subgraph
- Owner upgrades to v2. 100,000 GRT is migrated to a new bonding curve, where 97,500 GRT get put into the new curve and 2,500 GRT is burned
- The owner then has 1250 GRT burned to pay for half the fee. The owner must have this in their wallet before the upgrade, otherwise the upgrade will not succeed. This happens in the same transaction as the upgrade.
- The owner then has 1250 GRT burned to pay for half the fee. The owner must have this in their wallet before the upgrade, otherwise, the upgrade will not succeed. This happens in the same transaction as the upgrade.

_While this mechanism is currently live on the network, the community is currently discussing ways to reduce the cost of upgrades for subgraph developers._

### Maintaining a Stable Version of a Subgraph

If you're making a lot of changes to your subgraph, it is not a good idea to continually upgrade it and front the upgrade costs. Maintaining a stable and consistent version of your subgraph is critical, not only from the cost perspective, but also so that Indexers can feel confident in their syncing times. Indexers should be flagged when you plan for an upgrade so that Indexer syncing times do not get impacted. Feel free to leverage the [#Indexers channel](https://discord.gg/8tgJ7rKW) on Discord to let Indexers know when you're versioning your subgraphs.

Subgraphs are open API that external developers are leveraging. Open APIs need to follow strict standards so that they do not break external developers' applications. In The Graph Network, a subgraph developer must consider Indexers and how long it takes them to sync a new subgraph **as well as** other developers who are using their subgraphs.
Subgraphs are open APIs that external developers are leveraging. Open APIs need to follow strict standards so that they do not break external developers' applications. In The Graph Network, a subgraph developer must consider Indexers and how long it takes them to sync a new subgraph **as well as** other developers who are using their subgraphs.

### Updating the Metadata of a Subgraph

You can update the metadata of your subgraphs without having to publish a new version. The metadata includes the subgraph name, image, description, website URL, source code URL, and categories. Developers can do this by updating their subgraph details in the Subgraph Studio where you can edit all applicable fields.

Make sure **Update Subgraph Details in Explorer** is checked and click on **Save**. If this is checked, an an on-chain transaction will be generated that updates subgraph details in the Explorer without having to publish a new version with a new deployment.
Make sure **Update Subgraph Details in Explorer** is checked and click on **Save**. If this is checked, an on-chain transaction will be generated that updates subgraph details in the Explorer without having to publish a new version with a new deployment.

## Best Practices for Deploying a Subgraph to The Graph Network

1. Leveraging an ENS name for Subgraph Development
1. Leveraging an ENS name for Subgraph Development:

- Set up your ENS: [https://app.ens.domains/](https://app.ens.domains/)
- Add your ENS name to your settings [here](https://thegraph.com/explorer/settings?view=display-name).

The more filled out your profiles are, the better the chances for your subgraphs to be indexed and curated.
2. The more filled out your profiles are, the better the chances for your subgraphs to be indexed and curated.

## Deprecating a Subgraph on The Graph Network

Expand All @@ -123,11 +134,11 @@ In order for The Graph Network to truly be decentralized, query fees have to be

### Estimate Query Fees on the Network

While this is not a live feature in the product UI, you can set your maximum budget per query by taking the amount you're willing to pay per month and divide it by your expected query volume.
While this is not a live feature in the product UI, you can set your maximum budget per query by taking the amount you're willing to pay per month and dividing it by your expected query volume.

While you get to decide on your query budget, there is no guarantee that an Indexer will be willing to serve queries at that price. If a Gateway can match you to an Indexer willing to serve a query at, or lower than, the price you are willing to pay, you will pay the delta/difference of your budget **and** their price. As a consequence of that, a lower query price reduces the pool of Indexers available to you, which may affect the quality of service you receive. It's beneficial to have high query fees, as that may attract curation and big name Indexers to your subgraph.
While you get to decide on your query budget, there is no guarantee that an Indexer will be willing to serve queries at that price. If a Gateway can match you to an Indexer willing to serve a query at, or lower than, the price you are willing to pay, you will pay the delta/difference of your budget **and** their price. As a consequence, a lower query price reduces the pool of Indexers available to you, which may affect the quality of service you receive. It's beneficial to have high query fees, as that may attract curation and big-name Indexers to your subgraph.

Remember that it's a dynamic and growing market, but how you interact with it is in your control. There is no maximum or minimum price specified in the protocol or in the Gateways. For example, you can look at the price paid by a few of the dapps on the network (on a per week basis), below. See the last column which shows query fees in GRT. For example, [Pickle Finance](https://www.pickle.finance/) has 8 requests per second and paid 2.4 GRT for one week.
Remember that it's a dynamic and growing market, but how you interact with it is in your control. There is no maximum or minimum price specified in the protocol or the Gateways. For example, you can look at the price paid by a few of the dapps on the network (on a per-week basis), below. See the last column, which shows query fees in GRT. For example, [Pickle Finance](https://www.pickle.finance/) has 8 requests per second and paid 2.4 GRT for one week.

![QueryFee](/img/QueryFee.png)

Expand Down