github.com/fibonacci-chain/fbc@v0.0.0-20231124064014-c7636198c1e9/libs/cosmos-sdk/x/gov/spec/01_concepts.md (about)

     1  <!--
     2  order: 1
     3  -->
     4  
     5  # Concepts
     6  
     7  *Disclaimer: This is work in progress. Mechanisms are susceptible to change.*
     8  
     9  The governance process is divided in a few steps that are outlined below:
    10  
    11  * **Proposal submission:** Proposal is submitted to the blockchain with a 
    12    deposit.
    13  * **Vote:** Once deposit reaches a certain value (`MinDeposit`), proposal is 
    14    confirmed and vote opens. Bonded Atom holders can then send `TxGovVote` 
    15    transactions to vote on the proposal.
    16  * If the proposal involves a software upgrade:
    17    * **Signal:** Validators start signaling that they are ready to switch to the
    18      new version.
    19    * **Switch:** Once more than 75% of validators have signaled that they are 
    20      ready to switch, their software automatically flips to the new version.
    21  
    22  ## Proposal submission
    23  
    24  ### Right to submit a proposal
    25  
    26  Any Atom holder, whether bonded or unbonded, can submit proposals by sending a 
    27  `TxGovProposal` transaction. Once a proposal is submitted, it is identified by 
    28  its unique `proposalID`.
    29  
    30  ### Proposal types
    31  
    32  In the initial version of the governance module, there are two types of 
    33  proposal:
    34  * `PlainTextProposal` All the proposals that do not involve a modification of 
    35    the source code go under this type. For example, an opinion poll would use a 
    36    proposal of type `PlainTextProposal`.
    37  * `SoftwareUpgradeProposal`. If accepted, validators are expected to update 
    38    their software in accordance with the proposal. They must do so by following 
    39    a 2-steps process described in the [Software Upgrade](#software-upgrade) 
    40    section below. Software upgrade roadmap may be discussed and agreed on via 
    41    `PlainTextProposals`, but actual software upgrades must be performed via 
    42    `SoftwareUpgradeProposals`.
    43  
    44  Other modules may expand upon the governance module by implementing their own
    45  proposal types and handlers. These types are registered and processed through the
    46  governance module (eg. `ParamChangeProposal`), which then execute the respective
    47  module's proposal handler when a proposal passes. This custom handler may perform
    48  arbitrary state changes.
    49  
    50  ## Deposit
    51  
    52  To prevent spam, proposals must be submitted with a deposit in the coins defined in the `MinDeposit` param. The voting period will not start until the proposal's deposit equals `MinDeposit`.
    53  
    54  When a proposal is submitted, it has to be accompanied by a deposit that must be strictly positive, but can be inferior to `MinDeposit`. The submitter doesn't need to pay for the entire deposit on their own. If a proposal's deposit is inferior to `MinDeposit`, other token holders can increase the proposal's deposit by sending a `Deposit` transaction. The deposit is kept in an escrow in the governance `ModuleAccount` until the proposal is finalized (passed or rejected).
    55  
    56  Once the proposal's deposit reaches `MinDeposit`, it enters voting period. If proposal's deposit does not reach `MinDeposit` before `MaxDepositPeriod`, proposal closes and nobody can deposit on it anymore.
    57  
    58  ### Deposit refund and burn
    59  
    60  When a the a proposal finalized, the coins from the deposit are either refunded or burned, according to the final tally of the proposal:
    61  
    62  * If the proposal is approved or if it's rejected but _not_ vetoed, deposits will automatically be refunded to their respective depositor (transferred from the governance `ModuleAccount`).
    63  * When the proposal is vetoed with a supermajority, deposits be burned from the governance `ModuleAccount`.
    64  
    65  ## Vote
    66  
    67  ### Participants
    68  
    69  *Participants* are users that have the right to vote on proposals. On the 
    70  Cosmos Hub, participants are bonded Atom holders. Unbonded Atom holders and 
    71  other users do not get the right to participate in governance. However, they 
    72  can submit and deposit on proposals.
    73  
    74  Note that some *participants* can be forbidden to vote on a proposal under a 
    75  certain validator if:
    76  * *participant* bonded or unbonded Atoms to said validator after proposal 
    77    entered voting period.
    78  * *participant* became validator after proposal entered voting period.
    79  
    80  This does not prevent *participant* to vote with Atoms bonded to other 
    81  validators. For example, if a *participant* bonded some Atoms to validator A 
    82  before a proposal entered voting period and other Atoms to validator B after 
    83  proposal entered voting period, only the vote under validator B will be 
    84  forbidden.
    85  
    86  ### Voting period
    87  
    88  Once a proposal reaches `MinDeposit`, it immediately enters `Voting period`. We
    89  define `Voting period` as the interval between the moment the vote opens and
    90  the moment the vote closes. `Voting period` should always be shorter than 
    91  `Unbonding period` to prevent double voting. The initial value of 
    92  `Voting period` is 2 weeks.
    93  
    94  ### Option set
    95  
    96  The option set of a proposal refers to the set of choices a participant can 
    97  choose from when casting its vote.
    98  
    99  The initial option set includes the following options: 
   100  - `Yes`
   101  - `No`
   102  - `NoWithVeto` 
   103  - `Abstain` 
   104  
   105  `NoWithVeto` counts as `No` but also adds a `Veto` vote. `Abstain` option 
   106  allows voters to signal that they do not intend to vote in favor or against the
   107  proposal but accept the result of the vote. 
   108  
   109  *Note: from the UI, for urgent proposals we should maybe add a ‘Not Urgent’ 
   110  option that casts a `NoWithVeto` vote.*
   111  
   112  ### Quorum 
   113  
   114  Quorum is defined as the minimum percentage of voting power that needs to be 
   115  casted on a proposal for the result to be valid. 
   116  
   117  ### Threshold
   118  
   119  Threshold is defined as the minimum proportion of `Yes` votes (excluding 
   120  `Abstain` votes) for the proposal to be accepted.
   121  
   122  Initially, the threshold is set at 50% with a possibility to veto if more than
   123  1/3rd of votes (excluding `Abstain` votes) are `NoWithVeto` votes. This means 
   124  that proposals are accepted if the proportion of `Yes` votes (excluding 
   125  `Abstain` votes) at the end of the voting period is superior to 50% and if the 
   126  proportion of `NoWithVeto` votes is inferior to 1/3 (excluding `Abstain` 
   127  votes).
   128  
   129  Proposals can be accepted before the end of the voting period if they meet a special condition. Namely, if the ratio of `Yes` votes to `InitTotalVotingPower`exceeds 2:3, the proposal will be immediately accepted, even if the `Voting period` is not finished. `InitTotalVotingPower` is the total voting power of all bonded Atom holders at the moment when the vote opens. 
   130  This condition exists so that the network can react quickly in case of urgency.
   131  
   132  ### Inheritance
   133  
   134  If a delegator does not vote, it will inherit its validator vote.
   135  
   136  * If the delegator votes before its validator, it will not inherit from the 
   137    validator's vote.
   138  * If the delegator votes after its validator, it will override its validator 
   139    vote with its own. If the proposal is urgent, it is possible 
   140    that the vote will close before delegators have a chance to react and 
   141    override their validator's vote. This is not a problem, as proposals require more than 2/3rd of the total voting power to pass before the end of the voting period. If more than 2/3rd of validators collude, they can censor the votes of delegators anyway.
   142  
   143  ### Validator’s punishment for non-voting
   144  
   145  At present, validators are not punished for failing to vote.
   146  
   147  ### Governance address
   148  
   149  Later, we may add permissioned keys that could only sign txs from certain modules. For the MVP, the `Governance address` will be the main validator address generated at account creation. This address corresponds to a different PrivKey than the Tendermint PrivKey which is responsible for signing consensus messages. Validators thus do not have to sign governance transactions with the sensitive Tendermint PrivKey.
   150  
   151  ## Software Upgrade
   152  
   153  If proposals are of type `SoftwareUpgradeProposal`, then nodes need to upgrade 
   154  their software to the new version that was voted. This process is divided in 
   155  two steps.
   156  
   157  ### Signal
   158  
   159  After a `SoftwareUpgradeProposal` is accepted, validators are expected to 
   160  download and install the new version of the software while continuing to run 
   161  the previous version. Once a validator has downloaded and installed the 
   162  upgrade, it will start signaling to the network that it is ready to switch by 
   163  including the proposal's `proposalID` in its *precommits*.(*Note: Confirmation 
   164  that we want it in the precommit?*)
   165  
   166  Note: There is only one signal slot per *precommit*. If several 
   167  `SoftwareUpgradeProposals` are accepted in a short timeframe, a pipeline will 
   168  form and they will be implemented one after the other in the order that they 
   169  were accepted.
   170  
   171  ### Switch
   172  
   173  Once a block contains more than 2/3rd *precommits* where a common 
   174  `SoftwareUpgradeProposal` is signaled, all the nodes (including validator 
   175  nodes, non-validating full nodes and light-nodes) are expected to switch to the
   176  new version of the software. 
   177  
   178  *Note: Not clear how the flip is handled programmatically*