Skip to main content

Roles & Permissions

Overview​

KIRA governance system utilizes a combination of Roles & Permissions to create a multi-layered governance structure that enables a diverse range of councilors to participate and contribute to the network's decision-making processes. The system operates with just two rules enabling it to bootstrap and evolve almost any imaginable governance model. The rules state that :

  • Only whitelisted actors can execute on-chain actions (submit transactions of a given type).
  • Whitelisted actors can only execute on-chain actions that they have been given the permission to execute.

For example, a multicameral system can be created where subsets of councilors specialize in creating and voting on specific subsets of proposals. Alternatively, a separation of power through checks and balances can be implemented, preventing a single governance branch from achieving a privileged position. Overall, the KIRA governance system is designed to be flexible and adaptable, allowing it to constantly improve its efficiency and decentralization without relying on factors such as wealth or stake distribution. This makes it an effective tool for ensuring that network actors are motivated and aligned towards common goals, which is crucial for achieving consensus within the network.

Permissions​

In KIRA network, every type of transaction that can be sent to SEKAI has a unique permission identifier associated with it and there exist two types of permissions: governance permissions and sudo permissions. Governance permissions allow changes to be made through a governance proposal process, and is always associated with two permissions: proposal creation and voting. Sudo permissions, on the other hand, allow users to make changes directly, bypassing any governance proposal. These permission identifiers can be added to the whitelist or blacklist of an individual KIRA account or a role — more on this in the following section. If the permission identifier is on the account's whitelist, the account is able to send the corresponding transaction to the blockchain. If the identifier is not on the account's whitelist or is on its blacklist, the account is not able to send the transaction, with the exception of MsgSend, and MsgMultiSend transactions. For example, if you want to allow a KIRA account to claim a validator seat on the blockchain, you must add the 2[broken link] permission to its whitelist. Only then will the account be able to use the claim-validator-seat CLI command to send the MsgClaimValidator transaction.

Roles​

To make it easier to manage hundreds of different permissions, KIRA uses a concept of roles. A role is a collection of permissions that can be associated to a specific KIRA address. This allows the network to manage the permissions of all addresses associated with a role at once, rather than having to change permissions for each individual address. Each permission assigned to a role or individual address can have its own defined parameters, which can be used as input for the function that is triggered when a network actor submits a particular type of transaction. These parameters allow for more granular control of permissions, ensuring that the responsibilities and power of individual network actors can vary widely within the governance model. If the permissions associated with a role are changed, the permissions of all accounts that have been assigned that role will also be changed. Roles can be assigned either by a group of governance members with the appropriate permissions 22[broken link] and 23[broken link], or by a sudo member 9[broken link] .

Role & Account Permission Conflicts​

Permissions in the KIRA governance system can be managed at both account and role levels, each with separate whitelists and blacklists. Within the same type (account or role), a permission cannot be present on both the whitelist and the blacklist. In other words, if a permission is on a role's blacklist, it cannot be added to the role's whitelist, and vice versa. The same rule applies to account whitelists and blacklists.

It is important to note that conflicting permissions between account and role levels are possible. In cases where conflicts arise between an account's and a role's whitelists and blacklists, the blacklisted permissions always take precedence. This means that if a permission is blacklisted at either the account or role level, the user will be denied that permission, regardless of any whitelists.

tip

Suppose a user has permission 10[broken link] whitelisted on their account and is also assigned to a role that has permission 10[broken link] blacklisted. In this case, the user will be denied permission 10[broken link], as the blacklisted permission takes precedence over the whitelisted permission.

Parameters​

Permissions​

Existing permissions and their correspond types and identifiers are listed here, or in the following page:

Roles​

NAMETYPEEXAMPLEDESCRIPTION
idint1Identification number of the role - auto assigned
sidstringsome nameUnique identification name of the role
descriptionstringsome textDescription of the role

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​

role create roleCreate a new role with permissions.
role assignAssign a role to an account.
role unassign roleRemove a role from an account.
role blacklist-permissionBlacklist a permission for a role.
role remove-whitelisted-permissionRemove a whitelisted permission from a role.
role remove-blacklisted-permissionRemove a blacklisted permission from a role.
role whitelist-permissionWhitelist a permission for a role.
permission whitelistAssign a permission to an account's whitelist.
permission blacklistAssign a permission to an account's blacklist.
permission remove-whitelistedRemove a whitelisted permission from an account.
permission remove-blacklistedRemove a blacklisted permission from an account.

Create Role​

Create a new role with sudo permissions using the create command followed by the role's unique identifier $ROLE_SID and a description $ROLE_DESCRIPTION.

Variables

  • $ROLE_SID: Unique string identifier for the role.
  • $ROLE_DESCRIPTION: A brief description of the role.
sekaid tx customgov role create role \
--from=$SIGNER $FLAGS_TX \
$ROLE_SID $ROLE_DESCRIPTION

Assign Role​

Assign a role with sudo permissions to an account using the assign command followed by the role's identifier $ROLE_ID.

Args

  • $ROLE_ID: The unique identifier of the role to be assigned.

Flags

  • $TARGET_ADDRESS: The target address to which the role will be assigned.
sekaid tx customgov role assign \
--from=$SIGNER $FLAGS_TX \
$ROLE_ID --addr=$TARGET_ADDRESS

Remove Role​

Remove a role with sudo permissions from an account using the remove role command followed by the role's identifier $ROLE_ID.

Args

  • $ROLE_ID: The unique identifier of the role to be removed.

Flags

  • $TARGET_ADDRESS: The target address from which the role will be removed.
sekaid tx customgov role remove role \
--from=$SIGNER $FLAGS_TX \
$ROLE_ID --addr=$TARGET_ADDRESS

Whitelist Role Permission​

Whitelist a permission to a role with sudo permissions using the whitelist-permission command followed by the role's identifier $ROLE_ID and the permission's identifier $PERMISSION_ID.

Args

  • $ROLE_ID: The unique identifier of the role.
  • $PERMISSION_ID: The unique identifier of the permission to be whitelisted.
sekaid tx customgov role whitelist-permission \
--from=$SIGNER $FLAGS_TX \
$ROLE_ID $PERMISSION_ID

Blacklist Role’s Permission​

Blacklist a permission for a governance role with sudo permissions using the blacklist-permission command followed by the role's identifier $ROLE_ID and the permission's identifier $PERMISSION_ID.

Args

  • $ROLE_ID: The unique identifier of the role.
  • $PERMISSION_ID: The unique identifier of the permission to be blacklisted.
sekaid tx customgov role blacklist-permission \
--from=$SIGNER $FLAGS_TX \
$ROLE_ID $PERMISSION_ID

Remove Role’s Whitelisted Permission​

Remove a whitelisted permission from a governance role with sudo permissions using the remove-whitelisted-permission command followed by the role's identifier $ROLE_ID and the permission's identifier $PERMISSION_ID.

Args

  • $ROLE_ID: The unique identifier of the role.
  • $PERMISSION_ID: The unique identifier of the whitelisted permission to be removed.
sekaid tx customgov role remove-whitelisted-permission \
--from=$SIGNER $FLAGS_TX \
$ROLE_ID $PERMISSION_ID

Remove Role’s Blacklisted Permission​

Remove a blacklisted permission from a governance role with sudo permissions using the remove-blacklisted-permission command followed by the role's identifier $ROLE_ID and the permission's identifier $PERMISSION_ID.

Args

  • $ROLE_ID: The unique identifier of the role.
  • $PERMISSION_ID: The unique identifier of the blacklisted permission to be removed.
sekaid tx customgov role remove-blacklisted-permission \
--from=$SIGNER $FLAGS_TX \
$ROLE_ID $PERMISSION_ID

Whitelist Account Permission​

Assign permission to a Kira address whitelist with sudo permissions using the whitelist command.

Flags

  • $ADDRESS: The address for which permissions should be set.
  • $PERMISSION: The permission value to be assigned.
sekaid tx customgov permission whitelist \
--from=$SIGNER $FLAGS_TX \
--addr=$ADDRESS --permission=$PERMISSION

Remove Account Whitelisted Permission​

Remove whitelisted permission from an address with sudo permissions using the remove-whitelisted command.

Flags

  • $ADDRESS: The address from which permissions should be removed.
  • $PERMISSION: The permission value to be removed.
sekaid tx customgov permission remove-whitelisted \
--from=$SIGNER $FLAGS_TX \
--addr=$ADDRESS --permission=$PERMISSION

Blacklist Account’s Permission​

Assign permission to a Kira account blacklist with sudo permissions using the blacklist command.

Flags

  • $ADDRESS: The address for which permissions should be set.
  • $PERMISSION: The permission value to be assigned.
sekaid tx customgov permission blacklist \
--from=$SIGNER $FLAGS_TX \
--addr=$ADDRESS --permission=$PERMISSION

Remove Account’s Blacklisted Permissions​

Remove blacklisted permission from an address with sudo permissions using the remove-blacklisted command.

Flags

  • $ADDRESS: The address from which permissions should be removed.
  • $PERMISSION: The permission value to be removed.
sekaid tx customgov permission remove-blacklisted \
--from=$SIGNER $FLAGS_TX \
--addr=$ADDRESS --permission=$PERMISSION