Skip to main content

Builders Starter's Guide

Kusama is a blockchain protocol with two goals: providing shared security among all connected parachains and allowing all connected chains to interoperate by using XCM. With the advent of PDKs like Substrate and Cumulus, the time it takes to develop and launch a new chain has dropped significantly. While before, it would take years to launch a new chain, now it may only take weeks or even days, depending on your goals.

This guide will walk you through the steps you can take today to get started building your vision with Kusama. It will explain the difference between a parachain and a smart contract in deciding which best fits your architectural needs.

This build guide provides four different tracks:

  1. Building Parachains
  2. Building a Pallet
  3. Developing Smart Contracts
  4. Developing a dApp

Keep in mind that these tracks are merely suggestive, and there are many ways to utilize Kusama, Substrate, and their various developmental components. For more inspiration, look at the open source projects featured here in the wiki!

Before diving into any one of these tracks, it is encouraged to read about Kusama and its networks in order to gain context about the application you could make.

Development Ecosystem Overview

init: {
'theme': 'base',
'themeVariables': {
'fontFamily': 'Unbounded',
'primaryColor': '#E6007A',
'fontSize': '18px',
'primaryTextColor': '#fff',
'primaryBorderColor': '#7C0000',
'lineColor': '#140523',
'secondaryColor': '#552BBF',
'tertiaryColor': '#fff'
flowchart TB
subgraph PL ["Protocol Side (Parachains, Smart Contracts)"]
ST[Build a Blockchain]
BSC[Develop a Smart Contract] --> SC[Smart Contract Parachain]
SC --> ink!
SC --> Solidity
ST --> R[WASM Runtime - FRAME]
R -->Parachain["Parachain"]-->SSC["Shared Security - Cumulus"]
R -->SoloChain[Solo Chain]-->NSS["No Shared Security"]

CS-->| Develop apps| PL

subgraph CS ["Client Side (dApps/uApps)"]
UA[UApp - Smoldot]
UA --> PJS[Polkadot JS]
UA --> SubXT

Before diving into the various paths, one can take in developing on , it's important to realize and know key terms that make up the following sections. Even before considering what kind of application you want to build, it's prudent to understand what is and how Kusama relates to it, and how what each developmental component can do for you within the Polkadot ecosystem.

Polkadot Ecosystem Networks

  • Mainnet: Polkadot
  • Canary network: Kusama
    • Kusama is a value-bearing canary network that gets features before Polkadot does. Expect Chaos.
  • Official testnets:
    • Westend - Functionality equal to the current Polkadot mainnet, with possible next-generation testing of features from time to time that will eventually migrate onto Polkadot. Perma-testnet (is not reset back to genesis block).
    • Canvas - Wasm-based Smart Contract enabled testnet, primarily for ink! development.
    • Rococo - Parachains and XCM testnet. Occasionally reset (started over again with a new genesis block).

Kusama mainnet has been running since August 2019 and has implementations in various programming languages ranging from Rust to JavaScript. The leading implementation is built in Rust and uses the Substrate framework.

Tooling is rapidly evolving to interact with the network; there are many ways to get started!

But before you jump head-first into the code, you should consider the kind of decentralized application you want to make and understand the different paradigms available to developers who want to build on Kusama.

Building Parachains

Kusama is canonically referred to as the Relay Chain. It is also considered a layer zero protocol, as it enables the interoperability and shared security of multiple parachains, which are layer one protocols. Parachains connect to a relay chain using the Parachains Protocol.

build 1


Throughout this document, you will encounter the term runtime or STF (State Transition Function). Both refer to the same concept, as they define how exactly a particular system, i.e., a blockchain, should deal with state changes externally and internally. Both of these terms are used extensively in Kusama, and by association, Substrate contexts.

Parachains open possibilities to construct complex runtime, or STF (state transition function) the logic that would be too expensive to execute with smart contracts. However, unlike smart contracts, parachains lack a mandatory gas metering system entirely and could potentially be vulnerable to bugs that cause infinite loops (something that is prevented by design in smart contracts). This vulnerability is mitigated by the weight system that is implemented in Substrate -- although it places more of a burden on the developer of the parachain to perform properly benchmarks.

What is a parathread?

Parathreads, or "on-demand parachains," are like parachains and enable the developer to have lower-level control of the logic of their application. The main difference between the two is economical since parathreads will be much less expensive to secure than a parachain and is a "pay-as-you-go" model. The lower costs of parathreads are because parathreads will only produce a block when needed, unlike parachains, which have secured a slot to produce a block at every block of the Relay Chain. When building a parathread, you will use the same tools (like PDKs) and get all the benefits of building a parachain without the cost drawback.

Constructing FRAME Runtimes with Substrate

Polkadot is built using the Substrate framework. Substrate is a highly configurable and dynamic framework for building blockchains. At a lower level, Substrate provides a set of tools and libraries ranging from block production, finality gadgets, to peer-to-peer networking. Both Polkadot and Kusama, as well as most parachains, are built using Substrate.

In essence, Substrate can break down a blockchain's development process by providing crucial building blocks of functionality, removing the need for re-engineering complex mechanisms that usually involved when developing a blockchain.

Substrate can be used as a basis for a parachain to connect to a relay chain like Polkadot or Kusama, or even as a basis to form a conventional layer one solo chain.

Currently, the most streamlined way of utilizing Substrate is FRAME, which conveniently allows for a runtime/STF to be generated from a set of modules (called pallets). Runtimes in Substrate are built using WebAssembly (Wasm), and represent the state transition function for a network. FRAME allows for a collection of business logic-oriented modules, called pallets, to construct a runtime/STF and define how exactly the blockchain is supposed to behave. Ranging from identity to smart contracts, pallets can be quite extensive in providing on-chain functionality.

Even though FRAME is heavily used, it is not the only way to create a valid runtime/STF using Substrate. Substrate can be used to create new paradigms and abstractions that build on the concept of web3.


Although most parachains utilize FRAME and Substrate to build runtime/STFs for connecting to the relay chain, it is not contingent. Building a parachain using other tools is possible, so long as they follow the Parachains Protocol.

As a general rule of thumb, Substrate provides the means for this to become possible through comparably minimal effort.

Building Parachains with Cumulus

Diving further into building parachains, Cumulus is another set of tools that aid in building a parachain-ready blockchain for Polkadot or Kusama. Cumulus utilizes FRAME and Substrate to create an easy way to build your first parachain. It ensures the chain follows the Parachain Protocol.


Cumulus clouds are shaped sort of like dots; together, they form a system that is intricate, beautiful, and functional.

For most developers, the best place to start is to get familiar with Substrate independently, followed by FRAME, with Cumulus as the final step to understanding the entire parachain building process. This way, one can view how various paradigms are applied and make decisions on integrating or utilizing Substrate for their particular use case.

Please see the parachain development guide for how to get started on building a parachain or parathread.

Parachains Benefits

Parachains contain their own runtime/STF logic and benefit from the shared security and the cross-chain messaging provided by the relay chain. Parachains permit high flexibility and customization but require more effort to create and maintain over time. A production-grade parachain is typically more involved to create due to the complexity involved in blockchain networks' technical and economic aspects.

Parachains grant the creators more space to build the monetary system and other chain aspects from the ground up. They will allow for a more concise and efficient execution of complex logic than a smart contract platform could offer. Parachains also offer more flexibility in the form of governance and can perform complete upgrades in a less controversial way than the current process of hard forks.

Some examples of features you can have on a parachain or parathread:

  • Custom fee structure (for example, pay a flat transaction fee or pay per byte).
  • Shared security and finalization via the relay chain (Polkadot or Kusama).
  • Custom monetary policy for the native token and local economy.
  • Treasury to be funded through transitions in your state function.
  • A governance mechanism that could manage a DAO that is responsible for allocating your on-chain treasury.

Building a Pallet

While parachains are highly customizable, they are often complex to develop. If you wish to get familiar with FRAME and Substrate, a good place to start is by building a pallet in a development environment. A pallet is a fully customizable module that allows you to implement layer one logic with relatively minimal development time on a basic level while still allowing the possibility of building advanced functionality into your custom chain.

To learn how to build a pallet, follow the Substrate documentation.

Developing Smart Contracts

Smart contracts are another option that enables for an often simpler developer experience. Below is a quick comparison of how building a smart contract compares to building a parachain:

ParachainsSmart Contracts
Speed of Development-+
Ease of Deployment-+
Complexity of logic+-
Maintenance overhead-+
Level of customization+-
Strict resource control-+
Native chain features+-
What's the difference between a smart contract and a pallet?

If you recall, a parachain comprises a runtime/STF usually built on Substrate. These runtime/STFs often utilize FRAME, which is subsequently made of pallets. Pallets are part of a Substrate runtime/STF, whereas smart contracts are a product of a pallet (see: pallet_contracts). Pallets require more engineering and thought, as they can directly affect the chain's state.

ink! and EVM-based Smart Contracts

At a high level, a smart contract is simply some code that exists at an address on a chain and is callable by external actors. Whether it's EVM-based, or written using ink!, smart contracts sandboxed, executable programs that live on-chain.


The Polkadot relay chain does not support smart contracts. However, several parachains do. See the smart contracts guide for more information about the environments provided.

A popular choice for smart contracts is ink!. Other parachains that offer EVM-based contracts written in Solidity alongside ink! are also available.

Because smart contracts exist on a single chain at a time, they can have smooth interoperability with other smart contracts on the same chain. However, they will always be constrained and limited by the inherent characteristics of their host chain.

As a developer, you will need to consider the storage and complexity of your smart contract to ensure that gas usage stays within reasonable bounds. Consider using the listed options on the decentralized storage page to keep the data and submit only the content address on the chain.

Building a smart contract

Please see the smart contracts guide for how to get started on building a smart contract.

Developing a dApp/uApp

If one aims to develop a dApp (Decentralized App) or uApp (Unstoppable App), the Polkadot ecosystem contains various SDKs to tap into the relay chain and parachains.

For front-end applications, several options exist for interfacing with Substrate-based chains (parachains, relay chains, etc.) and smart contracts. These often will interact with the RPC of a Substrate node:

Promise and RxJS APIs around Polkadot and Substrate based chains via RPC calls. It is dynamically generated based on what the Substrate runtime provides in terms of metadata. Full documentation & examples available.

For a full list of tools please take a look here: Tools, APIs and Languages