Documentation
¶
Overview ¶
Package reward implements the Klaytn Reward System. The Klaytn reward system manages stakingInfo and distributes block rewards.
Managing stakingInfo ¶
Klaytn uses WeightedRandom policy to choose a block proposer. It means, the percentage of becoming a block proposer depends on how much KLAY a node has staked. Therefore, a node with stakes more than others will have more opportunities than other nodes.
StakingInfo is a data including stakingAmount and addresses (node, staking, reward, PoC and KIR). StakingAmount is a balance how much KLAY each node has staked. Only CCO can stake KLAY. Each CCO stakes KLAY by a smart contract called staking contract. StakingAmount is derived by checking balance of staking contract. StakingInfo has 5 types of addresses. All addresses are obtained by the addressBookContract which is pre-deployed in the genesis block. stakingAddress are addresses of staking contracts of CCO. reward, PoC and KIR addresses are the addresses which get a block reward when a block has been created. StakingInfo is made every 86400 blocks (stakingInterval) and used in a next interval.
type StakingInfo struct {
BlockNum uint64
CouncilNodeAddrs []common.Address // Address of Council
CouncilStakingAddrs []common.Address // Address of Staking contract which holds staking balance
CouncilRewardAddrs []common.Address // Address of Council account which will get a block reward
KIRAddr common.Address // Address of KIR contract
PoCAddr common.Address // Address of PoC contract
UseGini bool // configure whether Gini is used or not
Gini float64 // Gini coefficient
CouncilStakingAmounts []uint64 // StakingAmounts of Council. They are derived from Staking addresses of council
}
StakingInfo is managed by a StakingManager which has a cache for saving StakingInfos. The StakingManager calculates block number with interval to find a stakingInfo for current block and returns correct stakingInfo to use.
related struct - RewardDistributor - StakingManager - addressBookConnector - stakingInfoCache - stakingInfo
Distributing Reward ¶
Klaytn distributes the reward of a block to proposer, PoC and KIR. The detail information of PoC and KIR is available on Klaytn docs.
PoC - https://docs.klaytn.com/klaytn/token_economy#proof-of-contribution
KIR - https://docs.klaytn.com/klaytn/token_economy#klaytn-improvement-reserve
Configurations related to the reward system such as mintingAmount, ratio and unitPrice are determined by the Klaytn governance. All configurations are saved as rewardConfig on every epoch block (default 604,800 blocks) and managed by a rewardConfigCache.
A proposer which has made a current block will get the reward of the block. A block reward is calculated by following steps. First, calculate totalReward by adding mintingAmount and totalTxFee (unitPrice * gasUsed). Second, divide totalReward by ratio (default 34/54/12 - proposer/PoC/KIR). Last, distribute reward to each address (proposer, PoC, KIR).
related struct - RewardDistributor - rewardConfigCache
Index ¶
Constants ¶
const ( AddrNotFoundInCouncilNodes = -1 DefaultGiniCoefficient = -1.0 )
Variables ¶
var (
ErrAddrNotInStakingInfo = errors.New("Address is not in stakingInfo")
)
Functions ¶
func CalcGiniCoefficient ¶
func CalcGiniCoefficient(stakingAmount float64Slice) float64
Types ¶
type RewardDistributor ¶
type RewardDistributor struct {
// contains filtered or unexported fields
}
func NewRewardDistributor ¶
func NewRewardDistributor(gh governanceHelper) *RewardDistributor
func (*RewardDistributor) DistributeBlockReward ¶
func (rd *RewardDistributor) DistributeBlockReward(b BalanceAdder, header *types.Header, pocAddr common.Address, kirAddr common.Address) error
DistributeBlockReward distributes block reward to proposer, kirAddr and pocAddr.
func (*RewardDistributor) MintKLAY ¶
func (rd *RewardDistributor) MintKLAY(b BalanceAdder, header *types.Header) error
MintKLAY mints KLAY and gives the KLAY and the total transaction gas fee to the block proposer.
type StakingInfo ¶
type StakingInfo struct {
BlockNum uint64 // Block number where staking information of Council is fetched
// Information retrieved from AddressBook smart contract
CouncilNodeAddrs []common.Address // NodeIds of Council
CouncilStakingAddrs []common.Address // Address of Staking account which holds staking balance
CouncilRewardAddrs []common.Address // Address of Council account which will get block reward
KIRAddr common.Address // Address of KIR contract
PoCAddr common.Address // Address of PoC contract
UseGini bool
Gini float64 // gini coefficient
// Derived from CouncilStakingAddrs
CouncilStakingAmounts []uint64 // Staking amounts of Council
}
StakingInfo contains staking information.
func (*StakingInfo) GetIndexByNodeAddress ¶
func (s *StakingInfo) GetIndexByNodeAddress(nodeAddress common.Address) (int, error)
func (*StakingInfo) GetStakingAmountByNodeId ¶
func (s *StakingInfo) GetStakingAmountByNodeId(nodeAddress common.Address) (uint64, error)
func (*StakingInfo) String ¶ added in v1.2.0
func (s *StakingInfo) String() string
type StakingManager ¶
type StakingManager struct {
// contains filtered or unexported fields
}
func NewStakingManager ¶
func NewStakingManager(bc blockChain, gh governanceHelper) *StakingManager
func (*StakingManager) GetStakingInfo ¶
func (sm *StakingManager) GetStakingInfo(blockNum uint64) *StakingInfo
GetStakingInfo returns a corresponding stakingInfo for a blockNum.
func (*StakingManager) IsActivated ¶ added in v1.4.0
func (sm *StakingManager) IsActivated() bool
func (*StakingManager) Subscribe ¶
func (sm *StakingManager) Subscribe()
Subscribe setups a channel to listen chain head event and starts a goroutine to update staking cache.
func (*StakingManager) Unsubscribe ¶
func (sm *StakingManager) Unsubscribe()
Unsubscribe can unsubscribe a subscription to listen chain head event.
Source Files