Review Governance specification
This commit is contained in:
Adrian Brink
parent
dd0695afa0
commit
d0539d5e9d
|
|
@ -2,71 +2,115 @@
|
||||||
|
|
||||||
*Disclaimer: This is work in progress. Mechanisms are susceptible to change.*
|
*Disclaimer: This is work in progress. Mechanisms are susceptible to change.*
|
||||||
|
|
||||||
This document describes the high-level architecture of the governance module. The governance module allows bonded Atom holders to vote on proposals on a 1 bonded Atom 1 vote basis.
|
This document describes the high-level architecture of the governance module.
|
||||||
|
The governance module allows bonded Atom holders to vote on proposals on a 1
|
||||||
|
bonded Atom 1 vote basis.
|
||||||
|
|
||||||
## Design overview
|
## Design overview
|
||||||
|
|
||||||
The governance process is divided in a few steps that are outlined below:
|
The governance process is divided in a few steps that are outlined below:
|
||||||
|
|
||||||
- **Proposal submission:** Proposal is submitted to the blockchain with a deposit
|
* **Proposal submission:** Proposal is submitted to the blockchain with a
|
||||||
- **Vote:** Once deposit reaches a certain value (`MinDeposit`), proposal is confirmed and vote opens. Bonded Atom holders can then send `TxGovVote` transactions to vote on the proposal
|
deposit.
|
||||||
- If the proposal involves a software upgrade:
|
* **Vote:** Once deposit reaches a certain value (`MinDeposit`), proposal is
|
||||||
- **Signal:** Validators start signaling that they are ready to switch to the new version
|
confirmed and vote opens. Bonded Atom holders can then send `TxGovVote`
|
||||||
- **Switch:** Once more than 75% of validators have signaled that they are ready to switch, their software automatically flips to the new version
|
transactions to vote on the proposal.
|
||||||
|
* If the proposal involves a software upgrade:
|
||||||
|
* **Signal:** Validators start signaling that they are ready to switch to the
|
||||||
|
new version.
|
||||||
|
* **Switch:** Once more than 75% of validators have signaled that they are
|
||||||
|
ready to switch, their software automatically flips to the new version.
|
||||||
|
|
||||||
## Proposal submission
|
## Proposal submission
|
||||||
|
|
||||||
### Right to submit a proposal
|
### Right to submit a proposal
|
||||||
|
|
||||||
Any Atom holder, whether bonded or unbonded, can submit proposals by sending a `TxGovProposal` transaction. Once a proposal is submitted, it is identified by its unique `proposalID`.
|
Any Atom holder, whether bonded or unbonded, can submit proposals by sending a
|
||||||
|
`TxGovProposal` transaction. Once a proposal is submitted, it is identified by
|
||||||
|
its unique `proposalID`.
|
||||||
|
|
||||||
### Proposal filter (minimum deposit)
|
### Proposal filter (minimum deposit)
|
||||||
|
|
||||||
To prevent spam, proposals must be submitted with a deposit in Atoms. Voting period will not start as long as the proposal's deposit is smaller than the minimum deposit `MinDeposit`.
|
To prevent spam, proposals must be submitted with a deposit in Atoms. Voting
|
||||||
|
period will not start as long as the proposal's deposit is smaller than the
|
||||||
|
minimum deposit `MinDeposit`.
|
||||||
|
|
||||||
When a proposal is submitted, it has to be accompagnied by a deposit that must be strictly positive but can be inferior to `MinDeposit`. Indeed, the submitter need not pay for the entire deposit on its own. If a proposal's deposit is strictly inferior to `MinDeposit`, other Atom holders can increase the proposal's deposit by sending a `TxGovDeposit` transaction. Once the proposals's deposit reaches `MinDeposit`, it enters voting period.
|
When a proposal is submitted, it has to be accompanied by a deposit that must
|
||||||
|
be strictly positive but can be inferior to `MinDeposit`. Indeed, the submitter
|
||||||
|
need not pay for the entire deposit on its own. If a proposal's deposit is
|
||||||
|
strictly inferior to `MinDeposit`, other Atom holders can increase the
|
||||||
|
proposal's deposit by sending a `TxGovDeposit` transaction. Once the proposal's
|
||||||
|
deposit reaches `MinDeposit`, it enters voting period.
|
||||||
|
|
||||||
### Deposit refund
|
### Deposit refund
|
||||||
|
|
||||||
There are two instances where Atom holders that deposited can claim back their deposit:
|
There are two instances where Atom holders that deposited can claim back their
|
||||||
- If the proposal is accepted
|
deposit:
|
||||||
- If the proposal's deposit does not reach `MinDeposit` for a period longer than `MaxDepositPeriod` (initial value: 2 months). Then the proposal is considered closed and nobody can deposit on it anymore.
|
* If the proposal is accepted.
|
||||||
|
* If the proposal's deposit does not reach `MinDeposit` for a period longer
|
||||||
|
than `MaxDepositPeriod` (initial value: 2 months). Then the proposal is
|
||||||
|
considered closed and nobody can deposit on it anymore.
|
||||||
|
|
||||||
In such instances, Atom holders that deposited can send a `TxGovClaimDeposit` transaction to retrieve their share of the deposit.
|
In such instances, Atom holders that deposited can send a `TxGovClaimDeposit`
|
||||||
|
transaction to retrieve their share of the deposit.
|
||||||
|
|
||||||
### Proposal types
|
### Proposal types
|
||||||
|
|
||||||
In the initial version of the governance module, there are two types of proposal:
|
In the initial version of the governance module, there are two types of
|
||||||
- `PlainTextProposal`. All the proposals that do not involve a modification of the source code go under this type. For example, an opinion poll would use a proposal of type `PlainTextProposal`
|
proposal:
|
||||||
- `SoftwareUpgradeProposal`. If accepted, validators are expected to update their software in accordance with the proposal. They must do so by following a 2-steps process described in the [Software Upgrade](#software-upgrade) section below. Software upgrade roadmap may be discussed and agreed on via `PlainTextProposals`, but actual software upgrades must be performed via `SoftwareUpgradeProposals`.
|
* `PlainTextProposal` All the proposals that do not involve a modification of
|
||||||
|
the source code go under this type. For example, an opinion poll would use a
|
||||||
|
proposal of type `PlainTextProposal`.
|
||||||
|
* `SoftwareUpgradeProposal`. If accepted, validators are expected to update
|
||||||
|
their software in accordance with the proposal. They must do so by following
|
||||||
|
a 2-steps process described in the [Software Upgrade](#software-upgrade)
|
||||||
|
section below. Software upgrade roadmap may be discussed and agreed on via
|
||||||
|
`PlainTextProposals`, but actual software upgrades must be performed via
|
||||||
|
`SoftwareUpgradeProposals`.
|
||||||
|
|
||||||
### Proposal categories
|
### Proposal categories
|
||||||
|
|
||||||
There are two categories of proposal:
|
There are two categories of proposal:
|
||||||
- `Regular`
|
* `Regular`
|
||||||
- `Urgent`
|
* `Urgent`
|
||||||
|
|
||||||
These two categories are strictly identical except that `Urgent` proposals can be accepted faster if a certain condition is met. For more information, see [Threshold](#threshold) section.
|
These two categories are strictly identical except that `Urgent` proposals can
|
||||||
|
be accepted faster if a certain condition is met. For more information, see
|
||||||
|
[Threshold](#threshold) section.
|
||||||
|
|
||||||
## Vote
|
## Vote
|
||||||
|
|
||||||
### Participants
|
### Participants
|
||||||
|
|
||||||
*Participants* are users that have the right to vote on proposals. On the Cosmos Hub, participants are bonded Atom holders. Unbonded Atom holders and other users do not get the right to participate in governance. However, they can submit and deposit on proposals.
|
*Participants* are users that have the right to vote on proposals. On the
|
||||||
|
Cosmos Hub, participants are bonded Atom holders. Unbonded Atom holders and
|
||||||
|
other users do not get the right to participate in governance. However, they
|
||||||
|
can submit and deposit on proposals.
|
||||||
|
|
||||||
Note that some *participants* can be forbidden to vote on a proposal under a certain validator if:
|
Note that some *participants* can be forbidden to vote on a proposal under a
|
||||||
- *participant* bonded or unbonded Atoms to said validator after proposal entered voting period
|
certain validator if:
|
||||||
- *participant* became validator after proposal entered voting period
|
* *participant* bonded or unbonded Atoms to said validator after proposal
|
||||||
|
entered voting period.
|
||||||
|
* *participant* became validator after proposal entered voting period.
|
||||||
|
|
||||||
This does not prevent *participant* to vote with Atoms bonded to other validators. For example, if a *participant* bonded some Atoms to validator A before a proposal entered voting period and other Atoms to validator B after proposal entered voting period, only the vote under validator B will be forbidden.
|
This does not prevent *participant* to vote with Atoms bonded to other
|
||||||
|
validators. For example, if a *participant* bonded some Atoms to validator A
|
||||||
|
before a proposal entered voting period and other Atoms to validator B after
|
||||||
|
proposal entered voting period, only the vote under validator B will be
|
||||||
|
forbidden.
|
||||||
|
|
||||||
### Voting period
|
### Voting period
|
||||||
|
|
||||||
Once a proposal reaches `MinDeposit`, it immediately enters `Voting period`. We define `Voting period` as the interval between the moment the vote opens and the moment the vote closes. `Voting period` should always be shorter than `Unbonding period` to prevent double voting. The initial value of `Voting period` is 2 weeks.
|
Once a proposal reaches `MinDeposit`, it immediately enters `Voting period`. We
|
||||||
|
define `Voting period` as the interval between the moment the vote opens and
|
||||||
|
the moment the vote closes. `Voting period` should always be shorter than
|
||||||
|
`Unbonding period` to prevent double voting. The initial value of
|
||||||
|
`Voting period` is 2 weeks.
|
||||||
|
|
||||||
### Option set
|
### Option set
|
||||||
|
|
||||||
The option set of a proposal refers to the set of choices a participant can choose from when casting its vote.
|
The option set of a proposal refers to the set of choices a participant can
|
||||||
|
choose from when casting its vote.
|
||||||
|
|
||||||
The initial option set includes the following options:
|
The initial option set includes the following options:
|
||||||
- `Yes`
|
- `Yes`
|
||||||
|
|
@ -74,74 +118,128 @@ The initial option set includes the following options:
|
||||||
- `NoWithVeto`
|
- `NoWithVeto`
|
||||||
- `Abstain`
|
- `Abstain`
|
||||||
|
|
||||||
`NoWithVeto` counts as `No` but also adds a `Veto` vote. `Abstain` option allows voters to signal that they do not intend to vote in favor or against the proposal but accept the result of the vote.
|
`NoWithVeto` counts as `No` but also adds a `Veto` vote. `Abstain` option
|
||||||
|
allows voters to signal that they do not intend to vote in favor or against the
|
||||||
|
proposal but accept the result of the vote.
|
||||||
|
|
||||||
*Note: from the UI, for urgent proposals we should maybe add a ‘Not Urgent’ option that casts a `NoWithVeto` vote.*
|
*Note: from the UI, for urgent proposals we should maybe add a ‘Not Urgent’
|
||||||
|
option that casts a `NoWithVeto` vote.*
|
||||||
|
|
||||||
### Quorum
|
### Quorum
|
||||||
|
|
||||||
Quorum is defined as the minimum percentage of voting power that needs to be casted on a proposal for the result to be valid.
|
Quorum is defined as the minimum percentage of voting power that needs to be
|
||||||
|
casted on a proposal for the result to be valid.
|
||||||
|
|
||||||
In the initial version of the governance module, there will be no quorum enforced by the protocol. Participation is ensured via the combination of inheritance and validator's punishment for non-voting.
|
In the initial version of the governance module, there will be no quorum
|
||||||
|
enforced by the protocol. Participation is ensured via the combination of
|
||||||
|
inheritance and validator's punishment for non-voting.
|
||||||
|
|
||||||
### Threshold
|
### Threshold
|
||||||
|
|
||||||
Threshold is defined as the minimum proportion of `Yes` votes (excluding `Abstain` votes) for the proposal to be accepted.
|
Threshold is defined as the minimum proportion of `Yes` votes (excluding
|
||||||
|
`Abstain` votes) for the proposal to be accepted.
|
||||||
|
|
||||||
Initially, the threshold is set at 50% with a possibility to veto if more than 1/3rd of votes (excluding `Abstain` votes) are `NoWithVeto` votes. This means that proposals are accepted if the proportion of `Yes` votes (excluding `Abstain` votes) at the end of the voting period is superior to 50% and if the proportion of `NoWithVeto` votes is inferior to 1/3 (excluding `Abstain` votes).
|
Initially, the threshold is set at 50% with a possibility to veto if more than
|
||||||
|
1/3rd of votes (excluding `Abstain` votes) are `NoWithVeto` votes. This means
|
||||||
|
that proposals are accepted if the proportion of `Yes` votes (excluding
|
||||||
|
`Abstain` votes) at the end of the voting period is superior to 50% and if the
|
||||||
|
proportion of `NoWithVeto` votes is inferior to 1/3 (excluding `Abstain`
|
||||||
|
votes).
|
||||||
|
|
||||||
`Urgent` proposals also work with the aforementioned threshold, except there is another condition that can accelerate the acceptance of the proposal. Namely, if the ratio of `Yes` votes to `InitTotalVotingPower` exceeds 2:3, `UrgentProposal` 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.
|
`Urgent` proposals also work with the aforementioned threshold, except there is
|
||||||
|
another condition that can accelerate the acceptance of the proposal. Namely,
|
||||||
|
if the ratio of `Yes` votes to `InitTotalVotingPower` exceeds 2:3,
|
||||||
|
`UrgentProposal` 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.
|
||||||
|
|
||||||
### Inheritance
|
### Inheritance
|
||||||
|
|
||||||
If a delegator does not vote, it will inherit its validator vote.
|
If a delegator does not vote, it will inherit its validator vote.
|
||||||
|
|
||||||
- If the delegator votes before its validator, it will not inherit from the validator's vote.
|
* If the delegator votes before its validator, it will not inherit from the
|
||||||
- If the delegator votes after its validator, it will override its validator vote with its own. If the proposal is a `Urgent` proposal, it is possible that the vote will close before delegators have a chance to react and override their validator's vote. This is not a problem, as `Urgent` 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.
|
validator's vote.
|
||||||
|
* If the delegator votes after its validator, it will override its validator
|
||||||
|
vote with its own. If the proposal is a `Urgent` proposal, it is possible
|
||||||
|
that the vote will close before delegators have a chance to react and
|
||||||
|
override their validator's vote. This is not a problem, as `Urgent` 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.
|
||||||
|
|
||||||
### Validator’s punishment for non-voting
|
### Validator’s punishment for non-voting
|
||||||
|
|
||||||
Validators are required to vote on all proposals to ensure that results have legitimacy. Voting is part of validators' directives and failure to do it will result in a penalty.
|
Validators are required to vote on all proposals to ensure that results have
|
||||||
|
legitimacy. Voting is part of validators' directives and failure to do it will
|
||||||
|
result in a penalty.
|
||||||
|
|
||||||
If a validator’s address is not in the list of addresses that voted on a proposal and the vote is closed (i.e. `MinDeposit` was reached and `Voting period` is over), then the validator will automatically be partially slashed of `GovernancePenalty`.
|
If a validator’s address is not in the list of addresses that voted on a
|
||||||
|
proposal and the vote is closed (i.e. `MinDeposit` was reached and `Voting
|
||||||
|
period` is over), then the validator will automatically be partially slashed by
|
||||||
|
`GovernancePenalty`.
|
||||||
|
|
||||||
*Note: Need to define values for `GovernancePenalty`*
|
*Note: Need to define values for `GovernancePenalty`*
|
||||||
|
|
||||||
**Exception:** If a proposal is a `Urgent` proposal and is accepted via the special condition of having a ratio of `Yes` votes to `InitTotalVotingPower` that exceeds 2:3, validators cannot be punished for not having voted on it. That is because the proposal will close as soon as the ratio exceeds 2:3, making it mechanically impossible for some validators to vote on it.
|
**Exception:** If a proposal is an `Urgent` proposal and is accepted via the
|
||||||
|
special condition of having a ratio of `Yes` votes to `InitTotalVotingPower`
|
||||||
|
that exceeds 2:3, validators cannot be punished for not having voted on it.
|
||||||
|
That is because the proposal will close as soon as the ratio exceeds 2:3,
|
||||||
|
making it mechanically impossible for some validators to vote on it.
|
||||||
|
|
||||||
### Governance key and governance address
|
### Governance key and governance address
|
||||||
|
|
||||||
Validators can make use of a slot where they can designate a `Governance PubKey`. By default, a validator's `Governance PubKey` will be the same as its main PubKey. Validators can change this `Governance PubKey` by sending a `Change Governance PubKey` transaction signed by their main `Consensus PrivKey`. From there, they will be able to sign votes using the `Governance PrivKey` associated with their `Governance PubKey`. The `Governance PubKey` can be changed at any moment.
|
Validators can make use of a slot where they can designate a
|
||||||
|
`Governance PubKey`. By default, a validator's `Governance PubKey` will be the
|
||||||
|
same as its main PubKey. Validators can change this `Governance PubKey` by
|
||||||
|
sending a `Change Governance PubKey` transaction signed by their main
|
||||||
|
`Consensus PrivKey`. From there, they will be able to sign votes using the
|
||||||
|
`Governance PrivKey` associated with their `Governance PubKey`. The
|
||||||
|
`Governance PubKey` can be changed at any moment.
|
||||||
|
|
||||||
## Software Upgrade
|
## Software Upgrade
|
||||||
|
|
||||||
If proposals are of type `SoftwareUpgradeProposal`, then nodes need to upgrade their software to the new version that was voted. This process is divided in two steps.
|
If proposals are of type `SoftwareUpgradeProposal`, then nodes need to upgrade
|
||||||
|
their software to the new version that was voted. This process is divided in
|
||||||
|
two steps.
|
||||||
|
|
||||||
### Signal
|
### Signal
|
||||||
|
|
||||||
After a `SoftwareUpgradeProposal` is accepted, validators are expected to download and install the new version of the software while continuing to run the previous version. Once a validator has downloaded and installed the upgrade, it will start signaling to the network that it is ready to switch by including the proposal's `proposalID` in its *precommits*.(*Note: Confirmation that we want it in the precommit?*)
|
After a `SoftwareUpgradeProposal` is accepted, validators are expected to
|
||||||
|
download and install the new version of the software while continuing to run
|
||||||
|
the previous version. Once a validator has downloaded and installed the
|
||||||
|
upgrade, it will start signaling to the network that it is ready to switch by
|
||||||
|
including the proposal's `proposalID` in its *precommits*.(*Note: Confirmation
|
||||||
|
that we want it in the precommit?*)
|
||||||
|
|
||||||
Note: There is only one signal slot per *precommit*. If several `SoftwareUpgradeProposals` are accepted in a short timeframe, a pipeline will form and they will be implemented one after the other in the order that they were accepted.
|
Note: There is only one signal slot per *precommit*. If several
|
||||||
|
`SoftwareUpgradeProposals` are accepted in a short timeframe, a pipeline will
|
||||||
|
form and they will be implemented one after the other in the order that they
|
||||||
|
were accepted.
|
||||||
|
|
||||||
### Switch
|
### Switch
|
||||||
|
|
||||||
Once a block contains more than 2/3rd *precommits* where a common `SoftwareUpgradeProposal` is signaled, all the nodes (including validator nodes, non-validating full nodes and light-nodes) are expected to switch to the new version of the software.
|
Once a block contains more than 2/3rd *precommits* where a common
|
||||||
|
`SoftwareUpgradeProposal` is signaled, all the nodes (including validator
|
||||||
|
nodes, non-validating full nodes and light-nodes) are expected to switch to the
|
||||||
|
new version of the software.
|
||||||
|
|
||||||
*Note: Not clear how the flip is handled programatically*
|
*Note: Not clear how the flip is handled programatically*
|
||||||
|
|
||||||
|
|
||||||
## Implementation
|
## Implementation
|
||||||
|
|
||||||
*Disclaimer: This is a suggestion. Only structs and pseudocode. Actual logic and implementation might widely differ*
|
*Disclaimer: This is a suggestion. Only structs and pseudocode. Actual logic
|
||||||
|
and implementation might widely differ*
|
||||||
|
|
||||||
### State
|
### State
|
||||||
|
|
||||||
#### Procedures
|
#### Procedures
|
||||||
|
|
||||||
`Procedures` define the rule according to which votes are run. There can only be one active procedure at any given time. If governance wants to change a procedure, either to modify a value or add/remove a parameter, a new procedure has to be created and the previous one rendered inactive.
|
`Procedures` define the rule according to which votes are run. There can only
|
||||||
|
be one active procedure at any given time. If governance wants to change a
|
||||||
|
procedure, either to modify a value or add/remove a parameter, a new procedure
|
||||||
|
has to be created and the previous one rendered inactive.
|
||||||
|
|
||||||
```Go
|
```go
|
||||||
type Procedure struct {
|
type Procedure struct {
|
||||||
VotingPeriod int64 // Length of the voting period. Initial value: 2 weeks
|
VotingPeriod int64 // Length of the voting period. Initial value: 2 weeks
|
||||||
MinDeposit int64 // Minimum deposit for a proposal to enter voting period.
|
MinDeposit int64 // Minimum deposit for a proposal to enter voting period.
|
||||||
|
|
@ -157,14 +255,15 @@ type Procedure struct {
|
||||||
```
|
```
|
||||||
|
|
||||||
**Store**:
|
**Store**:
|
||||||
- `Procedures`: a mapping `map[int16]Procedure` of procedures indexed by their `ProcedureNumber`
|
* `Procedures`: a mapping `map[int16]Procedure` of procedures indexed by their
|
||||||
- `ActiveProcedureNumber`: returns current procedure number
|
`ProcedureNumber`
|
||||||
|
* `ActiveProcedureNumber`: returns current procedure number
|
||||||
|
|
||||||
#### Proposals
|
#### Proposals
|
||||||
|
|
||||||
`Proposals` are item to be voted on.
|
`Proposals` are item to be voted on.
|
||||||
|
|
||||||
```Go
|
```go
|
||||||
type Proposal struct {
|
type Proposal struct {
|
||||||
Title string // Title of the proposal
|
Title string // Title of the proposal
|
||||||
Description string // Description of the proposal
|
Description string // Description of the proposal
|
||||||
|
|
@ -182,7 +281,7 @@ type Proposal struct {
|
||||||
|
|
||||||
We also introduce a type `ValidatorGovInfo`
|
We also introduce a type `ValidatorGovInfo`
|
||||||
|
|
||||||
```Go
|
```go
|
||||||
type ValidatorGovInfo struct {
|
type ValidatorGovInfo struct {
|
||||||
InitVotingPower int64 // Voting power of validator when proposal enters voting period
|
InitVotingPower int64 // Voting power of validator when proposal enters voting period
|
||||||
Minus int64 // Minus of validator, used to compute validator's voting power
|
Minus int64 // Minus of validator, used to compute validator's voting power
|
||||||
|
|
@ -191,20 +290,39 @@ type ValidatorGovInfo struct {
|
||||||
|
|
||||||
**Store:**
|
**Store:**
|
||||||
|
|
||||||
- `Proposals`: A mapping `map[int64]Proposal` of proposals indexed by their `proposalID`
|
* `Proposals`: A mapping `map[int64]Proposal` of proposals indexed by their
|
||||||
- `Deposits`: A mapping `map[[]byte]int64` of deposits indexed by `<proposalID>:<depositorPubKey>` as `[]byte`. Given a `proposalID` and a `PubKey`, returns deposit (`nil` if `PubKey` has not deposited on the proposal)
|
`proposalID`
|
||||||
- `Options`: A mapping `map[[]byte]string` of options indexed by `<proposalID>:<voterPubKey>:<validatorPubKey>` as `[]byte`. Given a `proposalID`, a `PubKey` and a validator's `PubKey`, returns option chosen by this `PubKey` for this validator (`nil` if `PubKey` has not voted under this validator)
|
* `Deposits`: A mapping `map[[]byte]int64` of deposits indexed by
|
||||||
- `ValidatorGovInfos`: A mapping `map[[]byte]ValidatorGovInfo` of validator's governance infos indexed by `<proposalID>:<validatorGovPubKey>`. Returns `nil` if proposal has not entered voting period or if `PubKey` was not the governance public key of a validator when proposal entered voting period.
|
`<proposalID>:<depositorPubKey>` as `[]byte`. Given a `proposalID` and a
|
||||||
|
`PubKey`, returns deposit (`nil` if `PubKey` has not deposited on the
|
||||||
|
proposal)
|
||||||
|
* `Options`: A mapping `map[[]byte]string` of options indexed by
|
||||||
|
`<proposalID>:<voterPubKey>:<validatorPubKey>` as `[]byte`. Given a
|
||||||
|
`proposalID`, a `PubKey` and a validator's `PubKey`, returns option chosen by
|
||||||
|
this `PubKey` for this validator (`nil` if `PubKey` has not voted under this
|
||||||
|
validator)
|
||||||
|
* `ValidatorGovInfos`: A mapping `map[[]byte]ValidatorGovInfo` of validator's
|
||||||
|
governance infos indexed by `<proposalID>:<validatorGovPubKey>`. Returns
|
||||||
|
`nil` if proposal has not entered voting period or if `PubKey` was not the
|
||||||
|
governance public key of a validator when proposal entered voting period.
|
||||||
|
|
||||||
|
|
||||||
#### Proposal Processing Queue
|
#### Proposal Processing Queue
|
||||||
|
|
||||||
**Store:**
|
**Store:**
|
||||||
- `ProposalProcessingQueue`: A queue `queue[proposalID]` containing all the `ProposalIDs` of proposals that reached `MinDeposit`. Each round, the oldest element of `ProposalProcessingQueue` is checked during `BeginBlock` to see if `CurrentBlock == VotingStartBlock + InitProcedure.VotingPeriod`. If it is, then the application checks if validators in `InitVotingPowerList` have voted and, if not, applies `GovernancePenalty`. After that proposal is ejected from `ProposalProcessingQueue` and the next element of the queue is evaluated. Note that if a proposal is urgent and accepted under the special condition, its `ProposalID` must be ejected from `ProposalProcessingQueue`.
|
* `ProposalProcessingQueue`: A queue `queue[proposalID]` containing all the
|
||||||
|
`ProposalIDs` of proposals that reached `MinDeposit`. Each round, the oldest
|
||||||
|
element of `ProposalProcessingQueue` is checked during `BeginBlock` to see if
|
||||||
|
`CurrentBlock == VotingStartBlock + InitProcedure.VotingPeriod`. If it is,
|
||||||
|
then the application checks if validators in `InitVotingPowerList` have voted
|
||||||
|
and, if not, applies `GovernancePenalty`. After that proposal is ejected from
|
||||||
|
`ProposalProcessingQueue` and the next element of the queue is evaluated.
|
||||||
|
Note that if a proposal is urgent and accepted under the special condition,
|
||||||
|
its `ProposalID` must be ejected from `ProposalProcessingQueue`.
|
||||||
|
|
||||||
And the pseudocode for the `ProposalProcessingQueue`:
|
And the pseudocode for the `ProposalProcessingQueue`:
|
||||||
|
|
||||||
```
|
```go
|
||||||
in BeginBlock do
|
in BeginBlock do
|
||||||
|
|
||||||
checkProposal() // First call of the recursive function
|
checkProposal() // First call of the recursive function
|
||||||
|
|
@ -252,9 +370,10 @@ And the pseudocode for the `ProposalProcessingQueue`:
|
||||||
|
|
||||||
#### Proposal Submission
|
#### Proposal Submission
|
||||||
|
|
||||||
Proposals can be submitted by any Atom holder via a `TxGovSubmitProposal` transaction.
|
Proposals can be submitted by any Atom holder via a `TxGovSubmitProposal`
|
||||||
|
transaction.
|
||||||
|
|
||||||
```Go
|
```go
|
||||||
type TxGovSubmitProposal struct {
|
type TxGovSubmitProposal struct {
|
||||||
Title string // Title of the proposal
|
Title string // Title of the proposal
|
||||||
Description string // Description of the proposal
|
Description string // Description of the proposal
|
||||||
|
|
@ -265,18 +384,19 @@ type TxGovSubmitProposal struct {
|
||||||
```
|
```
|
||||||
|
|
||||||
**State modifications:**
|
**State modifications:**
|
||||||
- Generate new `proposalID`
|
* Generate new `proposalID`
|
||||||
- Create new `Proposal`
|
* Create new `Proposal`
|
||||||
- Initialise `Proposals` attributes
|
* Initialise `Proposals` attributes
|
||||||
- Store sender's deposit in `Deposits`
|
* Store sender's deposit in `Deposits`
|
||||||
- Decrease balance of sender by `InitialDeposit`
|
* Decrease balance of sender by `InitialDeposit`
|
||||||
- If `MinDeposit` is reached:
|
* If `MinDeposit` is reached:
|
||||||
- Push `proposalID` in `ProposalProcessingQueueEnd`
|
* Push `proposalID` in `ProposalProcessingQueueEnd`
|
||||||
- Store each validator's voting power in `ValidatorGovInfos`
|
* Store each validator's voting power in `ValidatorGovInfos`
|
||||||
|
|
||||||
A `TxGovSubmitProposal` transaction can be handled according to the following pseudocode
|
A `TxGovSubmitProposal` transaction can be handled according to the following
|
||||||
|
pseudocode.
|
||||||
|
|
||||||
```
|
```go
|
||||||
// PSEUDOCODE //
|
// PSEUDOCODE //
|
||||||
// Check if TxGovSubmitProposal is valid. If it is, create proposal //
|
// Check if TxGovSubmitProposal is valid. If it is, create proposal //
|
||||||
|
|
||||||
|
|
@ -338,13 +458,13 @@ upon receiving txGovSubmitProposal from sender do
|
||||||
return proposalID
|
return proposalID
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
#### Deposit
|
#### Deposit
|
||||||
|
|
||||||
Once a proposal is submitted, if `Proposal.Deposit < ActiveProcedure.MinDeposit`, Atom holders can send `TxGovDeposit` transactions to increase the proposal's deposit.
|
Once a proposal is submitted, if
|
||||||
|
`Proposal.Deposit < ActiveProcedure.MinDeposit`, Atom holders can send
|
||||||
|
`TxGovDeposit` transactions to increase the proposal's deposit.
|
||||||
|
|
||||||
```Go
|
```go
|
||||||
type TxGovDeposit struct {
|
type TxGovDeposit struct {
|
||||||
ProposalID int64 // ID of the proposal
|
ProposalID int64 // ID of the proposal
|
||||||
Deposit int64 // Number of Atoms to add to the proposal's deposit
|
Deposit int64 // Number of Atoms to add to the proposal's deposit
|
||||||
|
|
@ -352,16 +472,17 @@ type TxGovDeposit struct {
|
||||||
```
|
```
|
||||||
|
|
||||||
**State modifications:**
|
**State modifications:**
|
||||||
- Decrease balance of sender by `deposit`
|
* Decrease balance of sender by `deposit`
|
||||||
- Initialize or increase `deposit` of sender in `Deposits`
|
* Initialize or increase `deposit` of sender in `Deposits`
|
||||||
- Increase `proposal.Deposit` by sender's `deposit`
|
* Increase `proposal.Deposit` by sender's `deposit`
|
||||||
- If `MinDeposit` is reached:
|
* If `MinDeposit` is reached:
|
||||||
- Push `proposalID` in `ProposalProcessingQueueEnd`
|
* Push `proposalID` in `ProposalProcessingQueueEnd`
|
||||||
- Store each validator's voting power in `ValidatorGovInfos`
|
* Store each validator's voting power in `ValidatorGovInfos`
|
||||||
|
|
||||||
A `TxGovDeposit` transaction has to go through a number of checks to be valid. These checks are outlined in the following pseudocode.
|
A `TxGovDeposit` transaction has to go through a number of checks to be valid.
|
||||||
|
These checks are outlined in the following pseudocode.
|
||||||
|
|
||||||
```
|
```go
|
||||||
// PSEUDOCODE //
|
// PSEUDOCODE //
|
||||||
// Check if TxGovDeposit is valid. If it is, increase deposit and check if MinDeposit is reached
|
// Check if TxGovDeposit is valid. If it is, increase deposit and check if MinDeposit is reached
|
||||||
|
|
||||||
|
|
@ -438,9 +559,11 @@ upon receiving txGovDeposit from sender do
|
||||||
|
|
||||||
#### Claiming deposit
|
#### Claiming deposit
|
||||||
|
|
||||||
Finally, if the proposal is accepted or `MinDeposit` was not reached before the end of the `MaximumDepositPeriod`, then Atom holders can send `TxGovClaimDeposit` transaction to claim their deposits.
|
Finally, if the proposal is accepted or `MinDeposit` was not reached before the
|
||||||
|
end of the `MaximumDepositPeriod`, then Atom holders can send
|
||||||
|
`TxGovClaimDeposit` transaction to claim their deposits.
|
||||||
|
|
||||||
```Go
|
```go
|
||||||
type TxGovClaimDeposit struct {
|
type TxGovClaimDeposit struct {
|
||||||
ProposalID int64
|
ProposalID int64
|
||||||
}
|
}
|
||||||
|
|
@ -448,12 +571,12 @@ Finally, if the proposal is accepted or `MinDeposit` was not reached before the
|
||||||
|
|
||||||
**State modifications:**
|
**State modifications:**
|
||||||
If conditions are met, reimburse the deposit, i.e.
|
If conditions are met, reimburse the deposit, i.e.
|
||||||
- Increase `AtomBalance` of sender by `deposit`
|
* Increase `AtomBalance` of sender by `deposit`
|
||||||
- Set `deposit` of sender in `DepositorsList` to 0
|
* Set `deposit` of sender in `DepositorsList` to 0
|
||||||
|
|
||||||
And the associated pseudocode
|
And the associated pseudocode.
|
||||||
|
|
||||||
```
|
```go
|
||||||
// PSEUDOCODE //
|
// PSEUDOCODE //
|
||||||
/* Check if TxGovClaimDeposit is valid. If vote never started and MaxDepositPeriod is reached or if vote started and proposal was accepted, return deposit */
|
/* Check if TxGovClaimDeposit is valid. If vote never started and MaxDepositPeriod is reached or if vote started and proposal was accepted, return deposit */
|
||||||
|
|
||||||
|
|
@ -507,8 +630,7 @@ And the associated pseudocode
|
||||||
|
|
||||||
initProcedure = load(store, Procedures, proposal.InitProcedureNumber)
|
initProcedure = load(store, Procedures, proposal.InitProcedureNumber)
|
||||||
|
|
||||||
if (proposal.Category AND proposal.Votes['Yes']/proposal.InitTotalVotingPower >= 2/3) OR
|
if (proposal.Category AND proposal.Votes['Yes']/proposal.InitTotalVotingPower >= 2/3) OR ((CurrentBlock > proposal.VotingStartBlock + initProcedure.VotingPeriod) AND (proposal.Votes['NoWithVeto']/(proposal.Votes['Yes']+proposal.Votes['No']+proposal.Votes['NoWithVeto']) < 1/3) AND (proposal.Votes['Yes']/(proposal.Votes['Yes']+proposal.Votes['No']+proposal.Votes['NoWithVeto']) > 1/2)) then
|
||||||
((CurrentBlock > proposal.VotingStartBlock + initProcedure.VotingPeriod) AND (proposal.Votes['NoWithVeto']/(proposal.Votes['Yes']+proposal.Votes['No']+proposal.Votes['NoWithVeto']) < 1/3) AND (proposal.Votes['Yes']/(proposal.Votes['Yes']+proposal.Votes['No']+proposal.Votes['NoWithVeto']) > 1/2)) then
|
|
||||||
|
|
||||||
// Proposal was accepted either because
|
// Proposal was accepted either because
|
||||||
// Proposal was urgent and special condition was met
|
// Proposal was urgent and special condition was met
|
||||||
|
|
@ -516,15 +638,15 @@ And the associated pseudocode
|
||||||
|
|
||||||
store(Deposits, <txGovClaimDeposit.ProposalID>:<sender>, 0)
|
store(Deposits, <txGovClaimDeposit.ProposalID>:<sender>, 0)
|
||||||
sender.AtomBalance += deposit
|
sender.AtomBalance += deposit
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
#### Vote
|
#### Vote
|
||||||
|
|
||||||
Once `ActiveProcedure.MinDeposit` is reached, voting period starts. From there, bonded Atom holders are able to send `TxGovVote` transactions to cast their vote on the proposal.
|
Once `ActiveProcedure.MinDeposit` is reached, voting period starts. From there,
|
||||||
|
bonded Atom holders are able to send `TxGovVote` transactions to cast their
|
||||||
|
vote on the proposal.
|
||||||
|
|
||||||
```Go
|
```go
|
||||||
type TxGovVote struct {
|
type TxGovVote struct {
|
||||||
ProposalID int64 // proposalID of the proposal
|
ProposalID int64 // proposalID of the proposal
|
||||||
Option string // option from OptionSet chosen by the voter
|
Option string // option from OptionSet chosen by the voter
|
||||||
|
|
@ -533,19 +655,25 @@ Once `ActiveProcedure.MinDeposit` is reached, voting period starts. From there,
|
||||||
```
|
```
|
||||||
|
|
||||||
**State modifications:**
|
**State modifications:**
|
||||||
- If sender is not a validator and validator has not voted, initialize or increase minus of validator by sender's `voting power`
|
* If sender is not a validator and validator has not voted, initialize or
|
||||||
- If sender is not a validator and validator has voted, decrease `proposal.Votes['validatorOption']` by sender's `voting power`
|
increase minus of validator by sender's `voting power`
|
||||||
- If sender is not a validator, increase `[proposal.Votes['txGovVote.Option']` by sender's `voting power`
|
* If sender is not a validator and validator has voted, decrease
|
||||||
- If sender is a validator, increase `proposal.Votes['txGovVote.Option']` by validator's `InitialVotingPower - minus` (`minus` can be equal to 0)
|
`proposal.Votes['validatorOption']` by sender's `voting power`
|
||||||
|
* If sender is not a validator, increase `[proposal.Votes['txGovVote.Option']`
|
||||||
|
by sender's `voting power`
|
||||||
|
* If sender is a validator, increase `proposal.Votes['txGovVote.Option']` by
|
||||||
|
validator's `InitialVotingPower - minus` (`minus` can be equal to 0)
|
||||||
|
|
||||||
Votes need to be tied to a validator in order to compute validator's voting power. If a delegator is bonded to multiple validators, it will have to send one transaction per validator (the UI should facilitate this so that multiple transactions can be sent in one "vote flow").
|
Votes need to be tied to a validator in order to compute validator's voting
|
||||||
If the sender is the validator itself, then it will input its own GovernancePubKey as `ValidatorPubKey`
|
power. If a delegator is bonded to multiple validators, it will have to send
|
||||||
|
one transaction per validator (the UI should facilitate this so that multiple
|
||||||
|
transactions can be sent in one "vote flow"). If the sender is the validator
|
||||||
|
itself, then it will input its own GovernancePubKey as `ValidatorPubKey`
|
||||||
|
|
||||||
|
Next is a pseudocode proposal of the way `TxGovVote` transactions can be
|
||||||
|
handled:
|
||||||
|
|
||||||
|
```go
|
||||||
Next is a pseudocode proposal of the way `TxGovVote` transactions can be handled:
|
|
||||||
|
|
||||||
```
|
|
||||||
// PSEUDOCODE //
|
// PSEUDOCODE //
|
||||||
// Check if TxGovVote is valid. If it is, count vote//
|
// Check if TxGovVote is valid. If it is, count vote//
|
||||||
|
|
||||||
|
|
@ -644,16 +772,35 @@ Next is a pseudocode proposal of the way `TxGovVote` transactions can be handled
|
||||||
// i.e. sender == validator
|
// i.e. sender == validator
|
||||||
|
|
||||||
proposal.Votes['txGovVote.Option'] += (validatorGovInfo.InitVotingPower - validatorGovInfo.Minus)
|
proposal.Votes['txGovVote.Option'] += (validatorGovInfo.InitVotingPower - validatorGovInfo.Minus)
|
||||||
|
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
## Future improvements (not in scope for MVP)
|
## Future improvements (not in scope for MVP)
|
||||||
|
|
||||||
The current documentation only describes the minimum viable product for the governance module. Future improvements may include:
|
The current documentation only describes the minimum viable product for the
|
||||||
|
governance module. Future improvements may include:
|
||||||
|
|
||||||
- **`BountyProposals`:** If accepted, a `BountyProposal` creates an open bounty. The `BountyProposal` specifies how many Atoms will be given upon completion. These Atoms will be taken from the `reserve pool`. After a `BountyProposal` is accepted by governance, anybody can submit a `SoftwareUpgradeProposal` with the code to claim the bounty. Note that once a `BountyProposal` is accepted, the corresponding funds in the `reserve pool` are locked so that payment can always be honored. In order to link a `SoftwareUpgradeProposal` to an open bounty, the submitter of the `SoftwareUpgradeProposal` will use the `Proposal.LinkedProposal` attribute. If a `SoftwareUpgradeProposal` linked to an open bounty is accepted by governance, the funds that were reserved are automatically transferred to the submitter.
|
* **`BountyProposals`:** If accepted, a `BountyProposal` creates an open
|
||||||
- **Complex delegation:** Delegators could choose other representatives than their validators. Ultimately, the chain of representatives would always end up to a validator, but delegators could inherit the vote of their chosen representative before they inherit the vote of their validator. In other words, they would only inherit the vote of their validator if their other appointed representative did not vote.
|
bounty. The `BountyProposal` specifies how many Atoms will be given upon
|
||||||
- **`ParameterProposals` and `WhitelistProposals`:** These proposals would automatically change pre-defined parameters and whitelists. Upon acceptance, these proposals would not require validators to do the signal and switch process.
|
completion. These Atoms will be taken from the `reserve pool`. After a
|
||||||
- **Better process for proposal review:** There would be two parts to `proposal.Deposit`, one for anti-spam (same as in MVP) and an other one to reward third party auditors.
|
`BountyProposal` is accepted by governance, anybody can submit a
|
||||||
|
`SoftwareUpgradeProposal` with the code to claim the bounty. Note that once a
|
||||||
|
`BountyProposal` is accepted, the corresponding funds in the `reserve pool`
|
||||||
|
are locked so that payment can always be honored. In order to link a
|
||||||
|
`SoftwareUpgradeProposal` to an open bounty, the submitter of the
|
||||||
|
`SoftwareUpgradeProposal` will use the `Proposal.LinkedProposal` attribute.
|
||||||
|
If a `SoftwareUpgradeProposal` linked to an open bounty is accepted by
|
||||||
|
governance, the funds that were reserved are automatically transferred to the
|
||||||
|
submitter.
|
||||||
|
* **Complex delegation:** Delegators could choose other representatives than
|
||||||
|
their validators. Ultimately, the chain of representatives would always end
|
||||||
|
up to a validator, but delegators could inherit the vote of their chosen
|
||||||
|
representative before they inherit the vote of their validator. In other
|
||||||
|
words, they would only inherit the vote of their validator if their other
|
||||||
|
appointed representative did not vote.
|
||||||
|
* **`ParameterProposals` and `WhitelistProposals`:** These proposals would
|
||||||
|
automatically change pre-defined parameters and whitelists. Upon acceptance,
|
||||||
|
these proposals would not require validators to do the signal and switch
|
||||||
|
process.
|
||||||
|
* **Better process for proposal review:** There would be two parts to
|
||||||
|
`proposal.Deposit`, one for anti-spam (same as in MVP) and an other one to
|
||||||
|
reward third party auditors.
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue