Updated documentation in the roadmap and quickstart guides (plus mino…

…r config updates elsewhere).
pokt-network · Dec 11, 2023 · 2720509 · 2720509
1 parent 8ee4b44
commit 2720509
Show file tree

Hide file tree

Showing 6 changed files with 122 additions and 50 deletions.
diff --git a/Makefile b/Makefile
@@ -226,25 +226,18 @@ go_develop_and_test: go_develop go_test ## Generate protos, mocks and run all te
 # TODO_NB                     - An important note to reference later
 # TODO_DISCUSS_IN_THIS_COMMIT - SHOULD NEVER BE COMMITTED TO MASTER. It is a way for the reviewer of a PR to start / reply to a discussion.
 # TODO_IN_THIS_COMMIT         - SHOULD NEVER BE COMMITTED TO MASTER. It is a way to start the review process while non-critical changes are still in progress
-TODO_KEYWORDS = -e "TODO" -e "TODO_COMMUNITY" -e "TODO_DECIDE" -e "TODO_TECHDEBT" -e "TODO_IMPROVE" -e "TODO_OPTIMIZE" -e "TODO_DISCUSS" -e "TODO_INCOMPLETE" -e "TODO_INVESTIGATE" -e "TODO_CLEANUP" -e "TODO_HACK" -e "TODO_REFACTOR" -e "TODO_CONSIDERATION" -e "TODO_IN_THIS_COMMIT" -e "TODO_DISCUSS_IN_THIS_COMMIT" -e "TODO_CONSOLIDATE" -e "TODO_DEPRECATE" -e "TODO_ADDTEST" -e "TODO_RESEARCH" -e "TODO_BUG" -e "TODO_NB"
 
 .PHONY: todo_list
 todo_list: ## List all the TODOs in the project (excludes vendor and prototype directories)
-	grep --exclude-dir={.git,vendor,prototype} -r ${TODO_KEYWORDS}  .
-
-TODO_SEARCH ?= $(shell pwd)
-
-.PHONY: todo_search
-todo_search: ## List all the TODOs in a specific directory specific by `TODO_SEARCH`
-	grep --exclude-dir={.git,vendor,prototype} -r ${TODO_KEYWORDS} ${TODO_SEARCH}
+	grep --exclude-dir={.git,vendor,./docusaurus} -r TODO  .
 
 .PHONY: todo_count
 todo_count: ## Print a count of all the TODOs in the project
-	grep --exclude-dir={.git,vendor,prototype} -r ${TODO_KEYWORDS} . | wc -l
+	grep --exclude-dir={.git,vendor,./docusaurus} -r TODO  . | wc -l
 
 .PHONY: todo_this_commit
 todo_this_commit: ## List all the TODOs needed to be done in this commit
-	grep --exclude-dir={.git,vendor,prototype,.vscode} --exclude=Makefile -r -e "TODO_IN_THIS_COMMIT" -e "TODO_DISCUSS_IN_THIS_COMMIT"
+	grep --exclude-dir={.git,vendor,.vscode} --exclude=Makefile -r -e "TODO_IN_THIS_"
 
 ####################
 ###   Gateways   ###

diff --git a/docusaurus/docs/contributing/contributing.md b/docusaurus/docs/contributing/contributing.md
@@ -1,5 +1,41 @@
+---
+sidebar_position: 1
+title: How to contribute?
+---
 
+# Contributing <!-- omit in toc -->
 
-- Search for TODOs
-- Look at `community`
-- Leave a comment in this discord channel
+:::warning
+It is still really early to start contributing to Shannon, so we suggest you do
+so if you're a highly experienced and independent developer.
+:::
+
+- [Community Tickets](#community-tickets)
+- [TODOs](#todos)
+- [GitHub](#github)
+- [Discord](#discord)
+
+## Community Tickets
+
+You can find all GitHub issues that are labeled with `community` [here](https://github.com/pokt-network/poktroll/issues?q=is%3Aissue+is%3Aopen+label%3Acommunity). These were designed to be independent
+and easy to pick up by anyone.
+
+## TODOs
+
+If you run `make todo_list`, you will all the TODOs on our backlog. If there's one
+that peaks your interest simply:
+
+1. Open a GitHub issue (see instructions below)
+2. Provide a screenshot of the TODO you're interested in tackling
+3. Someone from the protocol team will reponsd
+
+## GitHub
+
+The best way to reach us is by opening a [GitHub Issue](https://github.com/pokt-network/poktroll/issues/new/choose)
+and outline your proposal, issue or suggestion before you start doing any piece of work.
+We want to make sure it is still relevant and not being duplicated by anyone else.
+
+## Discord
+
+Reach out to the protocol team on [discord](https://discord.com/channels/824324475256438814/1175166291976396861)
+once you have something actionable to discuss.
diff --git a/docusaurus/docs/packages/pkg/observable/observable.md b/docusaurus/docs/packages/pkg/observable/observable.md
@@ -1,7 +1,24 @@
-## `pocket/pkg/observable` Package
+---
+title: Observable Package
+sidebar_position: 1
+---
+
+## `pocket/pkg/observable` Package <!-- omit in toc -->
 
 The `pocket/pkg/observable` package provides a lightweight and straightforward mechanism to handle asynchronous notifications using the Observer pattern. This is achieved through two primary interfaces: `Observable` and `Observer`.
 
+- [Overview](#overview)
+- [Interfaces and Structures](#interfaces-and-structures)
+  - [`Observable` Interface](#observable-interface)
+  - [`Observer` Interface](#observer-interface)
+- [Architecture Diagrams](#architecture-diagrams)
+  - [Observable Synchronization](#observable-synchronization)
+  - [Observable Buffering](#observable-buffering)
+- [Usage](#usage)
+  - [Basic Example](#basic-example)
+- [Considerations](#considerations)
+- [Conclusion](#conclusion)
+
 ## Overview
 
 The `Observable` interface is responsible for notifying multiple subscribers about new values asynchronously, while the `Observer` interface allows access to the notified channel and facilitates unsubscribing from an `Observable`.

diff --git a/docusaurus/docs/quickstart.md b/docusaurus/docs/quickstart.md
@@ -15,9 +15,9 @@ title: Quickstart
 - [Interact with the chain](#interact-with-the-chain)
   - [Create a new Account](#create-a-new-account)
   - [Fund your account](#fund-your-account)
-  - [Send a relay](#send-a-relay)
   - [Stake Shannon as an Application](#stake-shannon-as-an-application)
-  - [Send a relay](#send-a-relay-1)
+  - [Send a relay](#send-a-relay)
+  - [Send a relay a shannon](#send-a-relay-a-shannon)
 - [Explore the tools](#explore-the-tools)
   - [poktrolld](#poktrolld)
   - [Makefile](#makefile)
@@ -84,7 +84,7 @@ Visit [localhost:10350](http://localhost:10350) and wait until all the container
 List all the accounts we get out of the box by running:
 
 ```bash
-ignite account list --keyring-dir=$(POKTROLLD_HOME) --keyring-backend test --address-prefix $(POCKET_ADDR_PREFIX)
+ignite account list --keyring-dir=./localnet/poktrolld --keyring-backend test --address-prefix pokt
 ```
 
 And create a new account named `shannon` by running:
@@ -106,7 +106,9 @@ export SHANNON_ADDRESS=pokt1mczm7xste7ckrwrmerda7m5ze89gyd9rzvxztr
 Query your account's balance by running:
 
 ```bash
-poktrolld --home=./localnet/poktrolld q bank balances $SHANNON_ADDRESS --node tcp://127.0.0.1:36657
+poktrolld --home=./localnet/poktrolld \
+  q bank balances $SHANNON_ADDRESS \
+  --node tcp://127.0.0.1:36657
 ```
 
 And you should see an empty balance:
@@ -121,7 +123,10 @@ pagination:
 But our sequencer has a lot of pokt from the genesis.json file (found at `localnet/poktrolld/config/genesis.json`)
 
 ```bash
-poktrolld --home=./localnet/poktrolld tx bank send sequencer1 $SHANNON_ADDRESS 199999100000000upokt --node tcp://127.0.0.1:36657
+poktrolld --home=./localnet/poktrolld \
+  tx bank send \
+  sequencer1 $SHANNON_ADDRESS 199999100000000upokt \
+  --node tcp://127.0.0.1:36657
 ```
 
 And you'll find that Shannon is now rolling in POKT:
@@ -135,12 +140,6 @@ pagination:
   total: "0"
 ```
 
-### Send a relay
-
-```bash
-curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' http://localhost:42069/anvil
-```
-
 ### Stake Shannon as an Application
 
 Run `make app_list` (a helper our team created) to see all the apps staked on the network.
@@ -163,52 +162,73 @@ We already have a supplier pre-configured to supply services for anvil
 Next, run the stake command:
 
 ```bash
-poktrolld --home=./localnet/poktrolld tx application stake-application 1000upokt --config shannon_app_config.yaml --keyring-backend test --from shannon --node tcp://127.0.0.1:36657
+poktrolld --home=./localnet/poktrolld \
+  tx application stake-application 1000upokt \
+  --config shannon_app_config.yaml \
+  --keyring-backend test --from shannon --node tcp://127.0.0.1:36657
 ```
 
 If you re-run, `make app_list` you should see that `SHANNON_ADDRESS` is now staked as an app.
 
 ### Send a relay
 
-## Explore the tools
+:::danger
+Please run `make supplier1_stake && make app1_stake` before sending a relay.
+This is related to some techdebt(#180) that will be fixed soon.
+:::
 
-There are three primary tools you'll use to develop and interact with the network:
+If you look in `localnet/poktrolld/config/appgate_server_config.yaml`, you'll find
+the configurations for an appgate server that is listening on port `42069`.
 
-1. `poktrolld` - the Pocket Rollup Node
-2. `make` - a collection of helpers to make your life easier
-3. `ignite` - a tool to manage the local k8s cluster
+Afterwards, you can send a relay to the `anvil` service (i.e. locally running
+ethereum node) like so:
 
-### poktrolld
+```bash
+curl -X POST -H "Content-Type: application/json" \
+  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
+  http://localhost:42069/anvil
+```
 
-### Makefile
+If everything worked as expected, you should see output similar to the following:
 
-### Ignite
+```json
+{"jsonrpc":"2.0","id":1,"result":"0x61"}%
+```
+
+### Send a relay a shannon
 
+```yaml
+self_signing: true
+signing_key: shannon
+listening_endpoint: http://localhost:42042
+query_node_url: tcp://127.0.0.1:36657
 ```
 
-1. Mint som new tokens
-2. Stake an application
-3. Send some funds
-4. Send a relay
+## Explore the tools
 
-## Develop
+There are three primary tools you'll use to develop and interact with the network:
+
+1. `poktrolld` - the Pocket Rollup Node
+2. `make` - a collection of helpers to make your life easier
+3. `ignite` - a tool to manage the local k8s cluster
 
-## Tools
+:::tip
+
+All of these are extensive and you will likely only need a small subset of their
+functionality in your day-to-day development. However, knowing of their existence
+will help you when you need to do something that you haven't done before.
+:::
 
 ### poktrolld
 
-Run `poktrolld --help`
+Run `poktrolld --help` in order to explore all the different. You will likely
+spend most of your time with either `poktrolld query --help` or `poktrolld tx --help`.
 
 ### Makefile
 
-Run `make` to see all the helpers we're working on
+Run `make` in order to see all the helpers our team has developed to
+improve our development experience.
 
 ### Ignite
 
-### LocalNe
-
-```
-
-```
-
-```
+Run `ignite --help` in order to explore all the different commands.
diff --git a/docusaurus/docs/roadmap/roadmap.md b/docusaurus/docs/roadmap/roadmap.md
@@ -1 +1,6 @@
-You can find our Roadmap [here](https://github.com/orgs/pokt-network/projects/144?query=is%3Aopen+sort%3Aupdated-desc)
+---
+title: Shannon Roadmap
+sidebar_position: 1
+---
+
+You can find our Roadmap [here](https://github.com/orgs/pokt-network/projects/144?query=is%3Aopen+sort%3Aupdated-desc).
diff --git a/docusaurus/docs/roadmap/roadmap_changelog.md b/docusaurus/docs/roadmap/roadmap_changelog.md
@@ -1,5 +1,6 @@
 ---
 title: Roadmap Changelog
+sidebar_position: 2
 ---
 
 # Roadmap Changelog <!-- omit in toc -->