Oliver Tale-Yazdi
eefd5fe449
This MR is the merge of https://github.com/paritytech/substrate/pull/14414 and https://github.com/paritytech/substrate/pull/14275. It implements [RFC#13](https://github.com/polkadot-fellows/RFCs/pull/13), closes https://github.com/paritytech/polkadot-sdk/issues/198. ----- This Merge request introduces three major topicals: 1. Multi-Block-Migrations 1. New pallet `poll` hook for periodic service work 1. Replacement hooks for `on_initialize` and `on_finalize` in cases where `poll` cannot be used and some more general changes to FRAME. The changes for each topical span over multiple crates. They are listed in topical order below. # 1.) Multi-Block-Migrations Multi-Block-Migrations are facilitated by creating `pallet_migrations` and configuring `System::Config::MultiBlockMigrator` to point to it. Executive picks this up and triggers one step of the migrations pallet per block. The chain is in lockdown mode for as long as an MBM is ongoing. Executive does this by polling `MultiBlockMigrator::ongoing` and not allowing any transaction in a block, if true. A MBM is defined through trait `SteppedMigration`. A condensed version looks like this: ```rust /// A migration that can proceed in multiple steps. pub trait SteppedMigration { type Cursor: FullCodec + MaxEncodedLen; type Identifier: FullCodec + MaxEncodedLen; fn id() -> Self::Identifier; fn max_steps() -> Option<u32>; fn step( cursor: Option<Self::Cursor>, meter: &mut WeightMeter, ) -> Result<Option<Self::Cursor>, SteppedMigrationError>; } ``` `pallet_migrations` can be configured with an aggregated tuple of these migrations. It then starts to migrate them one-by-one on the next runtime upgrade. Two things are important here: - 1. Doing another runtime upgrade while MBMs are ongoing is not a good idea and can lead to messed up state. - 2. **Pallet Migrations MUST BE CONFIGURED IN `System::Config`, otherwise it is not used.** The pallet supports an `UpgradeStatusHandler` that can be used to notify external logic of upgrade start/finish (for example to pause XCM dispatch). Error recovery is very limited in the case that a migration errors or times out (exceeds its `max_steps`). Currently the runtime dev can decide in `FailedMigrationHandler::failed` how to handle this. One follow-up would be to pair this with the `SafeMode` pallet and enact safe mode when an upgrade fails, to allow governance to rescue the chain. This is currently not possible, since governance is not `Mandatory`. ## Runtime API - `Core`: `initialize_block` now returns `ExtrinsicInclusionMode` to inform the Block Author whether they can push transactions. ### Integration Add it to your runtime implementation of `Core` and `BlockBuilder`: ```patch diff --git a/runtime/src/lib.rs b/runtime/src/lib.rs @@ impl_runtime_apis! { impl sp_block_builder::Core<Block> for Runtime { - fn initialize_block(header: &<Block as BlockT>::Header) { + fn initialize_block(header: &<Block as BlockT>::Header) -> RuntimeExecutiveMode { Executive::initialize_block(header) } ... } ``` # 2.) `poll` hook A new pallet hook is introduced: `poll`. `Poll` is intended to replace mostly all usage of `on_initialize`. The reason for this is that any code that can be called from `on_initialize` cannot be migrated through an MBM. Currently there is no way to statically check this; the implication is to use `on_initialize` as rarely as possible. Failing to do so can result in broken storage invariants. The implementation of the poll hook depends on the `Runtime API` changes that are explained above. # 3.) Hard-Deadline callbacks Three new callbacks are introduced and configured on `System::Config`: `PreInherents`, `PostInherents` and `PostTransactions`. These hooks are meant as replacement for `on_initialize` and `on_finalize` in cases where the code that runs cannot be moved to `poll`. The reason for this is to make the usage of HD-code (hard deadline) more explicit - again to prevent broken invariants by MBMs. # 4.) FRAME (general changes) ## `frame_system` pallet A new memorize storage item `InherentsApplied` is added. It is used by executive to track whether inherents have already been applied. Executive and can then execute the MBMs directly between inherents and transactions. The `Config` gets five new items: - `SingleBlockMigrations` this is the new way of configuring migrations that run in a single block. Previously they were defined as last generic argument of `Executive`. This shift is brings all central configuration about migrations closer into view of the developer (migrations that are configured in `Executive` will still work for now but is deprecated). - `MultiBlockMigrator` this can be configured to an engine that drives MBMs. One example would be the `pallet_migrations`. Note that this is only the engine; the exact MBMs are injected into the engine. - `PreInherents` a callback that executes after `on_initialize` but before inherents. - `PostInherents` a callback that executes after all inherents ran (including MBMs and `poll`). - `PostTransactions` in symmetry to `PreInherents`, this one is called before `on_finalize` but after all transactions. A sane default is to set all of these to `()`. Example diff suitable for any chain: ```patch @@ impl frame_system::Config for Test { type MaxConsumers = ConstU32<16>; + type SingleBlockMigrations = (); + type MultiBlockMigrator = (); + type PreInherents = (); + type PostInherents = (); + type PostTransactions = (); } ``` An overview of how the block execution now looks like is here. The same graph is also in the rust doc. <details><summary>Block Execution Flow</summary> <p>  </p> </details> ## Inherent Order Moved to https://github.com/paritytech/polkadot-sdk/pull/2154 --------------- ## TODO - [ ] Check that `try-runtime` still works - [ ] Ensure backwards compatibility with old Runtime APIs - [x] Consume weight correctly - [x] Cleanup --------- Signed-off-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io> Co-authored-by: Liam Aharon <liam.aharon@hotmail.com> Co-authored-by: Juan Girini <juangirini@gmail.com> Co-authored-by: command-bot <> Co-authored-by: Francisco Aguirre <franciscoaguirreperez@gmail.com> Co-authored-by: Gavin Wood <gavin@parity.io> Co-authored-by: Bastian Köcher <git@kchr.de>
Cumulus ☁️
This repository contains both the Cumulus SDK and also specific chains implemented on top of this SDK.
If you only want to run a Polkadot Parachain Node, check out our container section.
Cumulus SDK
A set of tools for writing Substrate-based Polkadot parachains. Refer to the included overview for architectural details, and the Connect to a relay chain how-to guide for a guided walk-through of using these tools.
It's easy to write blockchains using Substrate, and the overhead of writing parachains' distribution, p2p, database, and synchronization layers should be just as low. This project aims to make it easy to write parachains for Polkadot by leveraging the power of Substrate.
Cumulus clouds are shaped sort of like dots; together they form a system that is intricate, beautiful and functional.
Consensus
parachain-consensus
is a consensus engine for Substrate that follows a Polkadot relay
chain. This will run a Polkadot node internally,
and dictate to the client and synchronization algorithms which chain to follow,
finalize, and treat as best.
Collator
A Polkadot collator for the parachain is implemented by the
polkadot-parachain binary (previously called polkadot-collator).
You may run polkadot-parachain locally after building it or using one of the container option described
here.
Relay Chain Interaction
To operate a parachain node, a connection to the corresponding relay chain is necessary. This can be achieved in one of three ways:
- Run a full relay chain node within the parachain node (default)
- Connect to an external relay chain node via WebSocket RPC
- Run a light client for the relay chain
In-process Relay Chain Node
If an external relay chain node is not specified (default behavior), then a full relay chain node is spawned within the same process.
This node has all of the typical components of a regular Polkadot node and will have to fully sync with the relay chain to work.
Example command
polkadot-parachain \
--chain parachain-chainspec.json \
--tmp \
-- \
--chain relaychain-chainspec.json
External Relay Chain Node
An external relay chain node is connected via WebsSocket RPC by using the --relay-chain-rpc-urls command line
argument. This option accepts one or more space-separated WebSocket URLs to a full relay chain node. By default, only
the first URL will be used, with the rest as a backup in case the connection to the first node is lost.
Parachain nodes using this feature won't have to fully sync with the relay chain to work, so in general they will use fewer system resources.
Note: At this time, any parachain nodes using this feature will still spawn a significantly cut-down relay chain node in-process. Even though they lack the majority of normal Polkadot subsystems, they will still need to connect directly to the relay chain network.
Example command
polkadot-parachain \
--chain parachain-chainspec.json \
--tmp \
--relay-chain-rpc-urls \
"ws://relaychain-rpc-endpoint:9944" \
"ws://relaychain-rpc-endpoint-backup:9944" \
-- \
--chain relaychain-chainspec.json
Relay Chain Light Client
An internal relay chain light client provides a fast and lightweight approach for connecting to the relay chain network. It provides relay chain notifications and facilitates runtime calls.
To specify which chain the light client should connect to, users need to supply a relay chain chain-spec as part of the relay chain arguments.
Note: At this time, any parachain nodes using this feature will still spawn a significantly cut-down relay chain node in-process. Even though they lack the majority of normal Polkadot subsystems, they will still need to connect directly to the relay chain network.
Example command
polkadot-parachain \
--chain parachain-chainspec.json \
--tmp \
--relay-chain-light-client \
-- \
--chain relaychain-chainspec.json
Installation and Setup
Before building Cumulus SDK based nodes / runtimes prepare your environment by following Substrate installation instructions.
To launch a local network, you can use zombienet for quick setup and experimentation or follow the manual setup.
Zombienet
We use Zombienet to spin up networks for integration tests and local networks. Follow these installation steps to set it up on your machine. A simple network specification with two relay chain nodes and one collator is located at zombienet/examples/small_network.toml.
Which provider should I use?
Zombienet offers multiple providers to run networks. Choose the one that best fits your needs:
- Podman: Choose this if you want to spin up a network quick and easy.
- Native: Choose this if you want to develop and deploy your changes. Requires compilation of the binaries.
- Kubernetes: Choose this for advanced use-cases or running on cloud-infrastructure.
How to run
To run the example network, use the following commands:
# Podman provider
zombienet --provider podman spawn ./zombienet/examples/small_network.toml
# Native provider, assumes polkadot and polkadot-parachains binary in $PATH
zombienet --provider native spawn ./zombienet/examples/small_network.toml
Manual Setup
Launch the Relay Chain
# Clone
git clone https://github.com/paritytech/polkadot-sdk
# Compile Polkadot's required binaries
cargo build --release -p polkadot
# Generate a raw chain spec
./target/release/polkadot build-spec --chain rococo-local --disable-default-bootnode --raw > rococo-local-cfde.json
# Alice
./target/release/polkadot --chain rococo-local-cfde.json --alice --tmp
# Bob (In a separate terminal)
./target/release/polkadot --chain rococo-local-cfde.json --bob --tmp --port 30334
Launch the Parachain
# Compile
cargo build --release -p polkadot-parachain-bin
# Export genesis state
./target/release/polkadot-parachain export-genesis-state > genesis-state
# Export genesis wasm
./target/release/polkadot-parachain export-genesis-wasm > genesis-wasm
# Collator1
./target/release/polkadot-parachain --collator --alice --force-authoring \
--tmp --port 40335 --rpc-port 9946 -- --chain rococo-local-cfde.json --port 30335
# Collator2
./target/release/polkadot-parachain --collator --bob --force-authoring \
--tmp --port 40336 --rpc-port 9947 -- --chain rococo-local-cfde.json --port 30336
# Parachain Full Node 1
./target/release/polkadot-parachain --tmp --port 40337 --rpc-port 9948 -- \
--chain rococo-local-cfde.json --port 30337
Register the parachain
Asset Hub 🪙
This repository also contains the Asset Hub runtimes. Asset Hub is a system parachain providing an asset store for the Polkadot ecosystem.
Build & Launch a Node
To run an Asset Hub node, you will need to compile the polkadot-parachain binary:
cargo build --release --locked --bin polkadot-parachain
Once the executable is built, launch the parachain node via:
CHAIN=asset-hub-westend # or asset-hub-kusama
./target/release/polkadot-parachain --chain $CHAIN
Refer to the setup instructions to run a local network for development.
Contracts 📝
See the contracts-rococo readme for details.
Bridge-hub 📝
See the bridge-hubs readme for details.
Rococo 👑
Rococo is becoming a Community Parachain Testbed for parachain teams in the Polkadot ecosystem. It supports multiple parachains with the differentiation of long-term connections and recurring short-term connections, to see which parachains are currently connected and how long they will be connected for see here.
Rococo is an elaborate style of design and the name describes the painstaking effort that has gone into this project.
Build & Launch Rococo Collators
Collators are similar to validators in the relay chain. These nodes build the blocks that will eventually be included by the relay chain for a parachain.
To run a Rococo collator you will need to compile the following binary:
cargo build --release --locked --bin polkadot-parachain
Once the executable is built, launch collators for each parachain (repeat once each for chain tick, trick, track):
./target/release/polkadot-parachain --chain $CHAIN --validator
You can also build using a container.
Parachains
The network uses horizontal message passing (HRMP) to enable communication between parachains and the relay chain and, in turn, between parachains. This means that every message is sent to the relay chain, and from the relay chain to its destination parachain.