diff --git a/content/docs/guides/the-graph.mdx b/content/docs/guides/the-graph.mdx new file mode 100644 index 0000000..1285668 --- /dev/null +++ b/content/docs/guides/the-graph.mdx @@ -0,0 +1,203 @@ +--- +title: The Graph Network +description: Learn how to leverage Swellchain on The Graph +--- + +# The Graph + +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. + +With The Graph, you can benefit from: + +- **Decentralized Indexing, Built to Scale**: Tap into a global network of Indexers to efficiently index blockchain data with no single point of failure--just resilient infrastructure. +- **Powerful GraphQL Interface**: Query blockchain data using GraphQL. It's fast and flexible, accelerating data retrieval to enhance your dapps. +- **Customizable Data Logic**: Define your own logic for transforming and storing blockchain data. Reuse subgraphs published by other developers on The Graph Network. + +Pricing: **All developers receive 100K free monthly queries on the decentralized network**. After these free queries, you only pay based on usage at $2 for every 100K queries. + +## Quickstart + +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: + +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 Swell". + +![Create a Subgraph](/public/images/the-graph/create-a-subgraph.png) + +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: + +![CLI Command](/public/images/the-graph//cli-commands.png) + +### 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: + +![CLI Example](/public/images/the-graph/CLI-example.png) + +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. + +![Create a Subgraph](/public/images/the-graph/playground.png) + +### 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: + +![Publish Button](/public/images/the-graph/publish-button.png) + +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. + +![Publish Screen](/public/images/the-graph/publish-screen.png) + +> **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: + +![Query URL](/public/images/the-graph/query-url.png) + +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. + +![API Keys](/public/images/the-graph/api-keys.png) + +## 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/public/images/the-graph/CLI-Example.png b/public/images/the-graph/CLI-Example.png new file mode 100644 index 0000000..efc4c1d Binary files /dev/null and b/public/images/the-graph/CLI-Example.png differ diff --git a/public/images/the-graph/api-keys.png b/public/images/the-graph/api-keys.png new file mode 100644 index 0000000..5233cd7 Binary files /dev/null and b/public/images/the-graph/api-keys.png differ diff --git a/public/images/the-graph/cli-commands.png b/public/images/the-graph/cli-commands.png new file mode 100644 index 0000000..aa60cd5 Binary files /dev/null and b/public/images/the-graph/cli-commands.png differ diff --git a/public/images/the-graph/create-a-subgraph.png b/public/images/the-graph/create-a-subgraph.png new file mode 100644 index 0000000..876d7fd Binary files /dev/null and b/public/images/the-graph/create-a-subgraph.png differ diff --git a/public/images/the-graph/playground.png b/public/images/the-graph/playground.png new file mode 100644 index 0000000..9d9ffdb Binary files /dev/null and b/public/images/the-graph/playground.png differ diff --git a/public/images/the-graph/publish-button.png b/public/images/the-graph/publish-button.png new file mode 100644 index 0000000..b576068 Binary files /dev/null and b/public/images/the-graph/publish-button.png differ diff --git a/public/images/the-graph/publish-screen.png b/public/images/the-graph/publish-screen.png new file mode 100644 index 0000000..d35c0ba Binary files /dev/null and b/public/images/the-graph/publish-screen.png differ diff --git a/public/images/the-graph/query-url.png b/public/images/the-graph/query-url.png new file mode 100644 index 0000000..fdc61e8 Binary files /dev/null and b/public/images/the-graph/query-url.png differ