# Miyabi Access Control

# Overview

In Miyabi, access control can be managed at these levels:

  • system access control layer: Provides a way to manage the access to do operations on Miyabi world state.
  • table access control layer: Provides a way to manage the access to user defined tables in Miyabi.

# System Access Control Level

System permissions represent the permissions to manage the high level world state operations. Miyabi core needs certain set of permissions to manage the world state. Miyabi modules, which extend node functionality, may need their own set of permission hierarchies to be able to manage operations. For example, permission to change the blockchain configuration, permission to create new tables in world state, etc. The system permissions are stored in the system permission table in the world state. The SystemPermission includes the following:

# World Permission

Addresses with world permission can make core system level changes to Miyabi. WorldPermission consists of the following level access.

  • Root: It represents the top level of permission. By default, world admins in the blockchain configuration will be granted the root permission. An address can only be granted with either the Root permission or some other permission.
  • CreateTable: Represents the permission required to create a new table in Miyabi.
  • ChangeConfig: Represents the permission required for updating system-wide configurations , e.g., updating the blockchain configuration parameters.
  • GrantCreateTable: Represents the permission required to grant the CreateTable access to other addresses.
  • All: Cumulative of the CreateTable, ChangeConfig, and GrantCreateTable permissions.

# Module Permission

In Miyabi each module can have its own customized permission hierarchy. The actual access control level management and implementation are left to the module implementation. Modules can register the set of permission levels just like world permission.

An example of one such module permission is used by the Contract module and is defined as ContractPermission

  • ContractPermission - A type of module permission used to define access control to addresses to the smart contract functions
    • None: Represents no permission
    • Deploy: Represents the permission to deploy a smart contract on Miyabi.
    • GrantDeploy: Represents the permission to grant and revoke the Deploy contract permission to other addresses. Only addresses with Root world permission can grant/revoke the GrantDeploy contract permission.
    • All: Represents cumulative of Deploy and GrantDeploy contract permissions.

# Custom Table Access Control Level

The permissions for the custom tables in Miyabi are mainly governed by the permission model of the table. The table permission checks and the row permission checks are orthogonal to each other. A combination of these permission checks constitutes the permission model of the custom table and governs various access control behaviors.

# Permission Model

Each custom PermissionedTable is associated with a PermissionModel which represents the permission checks that have to be performed while performing CRUD operations on table data. There is a flag ReadRestricted which if enabled checks for the PermissionModel while reading a table. The various available PermissionModel in Miyabi are

  • PermissionLess - No permission checks will be applied.
  • CheckRowOnly - Row level permission check is activated.
  • CheckTableOnly - Table level permission check is activated.
  • TableOrRow - Both table level permission check and row level permission check are activated, at least one permission check must be passed.
  • TableAndRow - Both table level permission check and row level permission check are activated, all permission check must be passed.

# Row Permissions

The row permission checks are done against the row owners of a permissioned table. The default behavior for a row without owner is that the permission checks are passed. Otherwise, depending on the permission model of the table, if the row permission checks are required, then the presented credentials are validated against the row owner addresses.

# Table Permissions

The table level permission checks are mainly governed by the table access control list. Additionally, the Miyabi modules can define custom logical permissions, e.g., TokenAdmins in token type of tables.

# Custom Table Permission

The custom table permission represents the permission required for the insert, update (includes delete) and read operations for a custom table. This permission validation is triggered if the permission model requires table permission check. Following are the permissions defined under the custom table permissions:

  • None: No permission
  • Insert: Table permission to insert
  • Update: Table permission to update
  • Read: Table permission to read
  • All: Cumulative of Insert, Update, Read custom table permissions
# Table Access Control List

All custom tables in Miyabi are permissioned tables and have a table access control list associated with them. This TableAccessControlList consists of the following members:

  • TableOwners - The set of table owner addresses (Only the table owner can grant or revoke permissions for addresses on the TableAccessControlList)
  • Permissions - A key-value pair of addresses and the corresponding CustomTablePermission(Read, Insert, and Update) associated with that address
  • MultiKeyPermissions - A key-value pair of multisig addresses and the corresponding CustomTablePermission(Read, Insert, and Update) associated with that address
  • GrantedAddresses - An aggregation of the Permissions and MultiKeyPermissions. If the table level permission of one action is checked, only the addresses stored in GrantedAddress can pass the validation. If a certain operation requires table level permission, then only the table owner or the address with correct permission under the GrantedAddresses can perform that action.

# Miyabi Table Types

Tables

The table descriptors contain properties and metadata associated with key-value tables. The above diagram demonstrates how tables/table descriptors are classified in Miyabi. All table descriptors inherit from the base TableDescriptor.

  • System Table (SystemTableDescriptor) - This table stores Miyabi system related information.
  • Range List Table(RangeListTableDescriptor) - This base table supports fetching value by key and height.
    • Blockchain Parameters Table (BlockchainParametersTableDescriptor) - This table stores the blockchain parameters from the blockchain configuration at various heights
    • Consensus Credentials Table(ConsensusCredentialsTableDescriptor) - This table stores the credentials for the consensus members at various heights.
  • Permissioned Table (PermissionedTableDescriptor) - This base table has additional permission checks such as TableAccessControlList, IsReadRestricted, and PermissionModel. Custom Tables can be created as Permissioned Tables
    • Token Table (TokenTableDescriptor) - Token tables define token admin and trusted addresses for token logic.
      • Asset Table (AssetTableDescriptor) - This type of token table stores fungible tokens (value representable as decimals) values mapped to address keys
      • NFT Table (NFTTableDescriptor) - This type of token table stores addresses and NFT respective tokens
    • Binary Table (BinaryTableDescriptor) - A generic table type that stores hex key-value pairs
    • Entity Table (EntityTableDescriptor) - This table stores data in the form of a relational document type structure
    • PrivateData Table (PrivateDataTableDescriptor) - This table stores the proof of the private data shared between private data owners(PDOs).

# Miyabi Table Properties

The below table describes the properties associated with Miyabi tables

Parameters Type Description Present in Table type
Name string Unique name for the table All
Tracked bool Track the history of table changes All
SupportProofs bool Allow generation of verifiable proof for the data All
TableACL TableAccessControlList Defines the table owner and other addresses' table level permissions Permissioned
IsReadRestricted bool Defines if read permission should be checked or not Permissioned
PermissionModel PermissionModel Defines how permission should be checked when performing CRUD operations on the contents of this table Permissioned
TokenAdmins List of Addresses Addresses that can mint as well as move tokens, only table owners can grant token admins Asset, NFT
TrustedEntities List of Addresses Addresses who can move assets to themselves without the asset owner signature, only table owners can grant trusted entities Asset, NFT

# Permission Commands

Miyabi comes with some inbuilt commands to update Miyabi related permissions.

  • UpdateWorldPermissionCommand - Grant or revoke the world permission to addresses. Only addresses with Root world permission can successfully execute this command. Additionally, addresses with GrantCreateTable world permission can grant the CreateTable world permission.
  • AddTableOwnersCommand - Add table owners to a table. Only the existing table owner can successfully execute this command.
  • RemoveTableOwnersCommand - Remove table owners from a table. Only the existing table owner can successfully execute this command.
  • AddTokenAdminsCommand - Add token tables to a token table. Only the existing table owner can successfully execute this command.
  • RemoveTokenAdminsCommand- Remove token tables from a token table. Only the existing table owner can successfully execute this command.
  • AddTrustedEntitiesCommand- Add trusted entities to a token table. Only the existing table owner can successfully execute this command.
  • RemoveTrustedEntitiesCommand- Remove trusted entities from a token table. Only the existing table owner can successfully execute this command.

←