Councilors & governance ranking
Overview
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 2[broken link] or 3[broken 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).
Once a councilor seat is claimed, the username cannot be modified!
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 modified or deleted.moniker- (required)description- (optional) a longer description of the councilorsocial- (optional) comma-separated URL list of any social profiles such as Twitter, Telegram, etc…contact- (optional) email address, URL, or another emergency contactavatar- (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.
| STATUS | DESCRIPTION |
|---|---|
waiting | Default 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. |
active | Default state after sending a MsgClaimCouncilor transaction. Implies councilor ability to vote and create proposals. |
inactive | Councilor stopped voting on proposals and didn’t signal to the network any planned absence. As defined by the Ranking System (see section below). |
paused | Councilor signaled planned absence. |
jailed | Councilor is barred from executing any of their permissions. |
Ranking System
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.
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
| NAME | TYPE | EXAMPLE | DESCRIPTION |
|---|---|---|---|
address | cosmos-sdk/types.AccAddress | kira1zcjdw... | The account address of the councilor. |
status | string | active | The current status of the councilor. |
rank | int64 | 112 | The current rank of the councilor |
abstention | int64 | 10 | The current number of times the councilor missed to vote for a proposal for which it has the permission to vote for. |
CLI Syntax & Examples
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 CLI Guide page.
- Transactions
- Queries
- Governance
Transactions
councilor claim-seat | Claim a councilor seat. |
|---|---|
councilor pause | Signal an absence as a councilor. |
councilor unpause | Signal re-availability as a councilor. |
councilor activate | Activate 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
Queries
councilors | Query all councilors, including their statuses, ranks, and abstention counters. |
|---|---|
non-councilors | Query all governance members that are not councilors. |
council-registry | Query the governance registry by address or moniker. |
proposer-voters-count | Query separate counts for proposers and voters who can create or vote on at least one type of proposal. |
Query Councilors
Query all councilors, waiting or not, including their corresponding statuses, ranks & abstention counters.
sekaid query customgov councilors $FLAGS_QR | jq
Query Non-councilors
Query all governance members that are not councilors.
sekaid query customgov non-councilors $FLAGS_QR | jq
Query Council Registry
Query the governance registry. The registry can be queried by either address or moniker.
Flags
$ADDRESS: The address you want to query information.
$MONIKER: The moniker you want to query information.
sekaid query customgov council-registry \
--addr=$ADDRESS --moniker=$MONIKER \
$FLAGS_QR | jq
Query Proposer and Voters Count
Retrieve the count of accounts that can create a proposal (proposers) and the count of accounts that can vote on at least one type of proposal (voters).
sekaid query customgov proposer_voters_count $FLAGS_QR | jq
Governance
proposal-jail-councilor | Proposes to jail councilors for violating the network's rules |
|---|---|
proposal-reset-whole-councilor-rank | Proposes to reset the ranking of all councilors |
Jailing Councilors
Create a proposal to jail specific councilors using the proposal-jail-councilor command followed by councilor(s) $COUNCILORS.
Args
$COUNCILORS: List of councilors to be jailed, comma separated list of addresses.
Flags
$TITLE: The title of the proposal.
$DESCRIPTION: The description of the proposal, it can be a URL, some text, etc.
sekaid tx customgov proposal proposal-jail-councilor \
--from=$SIGNER $FLAGS_TX \
$COUNCILORS --title=$TITLE --description=$DESCRIPTION
Reset All Councilors Ranks
Create a proposal to reset all councilors rank using the proposal-reset-whole-councilor-rank command.
Flags
$TITLE: The title of the proposal.
$DESCRIPTION: The description of the proposal, it can be a URL, some text, etc.
sekaid tx customgov proposal proposal-reset-whole-councilor-rank \
--from=$SIGNER $FLAGS_TX \
--title=$TITLE --description=$DESCRIPTION
