Concept
Signaling proposals are a typical practice in blockchain governance activities. They provide a means for the community to gauge sentiment or reach consensus on a particular issue or suggestion without necessitating changes to the blockchain's state. However, these proposals simplify multifaceted issues into binary 'yes/no' votes, potentially distorting the accurate representation of varied community perspectives on complex issues. Additionally, they may slow down decision-making and introduce inefficiency to the overall governance process. Such potential drawbacks have led some projects, such as Ethereum and Celestia, to favor off-chain governance, a shift that arguably contradicts the decentralization principle.
Because of KIRA network's unique governance ranking system, the inclusion of signaling proposals adds another layer of complexity, potentially skewing the decision-making process as votes could be influenced more by score preservation than by authentic opinions. To circumvent these challenges, KIRA network introduces the Poll module, which offers a more inclusive and flexible mechanism for consensus. Unlike traditional signaling proposals, a Poll Proposal allows a select group of individuals to either present their own voting options or vote on pre-existing ones. This approach caters to a wide array of use cases and fosters a more accurate reflection of the diverse interests across various scenarios, such as agreeing on upgrade timeframes, selecting group administrators, or deciding on future changes to the network properties registrar.
Decision-Making Process
The decision-making process for the Poll module operates in line with the principles established by the Proposals logic, while accommodating the unique requirements of this module. This process is guided by the following key points:
Voting Eligibility and Single Vote Rule: Each account with the ability to vote can cast only one vote per proposal. However, this vote can be changed later on by sending another voting transaction.
Vote Options: A single vote can correspond to one or many voting options, as outlined by the options.choices variable.
Custom Choices: Voters are permitted to cast custom choices if the options.count exceeds the options.values.length. Such custom choices are subsequently added to options.values, enabling other users to vote on them. However, each voter can only cast a vote for a specific option once.
Abstain and Veto: Regardless of the defined options.values, voters are allowed to vote abstain or veto. These are reserved values and don't have to match the options.type.
Proposal Timeline: Poll proposals do not have an enactment time. A proposal can neither pass, be rejected, nor vetoed before its voting_end_time time has elapsed, unless all eligible voters have cast their votes and the result is decisive.
Quorum Requirement: A poll necessitates a minimum number of votes, or a quorum, to be considered valid. The quorum is essential for ensuring adequate participation and representation in the decision-making process.
The default poll minimum quorum percentage is the same as the proposal quorum, 33%, and is configurable by governance via the vote_quorum network property.
The outcome of a Poll proposal is determined based on the following rules:
Passed/Successful: A proposal is passed only if the vote_quorum, as defined by Network Properties, is reached and one of the options secures the majority of votes.
Rejected: A proposal is rejected if the majority of votes are veto votes, if the quorum is not reached, or if more than one non-veto options.values has the same number of votes (indicating an indecisive result).
A finalized Poll proposal records all options voted on, their corresponding scores, the final result, time of creation, contents, and end time. It is not necessary to persist information regarding which user voted for which option.
Logic Flow
I. Proposing & Voting Rights
Since KIRA governance is divided into potentially unlimited number of sub-groups through the use of Roles, we have to enable each individual role holder to create their own Poll. This will be achieved through a dedicated createPollPermission. If the createPollPermission is assigned to the account as individual permission or as a sub-component of a Role that is assigned to some account, then such account should be allowed to create their own Poll.
The Poll Proposal opposed to other types of KIRA proposals will NOT have a corresponding votePollPermission, instead a person raising a proposal should have ability to decide which other Role or Roles should have the ability to vote on the specific Poll in the form of whitelist and/or whitelist.
II. Creating Polls
Each poll should constitute of the following elements:
title - short title as for any other proposals (should be limited to 128 characters)
NOTE: If not already present add Network Property, which defines title character limit for all proposals (max_proposal_title_size)
Ensure that character limit is enforced for all proposals
description - short description as for any other proposals describing expected issue to be voted on (should be limited to 1024 characters)
NOTE: If not already present, add Network Property, which defines description character limit for all proposals (max_proposal_description_size)
Ensure that character limit is enforced for all proposals
reference - IPFS CID or URL reference to file describing proposal and voting options in depth (should be limited to 512 characters)
checksum - reference checksum (should be limited to 128 characters)
roles - list of roles that are allowed to take part in the poll vote
options.values - list of options that governance members can vote on (should be limited to 64 characters each item and have no less than 1 character)
Add Network Property, which defines option character limit for all proposals (max_proposal_poll_option_size)
Ensure that character limit is enforced for Poll proposals
Must be case insensitive
Cannot start or end with any whitespace characters
Only ASCII characters are allowed
options.count - maximum number of voting options that poll can have (this is necessary since we want to allow user provide their own voting option)
Add Network Property, which defines option count limit for Poll proposals (max_proposal_poll_option_count, default 128)
options.type - type of the options, all user supplied or predefined options must match its type
Option types: string, uint, int, float, bool
options.choices - should define maximum number of choices that voter can select (default 1)
expiry - time when new votes can no longer be casted
Example Data Structure:
JSON
Copy
{
"title": "My example Poll :)",
"description": "What kind of cookie should Bob eat?",
"reference": "bafybeifiixdxq4cli6qxib5zfiky7rilb6k66f336nymj4jty6tdsiixre", // example CID
"checksum": "f5aca3b1fafffdcf22a30aafd3392e473592944da28515ae0a06afbc71c27b09", // example sha256
"roles": [ "sudo", "validator", "ambassador" ],
"options": {
"values": [
"blueberry",
"chocolate",
"vanilla",
"Bob is too fat to have a cookie"
],
"count": 4, // default (if not specified) should be equal to length of options array
"type": "string",
"choices": 1
}
}
III. Voting Results & Rules
All voting logic should follow existing Proposals Logic voting rules, with exception for results & vote type, since the vote types will have a wider range - as per voter-supplied or pre-defined options in our case.
Each account with ability to vote should have the right to one and only one vote, the vote can be changed at any time by sending another vote tx (just like in the case of other proposals)
One vote can correspond to ONE or MANY voting options as per options.choices variable
Voters should be allowed to cast custom choices if options.count is greater than options.values.length
Custom choices should be added to options.values so that other users can vote on them
One voter can NOT vote multiple times on the same option
It should be allowed to vote abstain and veto regardless of the defined options.values and the abstain/veto should be a reserved values, that doesn’t have to match the options.type
Proposal is passed/successful only if vote_quorum is reached as defined by Network Properties and one of the options has majority votes
Proposal is rejected if majority of votes are veto votes, the quorum is NOT reached or more then one non veto options.values has the same number of votes (indecisive result).
Poll proposals should be instant and NOT have enactment time
Proposal can't pass, be rejected or vetoed before its expiration time passes unless all voters cast their vote and result would NOT be indecisive.
Finalized proposal should record all options voted on, their corresponding scores, final result, time of creation, contents & end time. We do NOT need to record/persist which user voted on which option.
Parameters
Polls parameters
PollOptions type
Vote types
Polls status
Transactions & Queries
List of essential transactions & queries
polls-list-by-address - list all polls by address that can vote on them, if address is not specified list all polls
Ensure that all polls are also visible in the already existing proposals query and that they can be queried by proposal id
poll-create - create a poll
poll-vote - vote on the poll
Notes
Ensure compatibility with KIP-81