1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138
//! # Polkadot SDK
//!
//! The [Polkadot SDK repository](https://github.com/paritytech/polkadot-sdk) provides the main
//! resources needed to start building on the [Polkadot network](https://polkadot.network), a
//! multi-chain blockchain platform that enables different blockchains to interoperate and share
//! information in a secure and scalable way.
//!
//! [](https://substrate.stackexchange.com/)
//!
//! [](https://github.com/Awsmdot/awesome-dot)
//! [](https://wiki.polkadot.network/)
//! [](https://forum.polkadot.network/)
//!
//! [](https://github.com/polkadot-fellows/rfcs)
//! [](https://github.com/polkadot-fellows/runtimes)
//! [](https://github.com/polkadot-fellows/manifesto)
//!
//! ## 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"](crate#getting-started).
//!
//! ## Structure
//!
//! #### Substrate
//!
//! [](https://github.com/paritytech/polkadot-sdk/blob/master/substrate/LICENSE-APACHE2)
//! [](https://github.com/paritytech/polkadot-sdk/blob/master/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
//!
//! [](https://github.com/paritytech/polkadot-sdk/blob/master/substrate/LICENSE-APACHE2)
//! [](https://github.com/paritytech/polkadot-sdk/blob/master/substrate/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
//!
//! [](https://github.com/paritytech/polkadot-sdk/blob/master/cumulus/LICENSE)
//! [](https://github.com/paritytech/polkadot-sdk/blob/master/cumulus)
//!
//! [`cumulus`] transforms FRAME-based runtimes into Polkadot-compatible parachain runtimes, and
//! Substrate-based clients into Polkadot-compatible collators.
//!
//! #### Polkadot
//!
//! [](https://github.com/paritytech/polkadot-sdk/blob/master/polkadot/LICENSE)
//! [](https://github.com/paritytech/polkadot-sdk/blob/master/polkadot)
//!
//! [`polkadot`] is an implementation of a Polkadot client in Rust, by `@paritytech`. The Polkadot
//! runtimes are located under the [`polkadot-fellows/runtimes`](https://github.com/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
//!
//! [](https://github.com/paritytech/polkadot-sdk/blob/master/polkadot/LICENSE)
//! [](https://github.com/paritytech/polkadot-sdk/blob/master/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:
#![doc = simple_mermaid::mermaid!("../../../docs/mermaid/polkadot_sdk_substrate.mmd")]
//!
//! 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.
#![doc = simple_mermaid::mermaid!("../../../docs/mermaid/polkadot_sdk_polkadot.mmd")]
//! 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.
#![doc = simple_mermaid::mermaid!("../../../docs/mermaid/polkadot_sdk_parachain.mmd")]
//!
//! ## 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`](https://github.com/paritytech/parity-scale-codec)
//! - [`parity-db`](https://github.com/paritytech/parity-db)
//! - [`trie`](https://github.com/paritytech/trie)
//! - [`parity-common`](https://github.com/paritytech/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](https://github.com/availproject/avail)
//! * [Cardano Partner Chains](https://iohk.io/en/blog/posts/2023/11/03/partner-chains-are-coming-to-cardano/)
//! * [Starknet's Madara Sequencer](https://github.com/keep-starknet-strange/madara)
//!
//! [`substrate`]: crate::polkadot_sdk::substrate
//! [`frame`]: crate::polkadot_sdk::frame_runtime
//! [`cumulus`]: crate::polkadot_sdk::cumulus
//! [`polkadot`]: crate::polkadot_sdk::polkadot
//! [`xcm`]: crate::polkadot_sdk::xcm
/// Lean about Cumulus, the framework that transforms [`substrate`]-based chains into
/// [`polkadot`]-enabled parachains.
pub mod cumulus;
/// Learn about FRAME, the framework used to build Substrate runtimes.
pub mod frame_runtime;
/// Learn about Polkadot as a platform.
pub mod polkadot;
/// Learn about different ways through which smart contracts can be utilized on top of Substrate,
/// and in the Polkadot ecosystem.
pub mod smart_contracts;
/// Learn about Substrate, the main blockchain framework used in the Polkadot ecosystem.
pub mod substrate;
/// Index of all the templates that can act as first scaffold for a new project.
pub mod templates;
/// Learn about XCM, the de-facto communication language between different consensus systems.
pub mod xcm;