github.com/klaytn/klaytn@v1.12.1/reward/doc.go (about)

     1  // Copyright 2019 The klaytn Authors
     2  // This file is part of the klaytn library.
     3  //
     4  // The klaytn library is free software: you can redistribute it and/or modify
     5  // it under the terms of the GNU Lesser General Public License as published by
     6  // the Free Software Foundation, either version 3 of the License, or
     7  // (at your option) any later version.
     8  //
     9  // The klaytn library is distributed in the hope that it will be useful,
    10  // but WITHOUT ANY WARRANTY; without even the implied warranty of
    11  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
    12  // GNU Lesser General Public License for more details.
    13  //
    14  // You should have received a copy of the GNU Lesser General Public License
    15  // along with the klaytn library. If not, see <http://www.gnu.org/licenses/>.
    16  
    17  /*
    18  Package reward implements the Klaytn Reward System.
    19  The Klaytn reward system manages stakingInfo and distributes block rewards.
    20  
    21  Managing stakingInfo
    22  
    23  Klaytn uses WeightedRandom policy to choose a block proposer.
    24  It means, the percentage of becoming a block proposer depends on how much KLAY a node has staked.
    25  Therefore, a node with stakes more than others will have more opportunities than other nodes.
    26  
    27  StakingInfo is a data including stakingAmount and addresses (node, staking, reward, KFF and KCF).
    28  StakingAmount is a balance how much KLAY each node has staked. Only CCO can stake KLAY.
    29  Each CCO stakes KLAY by a smart contract called staking contract.
    30  StakingAmount is derived by checking balance of staking contract.
    31  StakingInfo has 5 types of addresses. All addresses are obtained by the addressBookContract which is pre-deployed in the genesis block.
    32  stakingAddress are addresses of staking contracts of CCO. reward, KFF and KCF addresses are the addresses which get a block reward when a block has been created.
    33  StakingInfo is made every 86400 blocks (stakingInterval) and used in a next interval.
    34  
    35  	type StakingInfo struct {
    36  		BlockNum              uint64
    37  		CouncilNodeAddrs      []common.Address // Address of Council
    38  		CouncilStakingAddrs   []common.Address // Address of Staking contract which holds staking balance
    39  		CouncilRewardAddrs    []common.Address // Address of Council account which will get a block reward
    40  		KCFAddr               common.Address   // Address of KCF contract
    41  		KFFAddr               common.Address   // Address of KFF contract
    42  		UseGini               bool             // configure whether Gini is used or not
    43  		Gini                  float64          // Gini coefficient
    44  		CouncilStakingAmounts []uint64         // StakingAmounts of Council. They are derived from Staking addresses of council
    45  	}
    46  
    47  StakingInfo is managed by a StakingManager which has a cache for saving StakingInfos.
    48  The StakingManager calculates block number with interval to find a stakingInfo for current block
    49  and returns correct stakingInfo to use.
    50  
    51  
    52   related struct
    53   - RewardDistributor
    54   - StakingManager
    55   - addressBookConnector
    56   - stakingInfoCache
    57   - stakingInfo
    58  
    59  
    60  Distributing Reward
    61  
    62  Klaytn distributes the reward of a block to proposer, KFF and KCF.
    63  The detail information of KFF and KCF is available on Klaytn docs.
    64  
    65  Token Economy - https://docs.klaytn.foundation/content/klaytn/design/token-economy
    66  
    67  Configurations related to the reward system such as mintingAmount, ratio and unitPrice are determined by the Klaytn governance.
    68  All configurations are saved as rewardConfig on every epoch block (default 604,800 blocks) and managed by a rewardConfigCache.
    69  
    70  A proposer which has made a current block will get the reward of the block.
    71  A block reward is calculated by following steps.
    72  First, calculate totalReward by adding mintingAmount and totalTxFee (unitPrice * gasUsed).
    73  Second, divide totalReward by ratio (default 34/54/12 - proposer/KFF/KCF).
    74  Last, distribute reward to each address (proposer, KFF, KCF).
    75  
    76   related struct
    77   - RewardDistributor
    78   - rewardConfigCache
    79  */
    80  package reward