diff --git a/docs/kava-8/upgrade_oracle.md b/docs/kava-8/upgrade_oracle.md new file mode 100644 index 00000000..3d157c2e --- /dev/null +++ b/docs/kava-8/upgrade_oracle.md @@ -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 + diff --git a/docs/kava-8/upgrade_validator.md b/docs/kava-8/upgrade_validator.md new file mode 100644 index 00000000..7df859be --- /dev/null +++ b/docs/kava-8/upgrade_validator.md @@ -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). diff --git a/docs/kava-8/upgrade_wallet.md b/docs/kava-8/upgrade_wallet.md new file mode 100644 index 00000000..c1259cef --- /dev/null +++ b/docs/kava-8/upgrade_wallet.md @@ -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/). diff --git a/docs/readme.md b/docs/readme.md index 36b87d60..8127037f 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -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). diff --git a/docs/validator_guide.md b/docs/validator_guide.md new file mode 100644 index 00000000..548c2ca8 --- /dev/null +++ b/docs/validator_guide.md @@ -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 <> ~/.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 with the public name of your node +kvd init --chain-id kava-8 +# 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 `` 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= +ExecStart=/home//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 with a name for your key that you will remember +kvcli keys add +# 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 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= \ +--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).