governance

package
Version: v1.7.0 Latest Latest
Warning

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

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

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 (*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"`
}

Jump to

Keyboard shortcuts

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