mirror of
https://github.com/pezkuwichain/pezkuwi-subxt.git
synced 2026-08-05 11:25:41 +00:00
Introduce Polkadot-Sdk developer_hub (#2102)
This PR introduces the new crate `developer_hub` into the polkadot-sdk repo. The vision for the developer-hub crate is detailed in [this document](https://docs.google.com/document/d/1XLLkFNE8v8HLvZpI2rzsa8N2IN1FcKntc8q-Sc4xBAk/edit?usp=sharing). <img width="1128" alt="Screenshot 2023-11-02 at 10 45 48" src="https://github.com/paritytech/polkadot-sdk/assets/5588131/1e12b60f-fef5-42c4-8503-a3ba234077c3"> Other than adding the new crate, it also does the following: * Remove the `substrate` crate, as there is now a unique umbrella crate for multiple things in `developer_hub::polkadot_sdk`. * (backport candidate) A minor change to `frame-support` macros that allows `T::RuntimeOrigin` to also be acceptable as the origin type. * (backport candidate) A minor change to `frame-system` that allows us to deposit events at genesis because now the real genesis config is generated via wasm, and we can safely assume `cfg!(feature = "std")` means only testing. related to #62. * (backport candidate) Introduces a small `read_events_for_pallet` to `frame_system` for easier event reading in tests. * From https://github.com/paritytech/polkadot-sdk-docs/issues/31, it takes action on improving the `pallet::call` docs. * From https://github.com/paritytech/polkadot-sdk-docs/issues/31, it takes action on improving the `UncheckedExtrinsic` docs. ## Way Forward First, a version of this is deployed temporarily [here](https://blog.kianenigma.nl/polkadot-sdk/developer_hub/index.html). I will keep it up to date on a daily basis. ### This Pull Request I see two ways forward: 1. We acknowledge that everything in `developer-hub` is going to be WIP, and merge this asap. We should not yet use links to this crate anywhere. 2. We make this be the feature branch, make PRs against this, and either gradually backport it, or only merge to master once it is done. I am personally in favor of option 1. If we stick to option 2, we need a better way to deploy a staging version of this to gh-pages. ### Issue Tracking The main issues related to the future of `developer_hub` are: - https://github.com/paritytech/polkadot-sdk-docs/issues/31 - https://github.com/paritytech/polkadot-sdk-docs/issues/4 - https://github.com/paritytech/polkadot-sdk-docs/issues/26 - https://github.com/paritytech/polkadot-sdk-docs/issues/32 - https://github.com/paritytech/polkadot-sdk-docs/issues/36 ### After This Pull Request - [ ] create a redirect for https://paritytech.github.io/polkadot-sdk/master/substrate/ - [x] analytics - [ ] link checker - [ ] the matter of publishing, and how all of these relative links for when we do, that is still an open question. There is section on this in the landing page. - [ ] updated https://paritytech.github.io/ --------- Co-authored-by: Liam Aharon <liam.aharon@hotmail.com> Co-authored-by: Juan Girini <juangirini@gmail.com> Co-authored-by: bader y <ibnbassem@gmail.com> Co-authored-by: Sebastian Kunert <skunert49@gmail.com> Co-authored-by: James Wilson <james@jsdw.me> Co-authored-by: Michal Kucharczyk <1728078+michalkucharczyk@users.noreply.github.com>
This commit is contained in:
Kian Paimani
@@ -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!("../../../docs/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 [`developer_hub`'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!("../../../docs/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!("../../../docs/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!("../../../docs/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!("../../../docs/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