# Table

# The Features of Table

Miyabi uses 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 fundamental table descriptor contains a table name and two bool options for the feature of generating state proof and track the history.

In Miyabi, the table has been defined according to the value they are stored: Binary table, Asset table is used for store binary and digital value. Permissioned table is a special interface that requires an access control model to be implemented. Entity table, permissioned binary, and permissioned asset table have implemented this interface.

Permission Table Description
Create Table All Tables The permission to create a Table
Delete Table All Tables The permission to delete a Table
Asset Admin Asset Table The permission to generate assets to any address from void address
NFT Admin NFT Table The permission to generate NFT token to any address
Trusted Asset table/NFT table The permission to decrease assets from any address
Insert Permissioned Table The permission to Insert a value to the table
Update Permissioned Table The permission to update a value on the table
ACL Permissioned Table The Permission to change other permission of the table

# Binary Table

# Basic Information

Binary table is the base of all tables. In binary table, Both key and value are stored as binary array.

Field Description
Key Arbitrary byte array
Value Arbitrary byte array

To create a binary table, the following parameters are needed:

Parameters Type description
Table Admin private Key Signing the transaction for granting the permission of creating table
Table Name string Unique name for the table
Track bool Track the history of table changing
Proofs bool Allowing generating the proof of an entry that can be verified by state proof

# Permissioned Binary Table

# Basic Information

Permission Binary Table add the access control model to the binary table. The data stored in permissioned binary table are same as binary table, and following parameters are needed for creating it.

Parameters Type description
Table Admin private Key Signing the transaction for granting the permission of creating table
Table Name string Unique name for the table
Track bool Track the history of table changing
Proofs bool Allowing generating the proof of an entry that can be verified by state proof
Table Owner public Key The address who has insert/update/ACL permission
Read restricted bool If the table can be read by users without update permission

# Permissioned Row Binary Table

# Basic Information

Permissioned Binary table is a specific permissioned binary table where the value bytes are wrapped within permissioned row.

Field Description
Key Arbitrary byte array
Value Arbitrary byte array wrapped by permissioned row

Permissioned Row is a wrapper that can wrap the value of data and specify a public key as the owner to the value. For a permissioned row value, the signature from the owner of the row or the update admin are needed for updating the value of the row.

# Asset Table

# Basic Information

Asset table is the table designed for recoding decimal assets like digital coins. In asset table, key is the public key of asset owner and value is the amount of asset in decimal.

Field Description
Key public key of asset owner
Value amount of assets owned by asset owner

An asset table need following parameters to be created.

Parameters Type description
Table Admin private Key Signing the transaction for granting the permission of creating table
Table Name string Unique name for the table
Table Owner public Key The owner of table who has asset admin permission on this table
Rules validation Rule Restrictions to the table, which will be examined by kotowari
Trusted Address public Key Trusted address that can withdraw value from other address, can be forbidden by validation rule.
Track bool Track the history of table changing
Proofs bool Allowing generating the proof of an entry that can be verified by state proof

# Validation Rule

Validation rule is some policies set for a table. Whenever an transaction try to access to an asset table, Kotwari will check if the operation to table violate the validation rules. If the validation is failed, all changes to the table triggered by this transaction will be dropped.

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

Since all table has the same initial value as zero, to avoid non-negative rules, the void address is used as a specific address that can only be touched by table owner and allowed to move arbitrary assets to other address. The void address can pump out infinity assets, it is more flexible than the mining system in bitcoin. Only the table owner can use this address to generate assets.

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. Table owner 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.

For sum equal zero rule, Kotowari does not check the table every time. Since the rule implies , Kotowari checks which is more easy to be implemented. In this situation, the absolute value of all address should be equal to the absolute value of void address on any cases.

# Examples

Here provides a simple example (Figure 11) for using asset tables includes:

  1. Create an Asset table
  2. Generate assets from void address
  3. Move assets to another address

If No Negative rule is applied, all addresses other than 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.

example_of_asset_table
Figure 11. Example of Asset table usage

# Permissioned Asset Table

# Basic Information

Permission asset table adds the access control model to the asset table, the table owner will be granted with all permissions initially. The data stored in the permissioned asset table are the same as the binary table, and the following parameters are needed for creating it.

Parameters Type description
Table Admin Private Key Signing the transaction for granting the permission of creating table
Table Name string Unique name for the table
Table Owner Public Key The address who has insert/update/ACL permission and asset owner
rules Validation Rule Restrictions to the table, which will be examined by Kotowari
Trusted Address Public Key Trusted address that can withdraw value from other address, can be forbidden by validation rule.
proofs bool Allowing generating the proof of an entry that can be verified by state proof
Track bool Track the history of table changing
Read restricted bool if the table can be read by users without update permission

In the permissioned asset table, if it is read restricted, only the asset owner and address with update admin can read the value. To move the asset, the signature from both update admin and asset owner/trusted address is required.

# Entity Table

# Basic Information

Entity tables are specific permissioned row binary tables that optimized for storing the relationships between different entries. The storage rule and command for creating tables are the same as the permissioned binary table.

Entity tables support creating a link between different entity values in the world state. This links can be used to split data into pieces for complex management likes:

  1. Grant permission arbitrarily small

    Like the permissioned row binary table, each row has a row owner. Since an entity table allows links to manage different rows, the user can divide one binary value to several rows and grant them to different owners.

  2. Store history of a specific row

    User can also use rows to store the history of one row and links them together which allows user to manage history more flexible.

  3. 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 two rows to store the link. One row is will store the parents row of the child row and another row will store the children of the parent row. These automatically created row will be permissioned row whose owner is the owner of the child row.

# Permissions for Entity Table

The permission table inherits the access control model from both the permission row table and the permission table. The following rules are applied:

| Operation   | Required Signature                                 |
| ----------- | -------------------------------------------------- |
| Update  Row | Row Owner or Update admin                          |
| Insert Row  | Insert Admin                                       |
| Read        | No(Not restricted) / Update Admin(read restricted) |

# Example for Entity Table

Figure 12 shows an example of the entity table's structure.

example_of_entity_table
Figure 12. Example of Entity Table's Structure

# 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. The Fundamental structure is a [Binary Table][#binary-table] that stores Token ID and its owner's Address.

Field Description
Key Token ID of NFT
Value Address of Owner.

To create NFT table following parameters are required.

Parameters Type description
Table Admin private Key Signing the transaction for granting the permission of creating table
Table Name string Unique name for the table
Table Owner public Key The owner of table who has NFT admin permission on this table
Trusted Address public Key Trusted address that can withdraw value from other address, can be forbidden by validation rule.
Track bool Track the history of table changing
Proofs bool Allowing generating the proof of an entry that can be verified by state proof

NFT table supports [ERC-721][http://erc721.org/] and provide a set of address to be trusted address like asset table. Only NFT admin can generate NFT and only the token owner can/ trusted address can move the token.

Currently, the balance of an address is the number of token it owned. NFT table has implemented an inner table optimization for checking the balance of one address by caching the balance of each address within table.

← Smart Contract →