# General Architecture

# Abstract

Miyabi is a blockchain solution for high-speed decentralized applications. Miyabi comes with plug and play features like NFT and digital assets out of the box and offers great control via various configurations. It is a world-state based blockchain as opposed to a UTXO based blockchain. It can be seen as a state machine that executes transactions in each block and updates the state accordingly. Miyabi allows a rich form of data to be stored and handled.

Miyabi is a permissioned consortium-based permissioned blockchain. Only known nodes and members of the consortium with the required credentials can join a particular Miyabi network. In a Miyabi network, nodes running the consensus algorithm are called consensus nodes. In Miyabi, consensus nodes use the BFK2 consensus algorithm to agree on the content and order of transactions and their execution results within blocks (form a consensus). BFK2 achieves Byzantine Fault Tolerance (BFT) and guarantees the finality for the created blocks. As long as no more than of the nodes in Miyabi are byzantine nodes, any committed block can never be altered (finality).

Miyabi also supports smart contracts to support customized logics. Miyabi guarantees that the time-stamped contracts are tamper-proof. To prevent potential bugs in smart contracts, Miyabi has two layers of validations. In the first layer, a smart-contract analyzer and a compiler checks for potential syntax issues. In the second layer, each data set (assets, etc.) has independent validation process to check if the operation conforms to a set of predefined rules. For example, for the fungible digital assets, Miyabi has a special asset validator named Kotowari (理) which checks special validation rule over the touched asset data, ensuring that the remaining balance after an asset move does not fall below a minimum value among other checks.

# Distributed State Machine

Miyabi can be seen as a distributed state machine where each consensus node participates to decide the next state. A transaction can be viewed as an operation on a given state S of the blockchain. A transaction has the capability of making the state machine to transition from state S to S'. Miyabi satisfies the following properties:

Distributed set of nodes
All nodes start with the same initial state
The same set of ordered transactions is executed to allow node to move to the next state

The nodes in Miyabi start with the same initial state. As the peer to peer network receives the transactions, the transactions are bundled into blocks and are executed. New blocks are subsequently added to the blockchain. The order of transactions in a block and the execution result of the transactions are guaranteed to be consistent in accordance with BFK2 consensus algorithm. Since the consistency of the blockchain is guaranteed by BFK2, the order of transactions for each node is consistent.

Finally, deterministic transaction execution is implemented. For a given world state and transaction lists, all nodes will produce the same result.

The structure of the state machine is shown in Figure 1.


Figure 1. The concept of a state machine

# Node

A node is an active instance of the Miyabi program. It has the following major functions:

Expose public and admin APIs for user interaction
Receive and store transactions for processing
Share information with other peer nodes (including transactions and blocks)
Propose block (consensus nodes only)
Validate the proposed block by executing transactions
Making consensus about a block (consensus nodes only)
Persist block to the blockchain ledger

Each node exposes a set of public APIs which can be used to get:

Metadata related to current state of Miyabi blockchain
Information about the node which is hosting the API
World state data
Blocks and Transactions information

Additionally, users can also send transactions to a node through its API.

After a simple validation, the node stores the received transaction in an internal transaction memory storage (memory pool). The transaction memory pool is an in-memory data structure which holds the transactions received from the clients which have not yet been picked up by nodes for generating a new block. A transaction is added to the memory pool after verifying the signatures on it. If the signature verification fails, the transaction is dropped. Each node uses an inventory protocol to share newly received transactions and blocks between nodes. The inventory protocol guarantees the sent message will be received eventually. The memory pool of different nodes does not need to be consistent with the transactions they hold. In fact, the inconsistency is natural because of the asynchronous network. The inventory protocol ensures that the node has a particular transaction it needs, in case it is not present in the memory pool. The framework of the inventory protocol is shown in Figure 2.


Figure 2. Tx sharing among nodes using inventory protocol

To generate a block, one of the consensus nodes picks up a set of transactions from its memory pool, executes them, and creates a "block proposal" by signing the block and attaching an evidence. If other nodes agree on this proposal by the mechanism of consensus, then the proposal is accepted and signed by the other nodes. Hereafter, the block is added to the blockchain, and the state is updated. Due to the asynchronous nature of the network, the order of received transactions and the transactions included in the block are not guaranteed to be consistent. However, the order of the transactions within a committed block is guaranteed to be consistent across the network. If the transaction is expired, it will be dropped from the memory pool, therefore they will not be added into any block. There can be multiple block proposal candidates for creating the next block. This mechanism is controlled by the consensus layer of Miyabi. However, at the end of the consensus process for the new block, the network commits the same block in accordance with the finality guaranteed by the BFK2 consensus algorithm. A sketch of BFK2 is shown in Figure 3.


Figure 3. Illustration of consensus algorithm

Committed blocks are broadcast to all nodes via the inventory layer protocol. Upon receiving a new block, the node will check the validity of the block, and if valid, then it executes all the transactions within the block and updates its WorldState.

Each node possesses a unique consensus identity, which is the public key of the node that is shared by other nodes. The private key related to the node id is stored as a PKCS#12 keystore file whose path is stored in the node configuration file of the node. Each private key should only be accessed by the node, and it is used for signing the message to prove its integrity and reliability.

Apart from consensus nodes, Miyabi also has a special set of nodes called application nodes. The application nodes do not participate in the consensus mechanism. The application nodes add a block locally only after the consensus nodes have committed the block to the blockchain. Apart from the consensus mechanism, the application nodes run all the protocols which the consensus node runs. Additionally, application nodes also have a memory pool and transaction resending protocol for relaying the requests of clients. Application nodes can improve the capability of Miyabi without raising the complexity of consensus building. Application nodes can access the geographically closest nodes to reduce latency as shown in Figure 4. The set of all consensus nodes is called consensus members. It is possible to change the consensus members by executing transaction(s) that can add or remove specific consensus identity from the set of consensus members. Hence, an application node can become a consensus node if its identity is added to the consensus members.


Figure 4. Consensus nodes and application nodes

# Consensus Algorithm - BFK2

Miyabi uses a special crafted consensus algorithm called BFK2. BFK2 has been internally developed while considering various needs and use cases of Miyabi. Miyabi takes inspiration from the already existing consensus algorithms of public blockchains while removing the various bottlenecks that they have. BFK2 achieves the following attributes:

Security: Ensures that the consensus can not be reached on an invalid or a bad proposal
Liveness: Ensures that the consensus will eventually be reached
Finality: Ensures that achieved consensus cannot be reversed or revised

BFK2 guarantees the above attributes only when byzantine consensus nodes are less than of the total consensus nodes.

BFK2 is a communication based consensus algorithm, so it can achieve consensus within seconds with minimal network latency. BFK2 can also survive a limited attack on the Byzantine nodes. With N nodes participating in the consensus, the algorithm guarantees security if the number of byzantine nodes is less than N/3, and liveness if the total number of faulty nodes is less than N/3. The term Quorum refers to any sufficiently large subset of validator nodes. An agreement among a Quorum offers a strong guarantee for the progress of the consensus algorithm. Assume a Miyabi has nodes, then:

If , then , which means 3 different signatures from consensus nodes are required to confirm one block. Hence, is the necessary condition for BFK2 to be BFT. If Byzantine nodes are not considered, BFK2 can adjust the Quorum to have crash fault tolerance (CFT). If BFK2 only considers crash faults, then:

In this situation, is the necessary condition for BFK2 to be CFT.

# Structure of World State

The Miyabi blockchain, as mentioned earlier, manages a distributed state machine. The state of the miyabi blockchain, which is common among all the nodes (unless they lag behind due to certain situations), is called the World State. The fundamental structure of the World State is a set of tables. A table represents a logical group of data, which can have independent ownership rights, data types, and read and write rules. Internally, each table is an abstraction over a binary key-value store. In addition, users can also use a smart contract to define the logic of modifying their data for complex operations. Miyabi provides a Roslyn analyzer for security checks of smart contacts.

Users can only update the World State by transactions. Miyabi core defines some operations (read as "transactions") to modify the configuration of World State and some important system tables. Miyabi uses modules to implement different business logic including operation validations and permission check. All tables also support a track feature which can log the transactions that update the table’s data for traceability. Miyabi uses a hash tree to verify the existence of a table or a table’s data. Miyabi calculates the hash tree for the entries in a table with support proof flag. By using the root hash of all table trees, Miyabi can calculate the hash tree for the whole world state and provide a path to the specific entry as a proof of the existence of that entry. All users can calculate the entry and the proof to get the root hash which should be equal to the one in the specific block header for being accepted. The state proof mechanism thus provides a way to verify the existence or non-existence of a table or table data.

# Structure of Blocks

A block is a collection of transactions along with other relevant information. These blocks are linked together to form an immutable chain of blocks aka "blockchain". A block is included into the blockchain if the Quorum of consensus nodes reaches a consensus to include it. Blocks can also be denoted by a unique integer, height, which is the position of this block in the blockchain.

Each block contains three parts: block header , block body , and block evidence (Figure 5).

The block header is a data structure which encapsulates information about the previous block, the events in the current block, and a Merkle root hash of the current block’s transactions and transaction results. It also includes the merkle root hash for the World State and creation time of this block.

The block body is a data structure encapsulating information about all the transactions and the respective transaction results. It also contains information regarding the events which were triggered during the execution of the transactions in the block.

The block evidence is a data structure that proves the acceptance of a block by the consensus nodes.


Figure 5. Structure of Block

The hash of the block header of a block is referred to as block Id of that block. The previous block's block Id is also stored in the block header . Hence, if one committed block is changed, the Id of that block will be changed which will affect all the IDs of the following blocks which will be detected. This means that the integrity of the blockchain is guaranteed. The structure of blockchain is shown in Figure 6.


Figure 6. Blockchain Structure

# Transaction Structure

A transaction has the structure shown in Figure 7.


Figure 7. Transaction Structure

The Transaction header includes the metadata about the transaction, including the time it is created and the valid from and valid to time.

Transaction entry is the minimum unit of execution in Miyabi. One transaction can have multiple entries.

Required credentials are the credentials presented along with a transaction. The corresponding evidence for the ownership of these credentials also need to be presented as part of the transaction signatures. Miyabi verifies whether the signatures are presented for all the required credentials. When executing the transaction, in case of any permissioned operation which needs specific credentials, the node will try to validate it with the Required credentials which have been presented in the transaction. If the presented credentials do not have the permissions required for the permissioned operation, the transaction will fail. In simpler terms, the required credentials represent public keys corresponding to the private keys which were used to sign the transaction.

The Signatures for transaction are the signatures for the Transaction Id which should be signed by those designated in the Required credentials to guarantee the transaction’s integrity. If any signature is missing or incorrect, the transaction will be rejected.

There is a format checker for each transaction. If the transaction does not pass the format check, it will not be recognized as a valid transaction. The format checker includes:

The order of Signatures for transaction is equal to the related key's order in Required credentials.
The public key in Required credentials and Signatures for transactions are matched according to the used cryptography algorithms.

# Execution of Transaction

When a block proposal is prepared, the node picks up transactions from the memory pool and executes them in a certain order. This order is fixed for this block proposal and all other nodes validate and execute the transactions in the same order. If a transaction contains multiple entries, they will be executed according to the order within the transaction. Hence, all entries in a block will be executed with the same order.

Execution of entry means this entry will be deserialized and executed according to the specific rule to read and write the current world state of Miyabi. If transaction entry results in failure, the whole transaction is marked as failed and all the changes to the world state will be rolled back. Only the successful transactions, for which all it's entries are successful, can update the World State. The following table provides the possible status of transactions.

Code	Description	Comment
-1	Pending	The transaction is in the mempool and is waiting to be processed
0	Success	The transaction completed successfully, and any state changes will be reflected after the corresponding block
1	Negative Balance	(Asset-specific) Negative-balance rule was violated
2	Conservation Break	(Asset-specific) Total asset-value conservation rule was violated
3	Failed	Transaction failed for an unspecified reason
4	Canceled	Transaction was canceled
5	Signature Invalid	The transaction was not accepted because its signature was not valid and/or did not match the required credentials
6	Invalid Credentials	Credentials were not valid for this operation
7	Invalid Operation	The transaction performed an invalid operation while executing
9	Duplicate	A duplicate transaction was already in the mempool or a committed block
10	Corrupted	The transaction was not formatted correctly
11	Invalid Lifetime	The lifetime of the transaction was invalid
12	No Vacancy	Memory pool is full
13	Time Out	(Contract-specific) Execution timed out
14	Over Size Limit	Tx size or entries per transaction over the limit

# Event

Miyabi transactions can emit transaction events with relevant event data. A single block can have multiple of such transaction events. A Block Event contains collection of all the transaction events as well as a bloom filter which combines all the triggered events in this block. It is part of the Block Body. A bloom filter can easily help in checking the presence of a certain event in a block.

Each transaction event contains a filter and a set of triggered events. A triggered event is used for emitting data that's generated during the execution of transactions and will not be stored in a world state. Currently, Miyabi supports two ways to trigger the events:

Using transaction entries which emit events, and,
Using smart contracts

Below are some example entries that will create events:

ConsensusCredentialsChangeEntry Transaction entry will store the new credentials and the height it will take effect.
BlockchainParametersChangeEntry Transaction entry will store the activation height, new blockchain config, and its hash to the event.
UpdateWorldPermissionEntry and UpdateContractPermission Transaction entries also emit events and store the addresses and corresponding permission change information in the event data.

Users can get events from block through API GetBlockEvents and use BlockEvent.Events.Any(a => a.Maycontain(filter)) through SDK to judge if the block contains the specific events. The filter is generated by combing all target FilterData.

# Access Control Model

The access control model of Miyabi is based on asymmetric cryptography. The permissions granted to an address at system level or at table level are stored in the World State. There is a system permission table which stores all the system level permissions. In case of custom tables, the table level permissions are stored as a part of the table descriptor, the row level permissions in a table are stored alongside the row data. When one of those permission is required for an entry, the node will check whether the required credentials of the transaction can verify an address with that permission. Figure 8 summarizes permission checks when executing the tx. An address can either be a public key address, a threshold public key address, or a specific smart contract address. If the permission is granted to a smart contract address, then all methods in the smart contract can pass the permission check.


Figure 8. Access Control Model

# Executed Transactions

Once a transaction has been executed, the node stores it in a filter called the transaction filter. It contains all the recent transactions for a fixed time period. If a transaction is present, then the filter can check that this transaction has been seen before and needs to be dropped, thus, preventing the double inclusion in the blockchain. All the transactions with their corresponding results are indexed and stored by the node in its database and this indexing is maintained separately from the World State.

# Digital Signature

A digital signature is a cryptographic output used to verify the authenticity of data. A digital signature service should support the following functions:

Create key pairs. A single key pair contains a public key and a corresponding private key
Create a signature of a plaintext by using the private key
Verify each signature by using the public key

The workflow of a digital signature service is shown in Figure 9.


Figure 9. Digital Signature

# Access to Miyabi

As previously stated, all Miyabi nodes provide public Web API service. The Web Api service can be used to send various GET queries to the node and also to send the transactions. A client usually does not use the Web API directly, but accesses the node through the client SDK. The client SDK has wrapped the configuration of Web API and provides user-friendly functions and services. By using the client SDK, a client can easily get information from nodes, create signatures, create transactions, and send transactions.

Miyabi also provides a CLI program that wraps client SDK to provide CLI service. Their dependencies are shown in Figure 10.


Figure 10. Access of Miyabi

Table →