Skip to main content

Polls

Overview

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.

Proposing & Voting Rights

For any users to initiate a Poll, the necessary permission, represented by the 66[broken link], must be directly assigned to their account or embedded within a Role associated with their account. This permission is automatically granted to Councilors upon claiming their Councillor Seat. Contrary to KIRA Proposals, Polls do not have a corresponding voting permission. Rather, the user submitting the proposal determines which roles can vote on the particular Poll by setting up a whitelist.

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: All whitelisted roles can cast a vote per poll. 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.
note

The poll minimum quorum percentage is the same as the proposal quorum, 33% by default and is configurable by governance via the vote_quorum network property.

The outcome of a Poll proposal is determined based on the following rules:

OutcomeCondition
PassedIf quorum is reached and more than 121\over 2 (>50%) of all votes are for any Custom options or Abstain.
RejectedIf quorum is reached and there is a tie for the highest vote count between two or more options (indicating an indecisive result), or if the sum of Abstain and NoWithVeto votes is more than or equal to 121\over 2 (>=50%) of all votes.
RejectedWithVetoMore than or equal to veto_threshold percentage of votes are veto.
QuorumNotReachedvote_quorum was not reached before the end of the poll.

Other Relevant Network Properties

The following network properties establish limits over some of the Poll parameters:

  • The max_proposal_poll_option_size denotes the maximum character size of an individual Poll option and is set at 64 by default.
  • The max_proposal_poll_option_count sets the maximum number of custom options a Poll can have and is set at 128 by default.
  • The max_proposal_reference_size is used to indicate the maximum reference size in the poll and has a default value set at 512.
  • The max_proposal_checksum_size represents the maximum checksum size in the poll and is set to default at 128.

Parameters

Polls Parameters

NAMETYPEEXAMPLEDESCRIPTION
poll_iduint641The unique identifier of the poll.
creatorcosmos-sdk/types.AccAddresskira1d52r...The account address of the poll's creator.
titlestringsome titleThe title of the poll, limited to 128 characters by default as defined by the max_proposal_title_size network property.
descriptionstringAre you the boss of me now?The description of the poll, limited to 1024 characters by default as defined by the max_proposal_description_size network property.
referencestringbafybeifiixdxq4cli6qxib5zfiky7rilb6k66f336nymj4jty6tdsiixreReference to the subject matter of the poll, potentially an IPFS CID or URL. Limited to 512 characters by default, by the max_proposal_reference_size network property.
checksumstringf5aca3b1fafffdcf22a30aafd3392e473592944da28515ae0a06afbc71c27b09Checksum for the poll, ensuring data integrity. Limited to 128 characters by default, by the max_proposal_checksum_size network property.
roles[]uint64[1,2,...]The roles that are eligible to participate in the poll.
optionsPollOptionsThe list of available voting options in the poll.
voting_end_timegoogle.protobuf.Timestamp1678386530The timestamp indicating the end of the voting period for the poll.
resultstringPOLL_RESULT_PASSED (1)The result of the poll, updated after the voting period ends.

PollOptions type

NAMETYPEEXAMPLEDESCRIPTION
values[]string["yes","no","maybe","I dont know", "can you repeat the question?"]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.
countint5The maximum number of voting options that a poll can have, as defined by the max_proposal_poll_option_count network property.
typestringstringThe type of the options, all user supplied or predefined options must match this type. Possible types: string, uint, int, float, bool.
choicesint1The maximum number of choices that a voter can select, default is 1.

Vote Options Id

VOTE OPTIONDESCRIPTION
POLL_VOTE_OPTION_UNSPECIFIED (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

STATUSDESCRIPTION
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 veto_threshold being reached.
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 vote_quorum.

CLI Syntax & Examples

note

Each CLI command and proposal process in KIRA requires specific permissions. These permissions must be added to the account's whitelist or obtained as sudo permissions for direct changes. Refer to the Roles & Permissions documentation for more details.

note

$SIGNER represents the transaction signer's account name or address. For instructions on setting common flags as environment variables, such as $FLAGS_TX and $FLAGS_QR, see the CLI Guide page.

Transactions

poll createInitiates the creation of a new poll.
poll voteCast a vote on an existing poll.

Create Poll

Create a new poll using the create command.

Flags

$TITLE: The title of the poll.

$DESCRIPTION: The description of the poll, it can be a URL, text, etc.

$REFERENCE: IPFS CID or URL reference to file describing the poll and voting options in depth.

$CHECKSUM: Reference checksum.

$OPTIONS: The options for the poll in the format variant1, variant2, ...

$ROLES: List of roles allowed to take part in the poll vote in the format role1, role2, ...

$COUNT: Maximum number of voting options that a poll can have.

$TYPE: Type of the options, all user supplied or predefined options must match its type.

$CHOICES: Define the maximum number of choices a voter can select.

$DURATION: The duration of the poll.

sekaid tx customgov poll create \
--from=$SIGNER $FLAGS_TX \
--title=$TITLE --description=$DESCRIPTION --reference=$REFERENCE --checksum=$CHECKSUM \
--options=$OPTIONS --roles=$ROLES --count=$COUNT --type=$TYPE \
--choices=$CHOICES --duration=$DURATION

Vote on a Poll

Cast a vote on an existing poll using the vote command.

Args

$POLL_ID: The ID of the poll you wish to vote on.

$POLL_OPTION: The option ID you are voting for.

Flags

$CUSTOM_VALUE: The custom poll value.

sekaid tx customgov poll vote $POLL_ID $POLL_OPTION \
--from=$SIGNER $FLAGS_TX \
--custom-value=$CUSTOM_VALUE