# Table
# The Features of Table
Miyabi uses module tables to manage data in the world state like in most database software. Miyabi stores the world state by tables while keeping all the blocks as a record of all transactions. Each table has a unique table name for identification. The fundamental structure of the table is the Key-value pair, where the key is unique for searching values.
Each table maintains a table descriptor. A table descriptor contains a table name and two Boolean flags for the feature. One flag indicates whether to generate state proof or not and the other controls the table history tracking.
In Miyabi, the table has been defined according to the value they have stored: Asset Table stores the balance of each address; Binary Table stores arbitrary value for arbitrary keys; Entity Table contains the entity and its relationship with other entity by Id; NFT Table stores the owner of each nonfungible token. Private Data Table stores the evidence of private data only stored in specific nodes.
# Permissions Related to Tables
# Table Level Permission
Each module table has table-level permission, which is defined through the TableAccessControlList in the permissioned table descriptor. A TableAccessControlList must have a non-empty list of addresses for the table owner, who can delete this table and grant permissions to other addresses. Other than table owners, there is a collection GrantedAddress , which stores the CustomTablePermissiongranted to various addresses. The CustomTablePermission includes insert, update, and read three permissions. If the table level permission of one action is checked, only the addresses stored in GrantedAddress can pass the validation.
# Row Level Permission
Each module table needs to define row-level permission for each row to read and update(delete). A row-level check function is explicitly required for all module tables. A PermissionModel is defined to control how the permission is checked for operations toward rows:
| Permission Model | Behavior |
|---|---|
| Permission less | No check |
| Check row only | only need to pass row check |
| Check table only | Only need to pass table level check |
| Table or row | Either table level check or row level check should pass |
| Table and row | Both table level check and row level check should pass |
To be noticed, insert permission belongs to the table. Hence if a table use CheckRowOnly models, any address can create a new row, but only row owners, if defined, can update it.
# Read Restricted
A read restricted Boolean is presented to control the read permission check for each row. If a table is not read restricted, read permission will not be checked no matter which permission model is selected. Otherwise, read operation will trigger permission checks like insertion or updating.
# Token Table Permission
Token table(Asset Table and NFT Table) has two additional roles: TokenAdmins and TrustedEntities(AKA TrustedAddress). Token admin can generate tokens, while TrustedEntities can withdraw any tokens from any user address to its address. Only table owners can grant these two roles to an address.
# Permissioned Table Descriptor
All module table descriptors inherits from a permissioned table descriptor. It defines following properties:
| Parameters | Type | description |
|---|---|---|
| TableACL | TableAccessControlList | Defines the table owner and other addresses' table level permissions |
| Name | string | Unique name for the table |
| Tracked | bool | Track the history of table changing |
| SupportProofs | bool | Allowing generating the proof of an entry that can be verified by state proof |
| IsReadRestricted | bool | Defines if read permission should be checked or not |
| PermissionModel | PermissionModel | Defines how permission should be checked when updating the contents of this table |
# Table Interfaces
Tables are exposed through the following interfaces in smart contracts. Each table can be exposed as a reader and writer according to the context and requirements. These interfaces are available in the related module models. (i.e. Miyabi.Asset.Models)
 |
|---|
| Table Interfaces |
# Asset Table
# Basic Information
The asset table is the table designed for recoding decimal assets like digital coins. In the asset table, the key is the public key of the asset owner, and the value is a number of assets in decimal.
| Field | Description |
|---|---|
| Key | address of the asset owner |
| Value | amount of assets owned by asset owner |
An asset table descriptor needs following parameters in addition to general table descriptors.
| Parameters | Type | description |
|---|---|---|
| TokenAdmins | IReadOnlyList<Address> | Addresses that can mint token |
| TrustedEntities | IReadOnlyList<Address> | Addresses that can withdraw token from other addresses |
| Rules | Validation Rule | Restrictions to the table, which will be examined by an independent verifier Kotowari |
| VoidAddress | Address | Address that is kept as a source of tokens. |
| Granularity | AssetGranularity | Includes the maximum, minimum as well as the unit of value for each move. By default, they are ( |
# Validation Rule
The validation rule is some policies set for a table. Whenever a transaction tries to access an asset table, Kotwari will check if the operation to table violates the validation rules. If the validation failed, all changes introduced by this transaction will be discarded.
| Rule | Description |
|---|---|
| Sum equal zero (default) | The sum of all values in the table should be zero. E.g. balance sheet |
| No Negative (default) | All value should not be negative. E.g. bank account deposit |
| Prevent Admin Trusted (default) | Prevent table owner move asset from arbitrary address |
| Prevent Trusted Withdrawals | Prevent trusted address move asset from arbitrary address to their address |
Each table will reserve one void address, which can only be touched by token admins, to mint tokens. The void address can pump out infinity tokens, and send them to any addresses. The void address is the only address can have negative value under No Negative rule. According to the Sum Equal Zero rule, Kotowari only need to checks
The basic operations on the asset table are moving assets from one address to another address. Usually, move assets from one address require the signature of that address. Token admin can move an arbitrary asset from void address to arbitrary address if prevent admin trusted is not applied. The trusted address can withdrawal assets from arbitrary addresses except for the void address. Besides, a smart contract can use its instance ID to create an asset table and only the smart contract can modify its entry.
# Examples
Here provides a simple example (Figure 11) for using asset tables includes:
- Create an Asset table
- Generate assets from void address
- Move assets to another address
If No Negative rule is applied, all addresses other than the void address cannot have a negative value. Hence, the table owner will generate assets by moving assets from the void address which requires asset admin permission. For moving assets, either the signature of the source address is provided or the trusted address has signed the transaction. If Prevent Admin Trusted is not applied, the admin signature can also withdraw assets from arbitrary addresses.
 |
|---|
| Figure 11. Example of Asset table usage |
# Permission Model of Asset Table
For an asset table, the row permission check cannot be skipped. Hence, only CheckRowOnly and TableAndRow are allowed as the permission model. For TableAndRow model asset table, two additional operations are allowed called RegisterAccount and DeleteAccount. These two operations are defined in IPermissionedAssetTableWriter which allows creating a new row for a specific address with 0 balance. This operation is not needed in CheckRowOnly model because a row can be insert or deleted whenever someone transfers tokens to that address or the balance of the address return to 0. However, in the TableAndRow model, a row cannot be created or deleted without insert or update permission.
# NFT Table
# Basic Information
A non-fungible token (NFT), is a special type of asset, which represents something unique. In Miyabi, we implement a NFT module to support NFT. NFT table stores a token Id as key and its owner as of the value.
| Field | Description |
|---|---|
| Key | Token ID of NFT |
| Value | Address of Owner. |
An NFT table descriptor needs following in addition to general table descriptors.
| Parameters | Type | description |
|---|---|---|
| TokenAdmins | IReadOnlyList<Address> | Addresses that can mint token |
| TrustedEntities | IReadOnlyList<Address> | Addresses that can claim arbitrary token |
NFT table supports [ERC-721][http://erc721.org/] and provide a set of address to be trusted address like asset table. Only TokenAdmins can mint NFT and only the token owner can move the token. In addition, TrustedEntities can change an arbitrary token's owner to itself.
Currently, the balance of an address is the number of tokens it owned. NFT table has implemented an inner table optimization for speeding up checks of the balance of one address.
# Binary Table
# Basic Information
A binary table is a simple permissioned data table. In a binary table, key and value are byte strings. The value is stored within a PermissionedData together with a list of addresses who is treated as the owner of this row. If there is no owner for a row, the row permission check will always return true.
| Field | Description |
|---|---|
| Key | Arbitrary byte string |
| Value | Arbitrary byte string |
BinaryTableDescriptor has the same definition as PermissionedTableDescriptor
Binary tables support a special operation called UpsertRow, which will insert a row if it is not existed, otherwise update it with the new value. The permissions to be checked depending on the actual behavior is insert or update.
# Entity Table
# Basic Information
An entity table is an extended binary table optimized for storing the relationships between different entries. Each entry may link to multiple parent entries and multiple children entries to form a graph across entity tables. The storage rule and command for creating tables are the same as the binary table.
An entity table supports creating a link between different entity values in different entity tables. These links can be used to split data into pieces for complex management likes:
Grant permission arbitrarily small
Like binary tables, each row has row owners. Since an entity table allows links to manage different rows, the user can divide one binary value into several rows and grant them to different owners.
Store notes of a specific row
Users can create rows to store notes of another row and add the row as the parent of the note rows.
Optimize update only a part of a row
According to the frequency of updating data, one user can split data into different tables and use different keys to manage the update process. The integrity of the data is guaranteed by links. One link has two components
Item Description Parent the table name and key of the parent row Tag text marked this code When one link is created, Miyabi will automatically add several rows to store the link. A parent row contains all pointers to the parents row of the child row, and the child rows save the pointers to children of this row under the same tags. These automatically created rows will be permissioned rows whose owner is the owner of the child row.
# Example for Entity Table
Figure 12 shows an example of the entity table's structure.
 |
|---|
| Figure 12. Example of Entity Table's Structure |