Kratos distribution

# Kratos 激励系统

激励系统是kuchain链上进行激励管理的一套机制。kuchain的激励系统通过分配代币给验证者和出块者，从而鼓励积极参与链上活动。激励系统实现了一种在验证者和委托者之间分配奖励的功能。

这种分配奖励机制如下操作。所有的出块奖励在激励系统内汇总，并分配给验证者和委托人。每个验证者代替它的委托者收取的奖励和佣金。奖励直接发送到验证者奖励池中。

- 每当发生影响奖励分配率的参数更改时，会触发委托者领取奖励。
- 每当触发委托者领取奖励时，都必须领取获得的最大金额。
- 每当委托者创建委托抵押，解除委托抵押或重新委托抵押时，都必须完全领取奖励。
- 每当验证者选择更改奖励佣金时，必须同时领取所有累积的佣金奖励。

## 领取奖励

委托者领取奖励，首先要建立委托关系。一个委托者对验证者进行抵押一定数额的代币就建立了委托关系，详细介绍在验证者章节。从所有建立完成的委托关系中领取奖励，例如alice 投票给validator，这命令从validator 领取奖励

Example:
$ kucli tx kudistribution withdraw-rewards validator  Delegator --from jack
$ kucli tx kudistribution withdraw-rewards validator  Delegator --from jack --commission

Usage:
  kucli tx kudistribution withdraw-rewards [validator]  --from delegator [flags]

Flags:
  -a, --account-number uint      The account number of the signing account (offline mode only)
  -b, --broadcast-mode string    Transaction broadcasting mode (sync|async|block) (default "sync")
      --commission               also withdraw validator's commission
      --dry-run                  ignore the --gas flag and perform a simulation of a transaction, but don't broadcast it
      --fee-payer string         fee payer for tx
      --fees string              Fees to pay along with transaction; eg: 10uatom
      --from string              Name or address of private key with which to sign
      --gas string               gas limit to set per-transaction; set to "auto" to calculate required gas automatically (default 200000) (default "200000")
      --gas-adjustment float     adjustment factor to be multiplied against the estimate returned by the tx simulation; if the gas limit is set manually this flag is ignored  (default 1)
      --gas-prices string        Gas prices to determine the transaction fee (e.g. 10uatom)
      --generate-only            Build an unsigned transaction and write it to STDOUT (when enabled, the local Keybase is not accessible and the node operates offline)
  -h, --help                     help for withdraw-rewards
      --indent                   Add indent to JSON response
      --keyring-backend string   Select keyring's backend (os|file|test) (default "os")
      --ledger                   Use a connected Ledger device
      --memo string              Memo to send along with transaction
      --node string              <host>:<port> to tendermint rpc interface for this chain (default "tcp://localhost:26657")
  -s, --sequence uint            The sequence number of the signing account (offline mode only)
      --trust-node               Trust connected full node (don't verify proofs for responses) (default true)
  -y, --yes                      Skip tx broadcasting prompt confirmation

Global Flags:
      --chain-id string   Chain ID of tendermint node
  -e, --encoding string   Binary encoding (hex|b64|btc) (default "hex")
      --home string       directory for config and data (default "/root/.kucli")
  -o, --output string     Output format (text|json) (default "text")
      --trace             print out full stack trace on errors

常用参数说明：

- --commission 佣金一并领取
- --from 参数需要制定地址本身, 在生成事务数据时, 命令行假定并不和钱包与链通信, 所以需要输入原始数据.
- --home 和 --keyring-backend 对应的钱包不同, 在使用时, 可以先使用 keys list 命令查询对应的钱包中的key, 可以对应看是否是正确的钱包

- --chain-id 表示链 id, 这个对于一条链来说是常量, 如果 chain-id 不正确, 签名必然失败.
- flags 是一些额外的参数,文本提案有它需要的参数

例子：

先是准备，alice 投票给验证者账户validator：

./kucli tx kustaking delegate alice validator 800000000000000000000kuchain/sys --from alice --chain-id=testing --keyring-backend test

领取之前, 查询alice账户：

./kucli query asset coins  alice
- denom: kuchain/sys
  amount: "1199999999999999998000"
  
./kucli query asset coinpowers alice
[]

领取执行：

./kucli tx kudistribution withdraw-rewards validator alice --from alice --chain-id=testing --keyring-backend test	--commission

领取之后查询alice账户：

./kucli query asset coinpowers alice
- denom: kuchain/sys
  amount: "10678830653166400"

## 委托者领取所有奖励

委托者领取奖励，从所有建立完成的委托关系中领取奖励，例如alice 投票给validator1和validator2，这命令从validator1和validator2 领取奖励

Example:
$ kucli tx kudistribution withdraw-all-rewards  --from jack

Usage:
  kucli tx kudistribution withdraw-all-rewards [delegator] --from [delegator] [flags]

Flags:
  -a, --account-number uint      The account number of the signing account (offline mode only)
  -b, --broadcast-mode string    Transaction broadcasting mode (sync|async|block) (default "sync")
      --dry-run                  ignore the --gas flag and perform a simulation of a transaction, but don't broadcast it
      --fee-payer string         fee payer for tx
      --fees string              Fees to pay along with transaction; eg: 10uatom
      --from string              Name or address of private key with which to sign
      --gas string               gas limit to set per-transaction; set to "auto" to calculate required gas automatically (default 200000) (default "200000")
      --gas-adjustment float     adjustment factor to be multiplied against the estimate returned by the tx simulation; if the gas limit is set manually this flag is ignored  (default 1)
      --gas-prices string        Gas prices to determine the transaction fee (e.g. 10uatom)
      --generate-only            Build an unsigned transaction and write it to STDOUT (when enabled, the local Keybase is not accessible and the node operates offline)
  -h, --help                     help for withdraw-all-rewards
      --indent                   Add indent to JSON response
      --keyring-backend string   Select keyring's backend (os|file|test) (default "os")
      --ledger                   Use a connected Ledger device
      --max-msgs int             Limit the number of messages per tx (0 for unlimited) (default 5)
      --memo string              Memo to send along with transaction
      --node string              <host>:<port> to tendermint rpc interface for this chain (default "tcp://localhost:26657")
  -s, --sequence uint            The sequence number of the signing account (offline mode only)
      --trust-node               Trust connected full node (don't verify proofs for responses) (default true)
  -y, --yes                      Skip tx broadcasting prompt confirmation

Global Flags:
      --chain-id string   Chain ID of tendermint node
  -e, --encoding string   Binary encoding (hex|b64|btc) (default "hex")
      --home string       directory for config and data (default "/root/.kucli")
  -o, --output string     Output format (text|json) (default "text")
      --trace             print out full stack trace on errors
      

例子：

准备环境，创建多个节点，使得环境有多个验证者。

 ./kucli tx kustaking create-validator jack  --pubkey=$(./kucd tendermint show-validator --home "./slave")   --moniker="create new node"   --from=jack   --commission-rate="0.40"    --chain-id=testing --keyring-backend test
 
 ./kucli tx kustaking delegate alice validator 800000000000000000000kuchain/sys --from alice --chain-id=testing --keyring-backend test
 
 ./kucli tx kustaking delegate alice jack 800000000000000000000kuchain/sys --from alice --chain-id=testing --keyring-backend test
 

!!! warning "注意"

--pubkey=$(./kucd tendermint show-validator --home "./slave" ， --home 路径是新节点路径

查询验证环境，当前环境中有两个验证人账户，分别是 validaor和jack

./kucli query kustaking validators
- operator_account: jack
  consensus_pubkey: kuchainvalconspub1zcjduepqnxrr955j0yra8al0knhfpzg9xamyrdnuraz5t099qwgsp22vf2jqh8vd0x
  jailed: false
  status: 3
  tokens: "800000000000000000000"
  delegator_shares: "800000000000000000000.000000000000000000"
  description:
    moniker: create new node
    identity: ""
    website: ""
    security_contact: ""
    details: ""
  unbonding_height: 0
  unbonding_time: 1970-01-01T00:00:00Z
  commission:
    commission_rates:
      rate: "0.400000000000000000"
      max_rate: "1.000000000000000000"
      max_change_rate: "1.000000000000000000"
    update_time: 2020-08-12T05:42:42.507884859Z
  min_self_delegation: "1"
- operator_account: validator
  consensus_pubkey: kuchainvalconspub1zcjduepqu62j0eud0sllvwfe9h4t3knnzl334ntz9kq38h46lzafm4qgqdrqjmguk4
  jailed: false
  status: 3
  tokens: "100000000000000000000"
  delegator_shares: "100000000000000000000.000000000000000000"
  description:
    moniker: testing
    identity: ""
    website: ""
    security_contact: ""
    details: ""
  unbonding_height: 0
  unbonding_time: 1970-01-01T00:00:00Z
  commission:
    commission_rates:
      rate: "0.100000000000000000"
      max_rate: "1.000000000000000000"
      max_change_rate: "1.000000000000000000"
    update_time: 2020-08-12T05:41:39.22248249Z
  min_self_delegation: "1"

领取之前，alice 账户状态：

 ./kucli query asset coins  alice
- denom: kuchain/sys
  amount: "1199999999999999998000"

./kucli query asset coinpowers alice
[]

触发领取:

./kucli tx kudistribution withdraw-all-rewards alice --from alice  --chain-id=testing --keyring-backend test

领取之后，alice 账户状态：

./kucli query asset coins  alice

- denom: kuchain/sys
	amount: "1199999999999999998000"

./kucli query asset coinpowers alice

- denom: kuchain/sys
	amount: "885936749122400"

## 设置领取奖励账户

一个委托者投票抵押给一个验证者，建立了委托收益关系。当委托者触发领取出块奖励时，系统会转账到委托账户。委托者可以设置接收奖励的账户，当委托者触发领取出块奖励时，激励系统会把奖励转账到这个设置账户

Example:
$ kucli tx kudistribution set-withdraw withdrawacc  account --from account

Usage:
  kucli tx kudistribution set-withdraw [withdrawAccount] --from account [flags]

Flags:
  -a, --account-number uint      The account number of the signing account (offline mode only)
  -b, --broadcast-mode string    Transaction broadcasting mode (sync|async|block) (default "sync")
      --dry-run                  ignore the --gas flag and perform a simulation of a transaction, but don't broadcast it
      --fee-payer string         fee payer for tx
      --fees string              Fees to pay along with transaction; eg: 10uatom
      --from string              Name or address of private key with which to sign
      --gas string               gas limit to set per-transaction; set to "auto" to calculate required gas automatically (default 200000) (default "200000")
      --gas-adjustment float     adjustment factor to be multiplied against the estimate returned by the tx simulation; if the gas limit is set manually this flag is ignored  (default 1)
      --gas-prices string        Gas prices to determine the transaction fee (e.g. 10uatom)
      --generate-only            Build an unsigned transaction and write it to STDOUT (when enabled, the local Keybase is not accessible and the node operates offline)
  -h, --help                     help for set-withdraw
      --indent                   Add indent to JSON response
      --keyring-backend string   Select keyring's backend (os|file|test) (default "os")
      --ledger                   Use a connected Ledger device
      --memo string              Memo to send along with transaction
      --node string              <host>:<port> to tendermint rpc interface for this chain (default "tcp://localhost:26657")
  -s, --sequence uint            The sequence number of the signing account (offline mode only)
      --trust-node               Trust connected full node (don't verify proofs for responses) (default true)
  -y, --yes                      Skip tx broadcasting prompt confirmation

Global Flags:
      --chain-id string   Chain ID of tendermint node
  -e, --encoding string   Binary encoding (hex|b64|btc) (default "hex")
      --home string       directory for config and data (default "/root/.kucli")
  -o, --output string     Output format (text|json) (default "text")
      --trace             print out full stack trace on errors

例子：

准备环境设置委托关系，alice 投票给validator账户，查询alice 账户状态如下

./kucli tx kustaking delegate alice validator 800000000000000000000kuchain/sys --from alice --chain-id=testing --keyring-backend test

./kucli query asset coins test1
- denom: kuchain/sys
amount: "2000000000000000000000"

./kucli query asset coinpowers test1
[]

./kucli query asset coins alice
- denom: kuchain/sys
amount: "1199999999999999998000"

./kucli query asset coinpowers alice
[]

触发设置新的领取账户

./kucli tx kudistribution set-withdraw test1  alice --from alice  --chain-id=testing --keyring-backend test

触发领取

./kucli tx kudistribution withdraw-rewards validator alice --from alice --chain-id=testing --keyring-backend test

领取之后，查询alice 账户状态

./kucli query asset coinpowers test1
- denom: kuchain/sys
  amount: "1609862043449600"
./kucli query asset coinpowers alice
[]

./kucli query asset coins  test1
- denom: kuchain/sys
  amount: "2000000000000000000000"
./kucli query asset coins  alice
- denom: kuchain/sys
  amount: "1199999999999999994000"

## 查询分配系统参数

查询分配系统计算奖励的部分参数

Usage:
  kucli query kudistribution params [flags]

Flags:
      --height int    Use a specific height to query state at (this can error if the node is pruning state)
  -h, --help          help for params
      --indent        Add indent to JSON response
      --ledger        Use a connected Ledger device
      --node string   <host>:<port> to Tendermint RPC interface for this chain (default "tcp://localhost:26657")
      --trust-node    Trust connected full node (don't verify proofs for responses)

Global Flags:
      --chain-id string   Chain ID of tendermint node
  -e, --encoding string   Binary encoding (hex|b64|btc) (default "hex")
      --home string       directory for config and data (default "/root/.kucli")
  -o, --output string     Output format (text|json) (default "text")
      --trace             print out full stack trace on errors

查询：

./kucli query kudistribution params
community_tax: "0.020000000000000000"
base_proposer_reward: "0.010000000000000000"
bonus_proposer_reward: "0.040000000000000000"
withdraw_addr_enabled: true

- community_tax：佣金比率
- base_proposer_reward：基础出块奖励比率
- bonus_proposer_reward：绑定出块奖励比率

## 查询验证者未提取奖励

查询验证者及其代表的所有委托者未提取奖励。分配系统会把一个验证者的收益分配给验证者，这收益包含了这个验证者的所有未领取的收益。

Example:
$ kucli query kudistribution validator-outstanding-rewards validatorName

Usage:
  kucli query kudistribution validator-outstanding-rewards [validator] [flags]

Flags:
      --height int    Use a specific height to query state at (this can error if the node is pruning state)
  -h, --help          help for validator-outstanding-rewards
      --indent        Add indent to JSON response
      --ledger        Use a connected Ledger device
      --node string   <host>:<port> to Tendermint RPC interface for this chain (default "tcp://localhost:26657")
      --trust-node    Trust connected full node (don't verify proofs for responses)

Global Flags:
      --chain-id string   Chain ID of tendermint node
  -e, --encoding string   Binary encoding (hex|b64|btc) (default "hex")
      --home string       directory for config and data (default "/root/.kucli")
  -o, --output string     Output format (text|json) (default "text")
      --trace             print out full stack trace on errors

- validator：验证者账户
- flags：其他参数

查询执行前：

./kucli query kudistribution validator-outstanding-rewards validator
rewards:
- denom: kuchain/sys
  amount: "6640698428332862.400000000000000000"

委托者领取：

./kucli tx kudistribution withdraw-rewards validator alice --from alice --chain-id=testing --keyring-backend test

委托者领取后，查询后，alice领取了他的收益：

./kucli query kudistribution validator-outstanding-rewards validator
rewards:
- denom: kuchain/sys
  amount: "3206312390075289.140000000000000000"

## 查询验证人的佣金收益

查询验证者佣金从委托者到该验证者的奖励。

Example:
$ kucli query kudistribution commission validatorName

Usage:
  kucli query kudistribution commission [validator] [flags]

Flags:
      --height int    Use a specific height to query state at (this can error if the node is pruning state)
  -h, --help          help for commission
      --indent        Add indent to JSON response
      --ledger        Use a connected Ledger device
      --node string   <host>:<port> to Tendermint RPC interface for this chain (default "tcp://localhost:26657")
      --trust-node    Trust connected full node (don't verify proofs for responses)

Global Flags:
      --chain-id string   Chain ID of tendermint node
  -e, --encoding string   Binary encoding (hex|b64|btc) (default "hex")
      --home string       directory for config and data (default "/root/.kucli")
  -o, --output string     Output format (text|json) (default "text")
      --trace             print out full stack trace on errors

- validator： 验证者账户
- flags：其他参数

例子，查询验证人账户validator的佣金累计收益：

./kucli query kudistribution commission validator
commission:
- denom: kuchain/sys
  amount: "1066537555116439.476000000000000000"

## 查询削减（slashes）

查询给定块范围的验证器的所有削减。如果验证人，参与验证过程有失误，验证者收益将会受到削减

Example:
$ kucli query kudistribution slashes validatorName 0 100

Usage:
  kucli query kudistribution slashes [validator] [start-height] [end-height] [flags]

Flags:
      --height int    Use a specific height to query state at (this can error if the node is pruning state)
  -h, --help          help for slashes
      --indent        Add indent to JSON response
      --ledger        Use a connected Ledger device
      --node string   <host>:<port> to Tendermint RPC interface for this chain (default "tcp://localhost:26657")
      --trust-node    Trust connected full node (don't verify proofs for responses)

Global Flags:
      --chain-id string   Chain ID of tendermint node
  -e, --encoding string   Binary encoding (hex|b64|btc) (default "hex")
      --home string       directory for config and data (default "/root/.kucli")
  -o, --output string     Output format (text|json) (default "text")
      --trace             print out full stack trace on errors

- validator： 验证者账户
- start-height ：起始出块高度
- end-height：结束出块高度
- flags：其他参数

查询显示，验证人账户在0-100区块之间的收益没有受到削减

./kucli query kudistribution slashes validator 0 100
validator_slash_events: []

## 查询收益奖励

查询委托者的全部收益奖励或对一个委托关系收益奖励

Example:
$ kucli query kudistribution rewards jack
$ kucli query kudistribution rewards jack validatorName

Usage:
  kucli query kudistribution rewards [delegator] [<validator>] [flags]

Flags:
      --height int    Use a specific height to query state at (this can error if the node is pruning state)
  -h, --help          help for rewards
      --indent        Add indent to JSON response
      --ledger        Use a connected Ledger device
      --node string   <host>:<port> to Tendermint RPC interface for this chain (default "tcp://localhost:26657")
      --trust-node    Trust connected full node (don't verify proofs for responses)

Global Flags:
      --chain-id string   Chain ID of tendermint node
  -e, --encoding string   Binary encoding (hex|b64|btc) (default "hex")
      --home string       directory for config and data (default "/root/.kucli")
  -o, --output string     Output format (text|json) (default "text")
      --trace             print out full stack trace on errors

- delegator： 委托者账户
- validator： 验证者账户
- flags：其他参数

例子：

建立委托，alice 投票给validator 和jack

./kucli tx kustaking delegate alice validator 800000000000000000000kuchain/sys --from alice --chain-id=testing --keyring-backend test
./kucli tx kustaking delegate alice jack 800000000000000000000kuchain/sys --from alice --chain-id=testing --keyring-backend test

查询alice 账户所有奖励

./kucli query kudistribution rewards alice
rewards:
- validator_account: jack
  reward:
  - denom: kuchain/sys
    amount: "35946433164800.000000000000000000"
- validator_account: validator
  reward:
  - denom: kuchain/sys
    amount: "274043189720000.000000000000000000"
total:
- denom: kuchain/sys
  amount: "309989622884800.000000000000000000"

./kucli query kudistribution rewards alice jack
- denom: kuchain/sys
  amount: "35946433164800.000000000000000000"

领取对验证者账户validator的收益奖励

./kucli tx kudistribution withdraw-rewards validator alice --from alice --chain-id=testing --keyring-backend test

立即查询，对验证者账户validator的收益奖励已经为空：

 validator_account: jack
  reward:
  - denom: kuchain/sys
    amount: "2213758843697600.000000000000000000"
- validator_account: validator
  reward: []
total:
- denom: kuchain/sys
  amount: "2213758843697600.000000000000000000"

## 查询领取账户

查询领取收益的账户，分配系统支持设置领取收益的账户。委托账户和接收奖励账户可以不一样

Example:
$ kucli query kudistribution whithdraw-addr jack --from jack

Usage:
  kucli query kudistribution whithdraw-addr [flags]

Flags:
      --height int    Use a specific height to query state at (this can error if the node is pruning state)
  -h, --help          help for whithdraw-addr
      --indent        Add indent to JSON response
      --ledger        Use a connected Ledger device
      --node string   <host>:<port> to Tendermint RPC interface for this chain (default "tcp://localhost:26657")
      --trust-node    Trust connected full node (don't verify proofs for responses)

Global Flags:
      --chain-id string   Chain ID of tendermint node
  -e, --encoding string   Binary encoding (hex|b64|btc) (default "hex")
      --home string       directory for config and data (default "/root/.kucli")
  -o, --output string     Output format (text|json) (default "text")
      --trace             print out full stack trace on errors

例子：

查询alice领取账户：

./kucli query kudistribution   whithdraw-addr   alice
|-
  withdraw info:
  WithDrawAddress:alice ,DelegatorAddress:alice

设置test1为alice领取收益奖励的账户

./kucli tx kudistribution set-withdraw test1  alice --from alice  --chain-id=testing --keyring-backend test

查询alice领取账户：

./kucli query kudistribution   whithdraw-addr   alice
|-
  withdraw info:
  WithDrawAddress:test1 ,DelegatorAddress:alice