smeb_y/0g-chain
1
0
Fork 0
mirror of https://github.com/0glabs/0g-chain.git synced 2024-12-24 23:35:19 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merge pull request #1020 from Kava-Labs/at-validator-guide

Browse Source 
Update Documentation
This commit is contained in:
Adam Robert Turman 2021-09-28 10:37:46 -05:00 committed by GitHub
commit de750103ca
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 364 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
docs/kava-8/upgrade_oracle.md Normal file
View File

@ -0,0 +1,36 @@
# kava-8 Oracle Update Guide
The Kava blockchain is upgrading and minor updates are needed for oracles
## Update Guide For Standalone Oracle Operators
1. Install the latest version of kava-tools
2. In your `.env` configuration file, add an entry for `FEE`. This will set the default fee (in ukava) for each oracle transaction (can be 0).
- `FEE=”10000”`
3. In your `.env` configuration file, update the MARKET_IDS entry to include the latest markets for kava-5:
- `MARKET_IDS="bnb:usd,bnb:usd:30,btc:usd,btc:usd:30,xrp:usd,xrp:usd:30,busd:usd,busd:usd:30,kava:usd,kava:usd:30,hard:usd,hard:usd:30,usdx:usd,usdx:usd:30"`
4. Restart your oracle process
## Update Guide For Chainlink Oracle Operators
1. Pull the latest version of Kava’s external-adapters-js repo
2. Install `yarn`
3. Build the latest version of the kava adapter
- from top level external-adapter-js directory
- make docker adapter=kava
4. Edit your configuration file and add an entry for `FEE`. This will set the default fee (in ukava) for each oracle transaction (can be 0).
- `FEE=”10000”`
5. Restart the kava adapter with the latest version
6. If necessary, create jobs for the following market_ids, if they do not already exist
- bnb:usd
- bnb:usd:30
- btc:usd
- btc:usd:30
- xrp:usd
- xrp:usd:30
- busd:usd
- busd:usd:30
- kava:usd
- kava:usd:30
- hard:usd
- hard:usd:30
- usdx:usd
- usdx:usd:30

70
docs/kava-8/upgrade_validator.md Normal file
View File

@ -0,0 +1,70 @@
# kava-8 Validator Update Guide
The kava-8 update includes new features. This document contains important information about the new functionality and breaking changes.
kava-8 will use the same major version of the cosmos-sdk (v0.39.x). kava-8 will have the same golang compatibility as kava-7, requiring v1.13+. Golang v1.15 has been tested and is suitable for use on kava-8 mainnet.
## Migration Procedure
The specific steps to migrate your node can be found [here](https://github.com/Kava-Labs/kava/blob/master/migrate/v0_15/migrate.md).
## Breaking Changes
#### Claiming Rewards
Reward claims in the `x/incentive` module have been updated to enable selective reward claiming by type and token denom. There are four primary reward claim message types:
- **MsgClaimUSDXMintingReward** has arguments Sender (sdk.AccAddress) and MultiplierName (string). This message will claim all USDX minting rewards for the user, applying the specified reward multiplier.
- **MsgClaimHardReward** takes three arguments: Sender (sdk.AccAddress), Multiplier Name (string), and Denoms To Claim ([]string). This message will claim any available HARD supply/borrow rewards of the specified denoms for the user, applying the specified reward multiplier.
- **MsgClaimDelegatorReward** takes three arguments: Sender (sdk.AccAddress), Multiplier Name (string), and Denoms To Claim ([]string). This message will claim any available delegation rewards of the specified denoms for the user, applying the specified reward multiplier.
- **MsgClaimSwapReward** takes three arguments: Sender (sdk.AccAddress), Multiplier Name (string), and Denoms To Claim ([]string). This message will claim any available SWAP protocol rewards of the specified denoms for the user, applying the specified reward multiplier.
#### Committee Voting
Voting in the `x/committee` module has been updated to support Yes, No, and Abstain votes.
- **MsgVote** takes three arguments: Proposal ID (uint64), Voter (sdk.AccAddress), and Vote Type (VoteType). Valid Vote Types are “yes”, “y,” “no”, “n”, “abstain”, and “a”.
## New Features
#### SWAP Protocol
Kava-8 introduces SWAP protocol, a decentralized exchange that enables users to swap tokens against liquidity pools. SWAP protocol has several new messages:
- **MsgDeposit** enables liquidity providers to deposit tokens into a liquidity pool. It takes five arguments - the depositor (sdk.AccAddress) that is providing liquidity, token A (sdk.Coin) that is being deposited, token B (sdk.Coin) that is being deposited, minimum acceptable slippage (sdk.Dec), and deadline (int64). After a successful deposit the liquidity provider will be credited deposit shares in the pool.
- **MsgWithdraw** enables liquidity providers to withdraw deposited tokens from a liquidity pool. It takes five arguments - the withdrawer’s address (sdk.AccAddress), the amount of shares (sdk.Int) to be withdrawn, the minimum accepted token A amount (sdk.Coin) to be received by the withdrawer, the minimum accepted token B amount (sdk.Coin) to be received, and the deadline (int64). After a successful withdrawal the liquidity provider will receive tokens.
- **MsgSwapExactForTokens** supports token swaps with an exact amount of input tokens. It takes five arguments - the requester’s address (sdk.AccAddress), the exact input amount of token A (sdk.Coin), the desired output amount of token B (sdk.Coin), the minimum accepted slippage (sdk.Dec) i.e. percentage difference from the output amount, and the deadline (int64).
- **MsgSwapForExactTokens** supports token swaps for an exact amount of output tokens. It takes five arguments - the requester’s address (sdk.AccAddress), the desired input amount of token A (sdk.Coin), the exact output amount of token B (sdk.Coin), the minimum accepted slippage (sdk.Dec) i.e. percentage difference from the input amount, and the deadline (int64).
#### Committee
kava-8 introduces HARD and SWAP protocol governance by token holders via two new committees. Both committees have a proposal voting duration of seven days, a minimum quorum of 33%, and enact proposals that receive over 50% Yes votes.
The **HARD Governance Committee** will have permissions to change the following parameters:
- Hard module permissions
- *Money markets*: whitelist of supported money markets.
- *Minimum borrow USD value*: minimum valid borrow amount in USD from a money market.
- Incentive module permissions
- *Hard supply reward periods*: HARD token rewards for HARD protocol suppliers.
- *Hard borrow reward periods*: HARD token rewards for HARD protocol borrowers.
- *Delegator reward periods*: HARD token rewards for KAVA delegators
The **SWP Governance Committee** will have permissions to change the following parameters:
- Swap module permissions
- *Allowed pools*: whitelist of supported token pairs.
- *Swap fee*: global trading fee paid by users to liquidity providers.
- Incentive module permissions
- *Swap reward periods*: SWP token rewards for SWAP protocol liquidity providers.
- *Delegator reward periods*: SWP token rewards for KAVA delegators.
## Kava REST API
Kava’s REST API supports all Kava-8 changes and features. To minimize compatibility issues, commonly used endpoints are still supported and have not been deprecated. API documentation can be found here.
Testing
Kava-testnet-13000 is a publicly available testnet (http://app.swap-testnet.kava.io/) to test validation and external integrations. Publicly available REST and RPC endpoints are:
#### Pruning nodes:
- Rest: https://api.testnet.kava.io/node_info
- RPC: https://rpc.testnet.kava.io
#### Archive nodes:
- Rest: https://api.data-testnet.kava.io/node_info
- RPC: https://rpc.data-testnet.kava.io
## Questions/Feedback
Please reach out in your preferred communication channel (Discord, Slack, email) with any questions, or ask in [The Kava Platform Telegram](https://t.me/kavalabs).

51
docs/kava-8/upgrade_wallet.md Normal file
View File

@ -0,0 +1,51 @@
# kava-8 Wallet Update Guide
The kava-8 update includes new features. This document contains important information about the new functionality and breaking changes.
kava-8 will use the same major version of the cosmos-sdk (v0.39.x). kava-8 will have the same golang compatibility as kava-7, requiring v1.13+. Golang v1.15 has been tested and is suitable for use on kava-8 mainnet.
## Breaking Changes
#### Claiming Rewards
Reward claims in the `x/incentive` module have been updated to enable selective reward claiming by type and token denom. There are four primary reward claim message types:
- **MsgClaimUSDXMintingReward** has arguments Sender (sdk.AccAddress) and MultiplierName (string). This message will claim all USDX minting rewards for the user, applying the specified reward multiplier.
- **MsgClaimHardReward** takes three arguments: Sender (sdk.AccAddress), Multiplier Name (string), and Denoms To Claim ([]string). This message will claim any available HARD supply/borrow rewards of the specified denoms for the user, applying the specified reward multiplier.
- **MsgClaimDelegatorReward** takes three arguments: Sender (sdk.AccAddress), Multiplier Name (string), and Denoms To Claim ([]string). This message will claim any available delegation rewards of the specified denoms for the user, applying the specified reward multiplier.
- **MsgClaimSwapReward takes** three arguments: Sender (sdk.AccAddress), Multiplier Name (string), and Denoms To Claim ([]string). This message will claim any available SWAP protocol rewards of the specified denoms for the user, applying the specified reward multiplier.
#### Committee Voting
Voting in the `x/committee` module has been updated to support Yes, No, and Abstain votes.
- **MsgVote takes three arguments: Proposal ID (uint64), Voter (sdk.AccAddress), and Vote Type (VoteType). Valid Vote Types are “yes”, “y,” “no”, “n”, “abstain”, and “a”.
## New Features
#### SWAP Protocol
Kava-8 introduces SWAP protocol, a decentralized exchange that enables users to swap tokens against liquidity pools. SWAP protocol has several new messages:
- **MsgDeposit** enables liquidity providers to deposit tokens into a liquidity pool. It takes five arguments - the depositor (sdk.AccAddress) that is providing liquidity, token A (sdk.Coin) that is being deposited, token B (sdk.Coin) that is being deposited, minimum acceptable slippage (sdk.Dec), and deadline (int64). After a successful deposit the liquidity provider will be credited deposit shares in the pool.
- **MsgWithdraw** enables liquidity providers to withdraw deposited tokens from a liquidity pool. It takes five arguments - the withdrawer’s address (sdk.AccAddress), the amount of shares (sdk.Int) to be withdrawn, the minimum accepted token A amount (sdk.Coin) to be received by the withdrawer, the minimum accepted token B amount (sdk.Coin) to be received, and the deadline (int64). After a successful withdrawal the liquidity provider will receive tokens.
- **MsgSwapExactForTokens** supports token swaps with an exact amount of input tokens. It takes five arguments - the requester’s address (sdk.AccAddress), the exact input amount of token A (sdk.Coin), the desired output amount of token B (sdk.Coin), the minimum accepted slippage (sdk.Dec) i.e. percentage difference from the output amount, and the deadline (int64).
- **MsgSwapForExactTokens** supports token swaps for an exact amount of output tokens. It takes five arguments - the requester’s address (sdk.AccAddress), the desired input amount of token A (sdk.Coin), the exact output amount of token B (sdk.Coin), the minimum accepted slippage (sdk.Dec) i.e. percentage difference from the input amount, and the deadline (int64).
#### Committee
kava-8 introduces HARD and SWAP protocol governance by token holders via two new committees. Both committees have a proposal voting duration of seven days, a minimum quorum of 33%, and enact proposals that receive over 50% Yes votes.
The **HARD Governance Committee** will have permissions to change the following parameters:
- Hard module permissions
- *Money markets*: whitelist of supported money markets.
- *Minimum borrow USD value*: minimum valid borrow amount in USD from a money market.
- Incentive module permissions
- *Hard supply reward periods*: HARD token rewards for HARD protocol suppliers.
- *Hard borrow reward periods*: HARD token rewards for HARD protocol borrowers.
- *Delegator reward periods*: HARD token rewards for KAVA delegators
The **SWP Governance Committee** will have permissions to change the following parameters:
- Swap module permissions
- *Allowed pools*: whitelist of supported token pairs.
- *Swap fee*: global trading fee paid by users to liquidity providers.
- Incentive module permissions
- *Swap reward periods*: SWP token rewards for SWAP protocol liquidity providers.
- *Delegator reward periods*: SWP token rewards for KAVA delegators.
Kava REST API
Kava’s REST API supports all Kava-8 changes and features. To minimize compatibility issues, commonly used endpoints are still supported and have not been deprecated. API documentation can be found [here](https://swagger.kava.io/).

20
docs/readme.md
View File

@ -14,28 +14,38 @@ Reference implementation of Kava, a blockchain for cross-chain DeFi. Built using
## Mainnet
The current recommended version of the software for mainnet is [v0.14.1](https://github.com/Kava-Labs/kava/releases/tag/v0.14.1). The master branch of this repository often contains considerable development work since the last mainnet release and is __not__ runnable on mainnet.
The current recommended version of the software for mainnet is [v0.15.1](https://github.com/Kava-Labs/kava/releases/tag/v0.15.1). The master branch of this repository often contains considerable development work since the last mainnet release and is __not__ runnable on mainnet.
### Installation
```bash
git checkout v0.14.1
git checkout v0.15.1
make install
```
### Upgrade
The scheduled mainnet upgrade to `kava-7` took place on April 8th, 2021 at 15:00 UTC. The current version of Kava for `kava-7` is [__v0.14.1__](https://github.com/Kava-Labs/kava/releases/tag/v0.14.1).
The scheduled mainnet upgrade to `kava-8` took place on August 30th, 2021 at 15:00 UTC. The current version of Kava for `kava-8` is [__v0.15.1__](https://github.com/Kava-Labs/kava/releases/tag/v0.15.1).
The canonical genesis file can be found [here](https://github.com/Kava-Labs/launch/tree/master/kava-4)
The canonical genesis file can be found [here](https://github.com/Kava-Labs/launch/tree/master/kava-8)
The canonical genesis file hash is
```
jq -S -c -M '' genesis.json | shasum -a 256
9dbff5a0fb1a7aa20247f73e974bfd4a11090252768869ef8ccb23a515a01c51 -
f0c90f0cbf96d230a83cd2309b8fd032e52d7fb933881541472df1bf2703a939 -
```
For additional information about upgrades:
- Upgrading a [Validator](https://github.com/Kava-Labs/kava/blob/master/docs/kava-8/upgrade_validator.md)
- Upgrading a [Wallet](https://github.com/Kava-Labs/kava/blob/master/docs//kava-8/upgrade_wallet.md)
- Upgrading an [Oracle](https://github.com/Kava-Labs/kava/blob/master/docs//kava-8/upgrade_oracle.md)
### Validator Guide
Use this [guide](https://github.com/Kava-Labs/kava/blob/master/docs/validator_guide.md) to set up a mainnet validator. Note that this is a minimal guide and does not cover more advanced topics like [sentry node architecture](https://github.com/stakefish/cosmos-validator-design) and [double signing protection](https://github.com/tendermint/tmkms). It is strongly recommended that any parties considering validating do additional research. If you have questions, please join the active conversation in the #validators thread of the [__Kava Discord Channel__](https://discord.com/invite/kQzh3Uv).
## Testnet
For further information on joining the testnet, head over to the [testnet repo](https://github.com/Kava-Labs/kava-testnets).

192
docs/validator_guide.md Normal file
View File

@ -0,0 +1,192 @@
# Validator Guide
This is an updated guide on setting up a mainnet validator. Note that this is a minimal guide and does not cover more advanced topics like [sentry node architecture](https://github.com/stakefish/cosmos-validator-design) and [double signing protection](https://github.com/tendermint/tmkms). It is strongly recommended that any parties considering validating do additional research. If you have questions, please join the active conversation in the #validators thread of our [__Discord Channel__](https://discord.com/invite/kQzh3Uv).
## Installing Kava
### Prerequisites
You should select an all-purpose server with at least 8GB of RAM, good connectivity, and a solid state drive with sufficient disk space. Storage requirements are discussed further in the section below. In addition, you’ll need to open **port 26656** to connect to the Kava peer-to-peer network. As the usage of the blockchain grows, the server requirements may increase as well, so you should have a plan for updating your server as well.
### Storage
The monthly storage requirements for a node are as follows. These are estimated values based on experience, but should serve as a good guide.
- An archival node (`pruning = "nothing"`) grows at a rate of ~100 GB per month
- A fully pruning node (`pruning = "everything"`) grows at a rate of ~5 GB per month
- A default pruning node (`pruning = “default”`) grows at a rate of ~25 GB per month
## Install Go
Kava is built using Go and requires Go version 1.13+. In this example, you will be installing Go on a fresh install of ubuntu 18.04.
```bash
# Update ubuntu
sudo apt update
sudo apt upgrade -y
# Install packages necessary to run go and jq for pretty formatting command line outputs
sudo apt install build-essential jq -y
# Install go
wget https://dl.google.com/go/go1.17.1.linux-amd64.tar.gz (or latest version at https://golang.org/dl/)
sudo tar -xvf go1.17.1.linux-amd64.tar.gz
sudo mv go /usr/local
# Updates environmental variables to include go
cat <<EOF>> ~/.profile
export GOROOT=/usr/local/go
export GOPATH=$HOME/go
export GO111MODULE=on
export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin
EOF
source ~/.profile
```
To verify that Go is installed:
```bash
go version
# Should return go version go1.17.1 linux/amd64
```
## Install Kava
Install Kava using `git clone`. Note that version 0.15.1 is the correct version for mainnet.
```bash
git clone https://github.com/kava-labs/kava
cd kava
git checkout v0.15.1
make install
```
To verify that kava is installed:
```bash
kvd version --long
# name: kava
# server_name: kvd
# client_name: kvcli
# version: 0.15.1
# commit: f0c90f0cbf96d230a83cd2309b8fd032e52d7fb933881541472df1bf2703a939
# build_tags: netgo,ledger
# go: go version go1.15.14 linux/amd64
```
## Configuring Your Node
Next, download the correct genesis file and sync your node with the Kava mainnet. To download the genesis file:
```bash
# First, initialize kvd. Replace <name> with the public name of your node
kvd init --chain-id kava-8 <name>
# Download the genesis file
wget https://kava-genesis-files.s3.amazonaws.com/kava-8-genesis-migrated-from-block-1878508.json -O ~/.kvd/config/genesis.json
# Verify genesis hash
jq -S -c -M '' $HOME/.kvd/config/genesis.json | shasum -a 256
# f0c90f0cbf96d230a83cd2309b8fd032e52d7fb933881541472df1bf2703a939
```
Next, adjust some configurations. To open the config file:
```bash
vim $HOME/.kvd/config/config.toml
```
At line 160, add [seeds](https://docs.google.com/spreadsheets/d/1TWsD2lMi1idkPI6W9xFCn5W64x75yn9PDjvQaJVkIRk/edit?usp=sharing). These are used to connect to the peer-to-peer network:
At line 163, add some [persistent peers](https://docs.google.com/spreadsheets/d/1TWsD2lMi1idkPI6W9xFCn5W64x75yn9PDjvQaJVkIRk/edit?usp=sharing), which help maintain a connection to the peer-to-peer network
Next, chose how much historical state you want to store. To open the application config file:
```bash
vim $HOME/.kvd/config/app.toml
```
In this file, choose between `default`, `nothing`, and `everything`. To reduce hard drive storage, choose `everything` or `default`. To run an archival node, chose `nothing`.
```bash
pruning = "default"
```
In the same file, you will want to set minimum gas prices — setting a minimum prevents spam transactions:
```bash
minimum-gas-prices = "0.001ukava"
```
### Syncing Your Node
To sync your node, you will use systemd, which manages the Kava daemon and automatically restarts it in case of failure. To use systemd, you will create a service file. Be sure to replace `<your_user>` with the user on your server:
```bash
sudo tee /etc/systemd/system/kvd.service > /dev/null <<'EOF'
[Unit]
Description=Kava daemon
After=network-online.target
[Service]
User=<your_user>
ExecStart=/home/<your_user>/go/bin/kvd start
Restart=on-failure
RestartSec=3
LimitNOFILE=4096
[Install]
WantedBy=multi-user.target
EOF
```
To start syncing:
```bash
# Start the node
sudo systemctl enable kvd
sudo systemctl start kvd
```
To check on the status of syncing:
```bash
kvcli status --output json | jq '.sync_info'
```
This will give output like:
```bash
{
"latest_block_hash": "21D7E37A0A5992E1992DD43E42C05E4475A6E212694F746ABEE132267067847D",
"latest_app_hash": "FBE0E799BCCA57F12F781252787BD6340782E5D45E591294D01269F481B128AC",
"latest_block_height": "183566",
"latest_block_time": "2021-03-22T17:21:41.848445277Z",
"earliest_block_hash": "09E688467E5016159D74CEDE2EE870D671CAA772F76E6697AEEB685A398ACB08",
"earliest_app_hash": "",
"earliest_block_height": "1",
"earliest_block_time": "2021-03-05T06:00:00Z",
"catching_up": false
}
```
The main thing to watch is that the block height is increasing. Once you are caught up with the chain, `catching_up` will become false. At that point, you can start using your node to create a validator. If you need to sync using a snapshot, please use https://kava.quicksync.io/
To check the logs of the node:
```bash
sudo journalctl -u kvd -f
```
## Creating a Validator
First, create a wallet, which will give you a private key / public key pair for your node.
```bash
# Replace <your-key-name> with a name for your key that you will remember
kvcli keys add <your-key-name>
# To see a list of wallets on your node
kvcli keys list
```
**Be sure to write down the mnemonic for your wallet and store it securely. Losing your mnemonic could result in the irrecoverable loss of KAVA tokens.**
To see the options when creating a validator:
```bash
kvcli tx staking create-validator -h
```
An example of creating a validator with 50KAVA self-delegation and 10% commission:
```bash
# Replace <key_name> with the key you created previously
kvcli tx staking create-validator \
--amount=50000000ukava \
--pubkey=$(kvd tendermint show-validator) \
--moniker="choose moniker" \
--website="optional website for your validator"
--details="optional details for your validator"
--commission-rate="0.10" \
--commission-max-rate="0.20" \
--commission-max-change-rate="0.01" \
--min-self-delegation="1" \
--from=<key_name> \
--chain-id=kava-8 \
--gas=auto
--gas-adjustment=1.4
```
To check on the status of your validator:
```bash
kvcli status --output json | jq '.validator_info'
```
After you have completed this guide, your validator should be up and ready to receive delegations. Note that only the top 100 validators by weighted stake (self-delegations + other delegations) are eligible for block rewards. To view the current validator list, checkout one of the Kava block explorers:
- https://www.mintscan.io/kava
- https://kava.bigdipper.live/
- https://kavascan.com/
If you have questions, please join the active conversation in the #validators thread of the [__Kava Discord Channel__](https://discord.com/invite/kQzh3Uv).