diff --git a/docs/.vuepress/config.ts b/docs/.vuepress/config.ts index e455a283f5d..93b6d575a8c 100644 --- a/docs/.vuepress/config.ts +++ b/docs/.vuepress/config.ts @@ -303,6 +303,8 @@ export default defineUserConfig({ "/run_publish/query/subscription.html", "/quickstart/quickstart_chains/astar-zkatana.html": "/quickstart/quickstart_chains/astar-zkevm.html", + "/subquery_network/publish.html": + "/subquery_network/architects/publish.html", }; return { ...redirects, diff --git a/docs/.vuepress/public/assets/img/network/architect_manage_project.png b/docs/.vuepress/public/assets/img/network/architect_manage_project.png new file mode 100644 index 00000000000..753d4234b4c Binary files /dev/null and b/docs/.vuepress/public/assets/img/network/architect_manage_project.png differ diff --git a/docs/.vuepress/public/assets/img/network/architect_manage_project_deploy.png b/docs/.vuepress/public/assets/img/network/architect_manage_project_deploy.png new file mode 100644 index 00000000000..c5216b49ada Binary files /dev/null and b/docs/.vuepress/public/assets/img/network/architect_manage_project_deploy.png differ diff --git a/docs/.vuepress/public/assets/img/network/architect_publish.png b/docs/.vuepress/public/assets/img/network/architect_publish.png new file mode 100644 index 00000000000..ad7cbd846ca Binary files /dev/null and b/docs/.vuepress/public/assets/img/network/architect_publish.png differ diff --git a/docs/.vuepress/public/assets/img/network/architect_publish_ipfs.png b/docs/.vuepress/public/assets/img/network/architect_publish_ipfs.png new file mode 100644 index 00000000000..f9a098984d5 Binary files /dev/null and b/docs/.vuepress/public/assets/img/network/architect_publish_ipfs.png differ diff --git a/docs/.vuepress/sidebar.ts b/docs/.vuepress/sidebar.ts index c56cc4ac2c5..26df1e5d63d 100644 --- a/docs/.vuepress/sidebar.ts +++ b/docs/.vuepress/sidebar.ts @@ -574,14 +574,17 @@ export const getSidebar = (locale: string) => `${locale}/subquery_network/node_operators/plans.md`, ], }, - `${locale}/subquery_network/parameters.md`, - `${locale}/subquery_network/architects/introduction.md`, - `${locale}/subquery_network/foundation.md`, { - text: "Publish your Project", - link: `${locale}/subquery_network/publish.md`, + text: "Architects", + link: `${locale}/subquery_network/architects/introduction.md`, + collapsible: true, + children: [ + `${locale}/subquery_network/architects/introduction.md`, + `${locale}/subquery_network/architects/publish.md`, + ], }, - + `${locale}/subquery_network/parameters.md`, + `${locale}/subquery_network/foundation.md`, `${locale}/subquery_network/community.md`, ], }, diff --git a/docs/README.md b/docs/README.md index c3bad30ab92..fd2f35b2ca2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -89,7 +89,7 @@ photoSwipe: false
-

4. Deploy to the SubQuery Network

+

4. Deploy to the SubQuery Network

Our decentralised service is a web3 infrastructure revolution. We’re building the most open, performant, reliable, and scalable data service for dApp developers which will index and serve data to the global community in an incentivised and verifiable way.

diff --git a/docs/subquery_network/architects/publish.md b/docs/subquery_network/architects/publish.md new file mode 100644 index 00000000000..37021bea916 --- /dev/null +++ b/docs/subquery_network/architects/publish.md @@ -0,0 +1,112 @@ +# Publishing your Project to the SubQuery Network + +We're building the most open, performant, reliable, and scalable data service for dApp developers. The SubQuery Network indexes and services data to the global community in an incentivised and verifiable way. After publishing your project to the SubQuery Network, anyone can index and host it - providing data to users around the world faster and reliably. + +## Why you should publish your project to SubQuery's Decentralised Network + +The SubQuery Network is the future of web3 infrastructure, it allows you to completely decentralise your infrastructure stack. This provides the following benefits: + +- Unstoppable infrastructure - With almost 100 decentralised and geographically isolated Indexers providing data to your dApps, sleep safe knowing your infra will never go down. +- Superior performance - Since Indexers are all around the world, they're closer to your users. Lower latency and faster requests creates a better user experience for your users. +- Infinitely scalable - As your user base grows, more indexers will serve you data allowing you to infinitely scale without interruption. +- Seamless transition - We're here to help you migrate, and we've made it easy to integrate in your dApps with our network client SDKs. + +**With the SubQuery Network, you can now go to your community and say with confidence _"our dApp is truly decentralised"._** + +## Prerequisites for your project running on the Network + +1. The SubQuery Network does not support GraphQL subscriptions, so you can't enable the `--subscription` [command line argument](../../run_publish/query/subscription.md) +2. Your client application (the one that will query data) must be able to run a JS library +3. Your project can generate stable proof of indexing results. This means you should avoid: + 1. Random ordered DB operations, e.g. avoid using `Promise.all()` in your mapping functions. + 2. Introducing external data dependent on runtime, e.g. initialising a new current date using `new Date()`. +4. Your project is published to IPFS, [follow the guide here](../../run_publish/publish.md#publish-your-subquery-project-to-ipfs). + +## Deploying your Project + +The SubQuery Network is a public permissionless network, anyone can deploy their project freely. To do so, head to the SubQuery Explorer and click "Publish New Project". + +![Explorer - Publish Button](/assets/img/network/architect_publish.png) + +You will need to publish your project to IPFS first, [follow the guide here](../../run_publish/publish.md#publish-your-subquery-project-to-ipfs). Please enter the project CID and give your project a nice name. + +![Publish - Enter CID](/assets/img/network/architect_publish_ipfs.png) + +On the next page you are asked to enter a project description, and also populate information about the project that Consumers or Node Operators might find interesting. This includes: + +- a logo or image +- categories that the project can be classified by +- a website address for the project +- a link to where the source code can be found +- for the deployment + - a version number, we recommend it follows [semantic versioning rules](https://semver.org/) + - the deployment description, which might include additional information for Node Operators about migration steps or breaking changes in this version + +Once entered, click "Publish" to publish your project, you will then be taken to a page to manage your project. + +::: info How to encourage Node Operators to sync your project + +At this stage you should reach out to Node Operators in our Discord to encourage them to start syncing it, once they do you will be able to create plans and start quering this data. You might also want to consider [boosting your project](../consumers/boosting.md) to incentivise Node Operators to do so, and in return recieve free queries to it. + +::: + +## Managing Your Project + +You can easily make changes to your project or deploy a new version by accessing the Managed Project page. + +![Manage Existing Project](/assets/img/network/architect_manage_project.png) + +Firstly, you can publish a new verison by clicking "Deploy New Version". This will let Node Operators know and allow them to upgrade to the new version of your Project. For the deployment you shoud provide: + +- the deployment CID, you will need to publish your project to IPFS first, [follow the guide here](../../run_publish/publish.md#publish-your-subquery-project-to-ipfs) +- a version number, we recommend it follows [semantic versioning rules](https://semver.org/) +- check the box if you want to make this version recommended, this means that you are reccommending Node Operators to immediately update to it. Don't check this if it's a test build or if it has major breaking changes +- the deployment description, which might include additional information for Node Operators about migration steps or breaking changes in this version + +![Manage Existing Project - Deploy New Version](/assets/img/network/architect_manage_project_deploy.png) + +## Changes to your DApp + +Your client application (the one that will query data from the Network) will need to use [Apollo Client](https://www.apollographql.com/docs/react/) as it's primary GraphQL Client. Apollo Client is a comprehensive state management library for JavaScript that enables you to manage both local and remote data with GraphQL. Use it to fetch, cache, and modify application data, all while automatically updating your UI. + +Apollo Client helps you structure code in an economical, predictable, and declarative way that's consistent with modern development practices. The core `@apollo/client` library provides built-in integration with React, and the larger Apollo community maintains [integrations for other popular view layers](https://www.apollographql.com/docs/react/#community-integrations). + +SubQuery builds and publishes an additional library called [ApolloLink](https://github.com/subquery/network-clients/tree/main/packages/apollo-links). This client will be used to instantiate the connection via Indexers and perform authentication with our SubQuery Network services. Please follow [usage](https://github.com/subquery/network-clients/tree/main/packages/apollo-links) and view [test cases](https://github.com/subquery/network-clients/blob/main/test/authLink.test.ts) in the repository. + +```ts +import { + ApolloClient, + from, + HttpLink, + InMemoryCache, +} from "@apollo/client/core"; +import { authHttpLink } from "@subql/apollo-links"; +import fetch from "cross-fetch"; // Can be any HTTP library + +const options = { + authUrl: `http://example-url.com/token`, + sk: "", + indexer: "", + consumer: "", + chainId: 1287, + deploymentId: "", + agreement: "", +}; + +const link = await authHttpLink(options); +const client = new ApolloClient({ + cache: new InMemoryCache({ resultCaching: true }), + link: from([authLink, new HttpLink({ uri, fetch })]), +}); + +const metadataQuery = gql` + query Metadata { + _metadata { + indexerHealthy + indexerNodeVersion + } + } +`; + +await client.query({ query: metadataQuery }); +``` diff --git a/docs/subquery_network/publish.md b/docs/subquery_network/publish.md deleted file mode 100644 index 3cd641809bd..00000000000 --- a/docs/subquery_network/publish.md +++ /dev/null @@ -1,88 +0,0 @@ -# Publishing your Project to the SubQuery Network - -:::warning - -This guide is outdated as we have now moved to the mainnet. We will update it shortly with instructions on how anyone can submit a new project deployment to the SubQuery network. - -::: - -We're building the most open, performant, reliable, and scalable data service for dApp developers. The SubQuery Network indexes and services data to the global community in an incentivised and verifiable way. After publishing your project to the SubQuery Network, anyone can index and host it - providing data to users around the world faster and reliably. - -The final phase before launching the SubQuery Network is deploying the Kepler Network. You can think of Kepler as a pre-mainnet, a controlled phase that will help us bootstrap the mainnet with participants and activity. - -**Kepler is [already running today](https://kepler.subquery.network/) with a diverse set of Indexers from around the world. It powers many of our internal dictionary projects, as well as powering the Kepler application that participants use when engaging with the network. It has been production tested, and it's ready for your dApp.** - -## Benefits of moving your project to SubQuery's Decentralised Network - -The SubQuery Network is the future of web3 infrastructure, it allows you to completely decentralise your infrastructure stack. This provides the following benefits: - -- Unstoppable infrastructure - With almost 100 decentralised and geographically isolated Indexers providing data to your dApps, sleep safe knowing your infra will never go down. -- Superior performance - Since Indexers are all around the world, they're closer to your users. Lower latency and faster requests creates a better user experience for your users. -- Infinitely scalable - As your user base grows, more indexers will serve you data allowing you to infinitely scale without interruption. -- Seamless transition - We're here to help you migrate, and we've made it easy to integrate in your dApps with our network client SDKs. - -**With the SubQuery Kepler Network, you can now go to your community and say with confidence _"our dApp is truly decentralised"._** - -## Prerequisites for your project running on Kepler - -1. Kepler does not support GraphQL subscriptions, so you can't enable the `--subscription` [command line argument](../run_publish/query/subscription.md) -2. Your client application (the one that will query data from Kepler) must be able to run a JS library -3. Your project can generate stable proof of indexing results. This means you should avoid: - 1. Random ordered DB operations, e.g. avoid using `Promise.all()` in your mapping functions. - 2. Introducing external data dependent on runtime, e.g. initialising a new current date using `new Date()`. - -## Changes to your DApp - -Your client application (the one that will query data from Kepler) will need to use [Apollo Client](https://www.apollographql.com/docs/react/) as it's primary GraphQL Client. Apollo Client is a comprehensive state management library for JavaScript that enables you to manage both local and remote data with GraphQL. Use it to fetch, cache, and modify application data, all while automatically updating your UI. - -Apollo Client helps you structure code in an economical, predictable, and declarative way that's consistent with modern development practices. The core `@apollo/client` library provides built-in integration with React, and the larger Apollo community maintains [integrations for other popular view layers](https://www.apollographql.com/docs/react/#community-integrations). - -SubQuery builds and publishes an additional library called [ApolloLink](https://github.com/subquery/network-clients/tree/main/packages/apollo-links). This client will be used to instantiate the connection via Indexers and perform authentication with our SubQuery Kepler network services. Please follow [usage](https://github.com/subquery/network-clients/tree/main/packages/apollo-links) and view [test cases](https://github.com/subquery/network-clients/blob/main/test/authLink.test.ts) in the repository. - -```ts -import { - ApolloClient, - from, - HttpLink, - InMemoryCache, -} from "@apollo/client/core"; -import { authHttpLink } from "@subql/apollo-links"; -import fetch from "cross-fetch"; // Can be any HTTP library - -const options = { - authUrl: `http://example-url.com/token`, - sk: "", - indexer: "", - consumer: "", - chainId: 1287, - deploymentId: "", - agreement: "", -}; - -const link = await authHttpLink(options); -const client = new ApolloClient({ - cache: new InMemoryCache({ resultCaching: true }), - link: from([authLink, new HttpLink({ uri, fetch })]), -}); - -const metadataQuery = gql` - query Metadata { - _metadata { - indexerHealthy - indexerNodeVersion - } - } -`; - -await client.query({ query: metadataQuery }); -``` - -## Cost - -For the duration of the SubQuery Kepler Network, the SubQuery Foundation will charge 50% of the list price of the [SubQuery Managed Serivce](https://managedservice.subquery.network/pricing) for all customer projects hosted on the decentralised SubQuery Network. - -The SubQuery Foundation will manage all kSQT token exchanges and distribute rewards to indexers and delegators. - -## What's Next - -If you're interested in moving your SubQuery project to the Kepler Decentralised Network please reach out to your SubQuery contact, or email [start@subquery.network](mailto:start@subquery.network).