developing-page

website/pages/en/network/developing.mdx

@@ -2,52 +2,122 @@
 title: Developing
 ---
 
-Developers are the demand side of The Graph ecosystem. Developers build subgraphs and publish them to The Graph Network. Then, they query live subgraphs with GraphQL in order to power their applications.
+Learn developer fundamentals and review the basics of a subgraph’s lifecycle. To start coding right away and engage The Graph, go to the following: [Developer Quick Start](/quick-start/)
 
-## Subgraph Lifecycle
+## Overview
 
-Subgraphs deployed to the network have a defined lifecycle.
+As a developer, you need important data to build and power your dapps. Querying and indexing that blockchain data can be challenging, but The Graph provides a solution to this issue.
 
-### Build locally
+On The Graph, you can:
 
-As with all subgraph development, it starts with local development and testing. Developers can use the same local setup whether they are building for The Graph Network or a local Graph Node, leveraging `graph-cli` and `graph-ts` to build their subgraph. Developers are encouraged to use tools such as [Matchstick](https://github.com/LimeChain/matchstick) for unit testing to improve the robustness of their subgraphs.
+1.  Create, deploy and publish subgraphs to The Graph using **Graph CLI** and [Subgraph Studio](/https://thegraph.com/studio/).
+2.  Use Graph node via **GraphQL** to query live subgraphs and power dapps.
 
-> There are certain constraints on The Graph Network, in terms of feature and network support. Only subgraphs on [supported networks](/developing/supported-networks) will earn indexing rewards, and subgraphs which fetch data from IPFS are also not eligible.
+### What is GraphQL and Graph CLI?
 
-### Deploy to Subgraph Studio
+- **GraphCLI** is a command line interface tool for building and deploying to The Graph.
+- **GraphQL** is the query language use for APIs and a runtime for executing those queries with your existing data. The Graph uses GraphQL to query subgraphs.
 
-Once defined, the subgraph can be built and deployed to [Subgraph Studio](/deploying/subgraph-studio-faqs/). Subgraph Studio is a sandbox environment which will index the deployed subgraph and make it available for rate-limited development and testing. This gives developers an opportunity to verify that their subgraph does not encounter any indexing errors, and works as expected.
+### Developer Capabilities
 
-### Publish to the Network
+- Engage with the entire subgraph lifecycle on the network, including publishing, querying and iterating on your custom subgraphs.
+- Specialize in subgraph development, building open APIs for others to utilize and build on.
+- Focus on application development by querying subgraphs deployed by other developers.
 
-When the developer is happy with their subgraph, they can publish it to The Graph Network. This is an on-chain action, which registers the subgraph so that it is discoverable by Indexers. Published subgraphs have a corresponding NFT, which is then easily transferable. The published subgraph has associated metadata, which provides other network participants with useful context and information.
+### Network Economics
 
-### Signal to Encourage Indexing
+As a developer, you can do any of the following:
 
-Published subgraphs are unlikely to be picked up by Indexers without the addition of signal. Signal is locked GRT associated with a given subgraph, which indicates to Indexers that a given subgraph will receive query volume, and also contributes to the indexing rewards available for processing it. Subgraph developers will generally add signal to their subgraph, in order to encourage indexing. Third party Curators may also signal on a given subgraph, if they deem the subgraph likely to drive query volume.
+- Lock up GRT to encourage indexing and the query subgraphs.
+- Burn GRT whenever a subgraph is updated.
 
-### Querying & Application Development
+## Subgraph Specifics
 
-Once a subgraph has been processed by Indexers and is available for querying, developers can start to use the subgraph in their applications. Developers query subgraphs via a gateway, which forwards their queries to an Indexer who has processed the subgraph, paying query fees in GRT.
+### What are subgraphs?
 
-In order to make queries, developers must generate an API key, which can be done in Subgraph Studio. This API key must be funded with GRT, in order to pay query fees. Developers can set a maximum query fee, in order to control their costs, and limit their API key to a given subgraph or origin domain. Subgraph Studio provides developers with data on their API key usage over time.
+A subgraph is a custom API built on blockchain data. It extracts data from a blockchain, process it, and stores it so that it can be easily queried via GraphQL.
 
-Developers are also able to express an Indexer preference to the gateway, for example preferring Indexers whose query response is faster, or whose data is most up to date. These controls are set in Subgraph Studio.
+A subgraph primarily consists of the following files:
 
-### Updating Subgraphs
+- `subgraph.yaml`: this YAML file contains the subgraph manifest
+- `subgraph.graphql`: this GraphQL schema defines what data is stored for your subgraph, and how to query it via GraphQL
+- `AssemblyScript Mappings`: [AssemblyScript](https://github.com/AssemblyScript/assemblyscript) code that translates from the event data to the entities defined in your schema
 
-After a time a subgraph developer may want to update their subgraph, perhaps fixing a bug or adding new functionality. The subgraph developer may deploy new version(s) of their subgraph to Subgraph Studio for rate-limited development and testing.
+Learn the detailed specifics to [create a subgraph](/developing/creating-a-subgraph/).
 
-Once the Subgraph Developer is ready to update, they can initiate a transaction to point their subgraph at the new version. Updating the subgraph migrates any signal to the new version (assuming the user who applied the signal selected "auto-migrate"), which also incurs a migration tax. This signal migration should prompt Indexers to start indexing the new version of the subgraph, so it should soon become available for querying.
+### Subgraph Lifecycle
 
-### Deprecating Subgraphs
+Here is a general view of a subgraph’s cycle:
 
-At some point a developer may decide that they no longer need a published subgraph. At that point they may deprecate the subgraph, which returns any signalled GRT to the Curators.
+![Subgraph Lifecycle](/img/subgraph-lifecycle.png)
 
-### Diverse Developer Roles
+### Subgraph Development
 
-Some developers will engage with the full subgraph lifecycle on the network, publishing, querying and iterating on their own subgraphs. Some may be focused on subgraph development, building open APIs which others can build on. Some may be application focused, querying subgraphs deployed by others.
+Subgraph development starts with local development and staging.
 
-### Developers and Network Economics
+- You can use the same local setup whether you're building for The Graph Network or a local Graph Node.
+  - You can leverage `graph-cli` and `graph-ts` to build your subgraph.
+- You are encouraged to use tools such as [Matchstick](https://github.com/LimeChain/matchstick) for unit testing to improve the robustness of your subgraphs.
 
-Developers are a key economic actor in the network, locking up GRT in order to encourage indexing, and crucially querying subgraphs, which is the network's primary value exchange. Subgraph developers also burn GRT whenever a subgraph is updated.
+> Only subgraphs on [supported networks](/developing/supported-networks/) will earn indexing rewards. Subgraphs that fetch data from IPFS are also **not** eligible.
+
+## Deploy to Subgraph Studio
+
+Once defined, a subgraph can be built and deployed to [Subgraph Studio](/deploying-a-subgraph-to-studio/). In Subgraph Studio, you can do the following:
+
+- Verify that your subgraph doesn't have any indexing errors and works as expected.
+- Use its staging environment to index the deployed subgraph and make it available for review.
+
+Learn how to [deploy subgraphs](/deploying-a-subgraph-to-studio/).
+
+## Publish to the Network
+
+When you are happy with your subgraph, you can publish it to The Graph Network.
+
+- This is an on-chain action, which registers the subgraph and makes it discoverable by Indexers.
+- Published subgraphs have a corresponding NFT, which is then easily transferable.
+- Published subgraphs have associated metadata, which provides other network participants with useful context and information.
+
+Learn how to [publish a subgraph](/publishing/publishing-a-subgraph/).
+
+## Add Signal for Indexing
+
+Published subgraphs are unlikely to be picked up by Indexers without signal. To encourage indexing you should add signal to your subgraph.
+
+**What is signal?**
+
+- Signal is locked GRT associated with a given subgraph. It indicates to indexers that a given subgraph will receive query volume and it contributes to the indexing rewards available for processing it.
+- Third party Curators may also signal on a given subgraph, if they deem the subgraph likely to drive query volume.
+
+Learn more about signaling and [curating](/network/curating/) on The Graph.
+
+## Querying & Application Development
+
+Once a subgraph has been processed by Indexers and is available for querying, you can start using your subgraph in your applications.
+
+- You query subgraphs via a gateway, which forwards your queries to an Indexer who has processed the subgraph (paying query fees in GRT).
+- In order to make queries, you must generate an API key, which can be done in [Subgraph Studio](/https://thegraph.com/studio/).
+- This API key must be funded with GRT to pay query fees.
+- You can set a maximum query fee to control their costs and limit your API key to a given subgraph or origin domain.
+- Subgraph Studio provides you with data on your API key usage over time.
+- You can express an Indexer preference to the gateway, such as preferring Indexers with fast query response or have up-to-date data. These controls are set in Subgraph Studio.
+
+Learn more about [querying](/querying/querying-the-graph/).
+
+## Updating Subgraphs
+
+To update your subgraph with bug fixes or new functionalities, initiate a transaction to point it to the new version. You can deploy new versions of your subgraphs to [Subgraph Studio](/https://thegraph.com/studio/) for development and testing.
+
+- If you selected "auto-migrate" when you applied the signal, updating the subgraph will migrate any signal to the new version and incur a migration tax.
+- This signal migration should prompt Indexers to start indexing the new version of the subgraph, so it should soon become available for querying.
+
+## Deprecating Subgraphs
+
+If you no longer need a published subgraph, then you will need to deprecate the subgraph.
+
+- Deprecating a subgraph returns any signaled GRT to Curators.
+- To deprecate a subgraph, see the [deprecating a subgraph guide](/network/developing/deprecating-a-subgraph/).
+
+## Transferring Subgraph
+
+You can transfer the ownership of a subgraph. To transfer subgraph ownership, see the [transfer subgraph guide](/transferring-subgraph-ownership/).