diff --git a/docs/get-started/tooling/data-indexers/thegraph.mdx b/docs/get-started/tooling/data-indexers/thegraph.mdx index ac23f2a94..7c9188337 100644 --- a/docs/get-started/tooling/data-indexers/thegraph.mdx +++ b/docs/get-started/tooling/data-indexers/thegraph.mdx @@ -1,25 +1,280 @@ --- -title: TheGraph network +title: The Graph Network image: /img/socialCards/thegraph-network.jpg --- -As a dapp developer, retrieving onchain data for your dapp can be challenging -because you will most likely: +# The Graph -1. Consume your RPC provider quota with calls. -2. Need to implement error handling on multiple levels. -3. Define creative strategies to avoid UX impacts when managing a high volume of - data. +Getting historical data on smart contracts can be frustrating when building a +dapp. [The Graph](https://thegraph.com/) offers a powerful way to query smart +contract data with open APIs known as subgraphs. Anyone can create or query +subgraphs, making the data available to the entire ecosystem. The Graph is +powered by hundreds of independent Indexers, enabling your dapp to become truly +decentralized. -The Graph is a decentralized data indexer provider that indexes the Linea -blockchain for you and exposes onchain data through an HTTPS API. +Developers can use 100,000 free queries per month by using The Graph Network. -We run The Graph indexers on Linea to allow you to leverage the power of this -technology. +## Quickstart -:::info[update] +Subgraphs index emitted events by default, but additional functionality can be +added later. A subgraph can be created in just a few minutes by following these +steps: -TheGraph is now live with Linea Mainnet! For more information, take a look at -the official [documentation](https://thegraph.com/docs/en/) +1. Initialize your subgraph +2. Publish your subgraph to The Graph Network +3. Query from your dapp with your unique API key -::: +Here is a step-by-step walkthrough: + +## 1. Initialize your subgraph + +### Create a subgraph in subgraph studio + +Go to the [Subgraph Studio](https://thegraph.com/studio/) and connect your +wallet. Once your wallet is connected, you can begin by clicking "Create a +Subgraph". When choosing a name, it's recommended to use Title Case, including +the subgraph and chain name, e.g., "MyDapp Subgraph Linea". + +
+
+ alt text here +
+
+ +Then, you will land on your subgraph's page. All the CLI commands you need will +be visible on the right side of the page: + +
+
+ alt text here +
+
+ +### Install the Graph CLI⁠ + +On your local machine, run the following: + +``` +npm install -g @graphprotocol/graph-cli +``` + +### Initialize your subgraph⁠ + +You can copy this directly from your subgraph page to include your specific +subgraph slug: + +``` +graph init +``` + +You'll be prompted to provide some info on your subgraph like this: + +
+
+ alt text here +
+
+ +Simply verify your contract on the block explorer, and the CLI will +automatically obtain the ABI and set up your subgraph. The default settings will +generate an entity for each event. + +## 2. Deploy and publish + +### Deploy to Subgraph Studio + +First, run these commands: + +```bash +$ graph codegen +$ graph build +``` + +Then, run these to authenticate and deploy your subgraph. You can copy these +commands directly from your subgraph's page in Studio to include your specific +deploy key and subgraph slug: + +```bash +$ graph auth +$ graph deploy +``` + +You will be asked for a version label. You can enter something like v0.0.1, but +you're free to choose the format. + +### Test your subgraph + +You can test your subgraph by making a sample query in the playground section. +The Details tab will show you an API endpoint. You can use that endpoint to test +from your dapp. + +
+
+ alt text here +
+
+ +### Publish your subgraph to The Graph's decentralized network + +Once your subgraph is ready to be put into production, you can publish it to the +decentralized network. On your subgraph's page in Subgraph Studio, click on the +Publish button: + +
+
+ alt text here +
+
+ +Before you can query your subgraph, Indexers need to begin serving queries on +it. In order to streamline this process, you can curate your own subgraph using +GRT. + +When publishing, you'll see the option to curate your subgraph. As of May 2024, +it is recommended that you curate your own subgraph with at least 3,000 GRT to +ensure that it is indexed and available for querying as soon as possible. + +
+
+ alt text here +
+
+ +> **Note:** The Graph's smart contracts are all on Arbitrum One, even though +> your subgraph is indexing data from Ethereum, BSC or any other +> [supported chain](https://thegraph.com/docs/en/developing/supported-networks/). + +## 3. Query your subgraph + +Congratulations! You can now query your subgraph on the decentralized network! + +To query any subgraph on the decentralized network, pass a GraphQL query into +the subgraph's query URL, which can be found at the top of its Explorer page. + +Here's an example from the +[CryptoPunks Ethereum subgraph](https://thegraph.com/explorer/subgraphs/HdVdERFUe8h61vm2fDyycHgxjsde5PbB832NHgJfZNqK) +by Messari: + +
+
+ alt text here +
+
+ +The query URL for this subgraph is: + +`https://gateway-arbitrum.network.thegraph.com/api/`**[api-key]**`/subgraphs/id/HdVdERFUe8h61vm2fDyycgxjsde5PbB832NHgJfZNqK` + +Now, you simply need to fill in your own API Key to start sending GraphQL +queries to this endpoint. + +### Get your own API key + +In Subgraph Studio, you'll see the "API Keys" menu at the top of the page. Here, +you can create API Keys. + +
+
+ alt text here +
+
+ +## Appendix + +### Sample query + +This query shows the most expensive CryptoPunks sold. + +```graphql +{ + trades(orderBy: priceETH, orderDirection: desc) { + priceETH + tokenId + } +} +``` + +Passing this into the query URL returns this result: + +``` +{ + "data": { + "trades": [ + { + "priceETH": "124457.067524886018255505", + "tokenId": "9998" + }, + { + "priceETH": "8000", + "tokenId": "5822" + }, +// ... +``` + +### Sample code + +```jsx +const axios = require("axios"); + +const graphqlQuery = `{ + trades(orderBy: priceETH, orderDirection: desc) { + priceETH + tokenId + } +}`; +const queryUrl = + "https://gateway-arbitrum.network.thegraph.com/api/[api-key]/subgraphs/id/HdVdERFUe8h61vm2fDyycHgxjsde5PbB832NHgJfZNqK"; + +const graphQLRequest = { + method: "post", + url: queryUrl, + data: { + query: graphqlQuery, + }, +}; + +// Send the GraphQL query +axios(graphQLRequest) + .then((response) => { + // Handle the response here + const data = response.data.data; + console.log(data); + }) + .catch((error) => { + // Handle any errors + console.error(error); + }); +``` + +### Additional resources + +- To explore all the ways you can optimize and customize your subgraph for better + performance, read more about + [creating a subgraph here](https://thegraph.com/docs/en/developing/creating-a-subgraph/). +- To learn more about + [querying data from your subgraph](https://thegraph.com/docs/en/querying/querying-the-graph/). +- [Subgraph Studio](https://thegraph.com/studio/). diff --git a/static/img/get_started/tooling/data_indexers/the-graph/api-keys.png b/static/img/get_started/tooling/data_indexers/the-graph/api-keys.png new file mode 100644 index 000000000..5233cd79f Binary files /dev/null and b/static/img/get_started/tooling/data_indexers/the-graph/api-keys.png differ diff --git a/static/img/get_started/tooling/data_indexers/the-graph/cli-commands.png b/static/img/get_started/tooling/data_indexers/the-graph/cli-commands.png new file mode 100644 index 000000000..aa60cd598 Binary files /dev/null and b/static/img/get_started/tooling/data_indexers/the-graph/cli-commands.png differ diff --git a/static/img/get_started/tooling/data_indexers/the-graph/cli-example.png b/static/img/get_started/tooling/data_indexers/the-graph/cli-example.png new file mode 100644 index 000000000..efc4c1d5a Binary files /dev/null and b/static/img/get_started/tooling/data_indexers/the-graph/cli-example.png differ diff --git a/static/img/get_started/tooling/data_indexers/the-graph/create-a-subgraph.png b/static/img/get_started/tooling/data_indexers/the-graph/create-a-subgraph.png new file mode 100644 index 000000000..876d7fd31 Binary files /dev/null and b/static/img/get_started/tooling/data_indexers/the-graph/create-a-subgraph.png differ diff --git a/static/img/get_started/tooling/data_indexers/the-graph/playground.png b/static/img/get_started/tooling/data_indexers/the-graph/playground.png new file mode 100644 index 000000000..9d9ffdb1a Binary files /dev/null and b/static/img/get_started/tooling/data_indexers/the-graph/playground.png differ diff --git a/static/img/get_started/tooling/data_indexers/the-graph/publish-button.png b/static/img/get_started/tooling/data_indexers/the-graph/publish-button.png new file mode 100644 index 000000000..b5760684b Binary files /dev/null and b/static/img/get_started/tooling/data_indexers/the-graph/publish-button.png differ diff --git a/static/img/get_started/tooling/data_indexers/the-graph/publish-screen.png b/static/img/get_started/tooling/data_indexers/the-graph/publish-screen.png new file mode 100644 index 000000000..d35c0baae Binary files /dev/null and b/static/img/get_started/tooling/data_indexers/the-graph/publish-screen.png differ diff --git a/static/img/get_started/tooling/data_indexers/the-graph/query-url.png b/static/img/get_started/tooling/data_indexers/the-graph/query-url.png new file mode 100644 index 000000000..fdc61e87d Binary files /dev/null and b/static/img/get_started/tooling/data_indexers/the-graph/query-url.png differ