graphprotocol · MichaelMacaulay · Aug 3, 2023 · Jul 19, 2023 · Jul 25, 2023 · Jul 25, 2023
@@ -84,7 +84,8 @@ http {
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/supported-networks/cosmos/$                   $scheme://$http_host/docs/$1/cookbook/cosmos/                               permanent;
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/supported-networks/near/$                     $scheme://$http_host/docs/$1/cookbook/near/                                 permanent;
         rewrite ^/docs/([a-zA-Z][a-zA-Z])/developing/defining-a-subgraph/$              $scheme://$http_host/docs/$1/developing/creating-a-subgraph/                permanent;
-        rewrite ^/docs/([a-zA-Z][a-zA-Z])/arbitrum-faq/$                                $scheme://$http_host/docs/$1/arbitrum/arbitrum-faq/                                  permanent;
+        rewrite ^/docs/([a-zA-Z][a-zA-Z])/arbitrum-faq/$                                $scheme://$http_host/docs/$1/arbitrum/arbitrum-faq/                         permanent;
+        rewrite ^/docs/([a-zA-Z][a-zA-Z])/cookbook/migrating-a-subgraph/$               $scheme://$http_host/docs/$1/cookbook/upgrading-a-subgraph/                 permanent;
 
         # Temporary redirects (302)
         rewrite ^/docs/en/firehose/$                $scheme://$http_host/docs/en/firehose/README/               redirect;

@@ -14,7 +14,7 @@ By scaling The Graph on L2, network participants can expect:
 
 - Security inherited from Ethereum
 
-Scaling the protocol smart contracts onto L2 allows network participants to interact more frequently at a reduced cost in gas fees. For example, Indexers could open and close allocations to index a greater number of subgraphs with greater frequency, developers could deploy and upgrade subgraphs with greater ease, Delegators could delegate GRT with increased frequency, and Curators could add or remove signal to a larger number of subgraphs–actions previously considered too cost-prohibitive to perform frequently due to gas.
+Scaling the protocol smart contracts onto L2 allows network participants to interact more frequently at a reduced cost in gas fees. For example, Indexers could open and close allocations to index a greater number of subgraphs with greater frequency, developers could deploy and update subgraphs with greater ease, Delegators could delegate GRT with increased frequency, and Curators could add or remove signal to a larger number of subgraphs–actions previously considered too cost-prohibitive to perform frequently due to gas.
 
 The Graph community decided to move forward with Arbitrum last year after the outcome of the [GIP-0031](https://forum.thegraph.com/t/gip-0031-arbitrum-grt-bridge/3305) discussion.
 

@@ -14,7 +14,7 @@ Some frequent questions about these tools are answered in the [L2 Transfer Tools
 
 The Graph's community and core devs have [been preparing](https://forum.thegraph.com/t/gip-0031-arbitrum-grt-bridge/3305) to move to Arbitrum over the past year. Arbitrum, a layer 2 or "L2" blockchain, inherits the security from Ethereum but provides drastically lower gas fees.
 
-When you publish or upgrade your subgraphs to The Graph Network, you're interacting with smart contracts in the protocol and this requires paying for gas using ETH. By moving your subgraphs to Arbitrum, any future upgrades to your subgraph will require much lower gas fees. The lower fees, and the fact that curation bonding curves on L2 are flat, also make it easier for other Curators to curate on your subgraph, increasing the rewards for Indexers on your subgraph. This lower-cost environment also makes it cheaper for Indexers to index and serve your subgraph. Indexing rewards will be increasing on Arbitrum and decreasing on Ethereum mainnet over the coming months, so more and more Indexers will be transferring their stake and setting up their operations on L2.
+When you publish or upgrade your subgraph to The Graph Network, you're interacting with smart contracts on the protocol and this requires paying for gas using ETH. By moving your subgraphs to Arbitrum, any future updates to your subgraph will require much lower gas fees. The lower fees, and the fact that curation bonding curves on L2 are flat, also make it easier for other Curators to curate on your subgraph, increasing the rewards for Indexers on your subgraph. This lower-cost environment also makes it cheaper for Indexers to index and serve your subgraph. Indexing rewards will be increasing on Arbitrum and decreasing on Ethereum mainnet over the coming months, so more and more Indexers will be transferring their stake and setting up their operations on L2.
 
 ## Understanding what happens with signal, your L1 subgraph and query URLs
 
@@ -30,7 +30,7 @@ Queries to the L2 subgraph will need to be done to a different URL (on `arbitrum
 
 ## Choosing your L2 wallet
 
-When you published your subgraph on mainnet, you used a connected wallet to create the subgraph, and this wallet owns the NFT that represents this subgraph and allows you to publish upgrades.
+When you published your subgraph on mainnet, you used a connected wallet to create the subgraph, and this wallet owns the NFT that represents this subgraph and allows you to publish updates.
 
 When transferring the subgraph to Arbitrum, you can choose a different wallet that will own this subgraph NFT on L2.
 

@@ -1,7 +1,7 @@
 export default {
   'quick-start': '',
   'base-testnet': '',
-  'migrating-a-subgraph': '',
+  'upgrading-a-subgraph': '',
   'subgraph-debug-forking': '',
   near: '',
   cosmos: '',

@@ -1,21 +1,21 @@
 ---
-title: Migrating an Existing Subgraph to The Graph Network
+title: Upgrading an Existing Subgraph to The Graph Network
 ---
 
 ## Introduction
 
-This is a guide on how to migrate your subgraph from the Hosted Service to The Graph's decentralized network. Migration to The Graph Network has been successful for projects like Opyn, UMA, mStable, Audius, PoolTogether, Livepeer, RAI, Enzyme, DODO, Pickle, and BadgerDAO all of which are relying on data served by Indexers on the network. There are now over 700 subgraphs live on The Graph's decentralized network, generating query fees and actively indexing web3 data.
+This is a guide on how to upgrade your subgraph from the hosted service to The Graph's decentralized network. Over 1,000 subgraphs have successfully upgraded to The Graph Network including projects like Snapshot, Loopring, Audius, Premia, Livepeer, Uma, Curve, Lido, and many more!
 
-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.
+The process of upgrading is quick and your subgraphs will forever benefit from the reliability and performance that you can only get on The Graph Network.
 
-### Assumptions
+### Prerequisites
 
 - You have already deployed a subgraph on the hosted service.
 - The subgraph is indexing a chain available (or available in beta) on The Graph Network.
-- The subgraph does not use `ipfs.cat` in handler functions.
-- The subgraph does not have full-text search dependencies (it is not fully supported on the decentralized network yet).
+- You have a wallet with ETH to publish your subgraph on-chain.
+- You have ~10,000 GRT to curate your subgraph so Indexers can begin indexing it.
 
-## Migrating an Existing Subgraph to The Graph Network
+## Upgrading an Existing Subgraph to The Graph Network
 
 > You can find specific commands for your subgraph in the [Subgraph Studio](https://thegraph.com/studio/).
 
@@ -70,11 +70,14 @@ graph deploy --studio <SUBGRAPH_SLUG>
 
 6. At this point, your subgraph is now deployed on Subgraph Studio, but not yet published to the decentralized network. You can now test the subgraph to make sure it is working as intended using the temporary query URL as seen on top of the right column above. As this name already suggests, this is a temporary URL and should not be used in production.
 
-- Publishing is an on-chain action and will require gas to be paid for in Ethereum - see an example transaction [here](https://etherscan.io/tx/0xd0c3fa0bc035703c9ba1ce40c1862559b9c5b6ea1198b3320871d535aa0de87b). Prices are roughly around 0.0425 ETH at 100 gwei.
-- Any time you need to upgrade your subgraph, you will be charged an upgrade fee. Upgrading is just publishing another version of your existing subgraph on-chain. Because this incurs a cost, it is highly recommended to deploy and test your subgraph on Goerli before deploying to mainnet. It can, in some cases, also require some GRT if there is no signal on that subgraph. In the case there is signal/curation on that subgraph version (using auto-migrate), the taxes will be split.
+- Updating is just publishing another version of your existing subgraph on-chain.
+- Because this incurs a cost, it is highly recommended to deploy and test your subgraph in the Subgraph Studio, using the "Development Query URL" before publishing. See an example transaction [here](https://etherscan.io/tx/0xd0c3fa0bc035703c9ba1ce40c1862559b9c5b6ea1198b3320871d535aa0de87b). Prices are roughly around 0.0425 ETH at 100 gwei.
+- Any time you need to update your subgraph, you will be charged an update fee. Because this incurs a cost, it is highly recommended to deploy and test your subgraph on Goerli before deploying to mainnet. It can, in some cases, also require some GRT if there is no signal on that subgraph. In the case there is signal/curation on that subgraph version (using auto-migrate), the taxes will be split.
 
 7. Publish the subgraph on The Graph's decentralized network by hitting the "Publish" button.
 
+You should curate your subgraph with GRT to ensure that it is indexed by Indexers. To save on gas costs, you can curate your subgraph in the same transaction that you publish it to the network. It is recommended to curate your subgraph with at least 10,000 GRT for high quality of service.
+
 And that's it! After you are done publishing, you'll be able to view your subgraphs live on the decentralized network via [The Graph Explorer](https://thegraph.com/explorer).
 
 Feel free to leverage the [#Curators channel](https://discord.gg/rC8rBuRtbH) on Discord 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. Therefore, they can estimate how much GRT they should signal on your subgraph.
@@ -139,9 +142,9 @@ Congratulations! You are now a pioneer of decentralization!
 
 More information about the nature of the network and how to handle re-orgs are described in the documentation article [Distributed Systems](/querying/distributed-systems/).
 
-## Upgrading a Subgraph on the Network
+## Updating 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.
+If you would like to update 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.
 
 1. Make changes to your current subgraph. A good idea is to test small fixes on the Subgraph Studio by publishing to Goerli.
 2. Deploy the following and specify the new version in the command (eg. v0.0.1, v0.0.2, etc):
@@ -153,23 +156,25 @@ graph deploy --studio <SUBGRAPH_SLUG>
 3. Test the new version in the Subgraph Studio by querying in the playground
 4. Publish the new version on The Graph Network. Remember that this requires gas (as described in the section above).
 
-### Owner Upgrade Fee: Deep Dive
+### Owner Update Fee: Deep Dive
+
+> Note: Curation on Arbitrum does not use bonding curves. Learn more about Arbitrum [here](/arbitrum/arbitrum-faq/).
 
-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](/network/curating#bonding-curve-101)).
+An update requires GRT to be migrated from the old version of the subgraph to the new version. This means that for every update, a new bonding curve will be created (more on bonding curves [here](/network/curating#bonding-curve-101)).
 
-The new bonding curve charges the 1% 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.
+The new bonding curve charges the 1% 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 update 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.
+- Owner updates 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 update, otherwise, the update will not succeed. This happens in the same transaction as the update.
 
-_While this mechanism is currently live on the network, the community is currently discussing ways to reduce the cost of upgrades for subgraph developers._
+_While this mechanism is currently live on the network, the community is currently discussing ways to reduce the cost of updates 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/rC8rBuRtbH) on Discord to let Indexers know when you're versioning your subgraphs.
+If you're making a lot of changes to your subgraph, it is not a good idea to continually update it and front the update 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 update so that Indexer syncing times do not get impacted. Feel free to leverage the [#Indexers channel](https://discord.gg/rC8rBuRtbH) on Discord to let Indexers know when you're versioning your 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.
 
@@ -194,7 +199,7 @@ Follow the steps [here](/managing/deprecating-a-subgraph) to deprecate your subg
 
 ## Querying a Subgraph + Billing on The Graph Network
 
-The Hosted Service was set up to allow developers to deploy their subgraphs without any restrictions.
+The hosted service was set up to allow developers to deploy their subgraphs without any restrictions.
 
 In order for The Graph Network to truly be decentralized, query fees have to be paid as a core part of the protocol's incentives. For more information on subscribing to APIs and paying the query fees, check out billing documentation [here](/billing/).
 
@@ -210,7 +215,7 @@ Remember that it's a dynamic and growing market, but how you interact with it is
 
 ## Additional Resources
 
-If you're still confused, fear not! Check out the following resources or watch our video guide on migrating subgraphs to the decentralized network below:
+If you're still confused, fear not! Check out the following resources or watch our video guide on upgrading subgraphs to the decentralized network below:
 
 <VideoEmbed youtube="CzdQ3dFFrjo" />