# Table
# The Features of Table
Miyabi uses tables to store data in a key-value structure.
Custom data in Miyabi is stored in permissioned tables in the World State.
Each table maintains a TableDescriptor, which defines the attributes of the table.
# Types of TableDescriptors
A TableDescriptor is a data structure used to store properties and metadata of a given table.
Figure 1 illustrates how TableDescriptor are classified in Miyabi.
All table descriptors inherit from the base TableDescriptor.
 |
|---|
| Figure 1. Types of TableDescriptors |
# TableDescriptor
The structure of the TableDescriptor contains the following properties.
| Parameters | Type | Description |
|---|---|---|
| Name | string | Unique name for the table |
| Tracked | bool | Tracks the detailed transaction history of table |
| SupportProofs | bool | Allows generating the proof of an entry that can be verified by state proof |
# SystemTableDescriptor
The System table stores Miyabi system related information.
The SystemTableDescriptor has the same definition as the base TableDescriptor.
# RangeListTableDescriptor
A RangeList table supports fetching value by key and height.
The RangeListTableDescriptor has the same definition as TableDescriptor.
# BlockchainParametersTableDescriptor
This table stores the blockchain parameters from the blockchain configuration at various heights.
The BlockchainParametersTableDescriptor has the same definition as RangeListTableDescriptor.
# ConsensusCredentialsTableDescriptor
This table stores the credentials for the consensus members at various heights.
The ConsensusCredentialsTableDescriptor has the following parameters in addition to RangeListTableDescriptor.
| Parameters | Type | Description |
|---|---|---|
| Admins | IReadOnlyList<Address> | List of consensus credential admins |
| MultiSigThreshold | int | Admins quorum threshold when a multisig address is used |
# Permissioned Table Descriptor
A permissioned table facilitates access control to users to perform CRUD operations on the table.
A PermissionedTableDescriptor inherits from the base TableDescriptor.
The PermissionedTableDescriptor has the following parameters in addition to the base TableDescriptor.
| Parameters | Type | Description |
|---|---|---|
| TableACL | TableAccessControlList | Defines the table owner and other addresses table level permissions |
| IsReadRestricted | bool | Defines if read permission should be checked or not |
| PermissionModel | PermissionModel | Defines how permission should be checked when updating the contents of permissioned table |
# TokenTableDescriptor
A token table defines token admin and trusted addresses that can be used for token logic.
The TokenTableDescriptor has the following parameters in addition to the PermissionedTableDescriptor.
| Parameters | Type | Description |
|---|---|---|
| TokenAdmins | IReadOnlyList<Address> | Addresses that can mint tokens from the VoidAddress |
| TrustedEntities | IReadOnlyList<Address> | Addresses that can withdraw token from other addresses without permission checks. |
# AssetTableDescriptor
An asset table is a type of token table that stores fungible tokens (value representable as decimals) values mapped to address keys.
The AssetTableDescriptor has the following parameters in addition to the TokenTableDescriptor.
| Parameters | Type | Description |
|---|---|---|
| Rules | IReadOnlyList<ValidationRule> | 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 ( |
# NFTTableDescriptor
A NFT table is used to store addresses and NFT respective tokens.
The NFTTableDescriptor has the same parameters as the TokenTableDescriptor.
# BinaryTableDescriptor
A binary table is a generic table type that is used to store hex key-value pairs.
The BinaryTableDescriptor has the same definition as PermissionedTableDescriptor.
# EntityTableDescriptor
An entity table is used to store data in the form of a relational document type structure.
The EntityTableDescriptor has the same definition as PermissionedTableDescriptor.
# PrivateDataTableDescriptor
A private data table is used to store the proof of the private data shared between private data owners (PDOs).
The PrivateDataTableDescriptor has the following parameters in addition to the PermissionedTableDescriptor.
| Parameters | Type | description |
|---|---|---|
| PrivateDataOwners | IReadOnlyList<Address> | Addresses that store the evidence of private data |
# Table Interfaces
Tables are exposed through the following interfaces illustrated in Figure 2.
These interfaces are mainly used in Miyabi smart contract.
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)
 |
|---|
| Figure 2. Table Interfaces |
# Asset Table
# Basic Information
The asset table is a table designed for recording decimal assets like digital coins. In the asset table, the key is the public key of the asset owner, and the value is asset balance in decimal.
The data stored in Asset table is as follows:
| Field | Description | Type |
|---|---|---|
| Key | Address of the asset owner | Address |
| Value | Amount of assets owned by asset owner | Decimal |
# Validation Rule
The validation rule are some policies set for a table. Whenever a transaction attempts to access an asset table, Kotowari will verify whether the operation on the 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 values should not be negative (except for VoidAddress). E.g., bank account deposit |
| Prevent Admin Trustee (default) | Prevent admins from adjusting the balances of other addresses. |
| Prevent Trusted Withdrawals | Prevent trusted entities (listed in TrustedEntities) to withdraw from other addresses. |
Each table will reserve one VoidAddress, which can only be touched by TokenAdmins to mint tokens.
The VoidAddress can generate infinite tokens and send them to any address.
The VoidAddress is the only address that can have negative value if the NoNegative rule is enabled.
According to the Sum Equal Zero rule, Kotowari only need to check VoidAddress in any case.
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.
TokenAdmin can move an arbitrary asset from VoidAddress to arbitrary address if Prevent Admin Trustee is not applied.
The trusted address can withdraw assets from arbitrary addresses except for the VoidAddress.
Also, a smart contract can use its instance Id to create an asset table and only the smart contract can modify its entry.
# Examples
An example of using asset table which includes the following operations is illustrated in Figure 3:
- Create an Asset table
- Generate assets from
VoidAddress - Move assets to another address
 |
|---|
| Figure 3. 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 PermissionModel.
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 inserted or deleted whenever someone transfers tokens to that address, or the balance of the address returns to 0.
However, in the TableAndRow model, a row cannot be created or deleted without insert or update permission.
# Binary Table
# Basic Information
A binary table is a simple permissioned data table.
In a binary table, key and value are ByteString.
The value is stored within a PermissionedData together with an optional list of addresses who are treated as the owner of the row.
If there is no owner for a row, the row permission check will always return true.
The data stored in binary table is as follows:
| Field | Description | Type |
|---|---|---|
| Key | Arbitrary ByteString key | ByteString |
| Value | Permissioned data containing value and owner | PermissionedData<ByteString> |
# 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 child entries to form a graph within the same table or across different entity tables. The storage rule and command for creating tables are the same as the binary table.
| Field | Description | Type |
|---|---|---|
| Key | Arbitrary ByteString key | ByteString |
| Value | Permissioned data containing value and owner | PermissionedData<ByteString> |
An entity table enables the creation of links between entity values in the same or across different entity tables. One link has two components:
| Item | Description |
|---|---|
| Parent | the table name and key of the parent row |
| Tag | identifier for a unique parent-child relationship |
When a parent-child relationship is created, Miyabi will automatically add the necessary rows to store the relationship information. In case of a parent entity, all children and corresponding tags information will be stored. Similarly, for child entity, references to the parent entity corresponding to the respective tags will be stored. The entities can form a graph of parent-child relationship across different entity tables.
# Example for Entity Table
Figure 4 shows an example of the entity table's structure.
 |
|---|
| Figure 4. 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, a NFT table stores a token Id as key and its owner as the value.
The data stored in NFT table is as follows:
| Field | Description | Type |
|---|---|---|
| Key | Token Id of NFT | String |
| Value | Address of the token owner. | Address |
NFT table supports ERC-721 (opens new window) and provide a set of addresses referred to as called TrustedEntities to be trusted addresses just as in the asset table.
TokenAdmins can mint NFT and move token arbitrarily.
In addition, TrustedEntities can change an arbitrary token's owner to itself.
The balance of an address is the number of tokens it currently owns.
# Private Data Table
# Basic Information
The private data module extension of Miyabi allows a subset of nodes to privately share the data among themselves. The private data is stored in the node's Private State while the hash of this private data is stored in World State in a Private Data table.
The hash stored in the World State can be used to audit the existence of the actual private data in Private State.
The Private Data table is a permissioned table that stores the keys and values as ByteString.
The key-value in this table is the hash of the key and value that is stored locally in the Private State.
The raw data stored in the Private State is stored as follows:
| Field | Description | Type |
|---|---|---|
| Key | Arbitrary ByteString key | ByteString |
| Value | Permissioned data containing value and owner | PermissionedData<ByteString> |
The hash data stored in the World State is as follows:
| Field | Description | Type |
|---|---|---|
| Key | Hash of the ByteString key | ByteString |
| Value | Hash of the ByteString value | ByteString |