polkadot_sdk_docs/polkadot_sdk/mod.rs
1//! # Polkadot SDK
2//!
3//! [Polkadot SDK](https://github.com/paritytech/polkadot-sdk) provides the main resources needed to
4//! start building on the [Polkadot network](https://polkadot.com/), a scalable, multi-chain
5//! blockchain platform that enables different blockchains to securely interoperate.
6//!
7//! [](https://substrate.stackexchange.com/)
8//!
9//! [](https://github.com/Awsmdot/awesome-dot)
10//! [](https://wiki.polkadot.network/)
11//! [](https://forum.polkadot.network/)
12//!
13//! [](https://github.com/polkadot-fellows/rfcs)
14//! [](https://github.com/polkadot-fellows/runtimes)
15//! [](https://github.com/polkadot-fellows/manifesto/blob/main/manifesto.pdf)
16//!
17//! ## Getting Started
18//!
19//! The primary way to get started with the Polkadot SDK is to start writing a FRAME-based runtime.
20//! See:
21//!
22//! * [`polkadot`], to understand what is Polkadot as a development platform.
23//! * [`substrate`], for an overview of what Substrate as the main blockchain framework of Polkadot
24//! SDK.
25//! * [`frame`], to learn about how to write blockchain applications aka. "App Chains".
26//! * Continue with the [`polkadot_sdk_docs`'s "getting started"](crate#getting-started).
27//!
28//! ## Components
29//!
30//! #### Substrate
31//!
32//! [](https://github.com/paritytech/polkadot-sdk/blob/master/substrate/LICENSE-APACHE2)
33//! [](https://github.com/paritytech/polkadot-sdk/blob/master/substrate)
35//!
36//! [`substrate`] is the base blockchain framework used to power the Polkadot SDK. It is a full
37//! toolkit to create sovereign blockchains, including but not limited to those which connect to
38//! Polkadot as parachains.
39//!
40//! #### FRAME
41//!
42//! [](https://github.com/paritytech/polkadot-sdk/blob/master/substrate/LICENSE-APACHE2)
43//! [](https://github.com/paritytech/polkadot-sdk/blob/master/substrate/frame)
45//!
46//! [`frame`] is the framework used to create Substrate-based application logic, aka. runtimes.
47//! Learn more about the distinction of a runtime and node in
48//! [`reference_docs::wasm_meta_protocol`].
49//!
50//! #### Cumulus
51//!
52//! [](https://github.com/paritytech/polkadot-sdk/blob/master/cumulus/LICENSE)
53//! [](https://github.com/paritytech/polkadot-sdk/blob/master/cumulus)
55//!
56//! [`cumulus`] transforms FRAME-based runtimes into Polkadot-compatible parachain runtimes, and
57//! Substrate-based nodes into Polkadot/Parachain-compatible nodes.
58//!
59//! #### XCM
60//!
61//! [](https://github.com/paritytech/polkadot-sdk/blob/master/polkadot/LICENSE)
62//! [](https://github.com/paritytech/polkadot-sdk/blob/master/polkadot/xcm)
64//!
65//! [`xcm`], short for "cross consensus message", is the primary format that is used for
66//! communication between parachains, but is intended to be extensible to other use cases as well.
67//!
68//! #### Polkadot
69//!
70//! [](https://github.com/paritytech/polkadot-sdk/blob/master/polkadot/LICENSE)
71//! [](https://github.com/paritytech/polkadot-sdk/blob/master/polkadot)
73//!
74//! [`polkadot`] is an implementation of a Polkadot node in Rust, by `@paritytech`. The Polkadot
75//! runtimes are located under the
76//! [`polkadot-fellows/runtimes`](https://github.com/polkadot-fellows/runtimes) repository.
77//!
78//! ### Binaries
79//!
80//! The main binaries that are part of the Polkadot SDK are:
81
82//! * [`polkadot`]: The Polkadot relay chain node binary, as noted above.
83//! * [`polkadot-omni-node`]: A white-labeled parachain collator node. See more in
84//! [`crate::reference_docs::omni_node`].
85//! * [`polkadot-parachain-bin`]: The collator node used to run collators for all Polkadot system
86//! parachains.
87//! * [`frame-omni-bencher`]: a benchmarking tool for FRAME-based runtimes. Nodes typically contain
88//! a
89//! `benchmark` subcommand that does the same.
90//! * [`chain_spec_builder`]: Utility to build chain-specs Nodes typically contain a `build-spec`
91//! subcommand that does the same.
92//! * [`subkey`]: Substrate's key management utility.
93//! * [`substrate-node`](node_cli) is an extensive substrate node that contains the superset of all
94//! runtime and node side features. The corresponding runtime, called [`kitchensink_runtime`]
95//! contains all of the modules that are provided with `FRAME`. This node and runtime is only used
96//! for testing and demonstration.
97//!
98//! ### Summary
99//!
100//! The following diagram summarizes how some of the components of Polkadot SDK work together:
101#![doc = simple_mermaid::mermaid!("../../../mermaid/polkadot_sdk_substrate.mmd")]
102//!
103//! A Substrate-based chain is a blockchain composed of a runtime and a node. As noted above, the
104//! runtime is the application logic of the blockchain, and the node is everything else.
105//! See [`reference_docs::wasm_meta_protocol`] for an in-depth explanation of this. The
106//! former is built with [`frame`], and the latter is built with rest of Substrate.
107//!
108//! > You can think of a Substrate-based chain as a white-labeled blockchain.
109#![doc = simple_mermaid::mermaid!("../../../mermaid/polkadot_sdk_polkadot.mmd")]
110//! Polkadot is itself a Substrate-based chain, composed of the exact same two components. It has
111//! specialized logic in both the node and the runtime side, but it is not "special" in any way.
112//!
113//! A parachain is a "special" Substrate-based chain, whereby both the node and the runtime
114//! components have became "Polkadot-aware" using Cumulus.
115#![doc = simple_mermaid::mermaid!("../../../mermaid/polkadot_sdk_parachain.mmd")]
116//!
117//! ## Notable Upstream Crates
118//!
119//! - [`parity-scale-codec`](https://github.com/paritytech/parity-scale-codec)
120//! - [`parity-db`](https://github.com/paritytech/parity-db)
121//! - [`trie`](https://github.com/paritytech/trie)
122//! - [`parity-common`](https://github.com/paritytech/parity-common)
123//!
124//! ## Trophy Section: Notable Downstream Projects
125//!
126//! A list of projects and tools in the blockchain ecosystem that one way or another use parts of
127//! the Polkadot SDK:
128//!
129//! * [Avail](https://github.com/availproject/avail)
130//! * [Cardano Partner Chains](https://iohk.io/en/blog/posts/2023/11/03/partner-chains-are-coming-to-cardano/)
131//! * [Starknet's Madara Sequencer](https://github.com/keep-starknet-strange/madara)
132//! * [Polymesh](https://polymesh.network/)
133//!
134//! [`substrate`]: crate::polkadot_sdk::substrate
135//! [`frame`]: crate::polkadot_sdk::frame_runtime
136//! [`cumulus`]: crate::polkadot_sdk::cumulus
137//! [`polkadot`]: crate::polkadot_sdk::polkadot
138//! [`xcm`]: crate::polkadot_sdk::xcm
139//! [`frame-omni-bencher`]: https://crates.io/crates/frame-omni-bencher
140//! [`polkadot-parachain-bin`]: https://crates.io/crates/polkadot-parachain-bin
141//! [`polkadot-omni-node`]: https://crates.io/crates/polkadot-omni-node
142
143/// Learn about Cumulus, the framework that transforms [`substrate`]-based chains into
144/// [`polkadot`]-enabled parachains.
145pub mod cumulus;
146/// Learn about FRAME, the framework used to build Substrate runtimes.
147pub mod frame_runtime;
148/// Learn about Polkadot as a platform.
149pub mod polkadot;
150/// Learn about different ways through which smart contracts can be utilized on top of Substrate,
151/// and in the Polkadot ecosystem.
152pub mod smart_contracts;
153/// Learn about Substrate, the main blockchain framework used in the Polkadot ecosystem.
154pub mod substrate;
155/// Index of all the templates that can act as first scaffold for a new project.
156pub mod templates;
157/// Learn about XCM, the de-facto communication language between different consensus systems.
158pub mod xcm;