From c9b6a29d4ec976a6921454e57145d138e9b7ea81 Mon Sep 17 00:00:00 2001 From: ahmadmardeni1 Date: Thu, 24 Mar 2022 19:03:40 +0200 Subject: [PATCH 1/9] Updating all pages --- pages/en/curating.mdx | 28 ++++---- pages/en/delegating.mdx | 18 ++--- pages/en/developer/create-subgraph-hosted.mdx | 72 +++++++++---------- pages/en/developer/deprecating-a-subgraph.mdx | 6 +- pages/en/developer/developer-faq.mdx | 28 ++++---- pages/en/developer/publish-subgraph.mdx | 2 +- pages/en/developer/querying-from-your-app.mdx | 10 +-- pages/en/developer/quick-start.mdx | 10 +-- pages/en/explorer.mdx | 18 ++--- .../hosted-service/deploy-subgraph-hosted.mdx | 17 +++-- .../en/hosted-service/migrating-subgraph.mdx | 8 +-- .../hosted-service/what-is-hosted-service.mdx | 6 +- pages/en/studio/billing.mdx | 4 +- pages/en/studio/deploy-subgraph-studio.mdx | 8 +-- pages/en/studio/multisig.mdx | 14 ++-- pages/en/studio/studio-faq.mdx | 4 +- pages/en/studio/subgraph-studio.mdx | 18 ++--- .../transferring-subgraph-ownership.mdx | 6 +- pages/en/supported-networks/near.mdx | 26 +++---- 19 files changed, 151 insertions(+), 152 deletions(-) diff --git a/pages/en/curating.mdx b/pages/en/curating.mdx index 934241050593..95c18a90bc04 100644 --- a/pages/en/curating.mdx +++ b/pages/en/curating.mdx @@ -2,7 +2,7 @@ title: Curator --- -Curators are critical to the Graph decentralized economy. They use their knowledge of the web3 ecosystem to assess and signal on the subgraphs that should be indexed by The Graph Network. Through the Explorer, curators are able to view network data to make signalling decisions. The Graph Network rewards curators that signal on good quality subgraphs earn a share of the query fees that subgraphs generate. Curators are economically incentivized to signal early. These cues from curators are important for Indexers, who can then process or index the data from these signalled subgraphs. +Curators are critical to the Graph decentralized economy. They use their knowledge of the web3 ecosystem to assess and signal on the subgraphs that should be indexed by The Graph Network. Through the Explorer, curators are able to view network data to make signaling decisions. The Graph Network rewards curators that signal on good quality subgraphs earn a share of the query fees that subgraphs generate. Curators are economically incentivized to signal early. These cues from curators are important for Indexers, who can then process or index the data from these signaled subgraphs. When signaling, curators can decide to signal on a specific version of the subgraph or to signal using auto-migrate. When signaling using auto-migrate, a curator’s shares will always be upgraded to the latest version published by the developer. If you decide to signal on a specific version instead, shares will always stay on this specific version. @@ -10,7 +10,7 @@ Remember that curation is risky. Please do your diligence to make sure you curat ## Bonding Curve 101 -First we take a step back. Each subgraph has a bonding curve on which curation shares are minted, when a user adds signal **into** the curve. Each subgraph’s bonding curve is unique. The bonding curves are architected so that the price to mint a curation share on a subgraph increases linearly, over the number of shares minted. +First, we take a step back. Each subgraph has a bonding curve on which curation shares are minted when a user adds signal **into** the curve. Each subgraph’s bonding curve is unique. The bonding curves are architected so that the price to mint a curation share on a subgraph increases linearly, over the number of shares minted. ![Price per shares](/img/price-per-share.png) @@ -25,7 +25,7 @@ Consider we have two curators that mint shares for a subgraph: - Since both curators hold half the total of curation shares, they would receive an equal amount of curator royalties. - If any of the curators were now to burn their 2000 curation shares, they would receive 360,000 GRT. - The remaining curator would now receive all the curator royalties for that subgraph. If they were to burn their shares to withdraw GRT, they would receive 120,000 GRT. -- **TLDR:** The GRT valuation of curation shares is determined by the bonding curve and can be volatile. There is potential to incur big losses. Signalling early means you put in less GRT for each share. By extension, this means you earn more curator royalties per GRT than later curators for the same subgraph. +- **TLDR:** The GRT valuation of curation shares is determined by the bonding curve and can be volatile. There is potential to incur big losses. Signaling early means you put in less GRT for each share. By extension, this means you earn more curator royalties per GRT than later curators for the same subgraph. In general, a bonding curve is a mathematical curve that defines the relationship between token supply and asset price. In the specific case of subgraph curation, **the price of each subgraph share increases with each token invested** and the **price of each share decreases with each token sold.** @@ -33,13 +33,13 @@ In the case of The Graph, [Bancor’s implementation of a bonding curve formula] ## How to Signal -Now that we’ve covered the basics about how the bonding curve works, this is how you will proceed to signal on a subgraph. Within the Curator tab on the Graph Explorer, curators will be able to signal and unsignal on certain subgraphs based on network stats. For a step by step overview of how to do this in the Explorer, [click here.](/explorer) +Now that we’ve covered the basics about how the bonding curve works, this is how you will proceed to signal on a subgraph. Within the Curator tab on the Graph Explorer, curators will be able to signal and unsignal on certain subgraphs based on network stats. For a step-by-step overview of how to do this in the Explorer, [click here.](/explorer) A curator can choose to signal on a specific subgraph version, or they can choose to have their signal automatically migrate to the newest production build of that subgraph. Both are valid strategies and come with their own pros and cons. -Signalling on a specific version is especially useful when one subgraph is used by multiple dapps. One dapp might have the need to regularly update the subgraph with new features. Another dapp might prefer to use an older, well tested subgraph version. Upon initial curation, a 1% standard tax is incurred. +Signaling on a specific version is especially useful when one subgraph is used by multiple dApps. One dApp might need to regularly update the subgraph with new features. Another dApp might prefer to use an older, well-tested subgraph version. Upon initial curation, a 1% standard tax is incurred. -Having your signal automatically migrate to the newest production build can be valuable to ensure you keep accruing query fees. Every time you curate, a 1% curation tax is incurred. You will also pay a 0.5% curation tax on every migration. Subgraph developers are discouraged from frequently publishing new versions - they have to pay 0.5% curation tax on all auto-migrated curation shares. +Having your signal automatically migrate to the newest production build can be valuable to ensure you keep accruing query fees. Every time you curate, a 1% curation tax is incurred. You will also pay a 0.5% curation tax on every migration. Subgraph developers are discouraged from frequently publishing new versions - they have to pay a 0.5% curation tax on all auto-migrated curation shares. > **Note**: The first address to signal a particular subgraph is considered the first curator and will have to do much more gas-intensive work than the rest of the following curators because the first curator initializes the curation share tokens, initializes the bonding curve, and also transfers tokens into the Graph proxy. @@ -49,7 +49,7 @@ For end consumers to be able to query a subgraph, the subgraph must first be ind And so, if Indexers had to guess which subgraphs they should index, there would be a low chance that they would earn robust query fees because they’d have no way of validating which subgraphs are good quality. Enter curation. -Curators make The Graph network efficient and signaling is the process that curators use to let Indexers know that a subgraph is good to index, where GRT is added to a bonding curve for a subgraph. Indexers can inherently trust the signal from a curator because upon signaling, curators mint a curation share for the subgraph, entitling them to a portion of future query fees that the subgraph drives. Curator signal is represented as ERC20 tokens called Graph Curation Shares (GCS). Curators that want to earn more query fees should signal their GRT to subgraphs that they predict will generate a strong flow of fees to the network.Curators cannot be slashed for bad behavior, but there is a deposit tax on Curators to disincentivize poor decision making that could harm the integrity of the network. Curators also earn fewer query fees if they choose to curate on a low quality subgraph, since there will be fewer queries to process or fewer Indexers to process those queries. See the diagram below! +Curators make The Graph network efficient and signaling is the process that curators use to let Indexers know that a subgraph is good to index, where GRT is added to a bonding curve for a subgraph. Indexers can inherently trust the signal from a curator because upon signaling, curators mint a curation share for the subgraph, entitling them to a portion of future query fees that the subgraph drives. Curator signal is represented as ERC20 tokens called Graph Curation Shares (GCS). Curators that want to earn more query fees should signal their GRT to subgraphs that they predict will generate a strong flow of fees to the network. Curators cannot be slashed for bad behavior, but there is a deposit tax on Curators to disincentivize poor decision-making that could harm the integrity of the network. Curators also earn fewer query fees if they choose to curate on a low-quality Subgraph since there will be fewer queries to process or fewer Indexers to process those queries. See the diagram below! ![Signaling diagram](/img/curator-signaling.png) @@ -61,27 +61,27 @@ Indexers can find subgraphs to index based on curation signals they see in The G 1. The query market is inherently young at The Graph and there is risk that your %APY may be lower than you expect due to nascent market dynamics. 2. Curation Fee - when a curator signals GRT on a subgraph, they incur a 1% curation tax. This fee is burned and the rest is deposited into the reserve supply of the bonding curve. -3. When curators burn their shares to withdraw GRT, the GRT valuation of the remaining shares will be reduced. Be aware that in some cases, curators may decide to burn their shares **all at once**. This situation may be common if a dapp developer stops versioning/improving and querying their subgraph or if a subgraph fails. As a result, remaining curators might only be able to withdraw a fraction of their initial GRT. For a network role with a lower risk profile, see [Delegators](/delegating). +3. When curators burn their shares to withdraw GRT, the GRT valuation of the remaining shares will be reduced. Be aware that in some cases, curators may decide to burn their shares **all at once**. This situation may be common if a dApp developer stops versioning/improving and querying their subgraph or if a subgraph fails. As a result, remaining curators might only be able to withdraw a fraction of their initial GRT. For a network role with a lower risk profile, see [Delegators](/delegating). 4. A subgraph can fail due to a bug. A failed subgraph does not accrue query fees. As a result, you’ll have to wait until the developer fixes the bug and deploys a new version. - If you are subscribed to the newest version of a subgraph, your shares will auto-migrate to that new version. This will incur a 0.5% curation tax. - - If you have signalled on a specific subgraph version and it fails, you will have to manually burn your curation shares. Note that you may receive more or less GRT than you initially deposited into the curation curve, which is a risk associated with being a curator. You can then signal on the new subgraph version, thus incurring a 1% curation tax. + - If you have signaled on a specific subgraph version and it fails, you will have to manually burn your curation shares. Note that you may receive more or less GRT than you initially deposited into the curation curve, which is a risk associated with being a curator. You can then signal on the new subgraph version, thus incurring a 1% curation tax. ## Curation FAQs ### 1. What % of query fees do Curators earn? -By signalling on a subgraph, you will earn a share of all the query fees that this subgraph generates. 10% of all query fees goes to the Curators pro rata to their curation shares. This 10% is subject to governance. +By signalling on a subgraph, you will earn a share of all the query fees that this subgraph generates. 10% of all query fees goes to the Curators pro-rata to their curation shares. This 10% is subject to governance. ### 2. How do I decide which subgraphs are high quality to signal on? -Finding high quality subgraphs is a complex task, but it can be approached in many different ways. As a Curator, you want to look for trustworthy subgraphs that are driving query volume. A trustworthy subgraph may be valuable if it is complete, accurate, and supports a dapp’s data needs. A poorly architected subgraph might need to be revised or re-published, and can also end up failing. It is critical for Curators to review a subgraph’s architecture or code in order to assess if a subgraph is valuable. As a result: +Finding high-quality subgraphs is a complex task, but it can be approached in many different ways. As a Curator, you want to look for trustworthy subgraphs that are driving query volume. A trustworthy subgraph may be valuable if it is complete, accurate, and supports a dApp’s data needs. A poorly architected subgraph might need to be revised or re-published, and can also end up failing. It is critical for Curators to review a subgraph’s architecture or code in order to assess if a subgraph is valuable. As a result: - Curators can use their understanding of a network to try and predict how an individual subgraph may generate a higher or lower query volume in the future -- Curators should also understand the metrics that are available through the Graph Explorer. Metrics like past query volume and who the subgraph developer is can help determine whether or not a subgraph is worth signalling on. +- Curators should also understand the metrics that are available through The Graph Explorer. Metrics like past query volume and who the subgraph developer is can help determine whether or not a subgraph is worth signalling on. ### 3. What’s the cost of upgrading a subgraph? -Migrating your curation shares to a new subgraph version incurs a curation tax of 1%. Curators can choose to subscribe to the newest version of a subgraph. When curator shares get auto-migrated to a new version, Curators will also pay half curation tax, ie. 0.5%, because upgrading subgraphs is an on-chain action which costs gas. +Migrating your curation shares to a new subgraph version incurs a curation tax of 1%. Curators can choose to subscribe to the newest version of a subgraph. When curator shares get auto-migrated to a new version, Curators will also pay half curation tax, ie. 0.5%, because upgrading subgraphs is an on-chain action that costs gas. ### 4. How often can I upgrade my subgraph? @@ -89,7 +89,7 @@ It’s suggested that you don’t upgrade your subgraphs too frequently. See the ### 5. Can I sell my curation shares? -Curation shares cannot be "bought" or "sold" like other ERC20 tokens that you may be familiar with. They can only be minted (created) or burned (destroyed) along the bonding curve for a particular subgraph. The amount of GRT needed to mint new signal, and the amount of GRT you receive when you burn your existing signal, is determined by that bonding curve. As a Curator, you need to know that when you burn your curation shares to withdraw GRT, you can end up with more or less GRT than you initially deposited. +Curation shares cannot be "bought" or "sold" like other ERC20 tokens that you may be familiar with. They can only be minted (created) or burned (destroyed) along the bonding curve for a particular subgraph. The amount of GRT needed to mint a new signal, and the amount of GRT you receive when you burn your existing signal are determined by that bonding curve. As a Curator, you need to know that when you burn your curation shares to withdraw GRT, you can end up with more or less GRT than you initially deposited. Still confused? Check out our Curation video guide below: diff --git a/pages/en/delegating.mdx b/pages/en/delegating.mdx index e991a21ae52e..e335beffa081 100644 --- a/pages/en/delegating.mdx +++ b/pages/en/delegating.mdx @@ -8,11 +8,11 @@ By delegating to an Indexer, Delegators earn a portion of the Indexer's query fe ## Delegator Guide -This guide will explain how to be an effective Delegator in the Graph Network. Delegators share earnings of the protocol alongside all Indexers based on their delegated stake. A Delegator must use their best judgement to choose Indexers based on multiple factors. Please note this guide will not go over steps such as setting up Metamask properly, as that information is widely available on the internet. There are three sections in this guide: +This guide will explain how to be an effective Delegator in the Graph Network. Delegators share earnings of the protocol alongside all Indexers based on their delegated stake. A Delegator must use their best judgment to choose Indexers based on multiple factors. Please note this guide will not go over steps such as setting up Metamask properly, as that information is widely available on the internet. There are three sections in this guide: - The risks of delegating tokens in The Graph Network - How to calculate expected returns as a Delegator -- A Video guide showing the steps to delegate in the Graph Network UI +- A video guide showing the steps to delegate in the Graph Network UI ## Delegation Risks @@ -20,7 +20,7 @@ Listed below are the main risks of being a Delegator in the protocol. ### The delegation tax -Delegators cannot be slashed for bad behavior, but there is a tax on Delegators to disincentivize poor decision making that could harm the integrity of the network. +Delegators cannot be slashed for bad behavior, but there is a tax on Delegators to disincentivize poor decision-making that could harm the integrity of the network. It is important to understand that every time you delegate, you will be charged 0.5%. This means if you are delegating 1000 GRT, you will automatically burn 5 GRT. @@ -28,9 +28,9 @@ This means that to be safe, a Delegator should calculate what their return will ### The delegation unbonding period -Whenever a Delegator wants to undelegate, their tokens are subject to a 28 day unbonding period. This means they cannot transfer their tokens, or earn any rewards for 28 days. +Whenever a Delegator wants to undelegate, their tokens are subject to a 28-day unbonding period. This means they cannot transfer their tokens, or earn any rewards for 28 days. -One thing to consider as well is choosing an Indexer wisely. If you choose an Indexer who was not trustworthy, or not doing a good job, you will want to undelegate, which means you will be losing a lot of opportunity to earn rewards, which can be just as bad as burning GRT. +One thing to consider as well is choosing an Indexer wisely. If you choose an Indexer who was not trustworthy, or not doing a good job, you will want to undelegate, which means you will be losing a lot of opportunities to earn rewards, which can be just as bad as burning GRT.
![Delegation unbonding](/img/Delegation-Unbonding.png) _Note the 0.5% fee in the Delegation UI, as well as the 28 day @@ -41,7 +41,7 @@ One thing to consider as well is choosing an Indexer wisely. If you choose an In This is an important part to understand. First let's discuss three very important values, which are the Delegation Parameters. -Indexing Reward Cut - The indexing reward cut is the portion of the rewards that the Indexer will keep for themselves. That means, if it is set to 100%, as a Delegator you will get 0 indexing rewards. If you see 80% in the UI, that means as a Delegator, you will receive 20%. An important note - in the beginning of the network, Indexing Rewards will account for the majority of the rewards. +Indexing Reward Cut - The indexing reward cut is the portion of the rewards that the Indexer will keep for themselves. That means if it is set to 100%, as a Delegator you will get 0 indexing rewards. If you see 80% in the UI, that means as a Delegator, you will receive 20%. An important note - at the beginning of the network, Indexing Rewards will account for the majority of the rewards.
![Indexing Reward Cut](/img/Indexing-Reward-Cut.png) *The top Indexer is giving Delegators 90% of the rewards. The @@ -50,7 +50,7 @@ Indexing Reward Cut - The indexing reward cut is the portion of the rewards that - Query Fee Cut - This works exactly like the Indexing Reward Cut. However, this is specifically for returns on the query fees the Indexer collects. It should be noted that at the start of the network, returns from query fees will be very small compared to the indexing reward. It is recommended to pay attention to the network to determine when the query fees in the network will start to be more significant. -As you can see, there is a lot of thought that must go into choosing the right Indexer. This is why we highly recommend you explore The Graph Discord to determine who the Indexers are with the best social reputation, and technical reputation, to reward Delegators on a consistent basis. Many of the Indexers are very active in Discord, and will be happy to answer your questions. Many of them have been Indexing for months in the testnet, and are doing their best to help Delegators earn a good return, as it improves the health and success of the network. +As you can see, there is a lot of thought that must go into choosing the right Indexer. This is why we highly recommend you explore The Graph Discord to determine who the Indexers are with the best social reputation, and technical reputation, to reward Delegators consistently. Many of the Indexers are very active in Discord and will be happy to answer your questions. Many of them have been Indexing for months in the testnet, and are doing their best to help Delegators earn a good return, as it improves the health and success of the network. ### Calculating Delegators expected return @@ -77,9 +77,9 @@ A Delegator can therefore do the math to determine that the Indexer offering 20% ### Considering the delegation capacity -Another thing to consider is the delegation capacity. Currently the Delegation Ratio is set to 16. This means that if an Indexer has staked 1,000,000 GRT, their Delegation Capacity is 16,000,000 GRT of Delegated tokens that they can use in the protocol. Any delegated tokens over this amount will dilute all the Delegator rewards. +Another thing to consider is the delegation capacity. Currently, the Delegation Ratio is set to 16. This means that if an Indexer has staked 1,000,000 GRT, their Delegation Capacity is 16,000,000 GRT of Delegated tokens that they can use in the protocol. Any delegated tokens over this amount will dilute all the Delegator rewards. -Imagine an Indexer has 100,000,000 GRT delegated to them, and their capacity is only 16,000,000 GRT. This means effectively, 84,000,000 GRT tokens are not being used to earn tokens. And all the Delegators, and the Indexer, are earning way less rewards that they could be. +Imagine an Indexer has 100,000,000 GRT delegated to them, and their capacity is only 16,000,000 GRT. This means effectively, 84,000,000 GRT tokens are not being used to earn tokens. And all the Delegators, and the Indexer, are earning way less rewards than they could be. Therefore a Delegator should always consider the Delegation Capacity of an Indexer, and factor it into their decision making. diff --git a/pages/en/developer/create-subgraph-hosted.mdx b/pages/en/developer/create-subgraph-hosted.mdx index 2666d3965b8e..0ce410191fb6 100644 --- a/pages/en/developer/create-subgraph-hosted.mdx +++ b/pages/en/developer/create-subgraph-hosted.mdx @@ -4,7 +4,7 @@ title: Create a Subgraph Before being able to use the Graph CLI, you need to create your subgraph in [Subgraph Studio](https://thegraph.com/studio). You will then be able to setup your subgraph project and deploy it to the platform of your choice. Note that **subgraphs that do not index Ethereum mainnet will not be published to The Graph Network**. -The `graph init` command can be used to set up a new subgraph project, either from an existing contract on any of the public Ethereum networks, or from an example subgraph. This command can be used to create a subgraph on the Subgraph Studio by passing in `graph init --product subgraph-studio`. If you already have a smart contract deployed to Ethereum mainnet or one of the testnets, bootstrapping a new subgraph from that contract can be a good way to get started. But first, a little about the networks The Graph supports. +The `graph init` command can be used to set up a new subgraph project, either from an existing contract on any of the public Ethereum networks or from an example subgraph. This command can be used to create a subgraph on the Subgraph Studio by passing in `graph init --product subgraph-studio`. If you already have a smart contract deployed to Ethereum mainnet or one of the testnets, bootstrapping a new subgraph from that contract can be a good way to get started. But first, a little about the networks The Graph supports. ## Supported Networks @@ -44,7 +44,7 @@ The Graph Network supports subgraphs indexing mainnet Ethereum: - `aurora` - `aurora-testnet` -The Graph's Hosted Service relies on the stability and reliability of the underlying technologies, namely the provided JSON RPC endpoints. Newer networks will be marked as being in beta until the network has proven itself in terms of stability, reliability, and scalability. During this beta period, there is risk of downtime and unexpected behaviour. +The Graph's Hosted Service relies on the stability and reliability of the underlying technologies, namely the provided JSON RPC endpoints. Newer networks will be marked as being in beta until the network has proven itself in terms of stability, reliability, and scalability. During this beta period, there is a risk of downtime and unexpected behaviour. Remember that you will **not be able** to publish a subgraph that indexes a non-mainnet network to the decentralized Graph Network in [Subgraph Studio](/studio/subgraph-studio). @@ -122,15 +122,15 @@ The important entries to update for the manifest are: - `description`: a human-readable description of what the subgraph is. This description is displayed by the Graph Explorer when the subgraph is deployed to the Hosted Service. -- `repository`: the URL of the repository where the subgraph manifest can be found. This is also displayed by the Graph Explorer. +- `repository`: the URL of the repository where the subgraph manifest can be found. This is also displayed by The Graph Explorer. - `features`: a list of all used [feature](#experimental-features) names. -- `dataSources.source`: the address of the smart contract the subgraph sources, and the abi of the smart contract to use. The address is optional; omitting it allows to index matching events from all contracts. +- `dataSources.source`: the address of the smart contract the subgraph sources, and the ABI of the smart contract to use. The address is optional; omitting it allows to index matching events from all contracts. -- `dataSources.source.startBlock`: the optional number of the block that the data source starts indexing from. In most cases we suggest using the block in which the contract was created. +- `dataSources.source.startBlock`: the optional number of the block that the data source starts indexing from. In most cases, we suggest using the block in which the contract was created. -- `dataSources.mapping.entities`: the entities that the data source writes to the store. The schema for each entity is defined in the the schema.graphql file. +- `dataSources.mapping.entities`: the entities that the data source writes to the store. The schema for each entity is defined in the schema.graphql file. - `dataSources.mapping.abis`: one or more named ABI files for the source contract as well as any other smart contracts that you interact with from within the mappings. @@ -145,7 +145,7 @@ A single subgraph can index data from multiple smart contracts. Add an entry for The triggers for a data source within a block are ordered using the following process: 1. Event and call triggers are first ordered by transaction index within the block. -2. Event and call triggers with in the same transaction are ordered using a convention: event triggers first then call triggers, each type respecting the order they are defined in the manifest. +2. Event and call triggers within the same transaction are ordered using a convention: event triggers first then call triggers, each type respecting the order they are defined in the manifest. 3. Block triggers are run after event and call triggers, in the order they are defined in the manifest. These ordering rules are subject to change. @@ -164,9 +164,9 @@ The schema for your subgraph is in the file `schema.graphql`. GraphQL schemas ar ## Defining Entities -Before defining entities, it is important to take a step back and think about how your data is structured and linked. All queries will be made against the data model defined in the subgraph schema and the entities indexed by the subgraph. Because of this, it is good to define the subgraph schema in a way that matches the needs of your dapp. It may be useful to imagine entities as "objects containing data", rather than as events or functions. +Before defining entities, it is important to take a step back and think about how your data is structured and linked. All queries will be made against the data model defined in the subgraph schema and the entities indexed by the subgraph. Because of this, it is good to define the subgraph schema in a way that matches the needs of your dApp. It may be useful to imagine entities as "objects containing data", rather than as events or functions. -With The Graph, you simply define entity types in `schema.graphql`, and Graph Node will generate top level fields for querying single instances and collections of that entity type. Each type that should be an entity is required to be annotated with an `@entity` directive. +With The Graph, you simply define entity types in `schema.graphql`, and Graph Node will generate top-level fields for querying single instances and collections of that entity type. Each type that should be an entity is required to be annotated with an `@entity` directive. ### Good Example @@ -210,7 +210,7 @@ Entity fields can be defined as required or optional. Required fields are indica Null value resolved for non-null field 'name' ``` -Each entity must have an `id` field, which is of type `ID!` (string). The `id` field serves as the primary key, and needs to be unique among all entities of the same type. +Each entity must have an `id` field, which is of type `ID!` (string). The `id` field serves as the primary key and needs to be unique among all entities of the same type. ### Built-In Scalar Types @@ -224,9 +224,9 @@ We support the following scalars in our GraphQL API: | `ID` | Stored as a `string`. | | `String` | Scalar for `string` values. Null characters are not supported and are automatically removed. | | `Boolean` | Scalar for `boolean` values. | -| `Int` | The GraphQL spec defines `Int` to have size of 32 bytes. | +| `Int` | The GraphQL spec defines `Int` to have a size of 32 bytes. | | `BigInt` | Large integers. Used for Ethereum's `uint32`, `int64`, `uint64`, ..., `uint256` types. Note: Everything below `uint32`, such as `int32`, `uint24` or `int8` is represented as `i32`. | -| `BigDecimal` | `BigDecimal` High precision decimals represented as a signficand and an exponent. The exponent range is from −6143 to +6144. Rounded to 34 significant digits. | +| `BigDecimal` | `BigDecimal` High precision decimals represented as a significand and an exponent. The exponent range is from −6143 to +6144. Rounded to 34 significant digits. | #### Enums @@ -380,7 +380,7 @@ type MyFirstEntity @entity { ## Defining Fulltext Search Fields -Fulltext search queries filter and rank entities based on a text search input. Fulltext queries are able to return matches for similar words by processing the query text input into stems before comparing to the indexed text data. +Fulltext search queries filter and rank entities based on a text search input. Fulltext queries are able to return matches for similar words by processing the query text input into stems before comparing them to the indexed text data. A fulltext query definition includes the query name, the language dictionary used to process the text fields, the ranking algorithm used to order the results, and the fields included in the search. Each fulltext query may span multiple fields, but all included fields must be from a single entity type. @@ -407,7 +407,7 @@ type Band @entity { } ``` -The example `bandSearch` field can be used in queries to filter `Band` entities based on the text documents in the `name`, `description`, and `bio` fields. Jump to [GraphQL API - Queries](/developer/graphql-api#queries) for a description of the Fulltext search API and for more example usage. +The example `bandSearch` field can be used in queries to filter `Band` entities based on the text documents in the `name`, `description`, and `bio` fields. Jump to [GraphQL API - Queries](/developer/graphql-api#queries) for a description of the fulltext search API and more example usage. ```graphql query { @@ -424,7 +424,7 @@ query { ### Languages supported -Choosing a different language will have a definitive, though sometimes subtle, effect on the fulltext search API. Fields covered by a fulltext query field are examined in the context of the chosen language, so the lexemes produced by analysis and search queries vary language to language. For example: when using the supported Turkish dictionary "token" is stemmed to "toke" while, of course, the English dictionary will stem it to "token". +Choosing a different language will have a definitive, though sometimes subtle, effect on the fulltext search API. Fields covered by a fulltext query field are examined in the context of the chosen language, so the lexemes produced by analysis and search queries vary from language to language. For example: when using the supported Turkish dictionary "token" is stemmed to "toke" while, of course, the English dictionary will stem it to "token". Supported language dictionaries: @@ -440,7 +440,7 @@ Supported language dictionaries: | hu | Hungarian | | it | Italian | | no | Norwegian | -| pt | Portugese | +| pt | Portuguese | | ro | Romanian | | ru | Russian | | es | Spanish | @@ -491,7 +491,7 @@ export function handleUpdatedGravatar(event: UpdatedGravatar): void { The first handler takes a `NewGravatar` event and creates a new `Gravatar` entity with `new Gravatar(event.params.id.toHex())`, populating the entity fields using the corresponding event parameters. This entity instance is represented by the variable `gravatar`, with an id value of `event.params.id.toHex()`. -The second handler tries to load the existing `Gravatar` from the Graph Node store. If it does not exist yet, it is created on demand. The entity is then updated to match the new event parameters, before it is saved back to the store using `gravatar.save()`. +The second handler tries to load the existing `Gravatar` from the Graph Node store. If it does not exist yet, it is created on-demand. The entity is then updated to match the new event parameters before it is saved back to the store using `gravatar.save()`. ### Recommended IDs for Creating New Entities @@ -505,7 +505,7 @@ We provide the [Graph Typescript Library](https://github.com/graphprotocol/graph ## Code Generation -In order to make working smart contracts, events and entities easy and type-safe, the Graph CLI can generate AssemblyScript types from the subgraph's GraphQL schema and the contract ABIs included in the data sources. +In order to make working smart contracts, events, and entities easy and type-safe, the Graph CLI can generate AssemblyScript types from the subgraph's GraphQL schema and the contract ABIs included in the data sources. This is done with @@ -523,7 +523,7 @@ yarn codegen npm run codegen ``` -This will generate an AssemblyScript class for every smart contract in the ABI files mentioned in `subgraph.yaml`, allowing you to bind these contracts to specific addresses in the mappings and call read-only contract methods against the block being processed. It will also generate a class for every contract event to provide easy access to event parameters as well as the block and transaction the event originated from. All of these types are written to `//.ts`. In the example subgraph, this would be `generated/Gravity/Gravity.ts`, allowing mappings to import these types with +This will generate an AssemblyScript class for every smart contract in the ABI files mentioned in `subgraph.yaml`, allowing you to bind these contracts to specific addresses in the mappings and call read-only contract methods against the block being processed. It will also generate a class for every contract event to provide easy access to event parameters, as well as the block and transaction the event originated from. All of these types are written to `//.ts`. In the example subgraph, this would be `generated/Gravity/Gravity.ts`, allowing mappings to import these types with. ```javascript import { @@ -547,11 +547,11 @@ Code generation does not check your mapping code in `src/mapping.ts`. If you wan ## Data Source Templates -A common pattern in Ethereum smart contracts is the use of registry or factory contracts, where one contract creates, manages or references an arbitrary number of other contracts that each have their own state and events. The addresses of these sub-contracts may or may not be known upfront and many of these contracts may be created and/or added over time. This is why, in such cases, defining a single data source or a fixed number of data sources is impossible and a more dynamic approach is needed: _data source templates_. +A common pattern in Ethereum smart contracts is the use of registry or factory contracts, where one contract creates, manages, or references an arbitrary number of other contracts that each have their own state and events. The addresses of these sub-contracts may or may not be known upfront and many of these contracts may be created and/or added over time. This is why, in such cases, defining a single data source or a fixed number of data sources is impossible and a more dynamic approach is needed: _data source templates_. ### Data Source for the Main Contract -First, you define a regular data source for the main contract. The snippet below shows a simplified example data source for the [Uniswap](https://uniswap.io) exchange factory contract. Note the `NewExchange(address,address)` event handler. This is emitted when a new exchange contract is created on chain by the factory contract. +First, you define a regular data source for the main contract. The snippet below shows a simplified example data source for the [Uniswap](https://uniswap.io) exchange factory contract. Note the `NewExchange(address,address)` event handler. This is emitted when a new exchange contract is created on-chain by the factory contract. ```yaml dataSources: @@ -578,7 +578,7 @@ dataSources: ### Data Source Templates for Dynamically Created Contracts -Then, you add _data source templates_ to the manifest. These are identical to regular data sources, except that they lack a predefined contract address under `source`. Typically, you would define one template for each type of sub-contract managed or referenced by the parent contract. +Then, you add _data source templates_ to the manifest. These are identical to regular data sources, except that they lack a pre-defined contract address under `source`. Typically, you would define one template for each type of sub-contract managed or referenced by the parent contract. ```yaml dataSources: @@ -695,11 +695,11 @@ While events provide an effective way to collect relevant changes to the state o Call handlers will only trigger in one of two cases: when the function specified is called by an account other than the contract itself or when it is marked as external in Solidity and called as part of another function in the same contract. -> **Note:** Call handlers are not supported on Rinkeby, Goerli or Ganache. Call handlers currently depend on the Parity tracing API and these networks do not support it. +> **Note:** Call handlers are not supported on Rinkeby, Goerli, or Ganache. Call handlers currently depend on the Parity tracing API and these networks do not support it. ### Defining a Call Handler -To define a call handler in your manifest simply add a `callHandlers` array under the data source you would like to subscribe to. +To define a call handler in your manifest, simply add a `callHandlers` array under the data source you would like to subscribe to. ```yaml dataSources: @@ -747,7 +747,7 @@ The `handleCreateGravatar` function takes a new `CreateGravatarCall` which is a ## Block Handlers -In addition to subscribing to contract events or function calls, a subgraph may want to update its data as new blocks are appended to the chain. To achieve this a subgraph can run a function after every block or after blocks that match a predefined filter. +In addition to subscribing to contract events or function calls, a subgraph may want to update its data as new blocks are appended to the chain. To achieve this a subgraph can run a function after every block or after blocks that match a pre-defined filter. ### Supported Filters @@ -758,7 +758,7 @@ filter: _The defined handler will be called once for every block which contains a call to the contract (data source) the handler is defined under._ -The absense of a filter for a block handler will ensure that the handler is called every block. A data source can only contain one block handler for each filter type. +The absence of a filter for a block handler will ensure that the handler is called every block. A data source can only contain one block handler for each filter type. ```yaml dataSources: @@ -834,17 +834,17 @@ features: dataSources: ... ``` -Note that using a feature without declaring it will incur in a **validation error** during subgraph deployment, but no errors will occur if a feature is declared but not used. +Note that using a feature without declaring it will incur a **validation error** during subgraph deployment, but no errors will occur if a feature is declared but not used. ### IPFS on Ethereum Contracts -A common use case for combining IPFS with Ethereum is to store data on IPFS that would be too expensive to maintain on chain, and reference the IPFS hash in Ethereum contracts. +A common use case for combining IPFS with Ethereum is to store data on IPFS that would be too expensive to maintain on-chain, and reference the IPFS hash in Ethereum contracts. Given such IPFS hashes, subgraphs can read the corresponding files from IPFS using `ipfs.cat` and `ipfs.map`. To do this reliably, however, it is required that these files are pinned on the IPFS node that the Graph Node indexing the subgraph connects to. In the case of the [hosted service](https://thegraph.com/hosted-service), this is [https://api.thegraph.com/ipfs/](https://api.thegraph.com/ipfs/). > **Note:** The Graph Network does not yet support `ipfs.cat` and `ipfs.map`, and developers should not deploy subgraphs using that functionality to the network via the Studio. -In order to make this easy for subgraph developers, The Graph team wrote a tool for transfering files from one IPFS node to another, called [ipfs-sync](https://github.com/graphprotocol/ipfs-sync). +In order to make this easy for subgraph developers, The Graph team wrote a tool for transferring files from one IPFS node to another, called [ipfs-sync](https://github.com/graphprotocol/ipfs-sync). > **[Feature Management](#experimental-features):** `ipfsOnEthereumContracts` must be declared under `features` in the subgraph manifest. @@ -852,7 +852,7 @@ When running a local Graph Node, the `GRAPH_ALLOW_NON_DETERMINISTIC_IPFS` enviro ### Non-fatal errors -Indexing errors on already synced subgraphs will, by default, cause the subgraph to fail and stop syncing. Subgraphs can alternatively be configured to continue syncing in the presence of errors, by ignoring the changes made by the handler which provoked the error. This gives subgraph authors time to correct their subgraphs while queries continue to be served against the latest block, though the results will possibly be inconsistent due to the bug that caused the error. Note that some errors are still always fatal, to be non-fatal the error must be known to be deterministic. +Indexing errors on already synced subgraphs will, by default, cause the subgraph to fail and stop syncing. Subgraphs can alternatively be configured to continue syncing in the presence of errors, by ignoring the changes made by the handler which provoked the error. This gives subgraph authors time to correct their subgraphs while queries continue to be served against the latest block, though the results might be inconsistent due to the bug that caused the error. Note that some errors are still always fatal. To be non-fatal, the error must be known to be deterministic. > **Note:** The Graph Network does not yet support non-fatal errors, and developers should not deploy subgraphs using that functionality to the network via the Studio. @@ -878,7 +878,7 @@ _meta { } ``` -If the subgraph encounters an error that query will return both the data and a graphql error with the message `"indexing_error"`, as in this example response: +If the subgraph encounters an error, that query will return both the data and a graphql error with the message `"indexing_error"`, as in this example response: ```graphql "data": { @@ -900,11 +900,11 @@ If the subgraph encounters an error that query will return both the data and a g ### Grafting onto Existing Subgraphs -When a subgraph is first deployed, it starts indexing events at the genesis block of the corresponding chain (or at the `startBlock` defined with each data source) In some circumstances, it is beneficial to reuse the data from an existing subgraph and start indexing at a much later block. This mode of indexing is called _Grafting_. Grafting is, for example, useful during development to get past simple errors in the mappings quickly, or to temporarily get an existing subgraph working again after it has failed. +When a subgraph is first deployed, it starts indexing events at the genesis block of the corresponding chain (or at the `startBlock` defined with each data source) In some circumstances; it is beneficial to reuse the data from an existing subgraph and start indexing at a much later block. This mode of indexing is called _Grafting_. Grafting is, for example, useful during development to get past simple errors in the mappings quickly or to temporarily get an existing subgraph working again after it has failed. > **Note:** Grafting requires that the Indexer has indexed the base subgraph. It is not recommended on The Graph Network at this time, and developers should not deploy subgraphs using that functionality to the network via the Studio. -A subgraph is grafted onto a base subgraph when the subgraph manifest in `subgraph.yaml` contains a `graft` block at the toplevel: +A subgraph is grafted onto a base subgraph when the subgraph manifest in `subgraph.yaml` contains a `graft` block at the top-level: ```yaml description: ... @@ -915,9 +915,9 @@ graft: When a subgraph whose manifest contains a `graft` block is deployed, Graph Node will copy the data of the `base` subgraph up to and including the given `block` and then continue indexing the new subgraph from that block on. The base subgraph must exist on the target Graph Node instance and must have indexed up to at least the given block. Because of this restriction, grafting should only be used during development or during an emergency to speed up producing an equivalent non-grafted subgraph. -Because grafting copies rather than indexes base data it is much quicker in getting the subgraph to the desired block than indexing from scratch, though the initial data copy can still take several hours for very large subgraphs. While the grafted subgraph is being initialized, the Graph Node will log information about the entity types that have already been copied. +Because grafting copies rather than indexes base data, it is much quicker to get the subgraph to the desired block than indexing from scratch, though the initial data copy can still take several hours for very large subgraphs. While the grafted subgraph is being initialized, the Graph Node will log information about the entity types that have already been copied. -The grafted subgraph can use a GraphQL schema that is not identical to the one of the base subgraph, but merely compatible with it. It has to be a valid subgraph schema in its own right but may deviate from the base subgraph's schema in the following ways: +The grafted subgraph can use a GraphQL schema that is not identical to the one of the base subgraph, but merely compatible with it. It has to be a valid subgraph schema in its own right, but may deviate from the base subgraph's schema in the following ways: - It adds or removes entity types - It removes attributes from entity types @@ -927,4 +927,4 @@ The grafted subgraph can use a GraphQL schema that is not identical to the one o - It adds or removes interfaces - It changes for which entity types an interface is implemented -> **[Feature Management](#experimental-features):** `grafting` must be declared under `features` in the subgraph manifest. +> **[Feature Management](#experimental-features):** `grafting` must be declared under `features` in the subgraph manifest. \ No newline at end of file diff --git a/pages/en/developer/deprecating-a-subgraph.mdx b/pages/en/developer/deprecating-a-subgraph.mdx index f8966e025c13..d353368a6086 100644 --- a/pages/en/developer/deprecating-a-subgraph.mdx +++ b/pages/en/developer/deprecating-a-subgraph.mdx @@ -10,8 +10,8 @@ So you'd like to deprecate your subgraph on The Graph Explorer. You've come to t 4. Inputs for #2 and #3 can be found in your `` which is composed of the `{graphAccount}-{subgraphNumber}`. For example, the [Sushi Subgraph's](https://thegraph.com/explorer/subgraph?id=0x4bb4c1b0745ef7b4642feeccd0740dec417ca0a0-0&version=0x4bb4c1b0745ef7b4642feeccd0740dec417ca0a0-0-0&view=Overview) ID is `<0x4bb4c1b0745ef7b4642feeccd0740dec417ca0a0-0>`, which is a combination of `graphAccount` = `<0x4bb4c1b0745ef7b4642feeccd0740dec417ca0a0>` and `subgraphNumber` = `<0>` 5. Voila! Your subgraph will no longer show up on searches on The Graph Explorer. Please note the following: -- Curators will not be able to signal on the subgraph anymore -- Curators that already signaled on the subgraph will be able to withdraw their signal at an average share price +- Curators will not be able to signal on the subgraph anymore. +- Curators that already signaled on the subgraph will be able to withdraw their signal at an average share price. - Deprecated subgraphs will be indicated with an error message. -If you interacted with the now deprecated subgraph, you'll be able to find it in your user profile under the "Subgraphs", "Indexing", or "Curating" tab respectively. +If you interacted with the deprecated subgraph, you'll be able to find it in your user profile under the "Subgraphs", "Indexing", or "Curating" tab, respectively. diff --git a/pages/en/developer/developer-faq.mdx b/pages/en/developer/developer-faq.mdx index 41449c60e5ab..611085de48d7 100644 --- a/pages/en/developer/developer-faq.mdx +++ b/pages/en/developer/developer-faq.mdx @@ -8,7 +8,7 @@ It is not possible to delete subgraphs once they are created. ### 2. Can I change my subgraph name? -No. Once a subgraph is created, the name cannot be changed. Make sure to think of this carefully before you create your subgraph so it is easily searchable and identifiable by other dapps. +No. Once a subgraph is created, the name cannot be changed. Make sure to think of this carefully before you create your subgraph so it is easily searchable and identifiable by other dApps. ### 3. Can I change the GitHub account associated with my subgraph? @@ -16,9 +16,9 @@ No. Once a subgraph is created, the associated GitHub account cannot be changed. ### 4. Am I still able to create a subgraph if my smart contracts don't have events? -It is highly recommended that you structure your smart contracts to have events associated with data you are interested in querying. Event handlers in the subgraph are triggered by contract events, and are by far the fastest way to retrieve useful data. +It is highly recommended that you structure your smart contracts to have events associated with data you are interested in querying. Event handlers in the subgraph are triggered by contract events and are by far the fastest way to retrieve useful data. -If the contracts you are working with do not contain events, your subgraph can use call and block handlers to trigger indexing. Although this is not recommended as performance will be significantly slower. +If the contracts you are working with do not contain events, your subgraph can use call and block handlers to trigger indexing. Although this is not recommended, as performance will be significantly slower. ### 5. Is it possible to deploy one subgraph with the same name for multiple networks? @@ -26,7 +26,7 @@ You will need separate names for multiple networks. While you can't have differe ### 6. How are templates different from data sources? -Templates allow you to create data sources on the fly, while your subgraph is indexing. It might be the case that your contract will spawn new contracts as people interact with it, and since you know the shape of those contracts (ABI, events, etc) up front you can define how you want to index them in a template and when they are spawned your subgraph will create a dynamic data source by supplying the contract address. +Templates allow you to create data sources on the fly, while your subgraph is indexing. It might be the case that your contract will spawn new contracts as people interact with it, and since you know the shape of those contracts (ABI, events, etc) upfront you can define how you want to index them in a template and when they are spawned your subgraph will create a dynamic data source by supplying the contract address. Check out the "Instantiating a data source template" section on: [Data Source Templates](/developer/create-subgraph-hosted#data-source-templates). @@ -46,9 +46,9 @@ Take a look at `Access to smart contract` state inside the section [AssemblyScri ### 9. Is it possible to set up a subgraph using `graph init` from `graph-cli` with two contracts? Or should I manually add another datasource in `subgraph.yaml` after running `graph init`? -Unfortunately this is currently not possible. `graph init` is intended as a basic starting point, from which you can then add more data sources manually. +Unfortunately, this is currently not possible. `graph init` is intended as a basic starting point, from which you can then add more data sources manually. -### 10. I want to contribute or add a GitHub issue, where can I find the open source repositories? +### 10. I want to contribute or add a GitHub issue. Where can I find the open-source repositories? - [graph-node](https://github.com/graphprotocol/graph-node) - [graph-cli](https://github.com/graphprotocol/graph-cli) @@ -81,15 +81,15 @@ On Rinkeby we support block handlers, but without `filter: call`. Call handlers Not currently, as mappings are written in AssemblyScript. One possible alternative solution to this is to store raw data in entities and perform logic that requires JS libraries on the client. -### 16. Is it possible to specifying what block to start indexing on? +### 16. Is it possible to specify what block to start indexing on? -Yes. `dataSources.source.startBlock` in the `subgraph.yaml` file specifies the number of the block that the data source starts indexing from. In most cases we suggest using the block in which the contract was created: Start blocks +Yes. `dataSources.source.startBlock` in the `subgraph.yaml` file specifies the number of the block that the data source starts indexing from. In most cases, we suggest using the block in which the contract was created: Start blocks -### 17. Are there some tips to increase performance of indexing? My subgraph is taking a very long time to sync. +### 17. Are there some tips to increase the performance of indexing? My subgraph is taking a very long time to sync. Yes, you should take a look at the optional start block feature to start indexing from the block that the contract was deployed: [Start blocks](/developer/create-subgraph-hosted#start-blocks) -### 18. Is there a way to query the subgraph directly to determine what the latest block number it has indexed? +### 18. Is there a way to query the subgraph directly to determine the latest block number it has indexed? Yes! Try the following command, substituting "organization/subgraphName" with the organization under it is published and the name of your subgraph: @@ -145,15 +145,15 @@ Federation is not supported yet, although we do want to support it in the future ### 22. Is there a limit to how many objects The Graph can return per query? -By default query responses are limited to 100 items per collection. If you want to receive more, you can go up to 1000 items per collection and beyond that you can paginate with: +By default, query responses are limited to 100 items per collection. If you want to receive more, you can go up to 1000 items per collection and beyond that, you can paginate with: ```graphql someCollection(first: 1000, skip: ) { ... } ``` -### 23. If my dapp frontend uses The Graph for querying, do I need to write my query key into the frontend directly? What if we pay query fees for users – will malicious users cause our query fees to be very high? +### 23. If my dApp frontend uses The Graph for querying, do I need to write my query key into the frontend directly? What if we pay query fees for users – will malicious users cause our query fees to be very high? -Currently, the recommended approach for a dapp is to add the key to the frontend and expose it to end users. That said, you can limit that key to a host name, like _yourdapp.io_ and subgraph. The gateway is currently being run by Edge & Node. Part of the responsibility of a gateway is to monitor for abusive behavior and block traffic from malicious clients. +Currently, the recommended approach for a dApp is to add the key to the frontend and expose it to end-users. That said, you can limit that key to a hostname, like _yourdapp.io_ and subgraph. The gateway is currently being run by Edge & Node. Part of the responsibility of a gateway is to monitor for abusive behavior and block traffic from malicious clients. ### 24. Where do I go to find my current subgraph on the Hosted Service? @@ -169,4 +169,4 @@ If and when there are plans to do this, the community will be notified well ahea ### 27. How do I upgrade a subgraph on mainnet? -If you’re a subgraph developer, you can upgrade a new version of your subgraph to the Studio using the CLI. It’ll be private at that point but if you’re happy with it, you can publish to the decentralized Graph Explorer. This will create a new version of your subgraph that Curators can start signaling on. +If you’re a subgraph developer, you can upgrade a new version of your subgraph to the Studio using the CLI. It’ll be private at that point, but if you’re happy with it, you can publish to the decentralized Graph Explorer. This will create a new version of your subgraph that Curators can start signaling on. diff --git a/pages/en/developer/publish-subgraph.mdx b/pages/en/developer/publish-subgraph.mdx index 2f35f5eb1bae..9a3c778ec1e1 100644 --- a/pages/en/developer/publish-subgraph.mdx +++ b/pages/en/developer/publish-subgraph.mdx @@ -24,4 +24,4 @@ Subgraphs can be published to the decentralized network directly from the Subgra ### Updating metadata for a published subgraph -Once your subgraph has been published to the decentralized network, you can modify the metadata at any time by making the update in the Subgraph Studio dashboard of the subgraph. After saving the changes and publishing your updates to the network, they will be reflected in the Graph Explorer. This won’t create a new version, as your deployment hasn’t changed. +Once your subgraph has been published to the decentralized network, you can modify the metadata at any time by making the update in the Subgraph Studio dashboard of the subgraph. After saving the changes and publishing your updates to the network, they will be reflected in The Graph Explorer. This won’t create a new version, as your deployment hasn’t changed. \ No newline at end of file diff --git a/pages/en/developer/querying-from-your-app.mdx b/pages/en/developer/querying-from-your-app.mdx index c09c44efee72..532e7525001e 100644 --- a/pages/en/developer/querying-from-your-app.mdx +++ b/pages/en/developer/querying-from-your-app.mdx @@ -2,7 +2,7 @@ title: Querying from an Application --- -Once a subgraph is deployed to the Subgraph Studio or to the Graph Explorer, you will be given the endpoint for your GraphQL API that should look something like this: +Once a subgraph is deployed to the Subgraph Studio or to The Graph Explorer, you will be given the endpoint for your GraphQL API that should look something like this: **Subgraph Studio (testing endpoint)** @@ -24,9 +24,9 @@ Here are a couple of the more popular GraphQL clients in the ecosystem and how t ### Apollo client -[Apollo client](https://www.apollographql.com/docs/) supports web projects including frameworks like React and Vue, as well as mobile clients like iOS, Android, and React Native. +[Apollo client](https://www.apollographql.com/docs/) supports web projects, including frameworks like React and Vue, as well as mobile clients like iOS, Android, and React Native. -Let's look at how fetch data from a subgraph with Apollo client in a web project. +Let's look at how to fetch data from a subgraph with Apollo client in a web project. First, install `@apollo/client` and `graphql`: @@ -100,9 +100,9 @@ client ### URQL -Another option is [URQL](https://formidable.com/open-source/urql/), a somewhat lighter weight GraphQL client library. +Another option is [URQL](https://formidable.com/open-source/urql/), a somewhat lighter-weight GraphQL client library. -Let's look at how fetch data from a subgraph with URQL in a web project. +Let's look at how to fetch data from a subgraph with URQL in a web project. First, install `urql` and `graphql`: diff --git a/pages/en/developer/quick-start.mdx b/pages/en/developer/quick-start.mdx index 6893d424ddc2..3f1ced0cb25f 100644 --- a/pages/en/developer/quick-start.mdx +++ b/pages/en/developer/quick-start.mdx @@ -35,7 +35,7 @@ graph init --studio ### 3. Write your Subgraph -The previous commands creates a scaffold subgraph that you can use as a starting point for building your subgraph. When making changes to the subgraph, you will mainly work with three files: +The previous commands create a scaffold subgraph that you can use as a starting point for building your subgraph. When making changes to the subgraph, you will mainly work with three files: - Manifest (subgraph.yaml) - The manifest defines what datasources your subgraphs will index. - Schema (schema.graphql) - The GraphQL schema defines what data you wish to retreive from the subgraph. @@ -111,7 +111,7 @@ The logs should tell you if there are any errors. If your subgraph is failing, y ### 6. Query your Subgraph -You can now query your subgraph by following [these instructions](/developer/query-the-graph). You can query from your dapp if you don't have your API key via the free, rate limited temporary query URL that can be used for development and staging. You can read the additional instructions for how to query a subgraph from a frontend application [here](/developer/querying-from-your-app). +You can now query your subgraph by following [these instructions](/developer/query-the-graph). You can query from your dApp if you don't have your API key via the free, rate-limited temporary query URL that can be used for development and staging. You can read the additional instructions for how to query a subgraph from a frontend application [here](/developer/querying-from-your-app). ## Hosted Service @@ -157,9 +157,9 @@ For more information on how to write your subgraph, see [Create a Subgraph](/dev ### 4. Deploy your Subgraph -- Sign into the [Hosted Service](https://thegraph.com/hosted-service/) using your github account +- Sign into the [Hosted Service](https://thegraph.com/hosted-service/) using your GitHub account - Click Add Subgraph and fill out the required information. Use the same subgraph name as in step 2. -- Run codegen in the subgraph folder +- Run `codegen` in the subgraph folder ```sh # NPM @@ -224,4 +224,4 @@ The logs should tell you if there are any errors. If your subgraph is failing, y ### 6. Query your Subgraph -Follow [these instructions](/hosted-service/query-hosted-service) to query your subgraph on the Hosted Service. +Follow [these instructions](/hosted-service/query-hosted-service) to query your subgraph on the Hosted Service. \ No newline at end of file diff --git a/pages/en/explorer.mdx b/pages/en/explorer.mdx index db46cd6bdad9..895064ec5ac5 100644 --- a/pages/en/explorer.mdx +++ b/pages/en/explorer.mdx @@ -2,7 +2,7 @@ title: The Graph Explorer --- -Welcome to the Graph Explorer, or as we like to call it, your decentralized portal into the world of subgraphs and network data. 👩🏽‍🚀 The Graph Explorer consists of multiple parts where you can interact with other subgraph developers, dapp developers, Curators, Indexers, and Delegators. For a general overview of the Graph Explorer, check out the video below (or keep reading below): +Welcome to the Graph Explorer, or as we like to call it, your decentralized portal into the world of subgraphs and network data. 👩🏽‍🚀 The Graph Explorer consists of multiple parts where you can interact with other subgraph developers, dApp developers, Curators, Indexers, and Delegators. For a general overview of the Graph Explorer, check out the video below (or keep reading below):
-Remember, while you’re going through your publishing flow, you’ll be able to push to either mainnet or Rinkeby, the testnet we support. If you’re a first time subgraph developer, we highly suggest you start with publishing to Rinkeby, which is free to do. This will allow you to see how the subgraph will work in The Graph Explorer and will allow you to test curation elements. +Remember, while you’re going through your publishing flow, you’ll be able to push to either mainnet or Rinkeby, the testnet we support. If you’re a first-time subgraph developer, we highly suggest you start with publishing to Rinkeby, which is free to do. This will allow you to see how the subgraph will work in The Graph Explorer and will allow you to test curation elements. You’ll only be able to index data from mainnet (even if your subgraph was published to a testnet) because only subgraphs that are indexing mainnet data can be published to the network. This is because indexers need to submit mandatory Proof of Indexing records as of a specific block hash. Because publishing a subgraph is an action taken on-chain, remember that the transaction can take up to a few minutes to go through. Any address you use to publish the contract will be the only one able to publish future versions. Choose wisely! @@ -88,9 +88,9 @@ Subgraphs with curation signal are shown to Indexers so that they can be indexed Developers might want to update their subgraph, for a variety of reasons. When this is the case, you can deploy a new version of your subgraph to the Studio using the CLI (it will only be private at this point) and if you are happy with it, you can publish this new deployment to The Graph Explorer. This will create a new version of your subgraph that curators can start signaling on and indexers will be able to index this new version. -Up until recently, developers were forced to deploy and publish a new version of their subgraph to the Explorer to update the metadata of their subgraphs. Now, developers can update the metadata of their subgraphs **without having to publish a new version**. Developers can update their subgraph details in the Studio (under profile picture, name, description, etc) by checking an option called **Update Details** in The Graph Explorer. 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. +Up until recently, developers were forced to deploy and publish a new version of their subgraph to the Explorer to update the metadata of their subgraphs. Now, developers can update the metadata of their subgraphs **without having to publish a new version**. Developers can update their subgraph details in the Studio (under the profile picture, name, description, etc) by checking an option called **Update Details** in The Graph Explorer. 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. -Please note that there are costs associated with publishing a new version of a subgraph to the network. In addition to the transaction fees, developers must also fund a part of the curation tax on auto-migrating signal. You cannot publish a new version of your subgraph if curators have not signaled on it. For more information on the risks of curation, please read more [here](/curating). +Please note that there are costs associated with publishing a new version of a subgraph to the network. In addition to the transaction fees, developers must also fund a part of the curation tax on the auto-migrating signal. You cannot publish a new version of your subgraph if curators have not signaled on it. For more information on the risks of curation, please read more [here](/curating). ### Automatic Archiving of Subgraph Versions @@ -100,7 +100,7 @@ Whenever you deploy a new subgraph version in the Subgraph Studio, the previous ## Managing your API Keys -Regardless of whether you’re a dapp developer or a subgraph developer, you’ll need to manage your API keys. This is important for you to be able to query subgraphs because API keys make sure the connections between application services are valid and authorized. This includes authenticating the end user and the device using the application. +Regardless of whether you’re a dApp developer or a subgraph developer, you’ll need to manage your API keys. This is important for you to be able to query subgraphs because API keys make sure the connections between application services are valid and authorized. This includes authenticating the end-user and the device using the application. The Studio will list out existing API keys, which will give you the ability to manage or delete them. @@ -118,7 +118,7 @@ The Studio will list out existing API keys, which will give you the ability to m - **Lowest Price**: The amount paid per query. If you mark this as important we will optimize for the less expensive indexers. - **Data Freshness**: How recent the latest block an indexer has processed for the subgraph you are querying. If you mark this as important we will optimize to find the indexers with the freshest data. - **Economic Security**: The amount of GRT an indexer can lose if they respond incorrectly to your query. If you mark this as important we will optimize for indexers with a large stake. -4. Under **Budget**, you’ll be able to update the maximum price per query. Note that we have a dynamic setting for that that's based on a volume discounting algorithm. +4. Under **Budget**, you’ll be able to update the maximum price per query. Note that we have a dynamic setting for that, that's based on a volume discounting algorithm. **We strongly recommend using the default settings unless you are experiencing a specific problem.** Otherwise, you can update it under "Set a custom maximum budget". On this page you can also view different KPIs (in GRT and USD): - Average cost per query diff --git a/pages/en/studio/transferring-subgraph-ownership.mdx b/pages/en/studio/transferring-subgraph-ownership.mdx index d8bd97550fca..3903a2c5e528 100644 --- a/pages/en/studio/transferring-subgraph-ownership.mdx +++ b/pages/en/studio/transferring-subgraph-ownership.mdx @@ -30,10 +30,10 @@ To transfer ownership of a subgraph, you can use the UI built into Subgraph Stud ![Subgraph Ownership Trasfer](/img/subgraph-ownership-transfer-1.png) -And then choosing the address that you would like to transfer the subgraph to: +And then choose the address that you would like to transfer the subgraph to: ![Subgraph Ownership Trasfer](/img/subgraph-ownership-transfer-2.png) -You can also use the built in UI of NFT marketplaces like OpenSea: +You can also use the built-in UI of NFT marketplaces like OpenSea: -![Subgraph Ownership Trasfer from NFT marketplace](/img/subgraph-ownership-transfer-nft-marketplace.png) \ No newline at end of file +![Subgraph Ownership Transfer from NFT marketplace](/img/subgraph-ownership-transfer-nft-marketplace.png) \ No newline at end of file diff --git a/pages/en/supported-networks/near.mdx b/pages/en/supported-networks/near.mdx index 288ac380494c..671c251ac1ca 100644 --- a/pages/en/supported-networks/near.mdx +++ b/pages/en/supported-networks/near.mdx @@ -8,7 +8,7 @@ This guide is an introduction to building subgraphs indexing smart contracts on ## What is NEAR? -[NEAR](https://near.org/) is a smart contract platform for building decentralised applications. Visit the [official documentation](https://docs.near.org/docs/concepts/new-to-near) for more information. +[NEAR](https://near.org/) is a smart contract platform for building decentralized applications. Visit the [official documentation](https://docs.near.org/docs/concepts/new-to-near) for more information. ## What are NEAR subgraphs? @@ -25,13 +25,13 @@ Subgraphs are event-based, which means that they listen for and then process on- ## Building a NEAR Subgraph -`@graphprotocol/graph-cli` is a command line tool for building and deploying subgraphs. +`@graphprotocol/graph-cli` is a command-line tool for building and deploying subgraphs. `@graphprotocol/graph-ts` is a library of subgraph-specific types. NEAR subgraph development requires `graph-cli` above version `0.23.0`, and `graph-ts` above version `0.23.0`. -> Building a NEAR subgraph is very similar to building a subgraph which indexes Ethereum. +> Building a NEAR subgraph is very similar to building a subgraph that indexes Ethereum. There are three aspects of subgraph definition: @@ -39,7 +39,7 @@ There are three aspects of subgraph definition: **schema.graphql:** a schema file that defines what data is stored for your subgraph, and how to query it via GraphQL. The requirements for NEAR subgraphs are covered by [the existing documentation](/developer/create-subgraph-hosted#the-graphql-schema). -**AssemblyScript Mappings:** [AssemblyScript code](/developer/assemblyscript-api) that translates from the event data to the entities defined in your schema. NEAR support introduces NEAR-specific data types, and new JSON parsing functionality. +**AssemblyScript Mappings:** [AssemblyScript code](/developer/assemblyscript-api) that translates from the event data to the entities defined in your schema. NEAR support introduces NEAR-specific data types and new JSON parsing functionality. During subgraph development there are two key commands: @@ -74,7 +74,7 @@ dataSources: - NEAR subgraphs introduce a new `kind` of data source (`near`) - The `network` should correspond to a network on the hosting Graph Node. On the Hosted Service, NEAR's mainnet is `near-mainnet`, and NEAR's testnet is `near-testnet` -- NEAR data sources introduce an optional `source.account` field, which is a human readable ID corresponding to a [NEAR account](https://docs.near.org/docs/concepts/account). This can be an account, or a sub account. +- NEAR data sources introduce an optional `source.account` field, which is a human-readable ID corresponding to a [NEAR account](https://docs.near.org/docs/concepts/account). This can be an account or a sub-account. NEAR data sources support two types of handlers: @@ -83,7 +83,7 @@ NEAR data sources support two types of handlers: ### Schema Definition -Schema definition describes the structure of the resulting subgraph database, and the relationships between entities. This is agnostic of the original data source. There are more details on subgraph schema definition [here](/developer/create-subgraph-hosted#the-graphql-schema). +Schema definition describes the structure of the resulting subgraph database and the relationships between entities. This is agnostic of the original data source. There are more details on subgraph schema definition [here](/developer/create-subgraph-hosted#the-graphql-schema). ### AssemblyScript Mappings @@ -156,7 +156,7 @@ These types are passed to block & receipt handlers: - Block handlers will receive a `Block` - Receipt handlers will receive a `ReceiptWithOutcome` -Otherwise the rest of the [AssemblyScript API](/developer/assemblyscript-api) is available to NEAR subgraph developers during mapping execution. +Otherwise, the rest of the [AssemblyScript API](/developer/assemblyscript-api) is available to NEAR subgraph developers during mapping execution. This includes a new JSON parsing function - logs on NEAR are frequently emitted as stringified JSONs. A new `json.fromString(...)` function is available as part of the [JSON API](/developer/assemblyscript-api#json-api) to allow developers to easily process these logs. @@ -180,7 +180,7 @@ $ graph create --node subgraph/name # creates a subgraph on a l $ graph deploy --node --ipfs https://api.thegraph.com/ipfs/ # uploads the build files to a specified IPFS endpoint, and then deploys the subgraph to a specified Graph Node based on the manifest IPFS hash ``` -The node configuration will depend where the subgraph is being deployed. +The node configuration will depend on where the subgraph is being deployed. #### Hosted Service: @@ -234,15 +234,15 @@ NEAR support is in beta, which means that there may be changes to the API as we ### Can a subgraph index both NEAR and EVM chains? -No, a subgraph can only support data sources from one chain / network. +No, a subgraph can only support data sources from one chain/network. ### Can subgraphs react to more specific triggers? Currently, only Block and Receipt triggers are supported. We are investigating triggers for function calls to a specified account. We are also interested in supporting event triggers, once NEAR has native event support. -### Will receipt handlers trigger for accounts and their sub accounts? +### Will receipt handlers trigger for accounts and their sub-accounts? -Receipt handlers will only be triggered for the exact-match of the named account. More flexibility may be added in future. +Receipt handlers will only be triggered for the exact match of the named account. More flexibility may be added in the future. ### Can NEAR subgraphs make view calls to NEAR accounts during mappings? @@ -258,8 +258,8 @@ Pending functionality is not yet supported for NEAR subgraphs. In the interim, y ### My question hasn't been answered, where can I get more help building NEAR subgraphs? -If it is a general question about subgraph development, there is a lot more information in the rest of the [Developer documentation](/developer/quick-start). Otherwise please join [The Graph Protocol Discord](https://discord.gg/vtvv7FP) and ask in the #near channel, or email near@thegraph.com. +If it is a general question about subgraph development, there is a lot more information in the rest of the [Developer documentation](/developer/quick-start). Otherwise please join [The Graph Protocol Discord](https://discord.gg/vtvv7FP) and ask in the #near channel or email near@thegraph.com. ## References -- [NEAR developer documentation](https://docs.near.org/docs/develop/basics/getting-started) +- [NEAR developer documentation](https://docs.near.org/docs/develop/basics/getting-started) \ No newline at end of file From 6ddd6431c0b9378db75037c37fc8f1cb19c3d1a2 Mon Sep 17 00:00:00 2001 From: Ahmad Mardeni Date: Thu, 21 Apr 2022 00:23:57 +0300 Subject: [PATCH 2/9] Minor --- pages/en/developer/create-subgraph-hosted.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/en/developer/create-subgraph-hosted.mdx b/pages/en/developer/create-subgraph-hosted.mdx index 0ce410191fb6..bcc82604a6e3 100644 --- a/pages/en/developer/create-subgraph-hosted.mdx +++ b/pages/en/developer/create-subgraph-hosted.mdx @@ -164,7 +164,7 @@ The schema for your subgraph is in the file `schema.graphql`. GraphQL schemas ar ## Defining Entities -Before defining entities, it is important to take a step back and think about how your data is structured and linked. All queries will be made against the data model defined in the subgraph schema and the entities indexed by the subgraph. Because of this, it is good to define the subgraph schema in a way that matches the needs of your dApp. It may be useful to imagine entities as "objects containing data", rather than as events or functions. +Before defining entities, it is important to take a step back and think about how your data is structured and linked. All queries will be made against the data model defined in the subgraph schema and the entities indexed by the subgraph. Because of this, it is good to define the subgraph schema in a way that matches the needs of your dapp. It may be useful to imagine entities as "objects containing data", rather than as events or functions. With The Graph, you simply define entity types in `schema.graphql`, and Graph Node will generate top-level fields for querying single instances and collections of that entity type. Each type that should be an entity is required to be annotated with an `@entity` directive. @@ -927,4 +927,4 @@ The grafted subgraph can use a GraphQL schema that is not identical to the one o - It adds or removes interfaces - It changes for which entity types an interface is implemented -> **[Feature Management](#experimental-features):** `grafting` must be declared under `features` in the subgraph manifest. \ No newline at end of file +> **[Feature Management](#experimental-features):** `grafting` must be declared under `features` in the subgraph manifest. From ed0ee35d9c803f8e25e6ed44174d04c776ca0dbb Mon Sep 17 00:00:00 2001 From: Ahmad Mardeni Date: Thu, 21 Apr 2022 00:26:36 +0300 Subject: [PATCH 3/9] Minor --- pages/en/developer/developer-faq.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/pages/en/developer/developer-faq.mdx b/pages/en/developer/developer-faq.mdx index 611085de48d7..944bc358caab 100644 --- a/pages/en/developer/developer-faq.mdx +++ b/pages/en/developer/developer-faq.mdx @@ -8,7 +8,7 @@ It is not possible to delete subgraphs once they are created. ### 2. Can I change my subgraph name? -No. Once a subgraph is created, the name cannot be changed. Make sure to think of this carefully before you create your subgraph so it is easily searchable and identifiable by other dApps. +No. Once a subgraph is created, the name cannot be changed. Make sure to think of this carefully before you create your subgraph so it is easily searchable and identifiable by other dapps. ### 3. Can I change the GitHub account associated with my subgraph? @@ -48,7 +48,7 @@ Take a look at `Access to smart contract` state inside the section [AssemblyScri Unfortunately, this is currently not possible. `graph init` is intended as a basic starting point, from which you can then add more data sources manually. -### 10. I want to contribute or add a GitHub issue. Where can I find the open-source repositories? +### 10. I want to contribute or add a GitHub issue. Where can I find the open source repositories? - [graph-node](https://github.com/graphprotocol/graph-node) - [graph-cli](https://github.com/graphprotocol/graph-cli) @@ -151,9 +151,9 @@ By default, query responses are limited to 100 items per collection. If you want someCollection(first: 1000, skip: ) { ... } ``` -### 23. If my dApp frontend uses The Graph for querying, do I need to write my query key into the frontend directly? What if we pay query fees for users – will malicious users cause our query fees to be very high? +### 23. If my dapp frontend uses The Graph for querying, do I need to write my query key into the frontend directly? What if we pay query fees for users – will malicious users cause our query fees to be very high? -Currently, the recommended approach for a dApp is to add the key to the frontend and expose it to end-users. That said, you can limit that key to a hostname, like _yourdapp.io_ and subgraph. The gateway is currently being run by Edge & Node. Part of the responsibility of a gateway is to monitor for abusive behavior and block traffic from malicious clients. +Currently, the recommended approach for a dapp is to add the key to the frontend and expose it to end users. That said, you can limit that key to a hostname, like _yourdapp.io_ and subgraph. The gateway is currently being run by Edge & Node. Part of the responsibility of a gateway is to monitor for abusive behavior and block traffic from malicious clients. ### 24. Where do I go to find my current subgraph on the Hosted Service? From 497baa1319a8591244bed4d86735f4a015cee935 Mon Sep 17 00:00:00 2001 From: Ahmad Mardeni Date: Thu, 21 Apr 2022 00:27:23 +0300 Subject: [PATCH 4/9] Minor --- pages/en/explorer.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/en/explorer.mdx b/pages/en/explorer.mdx index 895064ec5ac5..eccad7219743 100644 --- a/pages/en/explorer.mdx +++ b/pages/en/explorer.mdx @@ -2,7 +2,7 @@ title: The Graph Explorer --- -Welcome to the Graph Explorer, or as we like to call it, your decentralized portal into the world of subgraphs and network data. 👩🏽‍🚀 The Graph Explorer consists of multiple parts where you can interact with other subgraph developers, dApp developers, Curators, Indexers, and Delegators. For a general overview of the Graph Explorer, check out the video below (or keep reading below): +Welcome to the Graph Explorer, or as we like to call it, your decentralized portal into the world of subgraphs and network data. 👩🏽‍🚀 The Graph Explorer consists of multiple parts where you can interact with other subgraph developers, dapp developers, Curators, Indexers, and Delegators. For a general overview of the Graph Explorer, check out the video below (or keep reading below):