Skip to main content

Polkadot Developer Portal

Polkadot 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 Polkadot. It will explain the difference between a parachain and a smart contract in deciding which best fits your architectural needs.

This build guide provides three different tracks:

  1. Protocol Development - Blockchain & Parachain Development
  2. Developing Smart Contracts
  3. Developing a dApp
Keep reading to find out more, or visit each respective track

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

Development Ecosystem Overview​

Before diving into the various paths, one can take in developing on Polkadot, 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 Polkadot is and how relates to it, and what each developmental component can do for you within the Polkadot ecosystem.

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

Building Parachains​

Polkadot 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

info

Throughout this document, you will encounter the term runtime or STF (State Transition Function). Both refer to the same concept, as they define how a particular system, i.e., a blockchain, should deal with state changes externally and internally. Both of these terms are used extensively in Polkadot, 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.

note

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, as 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.

info

Cumulus clouds are shaped like dots; together, they form an intricate, beautiful and functional system.

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 decide 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-consensus messaging provided by the Polkadot 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 provide 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 fundamental 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 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+-
Scalability+-
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.

note

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), 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.

Please visit the full documentation for developing dApps and other general client-side development resources.

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

Resources​