Merge remote-tracking branch 'pokt/main' into chore/migration/state-prep

* pokt/main:
  [Documentation] Refactoring `dev.poktroll.com` during Beta TestNet #1 of N (#1058)

README.md

@@ -1,6 +1,9 @@
+<!-- markdownlint-disable MD033 -->
+<!-- markdownlint-disable MD045 -->
+
 <div align="center">
   <a href="https://www.pokt.network">
-    <img src="https://user-images.githubusercontent.com/2219004/151564884-212c0e40-3bfa-412e-a341-edb54b5f1498.jpeg" alt="Pocket Network logo" width="340"/>
+    <img src="https://github.com/user-attachments/assets/5dbddd4a-d932-4c44-8396-270f140f086a" alt="Pocket Network logo" width="340"/>
   </a>
 </div>
 
@@ -22,52 +25,13 @@
 
 # poktroll <!-- omit in toc -->
 
-**poktroll** is built using the [Cosmos SDK](https://docs.cosmos.network) and
-[CometBFT](https://cometbft.com/), created with [Ignite CLI](https://ignite.com/cli)
-for the Shannon upgrade of the [Pocket Network](https://pokt.network) blockchain.
-
-- [Learn about Pocket Network](#learn-about-pocket-network)
-- [Developer Documentation](#developer-documentation)
-- [Roadmap](#roadmap)
-- [Quickstart](#quickstart)
-- [Godoc](#godoc)
-- [Have questions? Ask An PNYX](#have-questions-ask-an-pnyx)
-- [License](#license)
-
-## Learn about Pocket Network
-
-User friendly documentation of the Shannon upgrade is still a WIP, but there are
-a handful of (potentially outdated) resources you can reference in the meantime
-to build a better understanding of Pocket Network:
-
-- [Pocket Network official documentation](https://docs.pokt.network)
-- [[Live] Pocket Network Morse; aka v0](https://github.com/pokt-network/pocket-core)
-- [[Outdated] Pocket Network Protocol](https://github.com/pokt-network/pocket-network-protocol)
-- [[Deprecated]Pocket Network V1](https://github.com/pokt-network/pocket)
-
-## Developer Documentation
-
-The developer documentation is available at [dev.poktroll.com](https://dev.poktroll.com).
-
-## Roadmap
-
-You can view the Shannon Roadmap on [Github](https://github.com/orgs/pokt-network/projects/144?query=is%3Aopen+sort%3Aupdated-desc)
-
-## Quickstart
-
-The best way to get involved is by following the [quickstart instructions](https://dev.poktroll.com/develop/developer_guide/quickstart).
-
-## Godoc
-
-The Godoc for the source code in this can be found at [pkg.go.dev/github.com/pokt-network/poktroll](https://pkg.go.dev/github.com/pokt-network/poktroll).
-
-## Have questions? Ask An PNYX
+**poktroll** is the source code for [Pocket Network's](https://pokt.network/)
+[Shannon upgrade](https://docs.pokt.network/pokt-protocol/the-shannon-upgrade).
 
-You can use [PNYX](https://migration.pnyxai.com/), an AI-powered search engine that has been
-trained and indexed on the Pocket Network documentation, community calls, forums
-and much more!
+For technical documentation, visit [dev.poktroll.com](https://dev.poktroll.com).
 
----
+Documentation is maintained in the [docusaurus repo](./docusaurus) and is
+automatically deployed to the link above.
 
 ## License
 

docusaurus/docs/README.md

@@ -5,12 +5,23 @@ id: home-doc
 slug: /
 ---
 
+<!-- markdownlint-disable MD033 -->
+<!-- markdownlint-disable MD045 -->
+
 <div align="center">
   <a href="https://www.pokt.network">
-    <img src="https://user-images.githubusercontent.com/2219004/151564884-212c0e40-3bfa-412e-a341-edb54b5f1498.jpeg" alt="Pocket Network logo" width="340"/>
+    <img src="https://github.com/user-attachments/assets/01ddfcac-3b64-42ab-8e83-e87a5e9b36a6" alt="Pocket Network logo" width="340"/>
   </a>
 </div>
 
+:::note Pocket Network Project Documentation
+
+This is the living technical documentation for the protocol design, implementation,
+and operation. If you're looking for general documentation related to Pocket Network,
+please visit [docs.pokt.network](https://docs.pokt.network).
+
+:::
+
 <div>
   <a href="https://discord.gg/pokt"><img src="https://img.shields.io/discord/553741558869131266"/></a>
   <a  href="https://github.com/pokt-network/poktroll/releases"><img src="https://img.shields.io/github/release-pre/pokt-network/poktroll.svg"/></a>
@@ -27,47 +38,62 @@ slug: /
   <a href="https://github.com/tools/godep" ><img src="https://img.shields.io/badge/godep-dependency-71a3d9.svg"/></a>
 </div>
 
-# poktroll <!-- omit in toc -->
+## Pocket Network Shannon Technical Docs (aka poktroll) <!-- omit in toc -->
+
+**poktroll** is the source code and core implementation of the [Shannon upgrade](https://docs.pokt.network/pokt-protocol/the-shannon-upgrade) for [Pocket Network](https://pokt.network/).
+
+`poktroll` is built using the [Cosmos SDK](https://docs.cosmos.network), [CometBFT](https://cometbft.com/) and [Ignite CLI](https://ignite.com/cli).
+
+## What is Pocket Network? <!-- omit in toc -->
 
-**poktroll** is built using the [Cosmos SDK](https://docs.cosmos.network) and
-[CometBFT](https://cometbft.com/), created with [Ignite CLI](https://ignite.com/cli)
-for the Shannon upgrade of the [Pocket Network](https://pokt.network) blockchain.
+:::note 🚧 Under Construction 🚧
 
-- [Learn about Pocket Network](#learn-about-pocket-network)
-- [Roadmap](#roadmap)
-- [Quickstart](#quickstart)
-- [Godoc](#godoc)
-- [Have questions? Ask An PNYC](#have-questions-ask-an-pnyc)
+This documentation is not intended to answer this question as of 02/2025
+
+Consider reading [this post from 02/2025](https://medium.com/decentralized-infrastructure/an-update-from-grove-on-shannon-beta-testnet-path-the-past-the-future-5bf7ec2a9acf) by @olshansk
+to get some understanding of why you need Pocket & Grove.
+
+:::
+
+---
+
+## Table of Contents <!-- omit in toc -->
+
+- [Where do I start?](#where-do-i-start)
+- [Shannon Roadmap](#shannon-roadmap)
+- [PATH for Gateways](#path-for-gateways)
+- [GoDoc Documentation](#godoc-documentation)
 - [License](#license)
 
-## Learn about Pocket Network
+## Where do I start?
+
+1. [Guides & Deployment](./operate/cheat_sheets/full_node_cheatsheet.md): Deployment cheat sheets and config overviews for node runners, infrastructure operators and CLI users.
+2. [Tools & Explorers](./tools/user_guide/poktrolld_cli.md): Explorers, wallets, faucets and other resources to interact with the network.
+3. [Core Developers](./develop/developer_guide/walkthrough.md): Guides & walkthroughs for core or external developers looking to contribute to the core protocol or SDK.
+4. [Protocol Design](./protocol/actors/actors.md): Learn more about tokenomics design & protocol architecture.
 
-User friendly documentation of the Shannon upgrade is still a WIP, but there are
-a handful of (potentially outdated) resources you can reference in the meantime
-to build a better understanding of Pocket Network:
+:::note 🚧 Under Construction 🚧
 
-- [Pocket Network official documentation](https://docs.pokt.network)
-- [[Live] Pocket Network Morse; aka v0](https://github.com/pokt-network/pocket-core)
-- [[Outdated] Pocket Network Protocol](https://github.com/pokt-network/pocket-network-protocol)
-- [[Deprecated]Pocket Network V1](https://github.com/pokt-network/pocket)
+As of 02/2025, this documentation is under construction and does not have a clear
+user journey. Different parts are intended to serve as references one can link to
+or jump to/from when needed.
 
-## Roadmap
+:::
 
-You can view the Shannon Roadmap on [Github](https://github.com/orgs/pokt-network/projects/144?query=is%3Aopen+sort%3Aupdated-desc)
+## Shannon Roadmap
 
-## Quickstart
+The Shannon Roadmap, along with all past, active and future work is tracked via [this Github project](https://github.com/orgs/pokt-network/projects/144).
 
-The best way to get involved is by following the [quickstart instructions](develop/developer_guide/walkthrough.md).
+## PATH for Gateways
 
-## Godoc
+[Grove](https://grove.city/) is developing [PATH](https://path.grove.city/) for
+anyone who aims to deploy a Pocket Network gateway. Visit the docs to get started.
 
-The Godoc for the source code in this can be found at [pkg.go.dev/github.com/pokt-network/poktroll](https://pkg.go.dev/github.com/pokt-network/poktroll).
+The PATH Roadmap, along with all past, active and future work is tracked via [this Github project](https://github.com/orgs/buildwithgrove/projects/1).
 
-## Have questions? Ask An PNYC
+## GoDoc Documentation
 
-You can use [PNYX](https://pnyxai.com/), an AI-powered search engine that has been
-trained and indexed on the Pocket Network documentation, community calls, forums
-and much more!
+The Godoc for the source code can be found at [pkg.go.dev/github.com/pokt-network/poktroll](https://pkg.go.dev/github.com/pokt-network/poktroll).
 
 ---
 

docusaurus/docs/develop/developer_guide/_category_.json

@@ -1,6 +1,6 @@
 {
   "label": "Developer Guide",
-  "position": 2,
+  "position": 1,
   "link": {
     "type": "generated-index",
     "description": "Documentation related to onboarding as a developer to the Pocket Network protocol."

docusaurus/docs/develop/localnet/observability.md → docusaurus/docs/develop/developer_guide/pocketdex_indexer.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 1
+sidebar_position: 7
 title: Pocketdex Indexer
 ---
 

docusaurus/docs/develop/developer_guide/walkthrough.md

@@ -95,7 +95,7 @@ Install the following dependencies:
 6. [Tilt](https://docs.tilt.dev/install.html) - k8s local development tool & environment manager
 
 :::note
-If you've followed the [LocalNet instructions](../../operate/infrastructure/localnet.md),
+If you've followed the [LocalNet instructions](../networks/localnet.md),
 you may already have them installed.
 :::
 
@@ -106,7 +106,7 @@ and inspect it so you have an idea of what's going on!
 
 We'll be manually configuring a few actors to run in your shell for the sake of
 the tutorial so you have visibility into the types of onchain and offchain
-actors. In practice, you should be using [localnet](../../operate/infrastructure/localnet.md)
+actors. In practice, you should be using [localnet](../networks/localnet.md)
 to dynamically scale your actors.
 
 To learn more about the different actors type, see the docs [here](../../protocol/actors/actors.md).
@@ -653,7 +653,7 @@ We went through a flow of steps above just so you can get a feel for how things
 
 That said, you can dynamically scale the number of any actors in LocalNet by ony changing one line!
 
-Go to our [localnet tutorial](../../operate/infrastructure/localnet.md) to learn more.
+Go to our [localnet tutorial](../networks/localnet.md) to learn more.
 
 ## 7. Explore the tools
 

docusaurus/docs/operate/testing/_category_.json → docusaurus/docs/develop/e2e_testing/_category_.json

@@ -1,6 +1,6 @@
 {
-  "label": "Testing (Internal)",
-  "position": 6,
+  "label": "E2E Testing",
+  "position": 4,
   "link": {
     "type": "generated-index",
     "description": "Documentation related to the type of end-to-end testing (load or other) we are doing."

docusaurus/docs/operate/testing/load_testing.md → docusaurus/docs/develop/e2e_testing/load_testing.md

@@ -27,7 +27,7 @@ The load-testing suite is built on [Gherkin](https://cucumber.io/docs/gherkin/),
 
 ## Dependencies
 
-- [LocalNet](../infrastructure/localnet.md) (for local suite execution)
+- [LocalNet](../networks/localnet.md) (for local suite execution)
 - [Golang](https://go.dev/dl/)
 
 ## Load Test Manifests
@@ -63,7 +63,7 @@ This natural language syntax is parsed and used to match and execute the corresp
 
 To execute tests on LocalNet:
 
-1. Ensure [LocalNet](../infrastructure/localnet.md) is operational.
+1. Ensure [LocalNet](../networks/localnet.md) is operational.
 2. In the `localnet_config.yaml` file, set `gateways.count` and `relayminers.count` to `3`.
 3. Run `make acc_initialize_pubkeys` to initialize blockchain state public keys.
 4. Run `make test_load_relays_stress_localnet` to run the LocalNet stress-test.

docusaurus/docs/operate/testing/load_testing_devnet.md → docusaurus/docs/develop/e2e_testing/load_testing_devnet.md

@@ -27,12 +27,12 @@ single instance of each offchain actor. We can create custom DevNets with multip
 
 ### 1. Create and configure the DevNet
 
-Please refer to the DevNet creation guide [here](../infrastructure/devnet.md#how-to-create).
+Please refer to the DevNet creation guide [here](../networks/devnet.md#how-to-create).
 
 ### 2. Stake the necessary actors
 
 - Depending on your load testing requirements, you may need to stake one or more `gateways` and `suppliers`.
-- [DevNet documentation](../infrastructure/devnet.md#stake-actors) provides more details about staking actors in DevNets.
+- [DevNet documentation](../networks/devnet.md#stake-actors) provides more details about staking actors in DevNets.
 
 ### 3. Configure the load test manifest
 
@@ -96,7 +96,7 @@ gateways:
     exposed_url: https://devnet-sophon-gateway-1.poktroll.com
   - address: pokt15w3fhfyc0lttv7r585e2ncpf6t2kl9uh8rsnyz
     exposed_url: https://devnet-sophon-gateway-2.poktroll.com
-  - address: pokt1zhmkkd0rh788mc9prfq0m2h88t9ge0j83gnxya 
+  - address: pokt1zhmkkd0rh788mc9prfq0m2h88t9ge0j83gnxya
     exposed_url: https://devnet-sophon-gateway-3.poktroll.com
 ```
 

docusaurus/docs/operate/infrastructure/_category_.json → docusaurus/docs/develop/networks/_category_.json

@@ -1,6 +1,6 @@
 {
   "label": "Networks",
-  "position": 5,
+  "position": 3,
   "link": {
     "type": "generated-index",
     "description": "Infrastructure related to deploying, maintaining and testing various (Local, Dev, Test) environments."

docusaurus/docs/develop/packages/_category_.json

@@ -1,6 +1,6 @@
 {
   "label": "Packages",
-  "position": 5,
+  "position": 2,
   "link": {
     "type": "generated-index",
     "description": "Documentation related to the source code and packages in poktroll."

docusaurus/docs/develop/testing/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Testing",
+  "position": 5,
+  "link": {
+    "type": "generated-index",
+    "description": "Documentation related to unit testing."
+  }
+}