Skip to main content

Councilors & governance ranking

Concept​

A KIRA account is considered a Councilor if it has at least one whitelisted Permission or Role that allows the creation of proposals or voting. Accounts with no Permissions/Roles or blacklisted Permissions/Roles are not considered Councilors. It is essential to note that having permissions or a role does not automatically imply being a councilor. Councilors are governance members who can collude to raise proposals or vote on said proposals. Sudo users (users with sudo permissions such as [Problem Internal Link] or [Problem Internal Link]) are not considered councilors in this context.

Councilor Seat​

:::📌

Sending a MsgClaimCouncilor transaction is only allowed if the status of the Councilor is waiting (see next section).

:::

Before any governance member can execute their right to create proposals or vote, they must first "claim" their Councilor Seat, similar to how consensus nodes claim their Validator Seat. This action acknowledges the network Code of Conduct and allows registering a KIRA user in the governance registrar. When submitting a MsgClaimCouncilor transaction using the claim-councilor-seat CLI, the user must supply the following information, which will be persisted in the Identity Registrar:

  • username - (required) friendly governance member name with minimum 4 non-whitespace characters. It is globally unique and cannot be deleted (just like consensus nodes’ moniker).
  • description - (optional) a longer description of the councilor
  • social - (optional) comma-separated URL list of any social profiles such as Twitter, Telegram, etc…
  • contact - (optional) email address, URL, or another emergency contact
  • avatar - (optional) URL to .SVG image or gif

Councilor Statuses​

Councilors have statuses that implies their ability to perform their role in creating proposals and voting.

STATUSDESCRIPTION
waitingDefault state after a permission to vote or create a proposal is assigned to the account for the first time. Implies account ability to send a MsgClaimCouncilor transaction to claim a Councilor Seat.
activeDefault state after sending a MsgClaimCouncilor transaction. Implies councilor ability to vote and create proposals.
inactiveCouncilor stopped voting on proposals and didn’t signal to the network any planned absence. As defined by the Ranking System (see section below).
pausedCouncilor signaled planned absence.
jailedCouncilor is barred from executing any of their permissions.

Ranking System​

note

The councilor's status automatically transitions to jailed if they are a consensus node and their node's status changes to jailed due to being detected double signing.

The Councilor ranking system is used to apply changes to statuses and collect statistics that can be utilized by the governance to determine which network actors fulfill their assigned roles. Note that the ranking of Councilors and Consensus nodes is totally independent and has separate logic. The ranking system is based on proposal creation and proposal votes counters. If the Councilor participates in voting or creates a proposal, their rank increases by 1 and the abstention counter is set to 0. If the Councilor fails to vote, their rank is decreased by abstention_rank_decrease_amount (defined in Network Properties), and abstention is increased by 1.

When the abstention counter equals or surpasses the max_abstention value (set in Network Properties), a Councilor becomes inactive. In this status, they can't vote or initiate proposals, and their rank drops to 0. However, their abstention count remains. To resume voting, an inactive councilor must send a MsgCouncilorActivate transaction, resetting their abstention count to zero.

note

Keep in mind, governance can tailor transaction fees for each existing message type through the Fee processing module. This means they might impose a higher fee for MsgCouncilorActivate to act as a penalty.

Pause Raking​

To prevent the status from becoming inactive while being absent for prolonged periods of time, Councilors can submit a MsgCouncilorPause transaction, which changes their status to paused. In the paused state, the abstention counter does not change, and the rank is not automatically reset, but the Councilor cannot vote or create proposals. To exit the paused status, a Councilor must submit a MsgCouncilorUnpause transaction, but the abstention is not reset as a result.

The rank is reset to 0 if the Councilor's status changes to jailed. In the jailed status, a Councilor cannot vote and create proposals unless the Validator is unjailed by the governance, in which case the Councilor's status changes to inactive.

Reset Ranking​

It may be useful for the governance to have the ability to reset all ranks and abstention counters of all governance members simultaneously (e.g., incentivized games, etc.). For this purpose, the governance module has a dedicated proposal and corresponding voting permission.

Parameters​

NAMETYPEEXAMPLEDESCRIPTION
addresscosmos-sdk/types.AccAddresskira1zcjdw...The account address of the councilor.
statusstringactiveThe current status of the councilor.
rankint64112The current rank of the councilor
abstentionint6410The current number of times the councilor missed to vote for a proposal for which it has the permission to vote for.

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. $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 section

Transactions​

councilor claim-seatClaim a councilor seat.
councilor pauseSignal an absence as a councilor.
councilor unpauseSignal re-availability as a councilor.
councilor activateActivate councilor status previously deactivated due to excessive abstention.

Claim Councilor Seat​

Claim a councilor seat using the claim-seat command.

Flags

$ADDRESS: The address of the councilor.

$MONIKER: The moniker of the councilor.

$USERNAME: The username of the councilor.

$DESCRIPTION: The description of the councilor.

$SOCIAL: The social media handle of the councilor.

$CONTACT: The contact details of the councilor.

$AVATAR: The avatar of the councilor.

sekaid tx customgov councilor claim-seat \
--from=$SIGNER $FLAGS_TX \
--address=$ADDRESS --moniker=$MONIKER --username=$USERNAME \
--description=$DESCRIPTION --social=$SOCIAL --contact=$CONTACT --avatar=$AVATAR

Pause Councilor​

Signal to the network that you will not be present for a prolonged period of time using the pause command.

sekaid tx customgov councilor pause \
--from=$SIGNER $FLAGS_TX

Unpause Councilor​

Signal to the network that you wish to regain voting ability after planned absence using the unpause command.

sekaid tx customgov councilor unpause \
--from=$SIGNER $FLAGS_TX

Activate Councilor​

Signal to the network that Councilor wishes to regain voting ability using the activate command.

sekaid tx customgov councilor activate \
--from=$SIGNER $FLAGS_TX