It is with great delight that we announce the collaboration between Klaytn and Parity to build a Substrate-based Klaytn chain, Klaytn-Substrate. Parity, using its Substrate SDK, is perfectly positioned to help Klaytn explore the possibilities of a true multi-chain environment and achieve our vision for the metaverse in 2022 and beyond.

Klaytn-Substrate will initially serve as an alternate implementation of the Klaytn specification and as a sidechain to our main chain. It will be bridged to Polkadot and to the Klaytn mainnet to act as an intermediary environment where collaborative technological, business case, and community initiatives can combine in interesting and synergetic ways. Building out feature sets to capture and facilitate gaming and metaverse use cases on Klaytn’s existing mainnet and L2 architecture is still one of our key strategies. However, Klaytn-Substrate can act as a key “canary network” for us to safely, efficiently, and quickly capture new use cases, new technologies, and provide our community with more options for building great things within the Klaytn ecosystem.

Once the Klaytn-Substrate chain is launched, the tech lead collaboration will continue with the development of new dApps for the chain, as well as porting over multi-chain launches of existing applications from both the Klaytn and Polkadot ecosystems. Parity and Klaytn’s teams will also work together to expand the network of enterprises building on Klaytn-Substrate, to encourage a diverse array of service providers and a rich and highly functional business ecosystem.

The collaborative Klaytn-Substrate project will allow us to expand into more areas and ecosystems beyond those enabled by our existing Service Chain L2 solution. With great adoption comes great responsibility, and as our community grows, so will the demand on our main network. From this, Substrate is a natural candidate for expansion and exploration, providing the Klaytn ecosystem with an additional stable, upgradable and high throughput blockchain framework to support our thriving community.

“The collaboration with Parity is in line with our vision to create an interoperable blockchain platform for the metaverse. The Klaytn-Substrate will open up new possibilities for dApps to be developed in a multi-chain environment, to explore collaborative use cases between the Klaytn and Polkadot chains,” shared David Shin, Head of Global Adoption at Klaytn Foundation.

Omar Elassar, VP, Ecosystem Development at Parity Technologies, said: “We’re excited to work with Klaytn to help its onward journey as a major player in the metaverse and gaming. The team at Klatyn recognize that Substrate is the optimal SDK for technical and business use case exploration.”

A number of Substrate features gave us the confidence to embrace it as an additional implementation of the Klaytn vision. Due to its customisation capabilities, the chain’s performance could be modulated to support applications with higher transaction throughputs, such as many of Klaytn’s DeFi applications. But additionally using its modular and innately extensible design allows for the addition of new runtime features, customisable consensus and governance, EVM compatibility, as well as ability to perform live runtime updates. Substrate is the perfect SDK for Klaytn’s ecosystem growth ambitions for technical and business use case exploration. Not only does it provide the ability to build a highly customizable and future proof blockchain with its own unique governance model, it also allows us to rely on a battle-tested framework that takes the guesswork out of deployment.

Using Substrate means we can customise Klaytn-Substrate in a fast iterative manner to find market fit and drive vision towards technical exploration while synergising Klaytn-Substrate’s unique path with our existing proven network through bridging and interoperability functionality. Add to this the ability to easily and seamlessly bridge to Polkadot’s own secure, decentralized and highly interoperable network, and it’s easy to see that this collaboration makes sense.

Great collaborations are built on trust and a shared vision, and this is what we find with Substrate. Klaytn’s ecosystem expansion will be secured using the performant, intuitive and reliable infrastructure found in Substrate; and Substrate and Polkadot will continue to reach new heights of adoption with the support of Klaytn’s buoyant community. The collaboration is a positive flywheel for Parity, Klaytn and all our users, and we can’t wait to see it come to fruition.

In this post we want to explain to you about the overall architecture of Klaytn. Klaytn is a project that started as a fork of Ethereum in June 2018. It has been an open source project since the mainnet launch in June 2019, and is accessible on Github. The complete development process of Klaytn takes place in the repository, so feel free to drop by when you want to know more about it 😀 We also welcome code contributions!

First, here is a complete picture of the Klaytn architecture.

The following sections have short descriptions of each of these layers in more detail.

Application Layer

The application layer includes modules that run on top of Klaytn. This layer does not have anything to do with the actual blockchain core. Currently, it only consists of the contracts module, which contains the smart contract code for various integral purposes like Klaytn’s L2 ServiceChain and mainnet interaction or precompiled contract usage examples. To check out all standard smart contracts supported in the Klaytn ecosystem, please refer to klaytn-contracts.

Wallet Layer

The Wallet Layer includes modules related to wallet management on the Klaytn nodes themselves. With the wallet function nodes can manage private keys and give signatures on transactions, which is useful when individuals are operating nodes. Wallet management is tricky business, beware of vulnerabilities when you are using the same wallets to manage multiple nodes. Unlike Ethereum and other chains, Klaytn allows you to store multiple private keys attached to a single account giving developers to manage accounts through Role Based Access, or on-chain multi-signature account control. Key management and transaction signature features have changed to support this functionality. For more details on the newly added keystore v4, please refer to KIP-3 and to understand the Klaytn Account Model see our documentation here.

Interface Layer

The Interface Layer includes modules related to node execution and API calls.

Execution Layer

The Execution Layer is where the core blockchain functionalities sit. In the blockchain/types module, data structures such as account, transaction, block, receipt are stored. Klaytn has designed and implemented a new account and transaction model for higher performance and scalability. For more details, please refer to Klaytn Docs.

Governance Layer

The Governance Layer is where the governance features are implemented.

Consensus Layer

The consensus layer provides three possible algorithms: PoW, Clique, Istanbul BFT. Klaytn mainnet uses the Istanbul BFT algorithm, while the first two contain the exact same code originally forked from Ethereum and are not currently being maintained by Klaytn.

Cryptography Layer

The Cryptography layer includes various modules related to cryptography. Cryptography is an integral part of the blockchain system, it is used for merkle hashing and fast data verification as well as transaction signing and transaction authentication. Klaytn uses a safe, and widely verified cryptography system based on the ECDSA secp261k1 curve: same as Ethereum, Bitcoin and others blockchains.

Synchronization Layer

The Synchronization Layer provides a data fetcher, and a downloader for syncing with other nodes along with chaindatafetcher, which is used to stream block data effectively.

Network Layer

The Network Layer enables grpc, p2p, rpc network communications. The components of this layer uses the code forked from Ethereum without active maintenance on the part of the Klaytn Team. Compared to other layers, the Network Layer has been validated and optimized over a long period of time. It requires a long-term approach instead of immediate improvements to its performance.

Storage Layer

The Storage Layer provides the data structure and related features to store the blockchain data in the disc. We have implemented an interface to support various types of database using the database module. Currently, levelDB is being used.

In this article, we introduced the various modules in Klaytn in layers for developers and the community to better understand what is going on under the hood of the Klaytn blockchain. To further this understanding, we will go over each module in more detail in future posts. If you are curious about a specific module, please let us know in the comment section. Thank you!

From joining conferences to launching a highly-anticipated blockchain gaming ecosystem, it’s been a crazy month here at Klaytn! Here’s a quick take of our top highlights and latest happenings.

Highlights from this month

New integrations and listings

Want Klaytn’s latest news delivered straight to your inbox? Subscribe to our mailing list now!

Here’s an exciting announcement on our new Proof-of-Contribution (PoC) program! The Klaytn Foundation has selected crypto projects to help give back to users, who are essential to making the Klaytn ecosystem grow every day.

For our PoC Pilot round, we received an overwhelming response. Many teams have submitted brilliant projects, but it’s impossible to select all! So we have evaluated the projects based on the following four categories:

  1. Potential impact to the Klaytn ecosystem
  2. Creativity
  3. UI/UX
  4. Transparency and security of the protocol

After evaluating, we have selected a total of two projects to participate in the Pilot round. Congratulations to both!

#1 Kokoa Finance

Kokoa Finance is a decentralized protocol for issuing a collateralized stablecoin.

#2 Klaybank

Klaybank is a decentralized protocol for lending and borrowing, and bonding.

Projects with high potential but not selected this time can look forward to participating in the next Official round! DApp teams will also soon announce the specific reward process for users through their channels.

Find out more about the Poc program here!


If you have further questions, please reach out to us at [email protected].

A seamless bridge between Web2 and Web3 is at the heart of a new, exciting partnership between Smart Token Labs and the Klaytn Foundation. By building a pathway to smart token composability, both sides are set to create a new standard for a tokenized future. The collaboration will see Smart Token Labs introducing TokenScript, a smart token interface, into the Klaytn network. It could lay the infrastructure for the Web3 promise in gaming, NFTs, and the metaverse.

Launched in 2018, TokenScript has already been used to deliver more than 30 smart token projects. It addresses issues with trust, interoperability, security, and interface seen with current token transactions. By fusing token and smart contract logic in a standardized interface, TokenScript will help create a more secure environment in the Klaytn network. It raises the potential of creating a metaverse that is fully portable, completely owned, and controlled by users and developers.

Victor Zhang, CEO of Smart Token Labs, says, “We are delighted to be partnering with Klaytn Foundation to bring our open source technology to the Klaytn network and specifically to the many ecosystem partners and brands that are looking to bridge into Web3 in entertainment, gaming and the metaverse. The Klaytn vision for Web3 is strongly aligned with our own and we’re looking to do great things together via partnerships, collaborations and adoption of TokenScript and AlphaWallet in 2022 and beyond.”

Developers from both sides have already been working to build the infrastructure to support KLAY (Klaytn’s native token), DApp browser, and NFTs. It will set the stage for better user experience in a Web3 future, where tokens represent who you are, what you own, and how you interact.

David Shin, Head of Global Adoption at the Klaytn Foundation, says, “We are looking forward to onboarding Smart Token Labs to build more wallets and tooling on Klaytn’s network. By overcoming core limitations of current ecosystems, this strategic partnership is set to deliver a future of Web3 that is based on security, functionality, and interoperability.”

A Web3 that prioritizes tokens could deliver a hugely improved UX compared to Web2, helping to drive mass adoption. Through the partnership between Smart Token Labs and the Klaytn Foundation, the various promises of Web3 and the metaverse could soon come into full realization.


About Klaytn Foundation

Klaytn is a public blockchain focused on the metaverse, gamefi, and the creator economy. Officially launched in June 2019, it is the dominant blockchain platform in South Korea and is now undergoing global business expansion from its international base in Singapore.

These business expansion activities are supported by the $500m Klaytn Growth Fund, which aims to grow the ecosystem of companies built on Klaytn. The fund is managed and disbursed by Klaytn Foundation, a Singapore-based non-profit organization established in August 2021.

About Smart Token Labs

Australian blockchain company Smart Token Labs is creating a new standard for a tokenized future. It has built two highly successful open source products, TokenScript and AlphaWallet. Backed by high profile investors like Mark Cuban, Framework Ventures, and Crypto.com, TokenScript has delivered more than 30 smart token projects. AlphaWallet is also a key standout, having established itself as the most forked open source wallet on Ethereum.

Great news for MetaMask wallet users — the Klaytn network is now officially supported! To start storing and transferring KLAY with MetaMask, follow these simple steps below. To read the instructions in Korean, click here.

Important note: If you have previously added Klaytn to MetaMask via another RPC (such as Ozys), you will need to delete it first or you will encounter a Chain ID error. We strongly recommend re-adding Klaytn using the official RPC URL below as the unofficial RPCs are subject to call limits. Don’t worry, you won’t lose your KLAY by doing this.


MetaMask browser extension

Step 1
In your unlocked MetaMask wallet, click the network dropdown at the top.

Step 2
Select Add Network.

Step 3
Fill in the details as below and click Save.

Network Name: Klaytn Mainnet
New RPC URL: https://public-node-api.klaytnapi.com/v1/cypress
Chain ID: 8217
Currency Symbol: KLAY
Block Explorer URL: https://scope.klaytn.com

Step 4
Klaytn is now added to your MetaMask wallet!


MetaMask mobile app

Step 1
Unlock your MetaMask mobile app and tap on the hamburger menu on the top left.

Step 2
Tap on Settings.

Step 3
Tap on Networks.

Step 4
Tap on Add Network.

Step 5
Fill in the details as below and click Add.

Network Name: Klaytn Mainnet
New RPC URL: https://public-node-api.klaytnapi.com/v1/cypress
Chain ID: 8217
Currency Symbol: KLAY
Block Explorer URL: https://scope.klaytn.com

Step 6
Klaytn is now added to your MetaMask wallet!


With the Klaytn network added to your MetaMask wallet, you can now access the Klaytn ecosystem of games, DeFi, and DApps with more ease and convenience!

In this post we will introduce the concept of “State Trie Migration’’, which is a process for reducing chain data on Klaytn. This is a more detailed version of the If(Kakao) 2020 presentation (in Korean) given by our developer Ethan.

NOTE: If you are curious about how to run state migration, please refer to Klaytn v1.5.0 State Migration: Saving Node Storage.

What is Blockchain Storage?

Blockchain storage is where all the blockchain-related data gets saved. It looks something like this:

Blockchain data is basically a chain of blocks connected to one another, and each block includes a block header, the body and the receipt. The data of the current state forms the so-called trie structure, which can be accessed through the state root contained in the block header. As such, various data elements exist on the blockchain, which eventually get stored in the database (LevelDB).

Motivation for Development and Current State of Storage

On Klaytn’s mainnet Cypress, about 1.2TB of chaindata (the entire data of a given blockchain) have been accumulated since the genesis block. This chaindata is what is required if you want to operate a node on Cypress, but the costs ensuing from the storage have been pretty demanding.

The size of the chaindata on Cypress as of December 3rd 2020 is as follows:

Full node: 1.2TB in Full Node (Node which stores state in the storage for every 128 blocks)

942G ./statetrie
92G ./header
72G ./body
63G ./receipts
9.3G ./txlookup
4.1G ./misc
288K ./bridgeservice
1.2T .

A full node, which stores the state of the last 128 blocks, uses up about 1.2TB of data, 942GB of which are attributable to the state trie.

Archive node: 2.3TB (Node which stores state for every new block)

2.0T ./statetrie
92G ./header
72G ./body
63G ./receipts
9.3G ./txlookup
4.1G ./misc
48K ./bridgeservice
2.3T .

An archive node that stores the state for every block contains 2.3TB of chaindata, about 2TB are basically state tries.

Characteristics of the State Trie

Let’s take a closer look at the state trie, which takes up the most storage space in the chaindata. A state trie contains nonces, balances and account keys of all accounts (including contracts) that exist on Klaytn. In the case of a contract account, it has a separate storage trie, which also gets stored in the state trie.

The data is saved in the form of a trie and each trie node is stored in the form of a key/value. As can be seen below, each trie node is stored in the existing database in the form of a key/value. A key is the hash of the trie node’s value, so even if there are several identical trie nodes, they will be stored as one unique record in the database.

The Idea behind State Trie Migration

As we have seen so far, every block contains a state trie. But notice below the trie nodes A and B, which only exist in block #100 and are not necessary for processing block #102.

That is how unnecessary trie nodes start to pile up. And the idea was that removing these trie nodes would not affect the processing of new blocks, even though past state would not be retrievable.

On Ethereum there is the “fast sync” option; basically, when you start a new node, you sync the last state via p2p, and only the new blocks added from that point on will be processed. But Klaytn went further and thought of ways to reduce data size without having to compromise the newly added as well as the currently running nodes.

Process of State Migration

Here is a step-by-step process:

  1. Create a new DB (a new state trie database). First, you need to create a DB for a new state trie once you know which block you want to perform the migration on. This new DB will store the state trie of the newly added blocks including the block, which you chose for the migration.
  2. Traverse the state trie of the migrated block and copy it in the new state trie DB.
  3. After the migration is complete, delete the old DB.
  4. Now you have a new DB, which stores the state of the specified block and the new blocks.

State Trie Migration may be a simple process, but it’s not really a quick one. And new blocks will be added during the migration and they should also be processed, with their results written on the new DB as well. In the diagram below, the new block #102 is being processed while migration for block #101 is still in progress, which means both new and existing DBs have to be queried.

Result of the State Migration

Let’s take a look at the changes in the storage after the migration. The state trie, which used to take up 942GB of storage space in the full node, has been greatly reduced by 94% to 55GB.

Migrated Full node: 294GB

(node which saves state for block #45,131,309 and every 128 blocks)

55G ./statetrie_migrated_45131309
92G ./header
72G ./body
63G ./receipts
9.3G ./txlookup
4.1G ./misc
344K ./bridgeservice
294G .

Technical Issues and Resolution

In the process of developing State Migration, we achieved higher speed through performance optimization.

Performance/Memory Optimization for State Migration

  1. Parallel Processing

After the first implementation of State Migration, it was found that it took more than several weeks on AWS EC2 m5.4xlarge instance. It was then reduced to three days by parallel copying of the DB.

2. Optimized writing of duplicate trie nodes

As of block #45,131,309, there are about 800 million nodes in the state trie, but excluding the duplicates, about 400 million. In order to eliminate the duplicates, the hash of the state trie already written on the DB gets stored. Before requesting a store to the DB, it checks whether the state trie node is already stored in the DB. It cuts down the required time from three days to one.

3. LRU-based Key Caching

When processing duplicate trie nodes, all trie node keys have to be stored, which requires over 20GB memory space for Cypress. But there are about 100 million duplicate nodes, and, by using 2GB LRU cache, the achieved performance was just like how it would have been if you had stored and checked all the trie node keys.

Aborted Migration and Errors

Since State Migration takes more than a day, the possibility of a termination or an unexpected error must also be taken into account. For this reason, we made it so that the trie nodes from the latest block can be stored in both the existing as well as the new DBs even when the State Migration is in process. Even when the migration is aborted, it is still possible to keep the existing DB and delete the new. And when the migration is complete, the new DB can be kept in place of the old one.

We’ve taken a look at the technical aspects of the State Migration process. We hope this could make the operation of Klaytn Node easier and more affordable by reducing the size of the chaindata on Cypress. But we won’t stop exploring more options in order to promptly remove nonessential trie nodes while each new block is being processed, ultimately to enhance the sustainability of state trie operations.

State Trie Migration can be implemented by calling startStateMigration API, with Klaytn v1.5.0 or higher. We encourage you to give it a go. For more details on how to use State Migration, refer to this link: Klaytn v1.5.0 State Migration: Saving Node Storage.

We hope that this post is helpful in reducing your block data. Klaytn team is always committed to providing our users new and better features by putting ourselves in the users’ shoes, and we will continue to do so in the future!

Thank you and stay tuned for our next post!