docs: Osmosis protocol book (#5971)

.github/workflows/protocol-docs.yml

@@ -0,0 +1,52 @@
+name: Render and Deploy Docs
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+
+jobs:
+
+  build:
+    name: Render and deploy protocol and API docs
+    timeout-minutes: 30
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout the source code
+        uses: actions/checkout@v3
+        with:
+          lfs: true
+      - name: Install rust toolchain
+        uses: dtolnay/rust-toolchain@nightly
+      - name: Load Rust caching
+        uses: astriaorg/buildjet-rust-cache@v2.5.1
+      - name: Load get-version action to grab version component of deployment path
+        uses: battila7/get-version-action@v2
+        id: get_version
+      - name: Print version component of deployment path
+        run: echo ${{ steps.get_version.outputs.version }}
+      - name: Install mdbook
+        run: cargo install mdbook mdbook-katex mdbook-mermaid
+      - name: Build protocol spec
+        run: cd docs/protocol && mdbook build
+      - name: Move protocol spec to subdirectory & Deploy
+        env:
+          DO_DOCS_PK: ${{ secrets.DO_DOCS_PK }}
+          DO_DOCS_IP: ${{ secrets.DO_DOCS_IP }}
+        run: |
+          cd docs/protocol
+          if [ -d "do-tmp" ]; then rm -rf do-tmp; fi
+          mkdir do-tmp
+          mv book do-tmp/${{ steps.get_version.outputs.version }}
+          tree do-tmp
+          which ssh-agent || ( apt-get update -y && apt-get install openssh-client -y  )
+          which rsync || ( apt-get update -y && apt-get install rsync -y )
+          eval $(ssh-agent -s)
+          ssh-add <(echo "$DO_DOCS_PK" )
+          mkdir -p ~/.ssh
+          chmod 700 ~/.ssh
+          ssh-keyscan $DO_DOCS_IP >> ~/.ssh/known_hosts
+          chmod 644 ~/.ssh/known_hosts
+          cd do-tmp/main
+          scp -r * root@$DO_DOCS_IP:/var/www/html

.gitignore

@@ -250,5 +250,8 @@ blocks.db
 tests/cl-genesis-positions/script
 tests/cl-genesis-positions/*.json
 
+# Docs
+docs/protocol/book
+
 # Release folder
-dist/
+dist/

docs/protocol/book.toml

@@ -0,0 +1,16 @@
+[book]
+authors = ["Osmosis Labs"]
+language = "en"
+multilingual = false
+src = "src"
+title = "The Osmosis Protocol"
+
+[preprocessor.katex]
+
+[preprocessor.mermaid]
+command = "mdbook-mermaid"
+
+[output.html]
+curly-quotes = true
+fold = { enable = true, level = 1 }
+git-repository-url = "https://github.com/osmosis-labs/osmosis"

docs/protocol/src/SUMMARY.md

@@ -0,0 +1,12 @@
+# Summary
+
+[Osmosis](./osmosis.md)
+- [Decentralized Exchange](./core_dex.md)
+   - [Weighted Pool](./dex/weighted.md)
+   - [Stableswap Pool](./dex/stableswap.md)
+   - [Concentrated Pool](./dex/concentrated.md)
+   - [Cosmwasm Pool](./dex/cosmwasm.md)
+- [Governance](./governance.md)
+- [Staking](./staking.md)
+- [Smart Contracts](./smartcontracts.md)
+- [Ecosystem](./ecosystem.md)

docs/protocol/src/core_dex.md

@@ -0,0 +1,12 @@
+# Decentralized Exchange
+
+Osmosis is a decentralized automated market maker (AMM) protocol built using Cosmos SDK that represents a flexible building block for programmable liquidity.
+
+By separating the AMM curve logic and math from the core swapping functionality, Osmosis becomes an extensible AMM that can incorporate any number of swap curves and pool types. This includes:
+
+- Traditional 50/50  weighted pools
+- Custom weights like 80/20 for controlled exposure
+- Solidly-style Stableswap curve
+- Concentrated Liquidity pools
+- CosmWasm pools
+

docs/protocol/src/dex/concentrated.md

@@ -0,0 +1 @@
+# Concentrated Pool

docs/protocol/src/dex/cosmwams.md

@@ -0,0 +1 @@
+# CosmWasm Pool

docs/protocol/src/dex/cosmwasm.md

@@ -0,0 +1 @@
+# Cosmwasm Pool

docs/protocol/src/dex/stableswap.md

@@ -0,0 +1 @@
+# Stableswap Pool

docs/protocol/src/dex/weighted.md

@@ -0,0 +1,7 @@
+# Weighted Pool
+
+Liquidity pools are clusters of tokens with pre-determined weights. A token's weight is how much its value accounts for the total value within the pool. For example, Uniswap pools involve two tokens with 50-50 weights. The total value of Asset A must remain equal to the total value of Asset B. Other token weights are possible, such as 90-10. It is also possible to have a liquidity pool with more than two assets.
+
+In Osmosis, pool creators are allowed to choose the tokens within the pool and their respective weights. The parameters chosen by the pool creator cannot be changed. Other users can create separate pools with different parameters.
+
+Weighted Pools are an extension of the classical  AMM pools popularized by Uniswap v1. Weighted Pools are great for general cases, including tokens that don't necessarily have any price correlation (ex. DAI/WETH). Unlike pools in other AMMs that only provide 50/50 weightings, Osmosis Weighted Pools enable users to build pools with more than two tokens and custom weightings, such as pools with 80/20 or 60/20/20 weightings.

docs/protocol/src/ecosystem.md

@@ -0,0 +1 @@
+# Ecosystem

docs/protocol/src/governance.md

@@ -0,0 +1,17 @@
+# Governance
+
+Osmosis is a sovereign delegated Proof-of-Stake chain with its own validator set.
+Users delegate their stake to validators to secure the network while keeping the
+opportunity to overwrite validator's decision with their own vote.
+
+The decisions are made through the governance process consisting of proposals.
+
+A proposal can be created by anyone. Once created with the required deposit, the
+voting period begins.
+
+The proposal is either accepted or rejected.
+
+There are two types of proposals that determine the length of the voting period,
+deposit amount and quorum:
+1. Standard proposal
+2. Expedited proposal

docs/protocol/src/osmosis.md

@@ -0,0 +1,31 @@
+# Introduction to Osmosis
+
+Osmosis is a fair-launched, customizable automated market maker for
+interchain assets that allows the creation and management of
+non-custodial, self-balancing, interchain token index similar to one of
+Balancer.
+
+Inspired by [Balancer](http://balancer.finance/whitepaper) and Sunny
+Aggarwal's '[DAOfying Uniswap Automated Market Maker
+Pools](https://www.sunnya97.com/blog/daoifying-uniswap-automated-market-maker-pools)',
+the goal for Osmosis is to provide the best-in-class tools that extend
+the use of AMMs within the Cosmos ecosystem beyond traditional token
+swap-type use cases. Bonding curves, while have found its primary use
+case in decentralized exchange mechanisms, its potential use case can be
+further extended through the customizability that Osmosis offers.
+Through the customizability offered by Osmosis such as custom-curve AMMs,
+dynamic adjustments of spread factors, multi-token liquidity pools--the AMM
+can offer decentralized formation of token fundraisers, interchain
+staking, options market, and more for the Cosmos ecosystem.
+
+Whereas most Cosmos zones have focused their incentive scheme on the
+delegators, Osmosis attempts to align the interests of multiple
+stakeholders of the ecosystem such as LPs, DAO members, as well as
+delegators. One mechanism that is introduced is how staked liquidity
+providers have sovereign ownership over their pools, and through the
+pool governance process allow them to adjust the parameters depending on
+the pool's competition and market conditions. Osmosis is a sovereign
+Cosmos zone that derives its sovereignty not only from its
+application-specific blockchain architecture but also the collective
+sovereignty of the LPs that has aligned interest to different tokens
+that they are providing liquidity for.

docs/protocol/src/smartcontracts.md

@@ -0,0 +1 @@
+# Smart Contracts (CosmWasm)

docs/protocol/src/staking.md

@@ -0,0 +1 @@
+# Staking