docs: merge gitbook in master into main (#518)

medibloc · Dec 6, 2022 · 309cbee · 309cbee
1 parent 720d788
commit 309cbee
Show file tree

Hide file tree

Showing 10 changed files with 385 additions and 158 deletions.
diff --git a/.gitbook/SUMMARY.md b/.gitbook/SUMMARY.md
@@ -4,7 +4,8 @@
 
 ## Overview
 
-* [Tech Stack](overview/tech-stack.md)
+* [Panacea Ecosystem](overview/panacea-ecosystem.md)
+* [Roadmap](overview/roadmap.md)
 
 ## Guide
 
@@ -14,12 +15,12 @@
 * [Deploy a Testnet](guide/deploy-a-testnet.md)
 * [Interaction with the network: CLI](guide/interaction-with-the-network-cli.md)
 * [Ledger Nano Support](guide/ledger-nano-support.md)
+* [Cosmovisor](guide/cosmovisor.md)
 
 ## Specifications
 
 * [AOL](specifications/aol.md)
 * [DID](specifications/did.md)
-* [Token](specifications/token.md)
 
 ## Resources
 

diff --git a/.gitbook/guide/cosmovisor.md b/.gitbook/guide/cosmovisor.md
@@ -0,0 +1,166 @@
+# Cosmovisor
+
+`cosmovisor` is a small process manager for Cosmos SDK application binaries that monitors the governance module for incoming chain upgrade proposals. If it sees a proposal that gets approved, `cosmovisor` can automatically download the new binary, stop the current binary, switch from the old binary to the new one, and finally restart the node with the new binary.
+
+We will explain how to use it based on version `0.1.0` of `cosmovisor`.
+
+## Cosmovisor Setup
+
+Install the `cosmovisor` binary.
+
+You will find a `cosmovisor` in path `$GOPATH/bin`.
+
+```shell
+go get github.com/cosmos/cosmos-sdk/cosmovisor/cmd/cosmovisor@v0.1.0
+```
+
+
+Set the required environment variabes.
+
+There are four variables. (two are requirement, and two are optional)
+
+* DAEMON_HOME (Requirement)
+  * This includes genesis binary and upgrade binaries.
+  * `export DAEMON_HOME=$HOME/.panacea`
+* DAEMON_NAME (Requirement)
+  * It's the name of binary.
+  * `export DAEMON_NAME=panacead`
+* DAEMON_ALLOW_DOWNLOAD_BINARIES (Optional)
+  * Whether to automatically download the new binary.
+  * The default value is `false`.
+  * Unfortunately, automatic download is not available yet.(by `libwasmvm.so`)
+* DAEMON_RESTART_AFTER_UPGRADE (Optional)
+  * Whether to restart the process after the upgrade is completed.
+  * The default value is false, so the administrator must manually restart after the upgrade.
+  * `export DAEMON_RESTART_AFTER_UPGRADE=true`
+
+We make setting to manually download the binary and to automatically proceed with the upgrade.
+
+```shell
+export DAEMON_HOME=$HOME/.panacea
+export DAEMON_NAME=panacead
+export DAEMON_RESTART_AFTER_UPGRADE=true
+export DAEMON_ALLOW_DOWNLOAD_BINARIES=false
+```
+
+Create a directory for the genesis binary and upgrade binary.
+
+```shell
+mkdir -p $DAEMON_HOME/cosmovisor/genesis/bin
+mkdir -p $DAEMON_HOME/cosmovisor/upgrades/v2.0.2/bin
+```
+
+Clone and check out the current `panacead` mainnet version. (v2.0.1)
+
+```shell
+git clone -b v2.0.1 https://github.com/medibloc/panacea-core.git
+cd panacea-core
+```
+
+Build a binary and copy it to the genesis path of the `cosmovisor`.
+
+```shell
+make clean && make build
+cp ./build/panacead $DAEMON_HOME/cosmovisor/genesis/bin
+```
+
+Build the upgraded version(v2.0.2) and copy it to the `cosmovisor`.
+
+```shell
+git checkout tags/v2.0.2
+make clean && make build
+cp ./build/panacead $DAEMON_HOME/cosmovisor/upgrades/v2.0.2/bin
+```
+
+Verify that the `cosmovisor` is applied as the mainnet version normally.
+
+```shell
+cosmovisor version
+2.0.1 # output
+```
+
+Discontinue the currently running `panacead` and run it with `cosmovisor`.
+
+```shell
+stop panacead
+cosmovisor start
+```
+
+When this [proposal](https://www.mintscan.io/medibloc/proposals/2) passes and the upgrade date(`2021-10-01T07:00:00Z`) arrives, the upgrade will automatically proceed to v2.0.2.
+
+
+## Example
+
+Show an example of upgrading the version of panacead in a local environment.
+
+```shell
+go get github.com/cosmos/cosmos-sdk/cosmovisor/cmd/cosmovisor@v0.1.0
+
+export DAEMON_HOME=$HOME/.panacea
+export DAEMON_NAME=panacead
+export DAEMON_RESTART_AFTER_UPGRADE=true
+export DAEMON_ALLOW_DOWNLOAD_BINARIES=false
+
+mkdir -p $DAEMON_HOME/cosmovisor/genesis/bin
+mkdir -p $DAEMON_HOME/cosmovisor/upgrades/v2.0.2/bin
+```
+
+Clone and check out the current `panacead` mainnet version. (v2.0.1)
+
+Then, build it and copy it.
+```shell
+git clone -b v2.0.1 https://github.com/medibloc/panacea-core.git
+cd panacea-core
+
+make clean && make build
+cp ./build/panacead $DAEMON_HOME/cosmovisor/genesis/bin
+```
+
+Create a new key for the validator, then add a genesis account and transaction:
+
+```shell
+./build/panacead init test --chain-id test --overwrite
+./build/panacead keys add validator
+./build/panacead add-genesis-account validator 1000000000umed --keyring-backend test
+./build/panacead gentx validator 1000000umed --chain-id test
+./build/panacead collect-gentxs
+
+cat <<< $(jq '.app_state.gov.voting_params.voting_period = "20s" | .app_state.gov.deposit_params.min_deposit[].amount = "10000000"' $DAEMON_HOME/config/genesis.json) > $DAEMON_HOME/config/genesis.json
+```
+
+You need to run binary with cosmovisor.
+```shell
+cosmovisor version
+2.0.1 # output
+cosmovisor start
+```
+
+Submit upgrade proposal along with a deposit and a vote.
+
+```shell
+./build/panacead tx gov submit-proposal software-upgrade v2.0.2 \
+--title upgrade \
+--description upgrade \
+--upgrade-height 30 \
+--from validator \
+--chain-id test \
+--yes
+
+./build/panacead tx gov deposit 1 10000000umed --from validator --chain-id test --yes
+./build/panacead tx gov vote 1 yes --from validator --chain-id test --yes
+```
+
+Build the upgraded version(v2.0.2) and copy it to the `cosmovisor`.
+
+```shell
+git checkout tags/v2.0.2
+make clean && make build
+cp ./build/panacead $DAEMON_HOME/cosmovisor/upgrades/v2.0.2/bin
+```
+
+The upgrade will be performed automatically at height 30.
+
+```shell
+cosmovisor version
+2.0.2 # output
+```
diff --git a/.gitbook/guide/interaction-with-the-network-cli.md b/.gitbook/guide/interaction-with-the-network-cli.md
@@ -276,6 +276,7 @@ Don't use more `umed` than you have!
 panacead tx staking create-validator \
   --pubkey $(panacead tendermint show-validator) \
   --moniker "choose a moniker" \
+  --details "This is a detail description" \
   --chain-id <chain-id> \
   --commission-rate "0.10" \
   --commission-max-rate "0.20" \
@@ -290,6 +291,7 @@ panacead tx staking create-validator \
   The public key can be resolved by `panacead tendermint show-validator` in the node that you want to make as a validator.
   For details about various key types, please see this [guide](interaction-with-the-network-cli.md#keys).
 - `moniker`: A validator nickname that will be displayed publicly
+- `details`: A detail description of the validator
 - `commission-rate`: An initial commission rate on block rewards and fees charged to delegators
   - This shouldn't be smaller than the minimum commission rate (a genesis parameter) that can be queried by `panacead query staking params`.
 - `commission-max-rate`: A maximum commission rate which this validator can charge. This cannot be changed after the
@@ -330,12 +332,16 @@ panacead tx staking edit-validator \
   --fees "1000000umed"
 ```
 
+For more details of each flag, please see the [`Create your validator`](#create-your-validator) guide.
+
 **Note**: The `--commission-rate` value must adhere to the following invariants:
 
 - Must be between the minimum commission rate (a genesis parameter) and the validator's `commission-max-rate`
 - Must not exceed the validator's `commission-max-change-rate` which is maximum % point change rate **per day**.
   In other words, a validator can only change its commission once per day and within `commission-max-change-rate` bounds.
 
+If you want to set a logo image of your validator which will be displayed on Mintscan and Cosmostation, please refer to [this guide](https://github.com/cosmostation/cosmostation_token_resource).
+
 ### Delegate to a Validator
 
 You can delegate `umed` to a validator. These delegators can receive part of the validator's fee revenue.
@@ -492,7 +498,30 @@ With the `pool` command you will get the values for:
 
 * Not-bonded and bonded tokens
 
-## Fee Distribution
+## Reward Distribution
+
+### Withdraw rewards (and commissions)
+
+You can withdraw rewards proportional to your stake delegated to a specific validator.
+```bash
+panacead tx distribution withdraw-rewards <valoper-address> --from <delegator-address>
+```
+The `<valoper-address>` is an unique ID of a validator which starts with `panaceavaloper1`, while the `<delegator-address>` starts with `panacea1`.
+
+If you are a validator operator, you can withdraw commissions (collected from delegators) as well as rewards, by adding a `--commission` flag as below.
+```bash
+panacead tx distribution withdraw-rewards <valoper-address> --from <operator-address> --commission
+```
+
+If you are delegating to multiple validators, you can withdraw rewards from all validators that you are delegating to.
+```bash
+panacead tx distribution withdraw-all-rewards --from <delegator-address>
+```
+
+If you want to make your rewards to be withdrawn to another wallet, you can set an withdraw address as below. Then, whenever you execute `withdraw-rewards` or `withdraw-all-rewards` transactions, all rewards and commissions will be withdrawn to the withdraw address.
+```bash
+panacead tx distribution set-withdraw-addr <withdraw-address> --from <delegator-address>
+```
 
 ### Query distribution parameters
 
@@ -775,75 +804,3 @@ so that Panacea can verify that you are the DID owner.
 
 Deactivating a DID is not the same as deleting a DID. DIDs cannot be deleted permanently. They can just be deactivated.
 And DIDs cannot be reused to create another DID Documents forever.
-
-## Token
-
-### Issue a new token
-
-A new token can be issued by the following command. Anyone can issue a new token with fee paid.
-After issuing, the token would appear in the issuer's account.
-
-The symbol doesn't have to be unique. `-` followed by random 3 letters will be appended to the provided symbol to avoid uniqueness constraint.
-Those 3 letters are the first three letters of the Tx hash of the `issue` transaction.
-The generated symbol will be returned as a Tx response.
-
-For more details of each parameter, please see the [Token specification](../specifications/token.md).
-
-```bash
-# Note that the total supply must be in micro unit without a denomination.
-panacead tx token issue \
-    "my token" \
-    KAI \
-    1000000000 \
-    --mintable \
-    --from panacea126r28pr7sstg7yfmedv3qq4st4a4exlwccx2vc \
-    --chain-id testing
-```
-
-### Query a token
-
-```bash
-# List all token symbols
-$ panacead query token list-tokens --chain-id testing
-
-- KAI-0C5
-- KAI-0EA
-
-# Query a token
-$ panacead query token get-token KAI-0EA
-
-name: my secret token
-symbol: KAI-0EA
-totalsupply:
-  denom: ukai0ea
-  amount: "1000000000"
-mintable: true
-owneraddress: panacea126r28pr7sstg7yfmedv3qq4st4a4exlwccx2vc
-```
-
-### Query account balances and send tokens
-
-Of course, the new token is visible in the account balance.
-```bash
-$ panacead query account panacea126r28pr7sstg7yfmedv3qq4st4a4exlwccx2vc
-
-  address: panacea126r28pr7sstg7yfmedv3qq4st4a4exlwccx2vc
-  coins:
-  - denom: ukai0c5
-    amount: "1000000000"
-  - denom: ukai0ea
-    amount: "999999900"
-  - denom: ukai62e
-    amount: "1000000000"
-  - denom: umed
-    amount: "99000000000000"
-  pubkey: panaceapub1addwnpepqf2m7rxgazcem4e6x4hjnwexeagrqjfdlkvz65e0jpxv5sn76jurgpqmpd5
-  accountnumber: 0
-  sequence: 6
-```
-
-Also, the new token can be sent to other accounts.
-Note that the `amount` must be specified with the micro-denomination that contains the 3-letter suffix (without `-`).
-```bash
-panacead tx send <from-address> <to-address> 1000000ukai0ea
-```