Version: v1.7.0 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Oct 19, 2021 License: GPL-3.0 Imports: 20 Imported by: 8



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 -


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



View Source
const (
	AddrNotFoundInCouncilNodes = -1

	DefaultGiniCoefficient = -1.0


View Source
var (

	// errors for staking manager
	ErrStakingManagerNotSet = errors.New("staking manager is not set")
	ErrChainHeadChanNotSet  = errors.New("chain head channel is not set")
View Source
var (
	ErrAddrNotInStakingInfo = errors.New("Address is not in stakingInfo")
View Source
var ErrStakingDBNotSet = errors.New("stakingInfoDB is not set")


func CalcGiniCoefficient

func CalcGiniCoefficient(stakingAmount float64Slice) float64

func CheckStakingInfoStored added in v1.5.0

func CheckStakingInfoStored(blockNum uint64) error

CheckStakingInfoStored makes sure the given staking info is stored in cache and DB

func SetTestStakingManager added in v1.7.0

func SetTestStakingManager(sm *StakingManager)

SetTestStakingManager sets the staking manager for testing purpose. Note that this method is used only for testing purpose.

func SetTestStakingManagerWithStakingInfoCache added in v1.7.0

func SetTestStakingManagerWithStakingInfoCache(testInfo *StakingInfo)

SetTestStakingManagerWithStakingInfoCache sets the staking manager with the given test staking information. Note that this method is used only for testing purpose.

func StakingManagerSubscribe added in v1.5.0

func StakingManagerSubscribe()

StakingManagerSubscribe setups a channel to listen chain head event and starts a goroutine to update staking cache.

func StakingManagerUnsubscribe added in v1.5.0

func StakingManagerUnsubscribe()

StakingManagerUnsubscribe can unsubscribe a subscription on chain head event.


type BalanceAdder

type BalanceAdder interface {
	AddBalance(addr common.Address, v *big.Int)

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 GetStakingInfo added in v1.5.0

func GetStakingInfo(blockNum uint64) *StakingInfo

GetStakingInfo returns a corresponding stakingInfo for a blockNum.

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 GetStakingManager added in v1.5.0

func GetStakingManager() *StakingManager

func NewStakingManager

func NewStakingManager(bc blockChain, gh governanceHelper, db stakingInfoDB) *StakingManager

NewStakingManager creates and returns StakingManager.

On the first call, a StakingManager is created with given parameters. From next calls, the existing StakingManager is returned. (Parameters from the next calls will not affect.)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL