KIRA Utilizes Roles & Permissions for the purpose of managing and scaling its governance system.
Permissions
Every transaction type that can be sent on-chain has associated with it unique permission identifiers. Each KIRA account can have said identifiers assigned to its individual account permissions whitelist or blacklist. If the permission identifier is assigned to the KIRA account whitelist then the account has the ability to execute associated with it functions. If the permission identifier is NOT assigned to the KIRA account or if its assigned to its to a blacklist then the account is NOT able to send a corresponding message on-chain, with exception for MsgSend, MsgMultiSend & MsgSubmitEvidence. For example in order for the KIRA account to be able to claim a validator seat it must have a whitelisted PermClaimValidator permission (2), only then it will be possible for said account to call MsgClaimValidator.
Permission can only be blacklisted if its NOT whitelisted and vice versa it is NOT possible to whitelist a permission if it is blacklisted. Permissions can also be removed from the account blacklist / whitelist via dedicated proposal.
NOTE: Both permissions and roles are identified thought positive integer values to save space & computational resources, that's why when querying account permissions the result should be a list of blacklisted/whitelisted integers rather than explicit strings. List of all available permissions and their corresponding identifiers can be found here
Permissions can be assigned by a set of governance members with permissions PermWhitelistAccountPermissionProposal (4) and PermVoteWhitelistAccountPermissionProposal (5) enabling for creation and voting via corresponding proposal, or by the account with a "sudo" permission, that is PermSetPermissions (1).
Roles
It is very difficult to manage hundreds of permissions assigned to hundreds of different accounts, to manage that, collection of permissions can be associated with "roles", then those roles can be assigned to the individual KIRA accounts. If the permissions associated with the specific role changes then the permissions of all accounts to which that specific role is assigned change. Roles just like KIRA accounts have a permissions whitelist and blacklist. Blacklists always override the whitelists thus if user has a whitelisted permission and role with the same permission blacklisted then the blacklist takes priority.
Roles can be assigned by a set of governance members with permissions PermCreateRoleProposal (22) and PermVoteCreateRoleProposal (23) enabling for creation and voting via corresponding proposal, or by the account with a "sudo" permission, that is PermUpsertRole (9).
Commands Examples
Whitelisting / Blacklisting Standalone Permission
# Whitelisting Permission via proposal
# CLI
# TODO
# KM
# TODO
# Blacklisting Permission via proposal
# CLI
# TODO
# KM
# TODO
# Whitelisting Permission as sudo
# CLI
sekaid tx customgov permission whitelist --permission="$PERM" --addr="$ADDR" \
--from "$ACCOUNT" --keyring-backend=test --chain-id=$NETWORK_NAME --home=$SEKAID_HOME --fees=100ukex --yes --broadcast-mode=async --log_format=json --output=json
# KM
# e.g: whitelistPermission validator 11 kiraXXX..YYY 180
whitelistPermission $ACCOUNT $PERM $ADDR
# Blacklisting Permission as sudo
# CLI
sekaid tx customgov permission blacklist --permission="$PERM" --addr="$ADDR" \
--from "$ACCOUNT" --keyring-backend=test --chain-id=$NETWORK_NAME --home=$SEKAID_HOME --fees=100ukex --yes --broadcast-mode=async --log_format=json --output=json
# KM
# e.g: blacklistPermission validator 12 kiraXXX..YYY 180
blacklistPermission $ACCOUNT $PERM $ADDR
Bash
Removing Standalone Permission from Blacklist / Whitelist
# Removing Permission from Blacklist via proposal
# CLI
# TODO
# KM
# TODO
# Removing Permission from Whitelist via proposal
# CLI
# TODO
# KM
# TODO
# Removing Permission from Blacklist as sudo
# CLI
sekaid tx customgov permission remove-blacklisted-permission --permission="$PERM" --addr="$ADDR" \
--from="$ACCOUNT" --keyring-backend=test --chain-id=$NETWORK_NAME --home=$SEKAID_HOME --fees=100ukex --yes --broadcast-mode=async --log_format=json --output=json
# KM
# e.g: clearPermission validator 12 kiraXXX..YYY
clearPermission $ACCOUNT $PERM $ADDR
# Removing Permission from Whitelist as sudo
# CLI
sekaid tx customgov permission remove-whitelisted-permission --permission="$PERM" --addr="$ADDR" \
--from="$ACCOUNT" --keyring-backend=test --chain-id=$NETWORK_NAME --home=$SEKAID_HOME --fees=100ukex --yes --broadcast-mode=async --log_format=json --output=json
# KM
# e.g: clearPermission validator 12 kiraXXX..YYY
clearPermission $ACCOUNT $PERM $ADDR
Bash
Creating Role
# Creating Role via proposal
# CLI
sekaid tx customgov proposal role create-role "$NAME" "$DESCRIPTION" --title="Upsert Governance Role '$NAME'" --description="Role description: '$DESCRIPTION'" \
--from "$ACCOUNT" --keyring-backend=test --chain-id=$NETWORK_NAME --home=$SEKAID_HOME --fees=100ukex --yes --broadcast-mode=async --log_format=json --output=json
# KM
# e.g. createRoleProposal <account> <role-name> <role-description>
createRoleProposal validator validator "Role enabling to claim validator seat and perform essential gov. functions"
# Creating Role as sudo
# CLI
sekaid tx customgov role create "$NAME" "$DESCRIPTION" \
--from "$ACCOUNT" --keyring-backend=test --chain-id=$NETWORK_NAME --home=$SEKAID_HOME --fees=100ukex --yes --broadcast-mode=async --log_format=json --output=json
# KM
# e.g. createRole validator validator "Role enabling to claim validator seat and perform essential gov. functions"
createRole <account> <role-name> <role-description>
Bash
Assigning / Remove Role
# Assign Role via proposal
# CLI
# TBD
# KM
# TBD
# Remove Role via proposal
# CLI
# TBD
# KM
# TBD
# Assigning Role as sudo
# CLI
sekaid tx customgov role assign "$ROLE_NAME" --addr="$ADDRESS" \
--from "$ACCOUNT" --keyring-backend=test --chain-id=$NETWORK_NAME --home=$SEKAID_HOME --fees=100ukex --yes --broadcast-mode=async --log_format=json --output=json
# KM
# e.g. assignRole <account> <role-name> <kira-address>
assignRole validator someRoleName "kiraXXX...XXX"
# Remove Role as sudo
# CLI
sekaid tx customgov role remove "$ROLE_NAME" --addr="$ADDRESS" \
--from "$ACCOUNT" --keyring-backend=test --chain-id=$NETWORK_NAME --home=$SEKAID_HOME --fees=100ukex --yes --broadcast-mode=async --log_format=json --output=json
# KM
# e.g. removeRole <account> <role-name> <kira-address>
removeRole validator someRoleName "kiraXXX...XXX"
Bash
Whitelisting / Blacklisting Role Permission
# Whitelisting Role Permission via proposal
# CLI
# TODO
# KM
# TODO
# Blacklisting Role Permission via proposal
# CLI
# TODO
# KM
# TODO
# Whitelisting Role Permission as sudo
# CLI
sekaid tx customgov role whitelist-permission "$ROLE" "$PERM" \
--from "$ACCOUNT" --keyring-backend=test --chain-id=$NETWORK_NAME --home=$SEKAID_HOME --fees=100ukex --yes --broadcast-mode=async --log_format=json --output=json
# KM
# e.g: roleWhitelistPermission validator "sudo" $PermVoteSoftwareUpgradeProposal 180
roleWhitelistPermission $ACCOUNT $ROLE $PERM
# Blacklisting Role Permission as sudo
# CLI
sekaid tx customgov role blacklist-permission "$ROLE" "$PERM" \
--from "$ACCOUNT" --keyring-backend=test --chain-id=$NETWORK_NAME --home=$SEKAID_HOME --fees=100ukex --yes --broadcast-mode=async --log_format=json --output=json
# KM
# e.g: roleBlacklistPermission validator "sudo" $PermVoteSoftwareUpgradeProposal 180
roleBlacklistPermission $ACCOUNT $ROLE $PERM
Bash
Query Permissions
# Query Permissions by Account
# CLI
sekaid query customgov permissions "$ADDRESS" --output=json --home=$SEKAID_HOM
# KM
# e.g: showPermissions kiraXXX...XXX, showPermissions validator
showPermissions $ADDRESS
# Query Permissions by Role
# KM
# e.g: showRolePermissions validator
showRolePermissions "validator"
Bash
Query Roles
# Query All Roles
# CLI
sekaid query customgov all-roles --output=json --home=$SEKAID_HOME
# KM
showRoles
# Query Roles of Specific Address
# CLI
sekaid query customgov roles $ADDRESS --output=json --home=$SEKAID_HOME
# KM
# e.g: showRoles kiraXXX...XXX, showRoles validator
showRoles $ADDRESS
Bash