Introduce docs website (#759)

* init docusaurus repo

* unify theme with cosmos-sdk docs

* update config

* add FAQ sections

* terms

* Create overview.md

* consumer dev folder

* smol

* Create technical-specification.md

* add new stuff

* add key assignment documentation

* fix typo

* add clarification

* update documentation; add features section; improve overview

* mv website to docs root; mv old readmes to old_docs

* add doc deployer

* make deployable to github pages

* add consumer initiated slashing doc page

* sovereign -> standalone

* add validators section

* fix typos

* update small things

* rename validator stuff

* add joining-testnet docs

* add title to joining testnet

* minor refactors

* refactor faq, update testnet guide

* update footers

* update testnet repo links

* Fix typo

Change ". Ie." to ", i.e."

* Fix typo: you key => your key

* Fix typo: cosumer => consumer

* update copyright section so docusaurus builds

* Add . at the end of info boxes

* Minor grammar change

* Add missing word "the"

* Fix typo

* update broken link for ics-testnets

* Remove duplicated paragraphs

* Adjust wording

---------

Co-authored-by: Matija Salopek <matija.salopek994@gmail.com>
Co-authored-by: MSalopek <35486649+MSalopek@users.noreply.github.com>
Co-authored-by: Philip Offtermatt <57488781+p-offtermatt@users.noreply.github.com>

.github/workflows/deploy-docs.yml

@@ -0,0 +1,48 @@
+
+name: Deploy docs
+# This job builds and deploys documenation to github pages.
+# It runs on every push to main with a change in the docs folder.
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+      # - "release/**"
+    paths:
+      - "docs/**"
+      # - "x/**/*.md"
+      - .github/workflows/deploy-docs.yml
+
+permissions:
+  contents: read
+
+jobs:
+  build-and-deploy:
+    permissions:
+      contents: write # for JamesIves/github-pages-deploy-action to push changes in repo
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout 🛎️
+        uses: actions/checkout@v3
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+          path: "."
+
+      - name: Setup Node.js 🔧
+        uses: actions/setup-node@v3
+        with:
+          node-version: "16.x"
+
+      # npm install npm should be removed when https://github.com/npm/cli/issues/4942 is fixed
+      - name: Build 🔧
+        run: |
+          npm install -g npm@8.5.5
+          make build-docs
+
+      - name: Deploy 🚀
+        uses: JamesIves/github-pages-deploy-action@v4.4.1
+        with:
+          branch: gh-pages
+          folder: ~/output
+          single-commit: true

Makefile

@@ -183,3 +183,11 @@ proto-update-deps:
 
 .PHONY: proto-all proto-gen proto-gen-any proto-swagger-gen proto-format proto-lint proto-check-breaking proto-update-deps mocks
 
+###############################################################################
+###                              Documentation                              ###
+###############################################################################
+
+build-docs:
+	@cd docs && ./build.sh
+
+.PHONY: build-docs

docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

docs/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

docs/build.sh

@@ -0,0 +1,10 @@
+#!/bin/sh
+
+# This builds docs using docusaurus.
+COMMIT=$(git rev-parse HEAD)
+echo "building docusaurus main docs"
+(git clean -fdx && git reset --hard && git checkout $COMMIT)
+npm ci && npm run build
+mv build ~/output
+echo "done building docusaurus main docs"
+# echo $DOCS_DOMAIN > ~/output/CNAME

docs/docs/adrs/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "ADRs",
+  "position": 6
+}

docs/ADRs/adr-template.md → docs/docs/adrs/adr-template.md

@@ -1,3 +1,7 @@
+---
+sidebar_position: 4
+title: ADR Template
+---
 # ADR {ADR-NUMBER}: {TITLE}
 
 ## Changelog

docs/docs/consumer-development/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Consumer Guide",
+  "position": 4
+}

docs/docs/consumer-development/app-integration.md

@@ -0,0 +1,32 @@
+---
+sidebar_position: 1
+---
+# Developing an ICS consumer chain
+
+When developing an ICS consumer chain, besides just focusing on your chain's logic you should aim to allocate time to ensure that your chain is compatible with the ICS protocol.
+To help you on your journey, the ICS team has provied multiple examples of a minumum viable consumer chain applications.
+
+## Basic consumer chain
+
+The source code for the example app can be found [here](https://github.com/cosmos/interchain-security/tree/main/app/consumer).
+
+Please note that consumer chains do not implement the staking module - the validator set is replicated from the provider, meaning that the provider and the consumer use the same validator set and their stake on the provider directly determines their stake on the consumer.
+At present there is no opt-in mechanism available, so all validators of the provider must also validate on the provider chain.
+
+Your chain should import the consumer module from `x/consumer` and register it in the correct places in your `app.go`.
+The `x/consumer` module will allow your chain to communicate with the provider using the ICS protocol. The module handles all IBC communication with the provider, and it is a simple drop-in.
+You should not need to manage or override any code from the `x/consumer` module.
+
+## Democracy consumer chain
+
+The source code for the example app can be found [here](https://github.com/cosmos/interchain-security/tree/main/app/consumer-democracy).
+
+This type of consumer chain wraps the basic CosmosSDK `x/distribution`, `x/staking` and `x/governance` modules allowing the consumer chain to perform democratic actions such as participating and voting within the chain's governance system.
+
+This allows the consumer chain to leverage those modules while also using the `x/consumer` module.
+
+With these modules enabled, the consumer chain can mint its own governance tokens, which can then be delegated to prominent community members which are referred to as "representatives" (as opposed to "validators" in standalone chains). The token may have different use cases besides just voting on governance proposals.
+
+## Standalone chain to consumer chain changeover
+This feature is being actively worked on. Information will be provided at a later time.
+

docs/docs/consumer-development/consumer-chain-governance.md

@@ -0,0 +1,5 @@
+---
+sidebar_position: 2
+---
+
+# Consumer Chain Governance

docs/docs/consumer-development/consumer-chain-upgrade-procedure.md

@@ -0,0 +1,5 @@
+---
+sidebar_position: 3
+---
+
+# Upgrading Consumer Chains

docs/docs/consumer-development/offboarding.md

@@ -0,0 +1,24 @@
+---
+sidebar_position: 5
+title: Offboarding Checklist
+---
+# Consumer Offboarding
+
+To offboard a consumer chain simply submit a `ConsumerRemovalProposal` governance proposal listing a `stop_time`. After stop time passes, the provider chain will remove the chain from the ICS protocol (it will stop sending validator set updates).
+
+```js
+// ConsumerRemovalProposal is a governance proposal on the provider chain to remove (and stop) a consumer chain.
+// If it passes, all the consumer chain's state is removed from the provider chain. The outstanding unbonding
+// operation funds are released.
+{
+    // the title of the proposal
+    "title": "This was a great chain",
+    "description": "Here is a .md formatted string specifying removal details",
+    // the chain-id of the consumer chain to be stopped
+    "chain_id": "consumerchain-1",
+    // the time on the provider chain at which all validators are responsible to stop their consumer chain validator node
+    "stop_time": "2023-03-07T12:40:00.000000Z",
+}
+```
+
+More information will be listed in a future version of this document.

docs/docs/consumer-development/onboarding.md

@@ -0,0 +1,104 @@
+---
+sidebar_position: 4
+title: Onboarding Checklist
+---
+# Consumer Onboarding Checklist
+
+The following checklists will aid in onboarding a new consumer chain to replicated security.
+
+Additionally, you can check the [testnet repo](https://github.com/cosmos/testnets/blob/master/replicated-security/CONSUMER_LAUNCH_GUIDE.md) for a comprehensive guide on preparing and launching consumer chains.
+
+## 1. Complete testing & integration
+
+- [ ] test integration with gaia
+- [ ] test your protocol with supported relayer versions (minimum hermes 1.3)
+- [ ] reach out to the ICS team if you are facing issues
+
+## 2. Create an Onboarding Repository
+
+To help validators and other node runners onboard onto your chain, please prepare a repository with information on how to run your chain.
+
+This should include (at minumum):
+
+- [ ] genesis.json witout CCV data (before the propsal passes)
+- [ ] genesis.json with CCV data (after spawn time passes)
+- [ ] information about relevant seed/peer nodes you are running
+- [ ] relayer information (compatible versions)
+- [ ] copy of your governance proposal (as JSON)
+- [ ] a script showing how to start your chain and connect to peers (optional)
+- [ ] take feedback from other developers, validators and community regarding your onboarding repo and make improvements where applicable
+
+Example of such a repository can be found [here](https://github.com/hyphacoop/ics-testnets/tree/main/game-of-chains-2022/sputnik).
+
+## 3. Submit a Governance Proposal
+
+Before you submit a `ConsumerChainAddition` proposal, please consider allowing at least a day between your proposal passing and the chain spawn time. This will allow the validators, other node operators and the community to prepare for the chain launch.
+If possible, please set your spawn time so people from different parts of the globe can be available in case of emergencies. Ideally, you should set your spawn time to be between 12:00 UTC and 20:00 UTC so most validator operators are available and ready to respond to any issues.
+
+Additionally, reach out to the community via the [forum](https://forum.cosmos.network/) to formalize your intention to become an ICS consumer, gather community support and accept feedback from the community, validators and developers.
+
+- [ ] determine your chain's spawn time
+- [ ] determine consumer chain parameters to be put in the proposal
+- [ ] take note to include a link to your onboarding repository
+- [ ] describe the purpose and benefits of running your chain
+
+Example of a consumer chain addition proposal.
+
+```js
+// ConsumerAdditionProposal is a governance proposal on the provider chain to spawn a new consumer chain.
+// If it passes, then all validators on the provider chain are expected to validate the consumer chain at spawn time.
+// It is recommended that spawn time occurs after the proposal end time.
+{
+    // Title of the proposal
+    "title": "Add consumer chain",
+    // Description of the proposal
+    // format the text as a .md file and include the file in your onboarding repository
+    "description": ".md description of your chain and all other relevant information",
+    // Proposed chain-id of the new consumer chain.
+    // Must be unique from all other consumer chain ids of the executing provider chain.
+    "chain_id": "newchain-1",
+    // Initial height of new consumer chain.
+    // For a completely new chain, this will be {0,1}.
+    "initial_height" : {
+        "revision_height": 0,
+        "revision_number": 1,
+    },
+    // Hash of the consumer chain genesis state without the consumer CCV module genesis params.
+    // It is used for off-chain confirmation of genesis.json validity by validators and other parties.
+    "genesis_hash": "d86d756e10118e66e6805e9cc476949da2e750098fcc7634fd0cc77f57a0b2b0",
+    // Hash of the consumer chain binary that should be run by validators on chain initialization.
+    // It is used for off-chain confirmation of binary validity by validators and other parties.
+    "binary_hash": "376cdbd3a222a3d5c730c9637454cd4dd925e2f9e2e0d0f3702fc922928583f1",
+    // Time on the provider chain at which the consumer chain genesis is finalized and all validators
+    // will be responsible for starting their consumer chain validator node.
+    "spawn_time": "2023-02-28T20:40:00.000000Z",
+    // Unbonding period for the consumer chain.
+    // It should should be smaller than that of the provider.
+    "unbonding_period": 86400000000000,
+    // Timeout period for CCV related IBC packets.
+    // Packets are considered timed-out after this interval elapses.
+    "ccv_timeout_period": 259200000000000,
+    // IBC transfer packets will timeout after this interval elapses.
+    "transfer_timeout_period": 1800000000000,
+    // The fraction of tokens allocated to the consumer redistribution address during distribution events.
+    // The fraction is a string representing a decimal number. For example "0.75" would represent 75%.
+    // The reward amount distributed to the provider is calculated as: 1 - consumer_redistribution_fraction.
+    "consumer_redistribution_fraction": "0.75",
+    // BlocksPerDistributionTransmission is the number of blocks between IBC token transfers from the consumer chain to the provider chain.
+    // eg. send rewards to the provider every 1000 blocks
+    "blocks_per_distribution_transmission": 1000,
+    // The number of historical info entries to persist in store.
+    // This param is a part of the cosmos sdk staking module. In the case of
+    // a ccv enabled consumer chain, the ccv module acts as the staking module.
+    "historical_entries": 10000,
+}
+```
+
+## 4. Launch
+
+The consumer chain starts after at least 66.67% of all provider's voting power comes online. The consumer chain is considered interchain secured once the appropriate CCV channels are established and the first validator set update is propagated from the provider to the consumer
+
+- [ ] provide a repo with onboarding instructions for validators (it should already be listed in the proposal)
+- [ ] genesis.json with ccv data populated (MUST contain the initial validator set)
+- [ ] maintenance & emergency contact info (relevant discord, telegram, slack or other communication channels)
+- [ ] have a block explorer in place to track chain activity & health

docs/docs/features/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Features",
+  "position": 3
+}