Polkadot is a networking protocol that reduces development time for blockchain developers. Launching and securing a new blockchain used to take years. With Polkadot it will take weeks or maybe even days.

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 (and why one may be better suited for your application over the other). It will lay out the resources that are available now and the ones that are coming soon so that you can get started creating your application in anticipation of the Polkadot mainnet launch later this year.

For a full introduction to Polkadot and Substrate I strongly urge you to read this article, which gives an up-to-date overview on these two technologies.

What you need to know: Polkadot is currently on the PoC-4 release with a running testnet named Alexander. This testnet has been live for 3 months through the entire PoC-3 release cycle. The PoC-4 release happened earlier this week and brought some new features. Polkadot is being built on Substrate, a blockchain development framework. Substrate can be employed by developers to create their own custom state transitions for their own chains. Substrate is nearing the first 1.0 stable release, which will settle its API.

In summary, there hasn’t been a better time to get started preparing for Polkadot’s release. Before you jump into the code, you should understand the different paradigms that will be offered to developers interested in building on Polkadot.

Polkadot provides two ways for you to deploy your application: as a smart contract on an existing parachain, or as your own parachain. There are trade-offs when working with either one of these and reading this section will help you understand them.

Parachains are individual chains containing their own runtime logic that benefit from the shared security and the interchain messaging provided by the Polkadot relay chain. Parachains permit a high degree of flexibility and customization but will require more effort to create.

On the Polkadot mainnet, there will be one or more parachains that act as smart contract platforms. Smart contracts are executable programs that exist on only a single chain and are limited in complexity. Because they exist on a single chain, they have smooth interoperability with other smart contracts. However, they will always be constrained and limited by the inherent characteristics of their host chain.

If there is a need to have a large amount of control over the design and features of your application, a parachain is a better choice. Keep in mind, smart contracts can be used as a testing ground before later being turned into full-fledged parachains. Smart contract platforms will usually have more convenient tooling like IDEs to facilitate quick iterations. A smart contract MVP could be created to gauge user interest before putting in the fuller work to build out a parachain.

Parachains will grant the creators more space to build the monetary system of the chain from the ground up. They will allow for more succinct and efficient execution of complex logic than could ever be offered by a smart contract platform. Parachains also offer more 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:

• Custom fee structure (for example, pay a flat fee for transactions or pay by byte)
• Custom inflation policy for the native token
• 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

Parachains open possibilities to construct complex runtimes that would be too expensive to execute with smart contracts. Parachains in comparison lack a gas metering system entirely and could potentially be vulnerable to bugs that cause infinite loops (something that is prevented in smart contracts).

You may also decided to harness a combination of parachain and smart contract. If you have certain logic that requires loops and it cannot be removed, use the native parachain runtime to handle all complex logic and the smart contract to call iteration.

Most likely you’ve already realized that your application is better suited to be one or the other (or a hybrid of the two), but if you need a quick recap to digest the information, you can use this comparison chart as a cheat sheet:

This guide now splits into two sections depending on whether you’ve decided on smart contract or parachain to build your application. Feel free to read both sections, or just the one that is applicable to you.

Now that you have determined that building a parachain is the right approach for your new project, the next step would be to decide which framework to use. Right now, Substrate is the only framework for developing parachains.

In the future, there will be many implementations of the Polkadot runtime in various languages ranging through C++, Rust, Go, and JS.

Get started with Substrate

As mentioned above, Substrate is the underlying framework on which Polkadot itself is built. It is a tool set for blockchain innovators and provides the necessary building blocks for constructing a chain. It includes a library of modular plug-ins from which you can compose more complex chain logic.

The best way to get started with Substrate is to explore the Substrate Development Hub, an online resource built and maintained by Parity Technologies.

Visit the Substrate Developer Hub -> HERE

We recommend that you poke around in there to become familiar with the common patterns. Once you have a solid understanding, you can challenge yourself by progressing through the Substratekitties workshop then advancing to the TCR Dappchain tutorial.

How to set up your parachain

After creating your chain logic with Substrate, you will be able to compile it down to a Wasm executable. This Wasm code blob will contain the entire state transition function of your chain.

Validators on the Polkadot relay chain will use this Wasm blob to validate all of the state transitions of your parachain.

In order for the Polkadot validators to stay up to date with the recent state transitions of your parachain, it will need some required infrastructure. The work described above is performed by your parachain’s collator node.

Substrate comes with its own networking layer built-in but unfortunately it will not be a Polkadot-compatible collator node out-of-the-box.

For this, Parity Technologies has been developing an extension to Substrate called Cumulus, which will make it easy to turn any Substrate-built chain into a Polkadot-ready parachain.

Cumulus

The goal of Cumulus is to be an extension of Substrate that will make any Substrate runtime compatible with Polkadot.

It handles the network compatibility overhead that any parachain would need to implement to be connected to Polkadot. This includes:

• Interchain message passing
• Out-of-the-box Collator node setup
• An embedded light client of the relay chain
• Polkadot block authorship compatibility

Integrating Cumulus with your Substrate chain will port it into a parachain capable of working on Polkadot with minimal modification, possible as little work as importing a crate and adding a single line.

Rob Habermeier, a co-founder of Polkadot, recently gave a talk at EthCC that gave the latest on the development of Cumulus, which you can watch below.

Leasing a parachain slot for your chain

Note: For the full description of the parachain slot auction mechanism see the updated page on the wiki.

The primary mechanism for the allocation of parachain slots is through a permission-less candle auction which will require the winner to bond DOTs for the duration of their lease.

At Polkadot’s launch the number of parachain slots may only number a few. As time goes on, there should new slots opening up every 6 months or so to meet demand. The goal is to eventually open up around 200 parachain slots with auctions occurring continuously.

Parachain slots will be leased for units of 6-month duration with the maximum duration of a slot being 2 years.

In order to participate in the auction you would need DOTs to cover your highest bids, since if you are determined to be the highest bidder you would need to lock them up for the whole duration of the lease.

A small number of parachain slots will be held for community-good projects and held initially by the Web3 Foundation (and possibly later handed over to the governance system). But the vast majority of slots will be available through auction.

You may want to start considering the different ways that you would be able to come up with enough DOTs to participate in this auction. Some ideas include:

• Oversee a crowdfunding campaign in which many participants stake DOTs for a specific chain individually
• Manage a crowdsale in which individuals will purchase your token in exchange for the DOTs you need to bond for the slot
• Other/private means, which may include venture capital or footing the bill yourself

What will happen when the time of the slot runs out?

Once you have secured a slot in the parachain registry, you will be able to deploy your Wasm code to that slot until the duration of the lease elapses.

The philosophy for parachains slots is that everyone has a predictable end date to her slot and no one can snatch it away. Only in the most rare cases would the governance mechanism propose a vote to remove a parachain if it turned out to be especially malicious or harmful to Polkadot.

When the slot is approaching the conclusion of its duration, there are a few options you may consider:

• You can hold a referendum on the relay chain to include your parachain on Polkadot indefinitely; if your parachain has proven especially useful this may actually pass (remember, the governance system is all powerful and capable of extraordinary feats)
• You can hold a vote between the stakeholders of your parachain to determine if they would like to “renew” the slot by continuing to stake the DOTs or bidding in the auction process again
• Users can safely migrate all usage away from your parachain to another alternative before the parachain is removed
• You can perform one of the fundraising methods listed in the prior section to raise the requisite amount of DOTs to participate in the next auction
• You can choose to end your lease and enlist your own validator set to become a sovereign chain, separate from Polkadot and its shared security

In most cases it will be fairly straightforward to cast bids for a continuous parachain slot and continue to bond DOTs for a lease.

Although the Polkadot relay chain does not support smart contracts, there will be Polkadot parachains that do.

Parity Technologies has already laid much of the groundwork for a new smart contract stack that is based on a Wasm virtual machine and includes a domain specific language (pDSL) in Rust.

Substrate includes a contract module that includes the core logic needed for a smart contract chain. Along these lines, the pDSL will be a smart contract language written in Rust that takes advantage of the already existing Rust tooling and support and will compile to Wasm.

Edgeware is a project that has already announced its intent to launch using this smart contract technology described above and will connect to Polkadot at or soon after mainnet launch.

Note: It’s still early for most of the smart contract technology on Polkadot and the following information is intended to give you an idea of what you can expect. We will keep the corresponding wiki page updated with new information as it emerges.

Deploying a smart contract

A smart contract is simply some code that exists at an address on a chain and is callable by external actors. The key part is that you actually have to put the code on chain before anyone can start executing it!

Deploying your smart contract on chain will vary slightly for whichever specific parachain you will use, but generally you will send a special transaction that will CREATE the smart contract on the ledger.

Paying for your smart contract

Each platform will have a different way of paying for and maintaining the state of your smart contract.

The different patterns you may see for paying for your smart contract include:

• A transaction fee associated with the deploy transaction.
• A subscription model in which you pay some chain entity routinely for usage of the platform.
• An access token model for which you need to hold a threshold of native tokens to use the platform (EOS has something similar).
• Storage rent.
• Free trial or developer promotion.

Most smart contract platforms use some form of gas to limit the number of operations a user can perform. Users will be required to pay for the gas upfront and will be refunded for what they don’t use.

You will need to consider the storage and complexity of your smart contract to ensure that gas usage stays within reasonable bounds. Storage will likely be expensive for whichever smart contract platform you use, so it is necessary to keep as much data off-chain as possible. You may consider using IPFS or Storj to keep the data and submitting only the content address on chain.

It’s still early

It’s still very early for smart contracts on Polkadot and the development is only now stabilizing. We are actively producing content to help developers get up to speed and will maintain the wiki with the latest resources. You should also keep up to date with the following links:

• Edgeware.
• pDSL. (Keep an eye out for content on the wiki tab.)
• Substrate contracts module.

This guide has given you a mental model and shown the requisite resources to help you determine and start building your project as a parachain or smart contract today. Even though the tooling is still maturing, the advantage of being early will be the familiarity and head start on your project, allowing you to innovate and create something truly new.

If you have interesting ideas for parachains or smart contracts on Polkadot feel free to drop in to the Polkadot Watercooler to talk about them. Developers may be interested in joining the Polkadot Beginners Lounge or Substrate Technical to ask their questions. As always, keep up to date with Polkadot by following the socials channels. Good luck!

An up-to-date version of this post will be maintained on the wiki.