Understand Klayr blockchain
In the "Understand Klayr blockchain" category you learn the basic concepts of Klayr software and protocol. This page introduces the topics and terms that are important to know when developing within the Klayr ecosystem.
What is the Klayr Blockchain?
A blockchain [1] is a chain of interconnected blocks on various nodes distributed across a P2P network. Each node runs using an instance of the blockchain client and also stores node-specific on-chain and off-chain data. It syncs periodically with other nodes to ensure that the nodes' records are up to date.
The Klayr blockchain also follows the same principle. The Klayr blockchain can actually be described as an ecosystem of blockchains, where many different blockchains are interconnected through a central blockchain, called the Klayr Mainchain. All other connected blockchains are called sidechains in this context. To become interoperable with any other blockchain in the Klayr ecosystem, a blockchain needs to follow the Klayr Interoperability protocol.
What are Klayr applications?
A Klayr application refers to software that contains a klayr based blockchain client, a middleware, and a user interface.
Unlike smart contract-based platforms, where smart contracts have to share the same chain for their blockchain needs, Klayr provides the opportunity for each application to run on its own blockchain.
This provides faster block generation, reduces the burden on the network, and increases scalability as discussed on the Blockchain Scalability page. A blockchain can communicate with other blockchains with the help of Klayr Cross Chain Communication.
- Blockchain client
-
The blockchain client is the fundamental software that is needed to establish and maintain a blockchain network between various independent servers. Servers with running blockchain clients are called blockchain nodes. One of Klayr’s offerings: the Klayr SDK provides a lot of helpful tools to build a fitting blockchain client for your application. Check out the guide Building a sidechain with the Klayr SDK for more information on the topic. Furthermore, Klayr also offers the blockchain client to run Klayr Mainchain which is called Klayr Core.
- Middleware
-
A middleware can prepare, aggregate, and enrich data from the blockchain network, so it can be easily used and digested later by the application’s frontend. With Klayr Service, Klayr provides ready-to-use middleware, which can be easily configured for any Klayr application. Klayr Service is an enriched node API layer that provides a convenient set of endpoints for sending or getting data from the Klayr blockchain. Klayr Service also allows data aggregation of the relevant data for external services, enriching it if needed with off-chain data as well. Although middleware is optional, it will most probably become essential for bigger blockchain applications in the long run.
- User Interface (UI)
-
The frontend or User Interface of Klayr applications is highly customizable. Any UI that is able to communicate over HTTP or WS protocol will work. Use your preferred existing frameworks to develop an accessible and intuitive UI for users which fits your individual use case.
A high-level overview of the communication flow in the Klayr ecosystem can be seen below in the following diagram.
Network topology
The Klayr blockchain ecosystem consists of various interconnected Klayr applications. Each Klayr app maintains a separate, independent blockchain with a network of interconnected servers, which are also called nodes in this context.
The different sidechains communicate with each other via relayer nodes by following the Klayr Interoperability protocol.
A typical network of chains and their nodes is illustrated in the diagram below:
The three domains of a blockchain
From a high-level perspective, there are three domains of a blockchain as described below:
-
Application domain: Responsible for verifying data and transitioning the blockchain’s state with deterministic logic via the state machine.
-
Consensus domain: Responsible for replicating the same sequence of states among all nodes in the network. Nodes achieve this in the network by following a consensus protocol and utilizing the application and network domains.
-
Network domain: Responsible for the communication of the peer-to-peer network.
The three domains are the pillars of the Klayr blockchain and represent the core of the Klayr Protocol. Their functionality is defined in the LIPs.
| Other components of the blockchain client that are not part of the three domains, such as the Transaction Pool, etc. can be implemented differently by the developer if desired, without breaking the Klayr protocol. |
| It is recommended to use Klayr’s implementation of the engine components to avoid erroneous behavior. |
The Architecture of Klayr applications
The architecture of a Klayr application is divided into the following two layers:
-
Application layer (includes the application domain)
-
Engine layer (includes the consensus domains and network)
A detailed illustration of a Klayr app’s architecture can be seen in the following diagram below.
Application layer
The application layer handles state changes to the blockchain. The function of the application layer is to act as an interface to connect to the outside world, such as various external services in order to send and receive data. An application layer consists of a State machine, Modules, Plugins, and Configuration.
State machine
As the name suggests, a state machine is relevant to the states of a machine. A blockchain client relies heavily on its state machine to mutate the state of a blockchain.
-
States: A state machine is deterministic and can have multiple states, but only one state at any given time. In the context of the Klayr blockchain, a key-value store represents the current state of the blockchain, containing all on-chain data of the blockchain.
-
Transitions: A transition is defined as the instantaneous transfer from one state to another state. In the context of the Klayr blockchain, a transition of the state is triggered through blocks and the transactions present in those blocks; i.e. every new block that is added to the blockchain mutates the state of the blockchain.
Modules facilitate state changes in a blockchain. Klayr app developers can implement custom on-chain business logic for the blockchain. This can be done by either creating their own modules or reusing existing ones and registering them with the client.
Modules
Modules aid the state machine to transition the state of the blockchain with verified and validated data. They contain on-chain logic which is part of the blockchain protocol.
For example, if Bob wants to send 10 KLY tokens to Alice then, behind the scenes a module will verify the validity of such a request. Upon validation and verification, the module will ask the state machine to transfer 10 KLY tokens from Bob’s account to Alice’s account.
| Klayr provides a range of default modules out of the box. These modules are used automatically, whenever a Klayr application is bootstrapped via Klayr Commander. |
Plugins
Plugins represent the off-chain logic. A plugin is not part of the application layer and must be registered with the sApp before its use. Each node inside the network can deploy various kinds of plugins to support their off-chain logic.
For example, consider a case whereby a node wants to investigate any possible misbehavior in the Klayr network. To achieve this, the node operator must acquire all the blocks' data from the network, save it, and then analyze it to determine if any misbehavior had occurred.
A node manager can write a script to perform the aforementioned task. However, Klayr provides the Report Misbehavior Plugin which listens to blocks' data and reports a node with regard to a generator’s misbehavior. A node manager can write a script to perform the aforementioned task. However, Klayr provides the Report Misbehavior Plugin which listens to blocks' data and reports a node with regard to a generator’s misbehavior.
To add a new plugin to your application, either reuse an existing plugin from another app or create a new plugin based on the specific requirements of your application.
| Klayr provides a set of plugins that can be injected into the Application layer when needed. For more information, see Plugins. |
Configuration
The Klayr solution is both convenient and flexible in terms of how to operate a node, coupled with how to execute both on-chain and off-chain logic. To serve this purpose, the app accepts a configuration that is part of the state machine.
A set of default configurations are passed to a blockchain client. These configurations can be individually tweaked as necessary. For off-chain components and logic, e.g. Plugins, etc., the configurations can differ for each node. However, the Genesis configuration and the configuration for Modules must be the same across the network of each blockchain client.
| For more information about the available configurations, see Client configuration. |
Engine layer
The Engine layer acts as a bridge between the Blockchain and the Application layer. The engine is responsible for managing upcoming transactions, generating blocks, reaching consensus, storing the chain's data in data stores, and dispersing the new blocks to other nodes on the network.
The engine layer consists of the following components:
Transaction Pool
A transaction pool is where new transactions exist before they become part of the blockchain. It can be considered similar to mempool in Ethereum. Whenever a new transaction is created, it has to be sent to a transaction pool. The transaction pool receives the new transaction, verifies it, and then stores it temporarily in the transaction pool until it becomes part of a block.
A node operator can configure the Transaction pool via the Configurations passed to the Application layer.
Once a set of verified transactions are available in the pool, they are sent to the generator for further processing.
Generator
A generator handles the generation of new blocks. The generator picks up the transactions from the transaction pool and orders them and then executes each transaction with the help of the state machine to check its validity. Once verified, the transactions are added to the block header.
Consensus
The consensus component applies the fork choice rule and checks the properties contained in the block header. It is also responsible for the replication of the same sequence of states among all nodes in the network. After a block reaches consensus and the state has been changed, the new block’s information is then passed to the blockchain.
P2P
The P2P component handles sending and receiving data from nodes. It also maintains an active connection with the Klayr network. Every node receives new blocks generated by other nodes via the P2P network. The receiver node in that case repeats all the steps mentioned in the Engine layer. If the received block is verified, then the receiving node adds it to its blockchain instance.
Data Stores
Each blockchain node is an instance of a particular blockchain and each node keeps its data in various data stores. This data is of the following two types: on-chain and off-chain.
-
On-chain data includes but is not limited to state data of the chain, account balance, nonce, multi-signature keys, generators' information, and the Sparse Merkle tree, etc. The blocks, transactions, events, and assets are also part of the on-chain data among various other properties.
-
Off-chain data includes but is not limited to node information, peer list, random hash, etc. It also contains information for generators i.e. last generated block, encrypted keys, etc. Klayr also maintains off-chain data regarding the legacy chains. Legacy data consists of blocks from depreciated versions of the protocol.
Communication interfaces / APIs
The communication architecture of a blockchain client allows internal application components and external services to communicate with the client via various channels.
Blockchain clients support three industry-standard communication protocols:
-
Inter-Process Communication (IPC)
-
Web Sockets (WS), and
-
Hypertext Transfer Protocol (HTTP).
The communication protocol of a blockchain client can be changed through configurations.
It is possible to communicate to modules and plugins directly by invoking endpoints via an RPC request, or by subscribing to events.
It is recommended to use the IPC/WebSocket protocols where possible, as they provide more enhanced performance regarding the response times, (see the blog post: Benchmarking Klayr Core v3.0.0 against Klayr Core v2.1.6).
For more information about the communication architecture, see Communicating to a Klayr node via RPC.
Frontend & UI integration
Klayr applications usually consist of a frontend and a backend (blockchain client), just like traditional web applications.
However, in contrast to traditional server-client applications, there is not one central backend, but rather a whole network of nodes running instances of a similar blockchain client, that together secure and maintain the status of the blockchain. Each node can handle complex business logic and provides a flexible and customizable API. The blockchain itself is used as a database layer for the application.
The frontend allows users to interact with the blockchain client. The implementation of a frontend is flexible. For example, this can be achieved in the following ways:
-
Use your favorite framework/ programming language to develop a standalone user interface, and communicate to the node via the available Communication interfaces / APIs. Please be aware, every node has only a few basic API endpoints as described in the RPC API for the Klayr nodes page, which might not be ideally suited for more complex UIs. In this case, we recommend using the enriched API of Klayr Service as middleware to communicate between the frontend and blockchain client.
-
One example is the UI for the Hello World app, detailed in the guide: Integrating with UI.
-
-
[recommended] For later requirements in a production environment, we highly recommend using Klayr Service, a middleware that aggregates information from the blockchain network and other 3rd party sources to provide an extensive and enriched API. The frontend products can access and utilize such information both over HTTP and WS.
With Klayr Service, you can also create a custom service as per your business requirements to support various UI projects, such as mobile and web applications. You can also extend existing microservices; for more information, see Extending the Indexer microservice.