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

     1  // Copyright 2018 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 governance contains functions and variables used for voting and reflecting vote results in Klaytn.
    19  In Klaytn, various settings such as the amount of KLAY minted as a block reward can be changed by using governance vote.
    20  These votes can be casted by nodes of Governance Council and detailed introduction can be found at https://docs.klaytn.com/klaytn/design/governance
    21  
    22  How to cast a vote
    23  
    24  To cast a vote, a node have to be a member of the Governance Council.
    25  If the governance mode is "single", only one designated node (the governing node) can vote.
    26  In the console of the node, "governance.vote(key, value)" API can be used to cast a vote.
    27  
    28  Keys for the voting API
    29  
    30  Following keys can be handled as of 7/20/2019.
    31    - "governance.governancemode"   : To change the governance mode
    32    - "governance.governingnode"    : To change the governing node if the governance mode is "single"
    33    - "governance.unitprice"        : To change the unitprice of Klaytn (Unit price is same as gasprice in Ethereum)
    34    - "governance.addvalidator"     : To add new node as a council node
    35    - "governance.removevalidator"  : To remove a node from the governance council
    36    - "istanbul.epoch"              : To change Epoch, the period to gather votes
    37    - "istanbul.committeesize"      : To change the size of the committee
    38    - "reward.mintingamount"        : To change the amount of block generation reward
    39    - "reward.ratio"                : To change the ratio used to distribute the reward between block proposer node, KFF and KCF
    40    - "reward.useginicoeff"         : To change the application of gini coefficient to reduce gap between CCOs
    41    - "reward.deferredtxfee"        : To change the way of distributing tx fee
    42    - "reward.minimumstake"         : To change the minimum amount of stake to participate in the governance council
    43  
    44  
    45  How governance works
    46  
    47  Governance package contains a governance struct which stores current system configurations and voting status.
    48  If a vote passed, the governance struct is updated to provide new information to related packages and users.
    49  The API documentation can be found at https://docs.klaytn.com/bapp/json-rpc/api-references/governance
    50  
    51  When a CN (consensus node which is managed by CCO) proposes a block, it writes its vote on the block header and other nodes
    52  parse the header and handle it. This process is handled by snapshot.go in the consensus engine and processed by functions in handler.go
    53  
    54  If a vote satisfies the requirement (more than 50% of votes in favor of), it will update the governance struct and many other packages
    55  like "reward", "txpool" and so on will reference it.
    56  
    57  
    58  Source Files
    59  
    60  Governance related functions and variables are defined in the files listed below
    61    - default.go    : the governance struct, cache and persistence
    62    - handler.go    : functions to handle votes and its application
    63    - api.go        : console APIs to get governance information and to cast a vote
    64    - interface.go  : Abstract interfaces to various underlying implementations
    65    - mixed.go      : Wrapper for multiple engine implementations
    66  
    67  */
    68  package governance