mirror of
https://github.com/pezkuwichain/pezkuwi-subxt.git
synced 2026-06-19 00:41:03 +00:00
Move developer-hub to polkadot-sdk-docs (#2598)
This PR is a continuation of https://github.com/paritytech/polkadot-sdk/pull/2102 and part of an initiative started here https://hackmd.io/@romanp/rJ318ZCEp What has been done: - The content under `docs/*` (with the exception of `docs/mermaid`) has been moved to `docs/contributor/` - Developer Hub has been renamed to Polkadot SDK Docs, and the crate has been renamed from `developer-hub` to `polkadot-sdk-docs` - The content under `developer-hub/*` has been moved to `docs/sdk` --- Original PR https://github.com/paritytech/polkadot-sdk/pull/2565, it has been close due to too many rebase conflicts --------- Co-authored-by: Serban Iorga <serban@parity.io> Co-authored-by: Chevdor <chevdor@users.noreply.github.com> Co-authored-by: Egor_P <egor@parity.io> Co-authored-by: Bastian Köcher <git@kchr.de>
This commit is contained in:
Juan Girini
@@ -0,0 +1,130 @@
|
||||
//! # Cumulus
|
||||
//!
|
||||
//! Substrate provides a framework ([FRAME]) through which a blockchain node and runtime can easily
|
||||
//! be created. Cumulus aims to extend the same approach to creation of Polkadot parachains.
|
||||
//!
|
||||
//! > Cumulus clouds are shaped sort of like dots; together they form a system that is intricate,
|
||||
//! > beautiful and functional.
|
||||
//!
|
||||
//! ## Example: Runtime
|
||||
//!
|
||||
//! A Cumulus-based runtime is fairly similar to other [FRAME]-based runtimes. Most notably, the
|
||||
//! following changes are applied to a normal FRAME-based runtime to make it a Cumulus-based
|
||||
//! runtime:
|
||||
//!
|
||||
//! #### Cumulus Pallets
|
||||
//!
|
||||
//! A parachain runtime should use a number of pallets that are provided by Cumulus and Substrate.
|
||||
//! Notably:
|
||||
//!
|
||||
//! - [`frame-system`](frame::prelude::frame_system), like all FRAME-based runtimes.
|
||||
//! - [`cumulus_pallet_parachain_system`]
|
||||
//! - [`parachain_info`]
|
||||
#![doc = docify::embed!("./src/polkadot_sdk/cumulus.rs", system_pallets)]
|
||||
//!
|
||||
//! Given that all Cumulus-based runtimes use a simple Aura-based consensus mechanism, the following
|
||||
//! pallets also need to be added:
|
||||
//!
|
||||
//! - [`pallet_timestamp`]
|
||||
//! - [`pallet_aura`]
|
||||
//! - [`cumulus_pallet_aura_ext`]
|
||||
#![doc = docify::embed!("./src/polkadot_sdk/cumulus.rs", consensus_pallets)]
|
||||
//!
|
||||
//!
|
||||
//! Finally, a separate macro, similar to
|
||||
//! [`impl_runtime_api`](frame::runtime::prelude::impl_runtime_apis), which creates the default set
|
||||
//! of runtime APIs, will generate the parachain runtime's validation runtime API, also known as
|
||||
//! parachain validation function (PVF). Without this API, the relay chain is unable to validate
|
||||
//! blocks produced by our parachain.
|
||||
#![doc = docify::embed!("./src/polkadot_sdk/cumulus.rs", validate_block)]
|
||||
//!
|
||||
//! ---
|
||||
//!
|
||||
//! [FRAME]: crate::polkadot_sdk::frame_runtime
|
||||
|
||||
#![deny(rustdoc::broken_intra_doc_links)]
|
||||
#![deny(rustdoc::private_intra_doc_links)]
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
mod runtime {
|
||||
pub use frame::{
|
||||
deps::sp_consensus_aura::sr25519::AuthorityId as AuraId, prelude::*,
|
||||
runtime::prelude::*, testing_prelude::*,
|
||||
};
|
||||
|
||||
#[docify::export(CR)]
|
||||
construct_runtime!(
|
||||
pub struct Runtime {
|
||||
// system-level pallets.
|
||||
System: frame_system,
|
||||
Timestamp: pallet_timestamp,
|
||||
ParachainSystem: cumulus_pallet_parachain_system,
|
||||
ParachainInfo: parachain_info,
|
||||
|
||||
// parachain consensus support -- mandatory.
|
||||
Aura: pallet_aura,
|
||||
AuraExt: cumulus_pallet_aura_ext,
|
||||
}
|
||||
);
|
||||
|
||||
#[docify::export]
|
||||
mod system_pallets {
|
||||
use super::*;
|
||||
|
||||
#[derive_impl(frame_system::config_preludes::TestDefaultConfig as frame_system::DefaultConfig)]
|
||||
impl frame_system::Config for Runtime {
|
||||
type Block = MockBlock<Self>;
|
||||
type OnSetCode = cumulus_pallet_parachain_system::ParachainSetCode<Self>;
|
||||
}
|
||||
|
||||
impl cumulus_pallet_parachain_system::Config for Runtime {
|
||||
type RuntimeEvent = RuntimeEvent;
|
||||
type OnSystemEvent = ();
|
||||
type SelfParaId = parachain_info::Pallet<Runtime>;
|
||||
type OutboundXcmpMessageSource = ();
|
||||
type XcmpMessageHandler = ();
|
||||
type ReservedDmpWeight = ();
|
||||
type ReservedXcmpWeight = ();
|
||||
type CheckAssociatedRelayNumber =
|
||||
cumulus_pallet_parachain_system::RelayNumberMonotonicallyIncreases;
|
||||
type ConsensusHook = cumulus_pallet_aura_ext::FixedVelocityConsensusHook<
|
||||
Runtime,
|
||||
6000, // relay chain block time
|
||||
1,
|
||||
1,
|
||||
>;
|
||||
type WeightInfo = ();
|
||||
type DmpQueue = frame::traits::EnqueueWithOrigin<(), sp_core::ConstU8<0>>;
|
||||
}
|
||||
|
||||
impl parachain_info::Config for Runtime {}
|
||||
}
|
||||
|
||||
#[docify::export]
|
||||
mod consensus_pallets {
|
||||
use super::*;
|
||||
|
||||
impl pallet_aura::Config for Runtime {
|
||||
type AuthorityId = AuraId;
|
||||
type DisabledValidators = ();
|
||||
type MaxAuthorities = ConstU32<100_000>;
|
||||
type AllowMultipleBlocksPerSlot = ConstBool<false>;
|
||||
#[cfg(feature = "experimental")]
|
||||
type SlotDuration = pallet_aura::MinimumPeriodTimesTwo<Self>;
|
||||
}
|
||||
|
||||
#[docify::export(timestamp)]
|
||||
#[derive_impl(pallet_timestamp::config_preludes::TestDefaultConfig as pallet_timestamp::DefaultConfig)]
|
||||
impl pallet_timestamp::Config for Runtime {}
|
||||
|
||||
impl cumulus_pallet_aura_ext::Config for Runtime {}
|
||||
}
|
||||
|
||||
#[docify::export(validate_block)]
|
||||
cumulus_pallet_parachain_system::register_validate_block! {
|
||||
Runtime = Runtime,
|
||||
BlockExecutor = cumulus_pallet_aura_ext::BlockExecutor::<Runtime, Executive>,
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,179 @@
|
||||
//! # FRAME
|
||||
//!
|
||||
//! ```no_compile
|
||||
//! ______ ______ ________ ___ __ __ ______
|
||||
//! /_____/\ /_____/\ /_______/\ /__//_//_/\ /_____/\
|
||||
//! \::::_\/_\:::_ \ \ \::: _ \ \\::\| \| \ \\::::_\/_
|
||||
//! \:\/___/\\:(_) ) )_\::(_) \ \\:. \ \\:\/___/\
|
||||
//! \:::._\/ \: __ `\ \\:: __ \ \\:.\-/\ \ \\::___\/_
|
||||
//! \:\ \ \ \ `\ \ \\:.\ \ \ \\. \ \ \ \\:\____/\
|
||||
//! \_\/ \_\/ \_\/ \__\/\__\/ \__\/ \__\/ \_____\/
|
||||
//! ```
|
||||
//!
|
||||
//! > **F**ramework for **R**untime **A**ggregation of **M**odularized **E**ntities: Substrate's
|
||||
//! > State Transition Function (Runtime) Framework.
|
||||
//!
|
||||
//! ## Introduction
|
||||
//!
|
||||
//! As described in [`crate::reference_docs::wasm_meta_protocol`], at a high-level Substrate-based
|
||||
//! blockchains are composed of two parts:
|
||||
//!
|
||||
//! 1. A *runtime* which represents the state transition function (i.e. "Business Logic") of a
|
||||
//! blockchain, and is encoded as a WASM blob.
|
||||
//! 2. A node whose primary purpose is to execute the given runtime.
|
||||
#![doc = simple_mermaid::mermaid!("../../../mermaid/substrate_simple.mmd")]
|
||||
//!
|
||||
//! *FRAME is the Substrate's framework of choice to build a runtime.*
|
||||
//!
|
||||
//! FRAME is composed of two major components, **pallets** and a **runtime**.
|
||||
//!
|
||||
//! ## Pallets
|
||||
//!
|
||||
//! A pallet is a unit of encapsulated logic. It has a clearly defined responsibility and can be
|
||||
//! linked to other pallets. In order to be reusable, pallets shipped with FRAME strive to only care
|
||||
//! about its own responsibilities and make as few assumptions about the general runtime as
|
||||
//! possible. A pallet is analogous to a _module_ in the runtime.
|
||||
//!
|
||||
//! A pallet is defined as a `mod pallet` wrapped by the [`frame::pallet`] macro. Within this macro,
|
||||
//! pallet components/parts can be defined. Most notable of these parts are:
|
||||
//!
|
||||
//! - [Config](frame::pallet_macros::config), allowing a pallet to make itself configurable and
|
||||
//! generic over types, values and such.
|
||||
//! - [Storage](frame::pallet_macros::storage), allowing a pallet to define onchain storage.
|
||||
//! - [Dispatchable function](frame::pallet_macros::call), allowing a pallet to define extrinsics
|
||||
//! that are callable by end users, from the outer world.
|
||||
//! - [Events](frame::pallet_macros::event), allowing a pallet to emit events.
|
||||
//! - [Errors](frame::pallet_macros::error), allowing a pallet to emit well-formed errors.
|
||||
//!
|
||||
//! Some of these pallet components resemble the building blocks of a smart contract. While both
|
||||
//! models are programming state transition functions of blockchains, there are crucial differences
|
||||
//! between the two. See [`crate::reference_docs::runtime_vs_smart_contract`] for more.
|
||||
//!
|
||||
//! Most of these components are defined using macros, the full list of which can be found in
|
||||
//! [`frame::pallet_macros`].
|
||||
//!
|
||||
//! ### Example
|
||||
//!
|
||||
//! The following examples showcases a minimal pallet.
|
||||
#![doc = docify::embed!("src/polkadot_sdk/frame_runtime.rs", pallet)]
|
||||
//!
|
||||
//!
|
||||
//! A runtime is a collection of pallets that are amalgamated together. Each pallet typically has
|
||||
//! some configurations (exposed as a `trait Config`) that needs to be *specified* in the runtime.
|
||||
//! This is done with [`frame::runtime::prelude::construct_runtime`].
|
||||
//!
|
||||
//! A (real) runtime that actually wishes to compile to WASM needs to also implement a set of
|
||||
//! runtime-apis. These implementation can be specified using the
|
||||
//! [`frame::runtime::prelude::impl_runtime_apis`] macro.
|
||||
//!
|
||||
//! ### Example
|
||||
//!
|
||||
//! The following example shows a (test) runtime that is composing the pallet demonstrated above,
|
||||
//! next to the [`frame::prelude::frame_system`] pallet, into a runtime.
|
||||
#![doc = docify::embed!("src/polkadot_sdk/frame_runtime.rs", runtime)]
|
||||
//!
|
||||
//! ## More Examples
|
||||
//!
|
||||
//! You can find more FRAME examples that revolve around specific features at [`pallet_examples`].
|
||||
//!
|
||||
//! ## Alternatives 🌈
|
||||
//!
|
||||
//! There is nothing in the Substrate's node side code-base that mandates the use of FRAME. While
|
||||
//! FRAME makes it very simple to write Substrate-based runtimes, it is by no means intended to be
|
||||
//! the only one. At the end of the day, any WASM blob that exposes the right set of runtime APIs is
|
||||
//! a valid Runtime form the point of view of a Substrate client (see
|
||||
//! [`crate::reference_docs::wasm_meta_protocol`]). Notable examples are:
|
||||
//!
|
||||
//! * writing a runtime in pure Rust, as done in [this template](https://github.com/JoshOrndorff/frameless-node-template).
|
||||
//! * writing a runtime in AssemblyScript,as explored in [this project](https://github.com/LimeChain/subsembly).
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use frame::prelude::*;
|
||||
|
||||
/// A FRAME based pallet. This `mod` is the entry point for everything else. All
|
||||
/// `#[pallet::xxx]` macros must be defined in this `mod`. Although, frame also provides an
|
||||
/// experimental feature to break these parts into different `mod`s. See [`pallet_examples`] for
|
||||
/// more.
|
||||
#[docify::export]
|
||||
#[frame::pallet(dev_mode)]
|
||||
pub mod pallet {
|
||||
use super::*;
|
||||
|
||||
/// The configuration trait of a pallet. Mandatory. Allows a pallet to receive types at a
|
||||
/// later point from the runtime that wishes to contain it. It allows the pallet to be
|
||||
/// parameterized over both types and values.
|
||||
#[pallet::config]
|
||||
pub trait Config: frame_system::Config {
|
||||
/// A type that is not known now, but the runtime that will contain this pallet will
|
||||
/// know it later, therefore we define it here as an associated type.
|
||||
type RuntimeEvent: IsType<<Self as frame_system::Config>::RuntimeEvent>
|
||||
+ From<Event<Self>>;
|
||||
|
||||
/// A parameterize-able value that we receive later via the `Get<_>` trait.
|
||||
type ValueParameter: Get<u32>;
|
||||
|
||||
/// Similar to [`Config::ValueParameter`], but using `const`. Both are functionally
|
||||
/// equal, but offer different tradeoffs.
|
||||
const ANOTHER_VALUE_PARAMETER: u32;
|
||||
}
|
||||
|
||||
/// A mandatory struct in each pallet. All functions callable by external users (aka.
|
||||
/// transactions) must be attached to this type (see [`frame::pallet_macros::call`]). For
|
||||
/// convenience, internal (private) functions can also be attached to this type.
|
||||
#[pallet::pallet]
|
||||
pub struct Pallet<T>(PhantomData<T>);
|
||||
|
||||
/// The events tha this pallet can emit.
|
||||
#[pallet::event]
|
||||
pub enum Event<T: Config> {}
|
||||
|
||||
/// A storage item that this pallet contains. This will be part of the state root trie/root
|
||||
/// of the blockchain.
|
||||
#[pallet::storage]
|
||||
pub type Value<T> = StorageValue<Value = u32>;
|
||||
|
||||
/// All *dispatchable* call functions (aka. transactions) are attached to `Pallet` in a
|
||||
/// `impl` block.
|
||||
#[pallet::call]
|
||||
impl<T: Config> Pallet<T> {
|
||||
/// This will be callable by external users, and has two u32s as a parameter.
|
||||
pub fn some_dispatchable(
|
||||
_origin: OriginFor<T>,
|
||||
_param: u32,
|
||||
_other_para: u32,
|
||||
) -> DispatchResult {
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// A simple runtime that contains the above pallet and `frame_system`, the mandatory pallet of
|
||||
/// all runtimes. This runtime is for testing, but it shares a lot of similarities with a *real*
|
||||
/// runtime.
|
||||
#[docify::export]
|
||||
pub mod runtime {
|
||||
use super::pallet as pallet_example;
|
||||
use frame::{prelude::*, testing_prelude::*};
|
||||
|
||||
// The major macro that amalgamates pallets into `struct Runtime`
|
||||
construct_runtime!(
|
||||
pub struct Runtime {
|
||||
System: frame_system,
|
||||
Example: pallet_example,
|
||||
}
|
||||
);
|
||||
|
||||
// These `impl` blocks specify the parameters of each pallet's `trait Config`.
|
||||
#[derive_impl(frame_system::config_preludes::TestDefaultConfig as frame_system::DefaultConfig)]
|
||||
impl frame_system::Config for Runtime {
|
||||
type Block = MockBlock<Self>;
|
||||
}
|
||||
|
||||
impl pallet_example::Config for Runtime {
|
||||
type RuntimeEvent = RuntimeEvent;
|
||||
type ValueParameter = ConstU32<42>;
|
||||
const ANOTHER_VALUE_PARAMETER: u32 = 42;
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,134 @@
|
||||
//! # Polkadot SDK
|
||||
//!
|
||||
//! [Polkadot SDK](https://github.com/paritytech/polkadot-sdk) provides the main resources needed to
|
||||
//! start building on the [Polkadot network](https://polkadot.network), a scalable, multi-chain
|
||||
//! blockchain platform that enables different blockchains to securely interoperate.
|
||||
//!
|
||||
//! [](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 FRAME-based runtime.
|
||||
//! See:
|
||||
//!
|
||||
//! * [`polkadot`], to understand what is Polkadot as a development platform.
|
||||
//! * [`substrate`], for an overview of what Substrate as the main blockchain framework of Polkadot
|
||||
//! SDK.
|
||||
//! * [`frame`], to learn about how to write blockchain applications aka. "App Chains".
|
||||
//! * Continue with the [`polkadot_sdk_docs`'s "getting started"](crate#getting-started).
|
||||
//!
|
||||
//! ## Components
|
||||
//!
|
||||
//! #### 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 application logic, aka. runtimes.
|
||||
//! Learn more about the distinction of a runtime and node in
|
||||
//! [`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 nodes into Polkadot/Parachain-compatible nodes.
|
||||
//!
|
||||
//! #### 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.
|
||||
//!
|
||||
//! #### 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 node in Rust, by `@paritytech`. The Polkadot
|
||||
//! runtimes are located under the
|
||||
//! [`polkadot-fellows/runtimes`](https://github.com/polkadot-fellows/runtimes) repository.
|
||||
//!
|
||||
//! ### Summary
|
||||
//!
|
||||
//! The following diagram summarizes how some of the components of Polkadot SDK work together:
|
||||
#![doc = simple_mermaid::mermaid!("../../../mermaid/polkadot_sdk_substrate.mmd")]
|
||||
//!
|
||||
//! A Substrate-based chain is a blockchain composed of a runtime and a node. As noted above, the
|
||||
//! runtime is the application logic of the blockchain, and the node is everything else.
|
||||
//! See [`crate::reference_docs::wasm_meta_protocol`] for an in-depth explanation of this. The
|
||||
//! former is built with [`frame`], and the latter is built with rest of Substrate.
|
||||
//!
|
||||
//! > You can think of a Substrate-based chain as a white-labeled blockchain.
|
||||
#![doc = simple_mermaid::mermaid!("../../../mermaid/polkadot_sdk_polkadot.mmd")]
|
||||
//! Polkadot is itself a Substrate-based chain, composed of the exact same two components. It has
|
||||
//! specialized logic in both the node and the runtime side, but it is not "special" in any way.
|
||||
//!
|
||||
//! A parachain is a "special" Substrate-based chain, whereby both the node and the runtime
|
||||
//! components have became "Polkadot-aware" using Cumulus.
|
||||
#![doc = simple_mermaid::mermaid!("../../../mermaid/polkadot_sdk_parachain.mmd")]
|
||||
//!
|
||||
//! ## 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;
|
||||
@@ -0,0 +1,87 @@
|
||||
//! # Polkadot
|
||||
//!
|
||||
//! Implementation of the Polkadot node/host in Rust.
|
||||
//!
|
||||
//! ## Learn More and Get Involved
|
||||
//!
|
||||
//! - [Polkadot Forum](https://forum.polkadot.network/)
|
||||
//! - [Polkadot Parachains](https://parachains.info/)
|
||||
//! - [Polkadot (multi-chain) Explorer](https://subscan.io/)
|
||||
//! - Polkadot Fellowship
|
||||
//! - [Manifesto](https://github.com/polkadot-fellows/manifesto)
|
||||
//! - [Runtimes](https://github.com/polkadot-fellows/runtimes)
|
||||
//! - [RFCs](https://github.com/polkadot-fellows/rfcs)
|
||||
//! - [Polkadot Specs](spec.polkadot.network)
|
||||
//! - [The Polkadot Parachain Host Implementers' Guide](https://paritytech.github.io/polkadot-sdk/book/)
|
||||
//! - [Whitepaper](https://www.polkadot.network/whitepaper/)
|
||||
//!
|
||||
//! ## Alternative Node Implementations 🌈
|
||||
//!
|
||||
//! - [Smoldot](https://crates.io/crates/smoldot-light). Polkadot light node/client.
|
||||
//! - [KAGOME](https://github.com/qdrvm/kagome). C++ implementation of the Polkadot host.
|
||||
//! - [Gossamer](https://github.com/ChainSafe/gossamer). Golang implementation of the Polkadot host.
|
||||
//!
|
||||
//! ## Platform
|
||||
//!
|
||||
//! In this section, we examine what what platform Polkadot exactly provides to developers.
|
||||
//!
|
||||
//! ### Polkadot White Paper
|
||||
//!
|
||||
//! The original vision of Polkadot (everything in the whitepaper, which was eventually called
|
||||
//! **Polkadot 1.0**) revolves around the following arguments:
|
||||
//!
|
||||
//! * Future is multi-chain, because we need different chains with different specialization to
|
||||
//! achieve widespread goals.
|
||||
//! * In other words, no single chain is good enough to achieve all goals.
|
||||
//! * A multi-chain future will inadvertently suffer from fragmentation of economic security.
|
||||
//! * This stake fragmentation will make communication over consensus system with varying security
|
||||
//! levels inherently unsafe.
|
||||
//!
|
||||
//! Polkadot's answer to the above is:
|
||||
//!
|
||||
//! > The chains of the future must have a way to share their economic security, whilst maintaining
|
||||
//! > their execution and governance sovereignty. These chains are called "Parachains".
|
||||
//!
|
||||
//! * Shared Security: The idea of shared economic security sits at the core of Polkadot. Polkadot
|
||||
//! enables different parachains* to pool their economic security from Polkadot (i.e. "*Relay
|
||||
//! Chain*").
|
||||
//! * (heterogenous) Sharded Execution: Yet, each parachain is free to have its own execution logic
|
||||
//! (runtime), which also encompasses governance and sovereignty. Moreover, Polkadot ensures the
|
||||
//! correct execution of all parachain, without having all of its validators re-execute all
|
||||
//! parachain blocks. When seen from this perspective, the fact that Polkadot executes different
|
||||
//! parachains means it is a platform that has fully delivered (the holy grail of) "Full Execution
|
||||
//! Sharding". TODO: link to approval checking article. https://github.com/paritytech/polkadot-sdk-docs/issues/66
|
||||
//! * A framework to build blockchains: In order to materialize the ecosystem of parachains, an easy
|
||||
//! blockchain framework must exist. This is [Substrate](crate::polkadot_sdk::substrate),
|
||||
//! [FRAME](crate::polkadot_sdk::frame_runtime) and [Cumulus](crate::polkadot_sdk::cumulus).
|
||||
//! * A communication language between blockchains: In order for these blockchains to communicate,
|
||||
//! they need a shared language. [XCM](crate::polkadot_sdk::xcm) is one such language, and the one
|
||||
//! that is most endorsed in the Polkadot ecosystem.
|
||||
//!
|
||||
//! > Note that the interoperability promised by Polkadot is unparalleled in that any two parachains
|
||||
//! > connected to Polkadot have the same security and can have much better guarantees about the
|
||||
//! > security of the recipient of any message. TODO: weakest link in bridges systems. https://github.com/paritytech/polkadot-sdk-docs/issues/66
|
||||
//!
|
||||
//! Polkadot delivers the above vision, alongside a flexible means for parachains to schedule
|
||||
//! themselves with the Relay Chain. To achieve this, Polkadot has been developed with an
|
||||
//! architecture similar to that of a computer. Polkadot Relay Chain has a number of "cores". Each
|
||||
//! core is (in simple terms) capable of progressing 1 parachain at a time. For example, a parachain
|
||||
//! can schedule itself on a single core for 5 relay chain blocks.
|
||||
//!
|
||||
//! Within the scope of Polkadot 1.x, two main scheduling ways have been considered:
|
||||
//!
|
||||
//! * Long term Parachains, obtained through locking a sum of DOT in an auction system.
|
||||
//! * on-demand Parachains, purchased through paying DOT to the relay-chain whenever needed.
|
||||
//!
|
||||
//! ### The Future
|
||||
//!
|
||||
//! After delivering Polkadot 1.x, the future of Polkadot as a protocol and platform is in the hands
|
||||
//! of the community and the fellowship. This is happening most notable through the RFC process.
|
||||
//! Some of the RFCs that do alter Polkadot as a platform and have already passed are as follows:
|
||||
//!
|
||||
//! - RFC#1: [Agile-coretime](https://github.com/polkadot-fellows/RFCs/blob/main/text/0001-agile-coretime.md):
|
||||
//! Agile periodic-sale-based model for assigning Coretime on the Polkadot Ubiquitous Computer.
|
||||
//! - RFC#5: [Coretime-interface](https://github.com/polkadot-fellows/RFCs/blob/main/text/0005-coretime-interface.md):
|
||||
//! Interface for manipulating the usage of cores on the Polkadot Ubiquitous Computer.
|
||||
// TODO: add more context and explanations about Polkadot as the Ubiquitous Computer and related
|
||||
// tech. https://github.com/paritytech/polkadot-sdk-docs/issues/66
|
||||
@@ -0,0 +1,9 @@
|
||||
//! # Smart Contracts
|
||||
//!
|
||||
//! TODO: @cmichi https://github.com/paritytech/polkadot-sdk-docs/issues/56
|
||||
//!
|
||||
//! - WASM and EVM based, pallet-contracts and pallet-evm.
|
||||
//! - single-daap-chain, transition from ink! to FRAME.
|
||||
//! - Link to `use.ink`
|
||||
//! - Link to [`crate::reference_docs::runtime_vs_smart_contract`].
|
||||
//! - https://use.ink/migrate-ink-contracts-to-polkadot-frame-parachain/
|
||||
@@ -0,0 +1,151 @@
|
||||
//! # Substrate
|
||||
//!
|
||||
//! Substrate is a Rust framework for building blockchains in a modular and extensible way. While in
|
||||
//! itself un-opinionated, it is the main engine behind the Polkadot ecosystem.
|
||||
//!
|
||||
//! ## Overview, Philosophy
|
||||
//!
|
||||
//! Substrate approaches blockchain development with an acknowledgement of a few self-evident
|
||||
//! truths:
|
||||
//!
|
||||
//! 1. Society and technology evolves.
|
||||
//! 2. Humans are fallible.
|
||||
//!
|
||||
//! This, makes the task of designing a correct, safe and long-lasting blockchain system hard.
|
||||
//!
|
||||
//! Nonetheless, in strive towards achieve this goal, Substrate embraces the following:
|
||||
//!
|
||||
//! 1. Use of **Rust** as a modern and safe programming language, which limits human error through
|
||||
//! various means, most notably memory and type safety.
|
||||
//! 2. Substrate is written from the ground-up with a *generic, modular and extensible* design. This
|
||||
//! ensures that software components can be easily swapped and upgraded. Examples of this is
|
||||
//! multiple consensus mechanisms provided by Substrate, as listed below.
|
||||
//! 3. Lastly, the final blockchain system created with the above properties needs to be
|
||||
//! upgradeable. In order to achieve this, Substrate is designed as a meta-protocol, whereby the
|
||||
//! application logic of the blockchain (called "Runtime") is encoded as a WASM blob, and is
|
||||
//! stored in the state. The rest of the system (called "node") acts as the executor of the WASM
|
||||
//! blob.
|
||||
//!
|
||||
//! In essence, the meta-protocol of all Substrate based chains is the "Runtime as WASM blob"
|
||||
//! accord. This enables the Runtime to become inherently upgradeable, crucially without forks. The
|
||||
//! upgrade is merely a matter of the WASM blob being changed in the state, which is, in principle,
|
||||
//! same as updating an account's balance. Learn more about this in detail in
|
||||
//! [`crate::reference_docs::wasm_meta_protocol`].
|
||||
//!
|
||||
//! > A great analogy for substrate is the following: Substrate node is a gaming console, and a WASM
|
||||
//! > runtime, possibly created with FRAME is the game being inserted into the console.
|
||||
//!
|
||||
//! [`frame`], Substrate's default runtime development library, takes the above safety practices
|
||||
//! even further by embracing a declarative programming model whereby correctness is enhanced and
|
||||
//! the system is highly configurable through parameterization. Learn more about this in
|
||||
//! [`crate::reference_docs::trait_based_programming`].
|
||||
//!
|
||||
//! ## How to Get Started
|
||||
//!
|
||||
//! Substrate offers different options at the spectrum of technical freedom <-> development ease.
|
||||
//!
|
||||
//! * The easiest way to use Substrate is to use one of the templates (some of which listed at
|
||||
//! [`crate::polkadot_sdk::templates`]) and only tweak the parameters of the runtime or node. This
|
||||
//! allows you to launch a blockchain in minutes, but is limited in technical freedom.
|
||||
//! * Next, most developers wish to develop their custom runtime modules, for which the de-facto way
|
||||
//! is [`frame`](crate::polkadot_sdk::frame_runtime).
|
||||
//! * Finally, Substrate is highly configurable at the node side as well, but this is the most
|
||||
//! technically demanding.
|
||||
//!
|
||||
//! > A notable Substrate-based blockchain that has built both custom FRAME pallets and custom
|
||||
//! > node-side components is <https://github.com/Cardinal-Cryptography/aleph-node>.
|
||||
#![doc = simple_mermaid::mermaid!("../../../mermaid/substrate_dev.mmd")]
|
||||
//!
|
||||
//! ## Structure
|
||||
//!
|
||||
//! Substrate contains a large number of crates, therefore it is useful to have an overview of what
|
||||
//! they are, and how they are organized. In broad terms, these crates are divided into three
|
||||
//! categories:
|
||||
//!
|
||||
//! * `sc-*` (short for *Substrate-client*) crates, located under `./client` folder. These are all
|
||||
//! the crates that lead to the node software. Notable examples [`sc_network`], various consensus
|
||||
//! crates, RPC ([`sc_rpc_api`]) and database ([`sc_client_db`]), all of which are expected to
|
||||
//! reside in the node side.
|
||||
//! * `sp-*` (short for *substrate-primitives*) crates, located under `./primitives` folder. These
|
||||
//! are crates that facilitate both the node and the runtime, but are not opinionated about what
|
||||
//! framework is using for building the runtime. Notable examples are [`sp_api`] and [`sp_io`],
|
||||
//! which form the communication bridge between the node and runtime.
|
||||
//! * `pallet-*` and `frame-*` crates, located under `./frame` folder. These are the crates related
|
||||
//! to FRAME. See [`frame`] for more information.
|
||||
//!
|
||||
//! ### WASM Build
|
||||
//!
|
||||
//! Many of the Substrate crates, such as entire `sp-*`, need to compile to both WASM (when a WASM
|
||||
//! runtime is being generated) and native (for example, when testing). To achieve this, Substrate
|
||||
//! follows the convention of the Rust community, and uses a `feature = "std"` to signify that a
|
||||
//! crate is being built with the standard library, and is built for native. Otherwise, it is built
|
||||
//! for `no_std`.
|
||||
//!
|
||||
//! This can be summarized in `#![cfg_attr(not(feature = "std"), no_std)]`, which you can often find
|
||||
//! in any Substrate-based runtime.
|
||||
//!
|
||||
//! Substrate-based runtimes use [`substrate_wasm_builder`] in their `build.rs` to automatically
|
||||
//! build their WASM files as a part of normal build command (e.g. `cargo build`). Once built, the
|
||||
//! wasm file is placed in `./target/{debug|release}/wbuild/{runtime_name}.wasm`.
|
||||
//!
|
||||
//! ### Binaries
|
||||
//!
|
||||
//! Multiple binaries are shipped with substrate, the most important of which are located in the
|
||||
//! [`./bin`](https://github.com/paritytech/polkadot-sdk/tree/master/substrate/bin) folder.
|
||||
//!
|
||||
//! * [`node_cli`] is an extensive substrate node that contains the superset of all runtime and node
|
||||
//! side features. The corresponding runtime, called [`kitchensink_runtime`] contains all of the
|
||||
//! modules that are provided with `FRAME`. This node and runtime is only used for testing and
|
||||
//! demonstration.
|
||||
//! * [`chain_spec_builder`]: Utility to build more detailed chain-specs for the aforementioned
|
||||
//! node. Other projects typically contain a `build-spec` subcommand that does the same.
|
||||
//! * [`node_template`](https://github.com/paritytech/polkadot-sdk/tree/master/substrate/bin/node-template):
|
||||
//! a template node that contains a minimal set of features and can act as a starting point of a
|
||||
//! project.
|
||||
//! * [`subkey`]: Substrate's key management utility.
|
||||
//!
|
||||
//! ### Anatomy of a Binary Crate
|
||||
//!
|
||||
//! From the above, [`node_cli`]/[`kitchensink_runtime`] and `node-template` are essentially
|
||||
//! blueprints of a Substrate-based project, as the name of the latter is implying. Each
|
||||
//! Substrate-based project typically contains the following:
|
||||
//!
|
||||
//! * Under `./runtime`, a `./runtime/src/lib.rs` which is the top level runtime amalgamator file.
|
||||
//! This file typically contains the [`frame::runtime::prelude::construct_runtime`] and
|
||||
//! [`frame::runtime::prelude::impl_runtime_apis`] macro calls, which is the final definition of a
|
||||
//! runtime.
|
||||
//!
|
||||
//! * Under `./node`, a `main.rs`, which is the starting point, and a `./service.rs`, which contains
|
||||
//! all the node side components. Skimming this file yields an overview of the networking,
|
||||
//! database, consensus and similar node side components.
|
||||
//!
|
||||
//! > The above two are conventions, not rules.
|
||||
//!
|
||||
//! > See <https://github.com/paritytech/polkadot-sdk/issues/5> for an update on how the node side
|
||||
//! > components are being amalgamated.
|
||||
//!
|
||||
//! ## Parachain?
|
||||
//!
|
||||
//! As noted above, Substrate is the main engine behind the Polkadot ecosystem. One of the ways
|
||||
//! through which Polkadot can be utilized is by building "parachains", blockchains that are
|
||||
//! connected to Polkadot's shared security.
|
||||
//!
|
||||
//! To build a parachain, one could use [Cumulus](crate::polkadot_sdk::cumulus), the library on
|
||||
//! top of Substrate, empowering any substrate-based chain to be a Polkadot parachain.
|
||||
//!
|
||||
//! ## Where To Go Next?
|
||||
//!
|
||||
//! Additional noteworthy crates within substrate:
|
||||
//!
|
||||
//! - RPC APIs of a Substrate node: [`sc_rpc_api`]/[`sc_rpc`]
|
||||
//! - CLI Options of a Substrate node: [`sc_cli`]
|
||||
//! - All of the consensus related crates provided by Substrate:
|
||||
//! - [`sc_consensus_aura`]
|
||||
//! - [`sc_consensus_babe`]
|
||||
//! - [`sc_consensus_grandpa`]
|
||||
//! - [`sc_consensus_beefy`] (TODO: @adrian, add some high level docs https://github.com/paritytech/polkadot-sdk-docs/issues/57)
|
||||
//! - [`sc_consensus_manual_seal`]
|
||||
//! - [`sc_consensus_pow`]
|
||||
|
||||
#[doc(hidden)]
|
||||
pub use crate::polkadot_sdk;
|
||||
@@ -0,0 +1,45 @@
|
||||
//! # Templates
|
||||
//!
|
||||
//! ### Internal
|
||||
//!
|
||||
//! The following templates are maintained as a part of the `polkadot-sdk` repository:
|
||||
//!
|
||||
//! - classic [`substrate-node-template`]: is a white-labeled substrate-based blockchain with a
|
||||
//! moderate amount of features. It can act as a great starting point for those who want to learn
|
||||
//! Substrate/FRAME and want to have a template that is already doing something.
|
||||
//! - [`substrate-minimal-template`]: Same as the above, but it contains the least amount of code in
|
||||
//! both the node and runtime. It is a great starting point for those who want to deeply learn
|
||||
//! Substrate and FRAME.
|
||||
//! - classic [`cumulus-parachain-template`], which is the de-facto parachain template shipped with
|
||||
//! Cumulus. It is the parachain-enabled version of [`substrate-node-template`].
|
||||
//!
|
||||
//! ### External Templates
|
||||
//!
|
||||
//! Noteworthy templates outside of this repository.
|
||||
//!
|
||||
//! - [`extended-parachain-template`](https://github.com/paritytech/extended-parachain-template): A
|
||||
//! parachain template that contains more built-in functionality such as assets and NFTs.
|
||||
//! - [`frontier-parachain-template`](https://github.com/paritytech/frontier-parachain-template): A
|
||||
//! parachain template for launching EVM-compatible parachains.
|
||||
//!
|
||||
//! [`substrate-node-template`]: https://github.com/paritytech/polkadot-sdk/blob/master/substrate/bin/node-template/
|
||||
//! [`substrate-minimal-template`]: https://github.com/paritytech/polkadot-sdk/blob/master/substrate/bin/minimal/
|
||||
//! [`cumulus-parachain-template`]: https://github.com/paritytech/polkadot-sdk/blob/master/cumulus/parachain-template/
|
||||
|
||||
// TODO: in general, we need to make a deliberate choice here of moving a few key templates to this
|
||||
// repo (nothing stays in `substrate-developer-hub`) and the everything else should be community
|
||||
// maintained. https://github.com/paritytech/polkadot-sdk-docs/issues/67
|
||||
|
||||
// TODO: we should rename `substrate-node-template` to `substrate-basic-template`,
|
||||
// `substrate-blockchain-template`. `node` is confusing in the name.
|
||||
// `substrate-blockchain-template` and `cumulus-parachain-template` go well together 🤝. https://github.com/paritytech/polkadot-sdk-docs/issues/67
|
||||
|
||||
// NOTE: a super important detail that I am looking forward to here is
|
||||
// <https://github.com/paritytech/polkadot-sdk/issues/62#issuecomment-1691523754> and
|
||||
// <https://github.com/paritytech/polkadot-sdk/issues/5>. Meaning that I would not spend time on
|
||||
// teaching someone too much detail about the ugly thing we call "node" nowadays. In the future, I
|
||||
// am sure we will either have a better "node-builder" code that can actually be tested, or an
|
||||
// "omni-node" that can run (almost) any wasm file. We should already build tutorials in this
|
||||
// direction IMO. This also affects all the templates. If we have a good neat runtime file, which we
|
||||
// are moving toward, and a good node-builder, we don't need all of these damn templates. These
|
||||
// templates are only there because the boilerplate is super horrible atm.
|
||||
@@ -0,0 +1,5 @@
|
||||
//! # XCM
|
||||
//!
|
||||
//! @KiChjang @franciscoaguirre
|
||||
//! TODO: RFCs, xcm-spec, the future of the repo, minimal example perhaps, forward to where actual
|
||||
//! docs are hosted. https://github.com/paritytech/polkadot-sdk-docs/issues/58
|
||||
Reference in New Issue
Block a user