governance

package
v1.7.3 Latest Latest
Warning

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

 Go to latest Published: Dec 27, 2021 License: GPL-3.0 Imports: 21 Imported by: 26

Documentation

Overview

Package governance contains functions and variables used for voting and reflecting vote results in Klaytn. In Klaytn, various settings such as the amount of KLAY minted as a block reward can be changed by using governance vote. These votes can be casted by nodes of Governance Council and detailed introduction can be found at https://docs.klaytn.com/klaytn/design/governance

How to cast a vote

To cast a vote, a node have to be a member of the Governance Council. If the governance mode is "single", only one designated node (the governing node) can vote. In the console of the node, "governance.vote(key, value)" API can be used to cast a vote.

Keys for the voting API

Following keys can be handled as of 7/20/2019.

  • "governance.governancemode" : To change the governance mode
  • "governance.governingnode" : To change the governing node if the governance mode is "single"
  • "governance.unitprice" : To change the unitprice of Klaytn (Unit price is same as gasprice in Ethereum)
  • "governance.addvalidator" : To add new node as a council node
  • "governance.removevalidator" : To remove a node from the governance council
  • "istanbul.epoch" : To change Epoch, the period to gather votes
  • "istanbul.committeesize" : To change the size of the committee
  • "reward.mintingamount" : To change the amount of block generation reward
  • "reward.ratio" : To change the ratio used to distribute the reward between block proposer node, PoC and KIR
  • "reward.useginicoeff" : To change the application of gini coefficient to reduce gap between CCOs
  • "reward.deferredtxfee" : To change the way of distributing tx fee
  • "reward.minimumstake" : To change the minimum amount of stake to participate in the governance council

How governance works

Governance package contains a governance struct which stores current system configurations and voting status. If a vote passed, the governance struct is updated to provide new information to related packages and users. The API documentation can be found at https://docs.klaytn.com/bapp/json-rpc/api-references/governance

When a CN (consensus node which is managed by CCO) proposes a block, it writes its vote on the block header and other nodes parse the header and handle it. This process is handled by snapshot.go in the consensus engine and processed by functions in handler.go

If a vote satisfies the requirement (more than 50% of votes in favor of), it will update the governance struct and many other packages like "reward", "txpool" and so on will reference it.

Source Files

Governance related functions and variables are defined in the files listed below

  • default.go : the governance struct, cache and persistence
  • handler.go : functions to handle votes and its application
  • api.go : console APIs to get governance information and to cast a vote

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrValueTypeMismatch  = errors.New("Value's type mismatch")
	ErrDecodeGovChange    = errors.New("Failed to decode received governance changes")
	ErrUnmarshalGovChange = errors.New("Failed to unmarshal received governance changes")
	ErrVoteValueMismatch  = errors.New("Received change mismatches with the value this node has!!")
	ErrNotInitialized     = errors.New("Cache not initialized")
	ErrItemNotFound       = errors.New("Failed to find governance item")
	ErrItemNil            = errors.New("Governance Item is nil")
	ErrUnknownKey         = errors.New("Governnace value of the given key not found")
)
View Source 
var (
	GovernanceKeyMap = map[string]int{
		"governance.governancemode":     params.GovernanceMode,
		"governance.governingnode":      params.GoverningNode,
		"istanbul.epoch":                params.Epoch,
		"istanbul.policy":               params.Policy,
		"istanbul.committeesize":        params.CommitteeSize,
		"governance.unitprice":          params.UnitPrice,
		"reward.mintingamount":          params.MintingAmount,
		"reward.ratio":                  params.Ratio,
		"reward.useginicoeff":           params.UseGiniCoeff,
		"reward.deferredtxfee":          params.DeferredTxFee,
		"reward.minimumstake":           params.MinimumStake,
		"reward.stakingupdateinterval":  params.StakeUpdateInterval,
		"reward.proposerupdateinterval": params.ProposerRefreshInterval,
		"governance.addvalidator":       params.AddValidator,
		"governance.removevalidator":    params.RemoveValidator,
		"param.txgashumanreadable":      params.ConstTxGasHumanReadable,
		"istanbul.timeout":              params.Timeout,
	}

	GovernanceForbiddenKeyMap = map[string]int{
		"istanbul.policy":               params.Policy,
		"reward.stakingupdateinterval":  params.StakeUpdateInterval,
		"reward.proposerupdateinterval": params.ProposerRefreshInterval,
	}

	GovernanceKeyMapReverse = map[int]string{
		params.GovernanceMode:          "governance.governancemode",
		params.GoverningNode:           "governance.governingnode",
		params.Epoch:                   "istanbul.epoch",
		params.CliqueEpoch:             "clique.epoch",
		params.Policy:                  "istanbul.policy",
		params.CommitteeSize:           "istanbul.committeesize",
		params.UnitPrice:               "governance.unitprice",
		params.MintingAmount:           "reward.mintingamount",
		params.Ratio:                   "reward.ratio",
		params.UseGiniCoeff:            "reward.useginicoeff",
		params.DeferredTxFee:           "reward.deferredtxfee",
		params.MinimumStake:            "reward.minimumstake",
		params.StakeUpdateInterval:     "reward.stakingupdateinterval",
		params.ProposerRefreshInterval: "reward.proposerupdateinterval",
		params.AddValidator:            "governance.addvalidator",
		params.RemoveValidator:         "governance.removevalidator",
		params.ConstTxGasHumanReadable: "param.txgashumanreadable",
		params.Timeout:                 "istanbul.timeout",
	}

	ProposerPolicyMap = map[string]int{
		"roundrobin":     params.RoundRobin,
		"sticky":         params.Sticky,
		"weightedrandom": params.WeightedRandom,
	}

	ProposerPolicyMapReverse = map[int]string{
		params.RoundRobin:     "roundrobin",
		params.Sticky:         "sticky",
		params.WeightedRandom: "weightedrandom",
	}

	GovernanceModeMap = map[string]int{
		"none":   params.GovernanceMode_None,
		"single": params.GovernanceMode_Single,
		"ballot": params.GovernanceMode_Ballot,
	}
)
View Source 
var GovernanceItems = map[int]check{
	params.GovernanceMode:          {stringT, checkGovernanceMode, nil},
	params.GoverningNode:           {addressT, checkAddress, nil},
	params.UnitPrice:               {uint64T, checkUint64andBool, updateUnitPrice},
	params.AddValidator:            {addressT, checkAddress, nil},
	params.RemoveValidator:         {addressT, checkAddress, nil},
	params.MintingAmount:           {stringT, checkBigInt, nil},
	params.Ratio:                   {stringT, checkRatio, nil},
	params.UseGiniCoeff:            {boolT, checkUint64andBool, updateUseGiniCoeff},
	params.DeferredTxFee:           {boolT, checkUint64andBool, nil},
	params.MinimumStake:            {stringT, checkBigInt, nil},
	params.StakeUpdateInterval:     {uint64T, checkUint64andBool, updateStakingUpdateInterval},
	params.ProposerRefreshInterval: {uint64T, checkUint64andBool, updateProposerUpdateInterval},
	params.Epoch:                   {uint64T, checkUint64andBool, nil},
	params.Policy:                  {uint64T, checkUint64andBool, updateProposerPolicy},
	params.CommitteeSize:           {uint64T, checkUint64andBool, nil},
	params.ConstTxGasHumanReadable: {uint64T, checkUint64andBool, updateTxGasHumanReadable},
	params.Timeout:                 {uint64T, checkUint64andBool, nil},
}

Functions

func AddGovernanceCacheForTest 

func AddGovernanceCacheForTest(g *Governance, num uint64, config *params.ChainConfig)

func CalcGovernanceInfoBlock 

func CalcGovernanceInfoBlock(num uint64, epoch uint64) uint64

func CheckGenesisValues 

func CheckGenesisValues(c *params.ChainConfig) error

Types

type Governance 

type Governance struct {
	ChainConfig *params.ChainConfig

	GovernanceVotes   GovernanceVotes
	GovernanceTallies GovernanceTallyList

	TxPool txPool
	// contains filtered or unexported fields
}

func NewGovernance 

func NewGovernance(chainConfig *params.ChainConfig, dbm database.DBManager) *Governance

NewGovernance creates Governance with the given configuration.

func NewGovernanceInitialize added in v1.6.0 

func NewGovernanceInitialize(chainConfig *params.ChainConfig, dbm database.DBManager) *Governance

NewGovernanceInitialize creates Governance with the given configuration and read governance state from DB. If any items are not stored in DB, it stores governance items of the genesis block to DB.

func (*Governance) AddVote 

func (g *Governance) AddVote(key string, val interface{}) bool

AddVote adds a vote to the voteMap

func (*Governance) CanWriteGovernanceState 

func (gov *Governance) CanWriteGovernanceState(num uint64) bool

func (*Governance) ChainId added in v1.1.0 

func (gov *Governance) ChainId() uint64

func (*Governance) ClearVotes 

func (g *Governance) ClearVotes(num uint64)

func (*Governance) CommitteeSize added in v1.1.0 

func (gov *Governance) CommitteeSize() uint64

func (*Governance) DeferredTxFee added in v1.1.0 

func (gov *Governance) DeferredTxFee() bool

func (*Governance) Epoch added in v1.1.0 

func (gov *Governance) Epoch() uint64

func (*Governance) GetEncodedVote 

func (g *Governance) GetEncodedVote(addr common.Address, number uint64) []byte

func (*Governance) GetGovernanceChange 

func (g *Governance) GetGovernanceChange() map[string]interface{}

func (*Governance) GetGovernanceItemAtNumber 

func (gov *Governance) GetGovernanceItemAtNumber(num uint64, key string) (interface{}, error)

func (*Governance) GetGovernanceValue 

func (gov *Governance) GetGovernanceValue(key int) interface{}

func (*Governance) GetGoverningInfoAtNumber added in v1.7.0 

func (gov *Governance) GetGoverningInfoAtNumber(num uint64) (bool, common.Address, error)

GetGoverningInfoAtNumber returns whether the governing mode is single or not and the governing node.

func (*Governance) GetItemAtNumberByIntKey added in v1.1.0 

func (gov *Governance) GetItemAtNumberByIntKey(num uint64, key int) (interface{}, error)

func (*Governance) GetMinimumStakingAtNumber added in v1.7.0 

func (gov *Governance) GetMinimumStakingAtNumber(num uint64) (uint64, error)

func (*Governance) GovernanceMode added in v1.1.0 

func (gov *Governance) GovernanceMode() string

func (*Governance) GoverningNode added in v1.1.0 

func (gov *Governance) GoverningNode() common.Address

func (*Governance) HandleGovernanceVote 

func (gov *Governance) HandleGovernanceVote(valset istanbul.ValidatorSet, votes []GovernanceVote, tally []GovernanceTallyItem, header *types.Header, proposer common.Address, self common.Address) (istanbul.ValidatorSet, []GovernanceVote, []GovernanceTallyItem)

func (*Governance) IdxCache added in v1.1.0 

func (gov *Governance) IdxCache() []uint64

func (*Governance) IdxCacheFromDb added in v1.1.0 

func (gov *Governance) IdxCacheFromDb() []uint64

func (*Governance) MinimumStake added in v1.1.0 

func (gov *Governance) MinimumStake() string

func (*Governance) MintingAmount added in v1.1.0 

func (gov *Governance) MintingAmount() string

func (*Governance) ParseVoteValue 

func (g *Governance) ParseVoteValue(gVote *GovernanceVote) (*GovernanceVote, error)

parseVoteValue parse vote.Value from []uint8 to appropriate type

func (*Governance) PendingChanges added in v1.1.0 

func (gov *Governance) PendingChanges() map[string]interface{}

func (*Governance) ProposerPolicy added in v1.1.0 

func (gov *Governance) ProposerPolicy() uint64

func (*Governance) ProposerUpdateInterval added in v1.1.0 

func (gov *Governance) ProposerUpdateInterval() uint64

func (*Governance) Ratio added in v1.1.0 

func (gov *Governance) Ratio() string

func (*Governance) ReadGovernance 

func (g *Governance) ReadGovernance(num uint64) (uint64, map[string]interface{}, error)

func (*Governance) ReadGovernanceState 

func (gov *Governance) ReadGovernanceState()

ReadGovernanceState reads field values of the Governance struct from database. It also updates params.stakingUpdateInterval and params.proposerUpdateInterval with the retrieved value.

func (*Governance) ReflectVotes 

func (gov *Governance) ReflectVotes(vote GovernanceVote)

func (*Governance) RemoveVote 

func (g *Governance) RemoveVote(key string, value interface{}, number uint64)

RemoveVote remove a vote from the voteMap to prevent repetitive addition of same vote

func (*Governance) SetBlockchain 

func (gov *Governance) SetBlockchain(bc blockChain)

func (*Governance) SetMyVotingPower 

func (g *Governance) SetMyVotingPower(t uint64)

func (*Governance) SetNodeAddress 

func (g *Governance) SetNodeAddress(addr common.Address)

func (*Governance) SetTotalVotingPower 

func (g *Governance) SetTotalVotingPower(t uint64)

func (*Governance) SetTxPool 

func (gov *Governance) SetTxPool(txpool txPool)

func (*Governance) StakingUpdateInterval added in v1.1.0 

func (gov *Governance) StakingUpdateInterval() uint64

func (*Governance) UnitPrice added in v1.1.0 

func (gov *Governance) UnitPrice() uint64

func (*Governance) UnmarshalJSON 

func (gov *Governance) UnmarshalJSON(b []byte) error

func (*Governance) UpdateCurrentSet added in v1.7.0 

func (gov *Governance) UpdateCurrentSet(num uint64)

func (*Governance) UseGiniCoeff added in v1.1.0 

func (gov *Governance) UseGiniCoeff() bool

func (*Governance) ValidateVote 

func (gov *Governance) ValidateVote(vote *GovernanceVote) (*GovernanceVote, bool)

func (*Governance) VerifyGovernance 

func (gov *Governance) VerifyGovernance(received []byte) error

func (*Governance) Votes added in v1.1.0 

func (gov *Governance) Votes() []GovernanceVote

func (*Governance) WriteGovernance 

func (g *Governance) WriteGovernance(num uint64, data GovernanceSet, delta GovernanceSet) error

Store new governance data on DB. This updates Governance cache too.

func (*Governance) WriteGovernanceForNextEpoch added in v1.7.0 

func (gov *Governance) WriteGovernanceForNextEpoch(number uint64, governance []byte)

WriteGovernanceForNextEpoch creates governance items for next epoch and writes them to the database. The governance items on next epoch will be the given `governance` items applied on the top of past epoch items.

func (*Governance) WriteGovernanceState 

func (gov *Governance) WriteGovernanceState(num uint64, isCheckpoint bool) error

type GovernanceKlayAPI 

type GovernanceKlayAPI struct {
	// contains filtered or unexported fields
}

func NewGovernanceKlayAPI 

func NewGovernanceKlayAPI(gov *Governance, chain blockChain) *GovernanceKlayAPI

func (*GovernanceKlayAPI) GasPrice 

func (api *GovernanceKlayAPI) GasPrice() *hexutil.Big

func (*GovernanceKlayAPI) GasPriceAt 

func (api *GovernanceKlayAPI) GasPriceAt(num *rpc.BlockNumber) (*hexutil.Big, error)

TODO-Klaytn-Governance: Refine this API and consider the gas price of txpool

func (*GovernanceKlayAPI) GasPriceAtNumber 

func (api *GovernanceKlayAPI) GasPriceAtNumber(num int64) (uint64, error)

type GovernanceSet 

type GovernanceSet struct {
	// contains filtered or unexported fields
}

Governance item set

func GetGovernanceItemsFromChainConfig added in v1.6.0 

func GetGovernanceItemsFromChainConfig(config *params.ChainConfig) GovernanceSet

func NewGovernanceSet added in v1.1.0 

func NewGovernanceSet() GovernanceSet

func (*GovernanceSet) Clear added in v1.1.0 

func (gs *GovernanceSet) Clear()

func (*GovernanceSet) GetValue added in v1.1.0 

func (gs *GovernanceSet) GetValue(key int) (interface{}, bool)

func (*GovernanceSet) Import added in v1.1.0 

func (gs *GovernanceSet) Import(src map[string]interface{})

func (*GovernanceSet) Items added in v1.1.0 

func (gs *GovernanceSet) Items() map[string]interface{}

func (*GovernanceSet) Merge added in v1.1.0 

func (gs *GovernanceSet) Merge(change map[string]interface{})

func (*GovernanceSet) RemoveItem added in v1.1.0 

func (gs *GovernanceSet) RemoveItem(key string)

func (*GovernanceSet) SetValue 

func (gs *GovernanceSet) SetValue(itemType int, value interface{}) error

func (*GovernanceSet) Size added in v1.1.0 

func (gs *GovernanceSet) Size() int

type GovernanceTallyItem added in v1.1.0 

type GovernanceTallyItem struct {
	Key   string      `json:"key"`
	Value interface{} `json:"value"`
	Votes uint64      `json:"votes"`
}

GovernanceTallies represents a tally for each governance item

type GovernanceTallyList added in v1.1.0 

type GovernanceTallyList struct {
	// contains filtered or unexported fields
}

func NewGovernanceTallies added in v1.1.0 

func NewGovernanceTallies() GovernanceTallyList

func (*GovernanceTallyList) Clear added in v1.1.0 

func (gt *GovernanceTallyList) Clear()

func (*GovernanceTallyList) Copy added in v1.1.0 

func (gt *GovernanceTallyList) Copy() []GovernanceTallyItem

func (*GovernanceTallyList) Import added in v1.1.0 

func (gt *GovernanceTallyList) Import(src []GovernanceTallyItem)

type GovernanceVote 

type GovernanceVote struct {
	Validator common.Address `json:"validator"`
	Key       string         `json:"key"`
	Value     interface{}    `json:"value"`
}

Governance represents vote information given from istanbul.vote()

type GovernanceVotes added in v1.1.0 

type GovernanceVotes struct {
	// contains filtered or unexported fields
}

func NewGovernanceVotes added in v1.1.0 

func NewGovernanceVotes() GovernanceVotes

func (*GovernanceVotes) Clear added in v1.1.0 

func (gv *GovernanceVotes) Clear()

func (*GovernanceVotes) Copy added in v1.1.0 

func (gv *GovernanceVotes) Copy() []GovernanceVote

func (*GovernanceVotes) Import added in v1.1.0 

func (gv *GovernanceVotes) Import(src []GovernanceVote)

type PublicGovernanceAPI 

type PublicGovernanceAPI struct {
	// contains filtered or unexported fields
}

func NewGovernanceAPI 

func NewGovernanceAPI(gov *Governance) *PublicGovernanceAPI

func (*PublicGovernanceAPI) ChainConfig 

func (api *PublicGovernanceAPI) ChainConfig() *params.ChainConfig

func (*PublicGovernanceAPI) GetStakingInfo added in v1.6.1 

func (api *PublicGovernanceAPI) GetStakingInfo(num *rpc.BlockNumber) (*reward.StakingInfo, error)

func (*PublicGovernanceAPI) IdxCache added in v1.1.0 

func (api *PublicGovernanceAPI) IdxCache() []uint64

func (*PublicGovernanceAPI) IdxCacheFromDb added in v1.1.0 

func (api *PublicGovernanceAPI) IdxCacheFromDb() []uint64

func (*PublicGovernanceAPI) ItemCacheFromDb added in v1.1.0 

func (api *PublicGovernanceAPI) ItemCacheFromDb(num *rpc.BlockNumber) map[string]interface{}

TODO-Klaytn: Return error if invalid input is given such as pending or a too big number

func (*PublicGovernanceAPI) ItemsAt 

func (api *PublicGovernanceAPI) ItemsAt(num *rpc.BlockNumber) (map[string]interface{}, error)

func (*PublicGovernanceAPI) MyVotes 

func (api *PublicGovernanceAPI) MyVotes() []*VoteList

func (*PublicGovernanceAPI) MyVotingPower 

func (api *PublicGovernanceAPI) MyVotingPower() (float64, error)

func (*PublicGovernanceAPI) NodeAddress 

func (api *PublicGovernanceAPI) NodeAddress() common.Address

func (*PublicGovernanceAPI) PendingChanges added in v1.1.0 

func (api *PublicGovernanceAPI) PendingChanges() map[string]interface{}

func (*PublicGovernanceAPI) ShowTally 

func (api *PublicGovernanceAPI) ShowTally() []*returnTally

func (*PublicGovernanceAPI) TotalVotingPower 

func (api *PublicGovernanceAPI) TotalVotingPower() (float64, error)

func (*PublicGovernanceAPI) Vote 

func (api *PublicGovernanceAPI) Vote(key string, val interface{}) (string, error)

Vote injects a new vote for governance targets such as unitprice and governingnode.

func (*PublicGovernanceAPI) Votes added in v1.1.0 

func (api *PublicGovernanceAPI) Votes() []GovernanceVote

type VoteList 

type VoteList struct {
	Key      string
	Value    interface{}
	Casted   bool
	BlockNum uint64
}

type VoteMap added in v1.1.0 

type VoteMap struct {
	// contains filtered or unexported fields
}

func NewVoteMap added in v1.1.0 

func NewVoteMap() VoteMap

func (*VoteMap) Clear added in v1.1.0 

func (vl *VoteMap) Clear()

func (*VoteMap) Copy added in v1.1.0 

func (vl *VoteMap) Copy() map[string]VoteStatus

func (*VoteMap) GetValue added in v1.1.0 

func (vl *VoteMap) GetValue(key string) VoteStatus

func (*VoteMap) Import added in v1.1.0 

func (vl *VoteMap) Import(src map[string]VoteStatus)

func (*VoteMap) SetValue added in v1.1.0 

func (vl *VoteMap) SetValue(key string, val VoteStatus)

func (*VoteMap) Size added in v1.1.0 

func (vl *VoteMap) Size() int

type VoteStatus 

type VoteStatus struct {
	Value  interface{} `json:"value"`
	Casted bool        `json:"casted"`
	Num    uint64      `json:"num"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.