Module developer_hub::polkadot_sdk

An introduction to the Polkadot SDK. Read this module to learn about the structure of the SDK, the tools that are provided as a part of it, and to gain a high level understanding of each.

Polkadot SDK

The Polkadot SDK repository provides the main resources needed to start building on the Polkadot network, a multi-chain blockchain platform that enables different blockchains to interoperate and share information in a secure and scalable way.

Getting Started

The primary way to get started with the Polkadot SDK is to start writing a Substrate-based runtime using FRAME. See:

• polkadot, to understand what is Polkadot as a development platform.
• substrate, for an overview of what Substrate is.
• Jump right into frame to learn about how to write a FRAME-based blockchain runtime.
• Continue with the developer_hub’s “getting started”.

Structure

Substrate

substrate is the base blockchain framework used to power the Polkadot SDK. It is a full toolkit to create sovereign blockchains, including but not limited to those who connect to Polkadot as parachains.

FRAME

frame is the framework used to create Substrate-based runtimes. Learn more about the distinction of a runtime and client in crate::reference_docs::wasm_meta_protocol.

Cumulus

cumulus transforms FRAME-based runtimes into Polkadot-compatible parachain runtimes, and Substrate-based clients into Polkadot-compatible collators.

Polkadot

polkadot is an implementation of a Polkadot client in Rust, by @paritytech. The Polkadot runtimes are located under the polkadot-fellows/runtimes repository.

polkadot contains useful links to further learn about Polkadot, but is in general not part of the SDK, as it is rarely used by developers who wish to build on top of Polkadot.

XCM

xcm, short for “cross consensus message”, is the primary format that is used for communication between parachains, but is intended to be extensible to other use cases as well.

Summary

The following diagram summarizes how components of the Polkadot-SDK:

flowchart LR
	subgraph SubstrateChain[A Substrate-based blockchain]
		Client
		Runtime
	end

    FRAME -.-> Runtime
    Substrate[Substrate Client Libraries] -.-> Client

A Substrate-based chain is a blockchain composed of a “Runtime” and a “Client”. As noted above, the “Runtime” is the application logic of the blockchain, and the “Client” is everything else. See reference_docs::wasm_meta_protocol for an in-depth explanation of this. The former is built with frame, and the latter is built with Substrate client libraries.

You can think of a substrate-based chain as a while-labeled blockchain.

flowchart LR

	subgraph Polkadot[The Polkadot Relay Chain]
		PolkadotClient[Polkadot Client]
		PolkadotRuntime[Polkadot Runtime]
	end

    FRAME -.-> PolkadotRuntime
    Substrate[Substrate Client Libraries] -.-> PolkadotClient

Polkadot is itself a Substrate-based chain, composed of the exact same two components.

A parachain is a “special” Substrate-based chain, whereby both the client and the runtime components have became “Polkadot-aware” using Cumulus.

flowchart LR
	subgraph Parachain[A Polkadot Parachain]
		ParachainClient[Parachain Client]
		ParachainRuntime[Parachain Runtime]
	end

    FRAME -.-> ParachainRuntime
    Substrate[Substrate Client Libraries] -.-> ParachainClient

    CumulusC[Cumulus Client Libraries] -.-> ParachainClient
    CumulusR[Cumulus Runtime Libraries] -.-> ParachainRuntime

History

Substrate, Polkadot and Cumulus used to each have their own repository, each of which is now archived. For historical context about how they merged into this mono-repo, see:

• https://polkadot-public.notion.site/Polkadot-SDK-FAQ-fbc4cecc2c46443fb37b9eeec2f0d85f
• https://forum.polkadot.network/t/psa-parity-is-currently-working-on-merging-the-polkadot-stack-repositories-into-one-single-repository/2883

Notable Upstream Crates

• parity-scale-codec
• parity-db
• trie
• parity-common

Trophy Section: Notable Downstream Projects

A list of projects and tools in the blockchain ecosystem that one way or another parts of the Polkadot SDK.:

• Polygon’s spin-off, Avail
• Cardano Partner Chains
• Starknet’s Madara Sequencer

Modules

• cumulus
  Lean about Cumulus, the framework that transforms substrate-based chains into polkadot-enabled parachains.
• frame_runtime
  Learn about FRAME, the framework used to build Substrate runtimes.
• polkadot
  Learn about Polkadot as a platform.
• smart_contracts
  Learn about different ways through which smart contracts can be utilized on top of Substrate, and in the Polkadot ecosystem.
• substrate
  Learn about Substrate, the main blockchain framework used in the Polkadot ecosystem.
• templates
  Index of all the templates that can act as first scaffold for a new project.
• xcm
  Learn about XCM, the de-facto communication language between different consensus systems.