Search
Duplicate
Try Notion
🚧🚧
Polls
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 altered 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 expiration time has elapsed, unless all eligible voters have cast their votes and the result is decisive.
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
NAME
TYPE
EXAMPLE
DESCRIPTION
poll_id
uint64
1
The unique identifier of the poll.
creator
cosmos-sdk/types.AccAddress
kira1d52r...
The account address of the poll's creator.
title
string
some title
The title of the poll, limited to 128 characters as defined by the max_proposal_title_size network property.
description
string
some description
The description of the poll, limited to 1024 characters as defined by the max_proposal_description_size network property.
reference
string
Reference to the topic
Reference to the subject matter of the poll, potentially an IPFS CID or URL. Limited to 512 characters.
checksum
string
"Checksum value"
Checksum for the poll, ensuring data integrity. Limited to 128 characters.
roles
[]uint64
[1,2,3]
The roles that are eligible to participate in the poll.
options
PollOptions
"PollOptions object"
The list of available voting options in the poll.
voting_end_time
google.protobuf.Timestamp
1678386530
The timestamp indicating the end of the voting period for the poll.
result
string
POLL_RESULT_PASSED (1)
The result of the poll, updated after the voting period ends.
NAME
TYPE
EXAMPLE
DESCRIPTION
options.values
PollOptions
"PollOptions object"
The list of available voting options in the poll, each item limited to 64 characters as defined by the max_proposal_poll_option_size network property.
options.count
int
5
The maximum number of voting options that a poll can have, as defined by the max_proposal_poll_option_count network property.
options.type
string
"string"
The type of the options, all user supplied or predefined options must match this type. Possible types: string, uint, int, float, bool.
options.choices
int
1
The maximum number of choices that a voter can select, default is 1.
Vote types
VOTE OPTION
DESCRIPTION
POLL_OPTION_EMPTY (0)
No-op vote option.
POLL_OPTION_ABSTAIN (1)
Councilor has no strong opinion on the proposal, but wants to signify that they took note of it.
POLL_OPTION_CUSTOM (2)
Councilor has voted one or several custom option provided by the proposal.
POLL_OPTION_NO_WITH_VETO (3)
Councilor strongly disagrees with the poll and wants to prevent it from passing successfully, bypassing the majority vote requirements due to concerns highly impacting network operations or safety.
Polls status
STATUS
DESCRIPTION
POLL_RESULT_UNKNOWN (0)
Result of the proposal is not yet known/defined.
POLL_RESULT_PASSED (1)
Poll reached quorum with one of the options having majority votes and passed successfully.
POLL_RESULT_REJECTED (2)
Proposal was rejected because abstain votes have majority or more than one options.values have the highest and same number of votes (indecisive result).
POLL_RESULT_REJECTED_WITH_VETO (3)
Poll reached quorum but did not pass due to the rejection of >50% veto votes.
POLL_PENDING (4)
Poll is not finalized yet and is still awaiting votes.
POLL_RESULT_QUORUM_NOT_REACHED (5)
Poll was rejected because it failed to reach quorum?
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