Governance
The governance service is responsible for providing an on-chain governance mechanism.
The service interface definition lives in go/governance/api
. It defines the
supported queries and transactions. For more information you can also check out
the consensus service API documentation and the governance ADR
specification.
Methods
The following sections describe the methods supported by the consensus governance service.
Submit Proposal
Proposal submission enables a new consensus layer governance proposal to be created.
Method name:
governance.SubmitProposal
Body:
// ProposalContent is a consensus layer governance proposal content.
type ProposalContent struct {
Upgrade *UpgradeProposal `json:"upgrade,omitempty"`
CancelUpgrade *CancelUpgradeProposal `json:"cancel_upgrade,omitempty"`
}
// UpgradeProposal is an upgrade proposal.
type UpgradeProposal struct {
upgrade.Descriptor
}
// CancelUpgradeProposal is an upgrade cancellation proposal.
type CancelUpgradeProposal struct {
// ProposalID is the identifier of the pending upgrade proposal.
ProposalID uint64 `json:"proposal_id"`
}
Fields:
upgrade
(optional) specifies an upgrade proposal.cancel_upgrade
(optional) specifies an upgrade cancellation proposal.
Exactly one of the proposal kind fields needs to be non-nil, otherwise the proposal is considered malformed.
Vote
Voting for submitted consensus layer governance proposals.
Method name:
governance.CastVote
Body:
type ProposalVote struct {
// ID is the unique identifier of a proposal.
ID uint64 `json:"id"`
// Vote is the vote.
Vote Vote `json:"vote"`
}
Events
Proposal Submitted Event
Body:
type ProposalSubmittedEvent {
// ID is the unique identifier of a proposal.
ID uint64 `json:"id"`
// Submitter is the staking account address of the submitter.
Submitter staking.Address `json:"submitter"`
}
Emitted for every submitted proposal.
Proposal Finalized Event
Body:
type ProposalFinalizedEvent struct {
// ID is the unique identifier of a proposal.
ID uint64 `json:"id"`
// State is the new proposal state.
State ProposalState `json:"state"`
}
Emitted when a proposal is finalized.
Proposal Executed Event
Body:
type ProposalExecutedEvent {
// ID is the unique identifier of a proposal.
ID uint64 `json:"id"`
}
Emitted when a passed proposal is executed.
Vote Event
Body:
type VoteEvent {
// ID is the unique identifier of a proposal.
ID uint64 `json:"id"`
// Submitter is the staking account address of the vote submitter.
Submitter staking.Address `json:"submitter"`
// Vote is the cast vote.
Vote Vote `json:"vote"`
}
Emitted when a vote is cast.
Consensus Parameters
-
gas_costs
(transaction.Costs) are the governance transaction gas costs. -
min_proposal_deposit
(base units) specifies the number of base units that are deposited when creating a new proposal. -
voting_period
(epochs) specifies the number of epochs after which the voting for a proposal is closed and the votes are tallied. -
quorum
(uint8: [0,100]) specifies the minimum percentage of voting power that needs to be cast on a proposal for the result to be valid. -
threshold
(uint8: [0,100]) specifies the minimum percentage ofVoteYes
votes in order for a proposal to be accepted. -
upgrade_min_epoch_diff
(epochs) specifies the minimum number of epochs between the current epoch and the proposed upgrade epoch for the upgrade proposal to be valid. Additionally specifies the minimum number of epochs between two consecutive pending upgrades. -
upgrade_cancel_min_epoch_diff
(epochs) specifies the minimum number of epochs between the current epoch and the proposed upgrade epoch for the upgrade cancellation proposal to be valid.
Test Vectors
To generate test vectors for various governance transactions, run:
make -C go governance/gen_vectors
For more information about the structure of the test vectors see the section on Transaction Test Vectors.